browser/openspec/changes/implement-dependency-installation-and-run-self-update/specs/durable-dependency-execution/spec.md

ADDED Requirements

Requirement: Dependency plans are declared and reviewable

Platform SHALL derive a safe dependency catalog from the installed plugin version, selected runtime profile, complete binding, and Run target, and SHALL require approval of the exact plan digest before installation.

Scenario: Operator reviews an install plan

• WHEN an authorized owner or platform administrator queries dependency actions for a server
• THEN Platform MUST return declared probe keys, plan titles, target OS/architecture, typed step summaries, current safe status, and a deterministic plan digest without host paths, commands, credentials, secret refs, sockets, tokens, leases, sessions, hashes used for fencing, or PIDs

Scenario: Approved plan changes before dispatch

• WHEN the plugin version, runtime profile, target, binding generation, plan steps, or digest no longer matches the reviewed plan
• THEN Platform MUST reject installation and record a safe denied audit event before creating a job

Scenario: Caller crosses server ownership

• WHEN a non-owner without server-admin or platform-admin scope requests a catalog, check, or install
• THEN Platform MUST return the existing unauthorized/forbidden semantics and MUST NOT reveal whether private bindings or plans exist

Requirement: Dependency execution input is fenced and private

Run SHALL receive dependency declarations and resolved target values only through a signed Platform route scoped to the active endpoint, session, job, attempt, and lease.

Scenario: Active Run loads dependency input

• WHEN the selected Run requests input for its active dependency attempt
• THEN Platform MUST verify endpoint ownership, session/signature, job capability/state, attempt/lease, server/plugin/profile/target, immutable digest, and cancellation state before returning the bounded typed input

Scenario: Stale or cross-endpoint Run requests input

• WHEN the endpoint, session, attempt, lease, server, plugin version, profile, or capability does not match the active job
• THEN Platform MUST reject the request without returning declarations, bindings, host targets, or plan data

Requirement: Dependency probes and installs use closed typed adapters

Run SHALL execute only supported declared probe kinds and install step types through fixed adapters and SHALL never evaluate arbitrary shell, script text, environment overrides, or caller-supplied command vectors.

Scenario: Declared probe executes

• WHEN a supported command-version, Java, Docker, package, service, Steam app, or file probe is requested for the current Run platform
• THEN Run MUST resolve only the approved target, enforce timeout/output bounds, and return a safe present/missing/version classification

Scenario: Typed package plan executes

• WHEN an approved package step names a supported manager, safe package token, optional safe version, and matching platform
• THEN Run MUST use the fixed manager adapter, respect cancellation and timeout, persist step completion idempotently, and never invoke a shell or unapproved privilege escalation

Scenario: Verified download executes

• WHEN an approved verified-download step uses HTTPS, an allowed host, a SHA-256 checksum, a bounded size, and a scoped logical destination
• THEN Run MUST stream to an owner-only temporary file, verify checksum before atomic publication, and remove invalid partial data

Scenario: Unsafe or unsupported step is requested

• WHEN a declaration contains shell syntax, an unsafe package/version token, HTTP or credential-bearing URL, missing checksum, undeclared target, unsupported platform/manager/type, symlink escape, or manual-only step
• THEN validation or Run MUST reject it without machine mutation and return a bounded safe failure

Requirement: Dependency execution is durable and auditable

Platform and Run SHALL make dependency execution restart-safe, idempotent, cancellable, retry-bounded, and auditable.

Scenario: Run restarts during a multi-step install

• WHEN Run recovers an active attempt with a matching immutable digest
• THEN it MUST resume after the last durably completed idempotent step and MUST NOT repeat a completed step or accept a stale attempt

Scenario: Cancellation arrives during a blocked adapter

• WHEN Platform records cancellation for the active dependency job
• THEN Run MUST cancel the adapter context, stop before the next step, preserve recoverable evidence, and report a fenced cancelled result

Scenario: Terminal dependency evidence is accepted

• WHEN Platform accepts a current terminal probe or install result
• THEN it MUST update the durable dependency status and audit actor, server, plugin, probe/plan, attempt outcome, and safe summary without private execution details

Requirement: Dependency work preserves channel deadlines

Slow package managers and downloads SHALL NOT block Run control heartbeat, job acknowledgement/result, cancellation polling, log upload, or artifact channel progress.

Scenario: Dependency adapter is blocked

• WHEN a dependency command or download remains blocked beyond a heartbeat interval
• THEN heartbeat, log acknowledgement, cancellation polling, and unrelated job-channel requests MUST continue through independent bounded operations