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-protocoland 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
AgentRunor 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-protocolpasses 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-slotremains 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
AgentRunSchematests (312 unrelated cases skipped). Vite reports the repository's pre-existing absentlibs/contracts/src/index.js.map; the test process still exits zero. NX_DAEMON=false pnpm exec nx run @oshun/contracts:build --parallel=1passes. A runtimetsxprobe verifies the protocol version, derivation/import helpers, and release taxonomy through the root flat export, rootRunProtocolContractsnamespace, and@oshun/contracts/run-protocolsubpath.- 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