# RUN-005 evidence pack — atomic approval and execution lifecycle

## Work-package charter

- **Task ID:** `RUN-005`
- **Owner:** Oshun common run-protocol 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:** Critical stale-authority, approval-race, false-completion,
  final-ledger-loss, and recovery risk
- **Dependencies:** RUN-001 common aggregate, RUN-002 durable filesystem
  transaction and recovery semantics, RUN-003 durable effects, and RUN-004
  product-to-common adapters
- **Affected schemas and runtime:** Atomic lifecycle schema/reducer/operations;
  durable file-run record; contracts exports; focused protocol CI gate
- **Rollout strategy:** Store one append-only lifecycle journal inside the
  existing durable common run record. Product integrations may consume it only
  through the exported store interface and must retain their existing source
  records until migration and rollback certification passes.
- **Rollback strategy:** Revert the lifecycle module, durable-store extension,
  export, and gate update together. Existing files remain readable because the
  lifecycle field defaults to `null`; no product database migration was run.
- **Evidence-pack location:** This file

## One lifecycle and authority boundary

`AtomicRunLifecycleStateSchema` contains exactly `submitted`, `approved`,
`executing`, `paused`, `tool-wait`, `review`, `completed`, `rejected`,
`discarded`, `cancelled`, `killed`, `rolled-back`, and `withdrawn`. A guarded
transition table connects the ordinary control states. Three authority-bearing
targets cannot be entered through the generic transition function:

- `approved` requires `decideAtomicLifecycleApproval`;
- `executing` requires `startAtomicLifecycleExecution` with the exact current
  approval identity; and
- `completed` requires `finalizeAtomicLifecycle`, which writes the complete
  finalization record in the same event that changes the state.

Every lifecycle event carries the run identity, sequence, previous-event hash,
time, actor, rationale, before/after state, complete dependency identity, and
kind-specific approval, invalidation, or finalization data. Its SHA-256 and
derived event ID cover the complete event core. Reduction validates the hash
chain, monotonic sequence and time, state projection, allowed transition,
dependency digest, approval identity, approval availability/expiry, and
finalization digest. A modified event cannot be accepted merely by satisfying
the structural schema.

The journal is stored as `lifecycle` on the existing `FileRunRecord`, beside
RUN-002 events and RUN-003 effects. Every mutation therefore uses the existing
inter-process lock, reload/validation boundary, mode-0600 temporary write,
file/directory fsync, and atomic rename. It is not a competing product run
envelope or an eventually-consistent approval flag.

## Versioned approval identity and invalidation

Each decision has a monotonically increasing version and binds the immutable
tuple of:

1. plan SHA-256;
2. source SHA-256;
3. artifact SHA-256;
4. policy SHA-256; and
5. gate SHA-256.

The five fields produce a dependency SHA-256. The approval SHA-256 covers the
run ID, decision version, decision, complete dependency record, actor,
rationale, decision time, and optional expiry. The approval ID is derived from
that digest. The reducer independently recomputes both dependency and approval
digests.

`mutateAtomicLifecycleDependencies` accepts the next complete five-hash record.
It refuses a no-op and marks the current approval stale in the same journal
append. An approved package returns to `submitted`; an executing or tool-wait
package becomes `paused`; other mutable review states retain their state but
lose current authority. Mutation is forbidden after terminal completion,
discard, cancellation, kill, rollback, or withdrawal. The test matrix changes
each of the five fields independently, requires a new approval version after
each mutation, rejects the first stale approval, and proves an active execution
is paused immediately when its source changes.

## Atomic execution claim and finalization

`startAtomicLifecycleExecution` requires the caller's expected lifecycle
revision and approval ID. It rejects a missing, rejected, stale, mismatched, or
expired approval. `FileDurableRunStore` evaluates this inside the locked
transaction; two independent clients using the same approved revision cannot
both win. The concurrency test observes one fulfilled execution claim, one
`lifecycle-conflict`, and one durable `executing` event.

Generic transition rejects `completed` with `finalization-required`.
`finalizeAtomicLifecycle` accepts only `executing` or `review` and requires all
of these fields before producing the completion event:

- at least one final output identity and content hash;
- the complete failure list, including retryability and failure hashes;
- non-empty rationale;
- the tool-event ledger;
- at least one evidence-ledger entry; and
- actual cost with ISO currency, minor units, input/output tokens, and compute
  milliseconds.

The finalization SHA-256 covers the entire record. A fault injected immediately
after atomic rename makes the caller observe a failure, but a new store instance
recovers the hash-valid `completed` event with outputs, recovered failure,
rationale, tool/evidence ledgers, and exact cost intact. Completion is never a
separate write that can become visible before its ledger.

## Automated scenario matrix

| Scenario                       | Enforced result                                                                            |
| ------------------------------ | ------------------------------------------------------------------------------------------ |
| State vocabulary               | The exact 13 required states are schema-enumerated and exercised through guarded branches. |
| Dedicated authority operations | Generic transitions cannot create approval, execution, or completion.                      |
| Five-hash approval             | Approval identity changes with and retains plan/source/artifact/policy/gate digests.       |
| Dependent mutation             | Every hash class stales authority; active execution pauses.                                |
| Missing approval               | Execution fails with `approval-required`.                                                  |
| Stale or wrong approval        | Execution fails with `stale-approval`.                                                     |
| Expired approval               | The expiry boundary is fail-closed.                                                        |
| Approval race                  | Two durable clients produce exactly one winner under the same revision.                    |
| Premature completion           | `completed` is unavailable without the dedicated finalization operation.                   |
| Final-ledger crash             | Rename-boundary failure recovers the committed completion and full ledger.                 |
| Tamper resistance              | Changed dependency/event data fails hash-chain reduction.                                  |
| Backward file compatibility    | Existing run records parse with `lifecycle: null`.                                         |

## Artifact identity

| Artifact                                                       | SHA-256                                                            |
| -------------------------------------------------------------- | ------------------------------------------------------------------ |
| `libs/contracts/src/run-protocol/atomic-run-lifecycle.ts`      | `5606322d32361c69340957e0a83ce7c0d279bfac2149a3405f9cd1488990643b` |
| `libs/contracts/src/run-protocol/atomic-run-lifecycle.spec.ts` | `6dd7d1a35cd4c3d3ecdc4afaeb761131d578460e42806c367e992f8581da6705` |
| `libs/contracts/src/run-protocol/file-durable-run-store.ts`    | `405a7cec63961ed5ce9a0f361452382d3ee1aea03ac1319c3320a409feee575a` |
| `libs/contracts/src/run-protocol/index.ts`                     | `0ae5f2b4ffbb44cdea505f31c682e6d5951704ab5f68a3ef6e082cbc0137a153` |
| `package.json`                                                 | `a96495b9010b06137c89087b1f7b43143da49c536e22dc7a9e569f85a5da5800` |
| `pnpm-lock.yaml`                                               | `627422a4715c85693b8fccf921ee7c615f0f002911f8506758769e5f6bbbc04e` |

## Automated and adversarial verification

- `pnpm run verify:contracts:run-protocol` passes targeted ESLint with zero
  warnings, **54/54** common protocol cases with one worker, and contracts
  production typechecking. RUN-005 contributes **5/5** focused cases.
- The focused cases cover the full state vocabulary and guarded branches, all
  five dependency mutations, approval versioning, stale/missing/expired
  authority, tamper detection, two-client execution contention, mandatory
  finalization, and rename-boundary recovery of every required final field.
- `NX_DAEMON=false pnpm exec nx run @oshun/contracts:build --parallel=1 --outputStyle=static`
  succeeds. Runtime probes confirm the lifecycle through the root flat export,
  `RunProtocolContracts` namespace, and `@oshun/contracts/run-protocol` subpath.
- `pnpm install --frozen-lockfile --lockfile-only --offline --ignore-scripts`
  passes with no lockfile change.
- `git diff --check` passes. The source commit was pushed and verified equal to
  `origin/main` before this evidence pack was authored.
- The build ran after the required resource check. The host had 15 GiB RAM, 31
  GiB swap, about 10 GiB available RAM, and 38 GiB free disk. No broad workspace
  sweep or parallel build matrix was run while another agent process was active.

## Scope and negative proof

- This is a portable common contract plus its filesystem reference adapter. It
  is not evidence that a V1–V9 product database, API, worker, or operator
  console consumes the lifecycle in production.
- No data migration, dual-write comparison, product replay, provider call,
  publication, deployment, or live rollback drill occurred. Existing product
  envelopes remain authoritative and are not deprecated.
- RUN-005 closes the common atomic-lifecycle package. HITL-001 through HITL-005,
  product runtime packages, and P1-001 still own authenticated operator
  consumption, interruption semantics, product-store recovery, and live
  certification.
- No user-facing UI, mobile flow, media/model pipeline, database migration, or
  Unreal asset changed. Playwright/mobile/browser accessibility,
  provider/media/database, and Unreal verification are inapplicable.

## Publication identity

- **Implementation and first remote-integrated tested source commit:**
  `f20ba9c007fdd175ed45faea2893a1768bdf0982`
- **Publication metadata commit:** `c61768e3fb7178880f082bf2694dc6e11ea6512a`
