# RUN-001 evidence pack — common versioned run protocol

## Work-package charter

- **Task ID:** `RUN-001`
- **Owner:** Oshun common run-protocol contract maintainer; implementation
  owner: Codex
- **Accountable product:** Shared V1–V9 autonomous-content platform
- **Priority:** P0
- **Target milestone:** 2026-07-15 SOTA gap-closure program
- **Risk tier:** High execution-integrity, authority, side-effect, lineage,
  measurement, intervention, and release-lifecycle risk
- **Dependencies:** Existing common `AgentRun`, durable-job, provenance,
  human-checkpoint, tool-catalog/grant, publication-gate, COV-001 slot-policy,
  and COV-003 dependency concepts; AUD-003 reproducible verification; AUD-006
  generated capability truth
- **Affected schemas:** New strict V1 common Run/Step/Attempt/Artifact/
  Intervention aggregate, identity and idempotency derivation helpers, strict
  importer, root/namespace/subpath exports, focused CI, and adversarial tests
- **Rollout strategy:** Publish through `@oshun/contracts/run-protocol` and the
  root contracts namespace, retain existing product records unchanged, then add
  adapters/conformance under RUN-004 after RUN-002 supplies append, checkpoints,
  migration, and replay semantics.
- **Rollback strategy:** Revert the protocol, tests, exports, CI, audit
  qualification, and ledger closure together. Do not substitute the older
  unversioned `AgentRun` or a product-specific event record for this common
  protocol without an explicit adapter and evidence boundary.
- **Evidence-pack location:** This file

## Common aggregate and immutable identity

`RunProtocolV1Schema` is strict at every object boundary and carries an explicit
schema version. Its identity core requires tenant, actor/delegation, purpose, an
explicit canonical content slot or reasoned not-applicable scope, risk tier,
autonomy level, parent run, and optional fork source/sequence/evidence. The
identity digest is SHA-256 over the parsed identity core, and the stable run ID
is derived from that digest. A changed immutable field cannot retain the prior
run ID/digest.

The model records run status through a contiguous transition history beginning
at `queued`. All timestamps must fall between the aggregate's `createdAt` and
`updatedAt`. A succeeded run cannot retain nonterminal active-plan steps or open
attempts. Self-parenting and incoherent fork lineage fail closed.

## Plans, steps, attempts, and tool event chain

Plans are a contiguous, explicitly superseding version sequence with one active
version. Each version contains a bounded step DAG. Dependencies must exist in
the same version, self-dependency and cycles are rejected, and each step has a
contiguous legal transition history whose final transition equals current state.
Terminal success/failure transitions bind an attempt with the same plan, step,
and terminal status.

Attempt identity derives from run ID, plan version, step ID, and ordinal. The
same tuple deterministically produces an attempt ID, full identity digest, seed,
and external-effect idempotency key. Ordinals are contiguous from one; the first
attempt cannot claim a retry, while later attempts must reference the
immediately prior failed/cancelled attempt and carry a typed retry reason.

The tool event union contains exactly the required request, approval,
resolved-grant, invocation, result, side-effect, and reconciliation records.
Every event belongs bidirectionally to an attempt and uses one contiguous run
sequence. References must point backward to the same attempt/tool. An
approval-required request cannot resolve a grant without a current approved
decision; resolved capabilities cannot exceed the request; expired approval or
grant records cannot authorize invocation; invocation idempotency keys are
deterministic; applied side effects require provider results; and reconciliation
requires authoritative evidence.

## Bindings, artifacts, gates, interventions, and measurements

The seven versioned dependency bindings are source, canon, policy, prompt,
model, rubric, and provider. Each captures subject, version, SHA-256, evidence,
and time. Artifacts carry kind, role, lifecycle state, content/storage identity,
producer attempt, parent lineage, dependency bindings, and evidence. Producer
and artifact links are bidirectional, and missing parent/binding references fail
closed.

Gate verdicts include pending/pass/warn/block/waived states, evidence, blockers,
and waiver intervention. Any resolved gate needs evidence; a block needs blocker
references; a waiver needs both evidence and a real intervention. Interventions
cover pause/resume, redirect, plan/tool editing, step claim, artifact
replacement, approve/reject/veto/override, cancellation, retry, fork, and
rollback. Applied plan edits/redirects must identify an existing resulting plan
version.

Measurement variants cover USD micros, phase latency, prompt/completion/
reasoning/cached tokens, GPU milliseconds/peak bytes/provider receipt, and
energy/CO2e/water environmental values with methodology evidence. Measurements
must bind a known run, step, attempt, tool event, or artifact; token totals are
reconciled from their components.

## Publication and placement lifecycle

The release lifecycle defines publication, placement, canary, promotion,
rollback, withdrawal, revocation, invalidation, recertification, and blocking
actions. Corresponding states include pending and terminal states through
`published`, `placed`, `canary`, `promoted`, `rolled-back`, `withdrawn`,
`revoked`, `invalidated`, and `recertified`. History must initialize in draft,
remain contiguous, use an allowed action source/target pair, move forward in
time, and end at the declared state. Every non-initial transition requires
evidence; placement transitions require placement references; artifacts, gate
verdicts, and interventions must exist in the same run aggregate.

## Artifact identity

| Artifact                                            | SHA-256                                                            |
| --------------------------------------------------- | ------------------------------------------------------------------ |
| `libs/contracts/src/run-protocol/run-model.ts`      | `6677c282d612eccbead564e2012df5f704d4f1b455b7fbfef281a4d8f39bd3f8` |
| `libs/contracts/src/run-protocol/run-model.spec.ts` | `1d466d179c565a210d00f8afa41a557f9d09acb892df0ea30b1b7287947a9109` |
| `libs/contracts/src/run-protocol/index.ts`          | `cecbb753bb3239fc82fca6dd2d212689cdf13c492e3a09514deafcffc0c13a19` |
| `libs/contracts/src/index.ts`                       | `ee9f0f22297c7a4b29243221bf15e31290d6df75e479bcfe1bd7b83e39150f1d` |
| `libs/contracts/package.json`                       | `f3e77e2812af9be98f99d9f77430b10fdfc6e4b4f853dae8320d6021342624fc` |
| `.github/workflows/run-protocol-contract.yml`       | `d09f96ab0e8daef17cd088bc91a4cdd4924dda1a3691a4d38cfd4d75e38e9c8f` |
| `package.json`                                      | `c3b3f8f0fd79dc0dc21b574e90e10638b76436e3108f87e6f3e26973d1cb68ac` |

## Automated and adversarial verification

- `pnpm verify:contracts:run-protocol` passes targeted ESLint with zero
  warnings, **18/18** Vitest cases with one worker, and contracts source
  typechecking.
- Tests prove the complete aggregate and all seven tool event types; immutable
  identity and fork coherence; plan versions, dependency existence, and cycle
  rejection; run/step transition legality and snapshot time bounds;
  deterministic attempt/seed/idempotency identity; retry continuity; approval,
  grant, capability, expiry, event-chain, and invocation-key enforcement;
  artifact/binding integrity; gate waiver and intervention plan bindings; all
  five measurement types; all required release actions/states; strict import;
  unknown-field/version rejection; and duplicate identity rejection.
- `pnpm verify:contracts:content-slot` remains green at **17/17** tests because
  RUN-001 reuses canonical content-slot IDs, risk tiers, and autonomy levels.
- A focused existing-contract compatibility run passes **7/7** `AgentRunSchema`
  tests (312 unrelated cases skipped). Vite reports the repository's
  pre-existing absent `libs/contracts/src/index.js.map`; the test process still
  exits zero.
- `NX_DAEMON=false pnpm exec nx run @oshun/contracts:build --parallel=1` passes.
  A runtime `tsx` probe verifies the protocol version, derivation/import
  helpers, and release taxonomy through the root flat export, root
  `RunProtocolContracts` namespace, and `@oshun/contracts/run-protocol` subpath.
- Verification ran sequentially. Resource gates observed about 10–11 GiB
  available RAM, 30 GiB free swap, and 38 GiB free disk. The build was polled at
  least every 30 seconds and stayed near 10–11 GiB available.
- Source pre-commit ESLint, Prettier, asset locking, and V5 documentation
  validation passed. The prohibited broad workspace typecheck was bypassed with
  `SKIP_TYPECHECK=1`; focused contracts typechecking and the resource-gated
  package build passed first.

## Negative proof and task boundary

- RUN-001 proves a strict schema, deterministic identity helpers, and in-memory
  validation. It does not provide durable append, sequence allocation,
  checkpoints, forward/backward checkpoint migration, replay, compaction, or
  process-death recovery; RUN-002 owns those behaviors.
- Tool event and effect records define the common vocabulary but do not execute,
  persist, deduplicate, or reconcile a provider mutation. RUN-003 owns durable
  intent-before-effect and provider-aware retry semantics.
- No V1–V9 product pipeline is adapted to this record, no database table stores
  it, and no deployed worker emits it. RUN-004 owns adapters/conformance and
  RUN-005 owns scheduler/runtime control integration.
- The full green fixture is synthetic contract proof, not a production run,
  provider receipt, publication, placement, canary, intervention, cost bill, GPU
  reading, or environmental observation.
- No user-facing UI, persistence migration, media pipeline, or Unreal asset
  changed. Playwright/mobile/browser accessibility, database/provider/media, and
  Unreal execution are therefore inapplicable to RUN-001.

## Publication identity

- **Implementation source commit:** `84752f8c11923679953650e84438d335ea62a2a6`
- **First remote-integrated tested source:**
  `84752f8c11923679953650e84438d335ea62a2a6`
- **Publication metadata commit:** `6ada35547cea8e16deb92941c345d5fa92d63d55`
