Skip to content

ADR-0007: Key-Bound External Runtime Runs

Target architecture — not the current operating contract

This decision records the implemented external-runtime identity boundary and its relationship to future managed Agent Builder resources. Use Current release for operating procedures.

Superseded

ADR-0010 replaced this Run lifecycle and Runtime API boundary in the 2026-08-31 big-bang development cutover. This record remains historical and is not a current API contract.

Status

Accepted — 2026-08-26

Context

The former external runtime workflow asked a caller to submit an immutable manifest and then create an environment record describing what it claimed to run. Those records did not establish Agent identity, grant authority, published policy, or governed gateway evidence. They could drift from the executing process and made Run start depend on manually maintained caller assertions.

The existing Agent-key verification already resolves organization, project, Agent, environment, exact key, and immutable key scope. Runtime implementation fields such as framework, instrumentation scope, release, and service.version are ordinary caller-observed OpenTelemetry data and cannot prove an artifact executed.

Decision

An external Run's trusted identity is Agent, environment, exact starting key, and Run/Trace state. The supported flow is Agent -> grants -> Agent keys -> Runs.

  • POST /runtime/v1/runs accepts {} or only frameworkRunReference.
  • The server derives organization, project, Agent, environment, and key identity from the verified key.
  • Model/MCP authority remains the conjunction of immutable key scope, current grant, active configuration/resource resolution, and allowing published policy.
  • The exact starting key owns telemetry and finalization writes. Terminal key revocation is the per-key containment path; Agent suspension contains all keys and new Runs.
  • Capture resolves organization maximum, project restriction, then Agent restriction and is pinned to the new Run.
  • Optional service.name, service.version, instrumentation scope, framework, model, and tool data remains Observed only OpenTelemetry.
  • No source tree, Git state, CI-vendor environment, working-copy hash, or runtime-release registry is inspected or invented.
  • A future Agent Builder may introduce Mission-Control-managed authoring, release, and deployment resources through a separate approved design. It does not reuse removed caller-asserted external state.

Consequences

  • External onboarding is shorter and matches the actual authorization boundary.
  • This is a breaking development reset: SQLite migration 0012 and ClickHouse schema 3 fail before mutation when removed state or serving rows exist.
  • Key rotation does not change capture policy; capture is Agent-scoped rather than credential-scoped.
  • Runtime version data may be absent or inaccurate and is never authorization or attestation.
  • Standard OTLP transports, Run/Trace headers, Model/MCP gateway routes, key format, governed evidence, Tree/Timeline, content boundaries, retention, deletion, backup/restore, resilience, and load contracts remain unchanged.
  • Trace discovery/search remains a separate Slice 2 design and must use the reduced dimensions.

2026-09-23: storage moved to Postgres

The SQLite migration named above belongs to the retired SQLite history. ADR-0012 replaced that history with a fresh PostgreSQL baseline; this record is otherwise unchanged.

Rejected alternatives

  • Keep the caller manifest and lifecycle record. Rejected because it adds workflow and drift without adding authority.
  • Bypass the record only for some callers. Rejected because dual identity paths and hidden compatibility branches weaken the contract.
  • Auto-register a manifest or release from the first span. Rejected because telemetry is caller-observed and cannot establish provenance.
  • Fabricate empty legacy IDs. Rejected because placeholders create false authority and corrupt serving schemas.

Relationship to ADR-0006

ADR-0006 remains accepted for treating native and external Agents as governance peers. This record supersedes its external manifest, immutable-version, and attestation requirements. Managed native/Agent Builder release semantics remain future work.

Current governance mapping

The current source release uses Organizations, Teams, real user/service-account virtual keys and separate human management roles. Agent is managed application content; deployments own secretless execution access and publisher funding. Observe uses Requests, Traces, Sessions and Usage with separate metadata/content/export permissions. Historical identity terms in this target proposal are not the operating contract. See Current release.