browser/platform/protocol/dependency-update-contracts.md

Dependency And Run Update Contracts

Platform owns the reviewable dependency catalog, immutable plan digest, selected server/profile/binding, endpoint target, distribution artifact, job attempt, and audit projection. Plugins and platform_web see only catalog/status/update projections. They never receive resolved host paths, commands, raw bindings, credentials, secret refs, Run/session/lease values, fencing hashes, PIDs, sockets, or artifact bodies.

Dependency flow

1. GET /api/v1/server-instances/{id}/dependencies resolves the installed plugin version, complete runtime binding, online Run endpoint OS/architecture, target-matched probes/plans, and canonical SHA-256 digest.
2. An install request must submit that exact digest. Platform re-resolves the declaration before creating dependencies.install; missing or stale approval is denied and audited.
3. Run retrieves private input through signed POST /api/v1/run/jobs/dependency-input only for the active endpoint/session/attempt/lease and non-cancelled job. It executes closed command-version, Java, Docker, package, service, Steam, file, package-manager, verified HTTPS download, and SteamCMD adapters with bounded output/timeouts and a durable step journal.
4. Terminal evidence is typed and redacted. Platform verifies probe key, plan digest, result checksum, and job attempt before updating DependencyStatus.

Self-update flow

1. Platform accepts only an available Run distribution owned by the same server and matching the registered endpoint OS/architecture/checksum.
2. Run retrieves private metadata through update-input, reads 1 MiB-or-smaller ranges through update-chunk, persists offsets, verifies the final artifact checksum, rejects traversal/links/devices/unexpected entries, and stages exactly the expected executable without replacing configuration.
3. The terminal staged result moves the safe phase to restart-requested. The local journal persists the activation manifest before helper launch. The helper backs up/replaces atomically, starts the new binary with helper environment removed, waits for health, and rolls back on timeout or identity failure.
4. The new Run reports success or rollback through signed update-health only after registration and job reconciliation. Platform then projects succeeded or rolled-back; a hello-only outcome is never treated as health confirmation.

Control heartbeat, job ack/result/cancel/reconcile, durable logs, and artifact upload use independent loops and deadlines. This contract does not include production code signing/KMS, rollout rings/fleet orchestration, client-manager lifecycle, plugin lifecycle, production scaling/alerts, external mirrors/storage, or real AI-provider integration.