Eve library

RUN-005 evidence pack — atomic approval and execution lifecycle

Evidence

Revision 1

On this page

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