Eve library

RUN-001 evidence pack — common versioned run protocol

Evidence

Revision 1

On this page

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