Work-package charter#
- Task ID:
HITL-003 - Owner: Oshun run-protocol and Agentic Studio maintainers; implementation owner: Codex
- Accountable product: V1 Oshun autonomous-content platform
- Priority: P0
- Target milestone: 2026-07-15 SOTA gap-closure program
- Risk tier: Critical race, stale-authority, partial-commit, effect replay, provenance, and rollback risk
- Dependencies: RUN-002 durable run journal/checkpoints, RUN-003 durable effect identity, RUN-005 atomic approval lifecycle, and the HITL-002 command vocabulary
- Affected runtime: shared V1–V9 run-protocol contracts and the crash-recoverable reference file store
- Rollback strategy: Revert the source commit. The new
interventionsfield is defaulted, so pre-HITL-003 file records remain readable. - Evidence-pack location: This file
One atomic commit boundary#
The reference FileDurableRunStore now implements
TransactionalInterventionStore in the same durable record that already owns
the canonical run history, effect journal, checkpoints, and RUN-005 lifecycle.
An accepted intervention runs under the existing inter-process lock and commits
all of the following together:
- a new canonical
RunProtocolV1state event; - the hash-chained transactional intervention event;
- the dependency-mutated atomic approval lifecycle;
- claim, invalidation, gate-rerun, and lineage projections.
The fully updated document is schema/reducer validated before it is written to a mode-0600 temporary file, fsynced, atomically renamed, and followed by a directory fsync. An injected failure immediately before the temporary write proves that no canonical state, lifecycle event, or intervention journal entry survives a failed transaction.
Optimistic claims and canonical edits#
Every mutation carries the expected durable run head, lifecycle revision, and intervention revision. A step claim additionally binds the active plan version, step ID, claimant identity/role, and an expiring lease. Concurrent claims with the same tokens serialize to one winner. Active claims block a second claimant; expired claims are automatically abandoned; explicit abandonment is limited to the claimant or an operator; a plan edit abandons claims on the superseded version; a successful human branch merge marks the author's active claim merged.
Plan edits append the next contiguous RunPlanVersionV1 and make it the
canonical active version. Artifact edits invalidate the former canonical
artifact, append a fresh parent-linked replacement, and update the exact durable
run snapshot—not only an annotation. Branch merge fails if its base or branch
digest changed. Rollback invalidates the current artifact and restores the
retained prior artifact in the canonical snapshot.
Dependency invalidation and gate equality#
Plan, source, artifact, policy, and gate dependency hashes are recomputed from
the mutated canonical run inside the transaction. The RUN-005 lifecycle marks an
approval stale and returns approved/executing work to its governed state when
any dependent hash changes. An execution attempt using the pre-edit approval is
rejected with stale-approval.
Invalidation records preserve all caller-known dependent judgment, approval, signature, cache, and placement receipt references. The protocol also derives canonical gate-verdict IDs and release placement receipts for the affected artifact, and injects the RUN-005 approval ID when it becomes stale.
Replacement and rollback derive required gates from the prior artifact's actual gate verdicts. The exact gate-ref set is appended as new pending verdicts for the new/restored subject, regardless of whether its authorship is agent, human, or mixed. A separate transactional operation records rerun outcomes on those canonical pending verdicts and recomputes the gate dependency hash.
Signed mixed lineage and exact resume#
Every artifact event records actor identity, authority role, rationale, the full operation input, an input digest, the structured edit diff and digest, parent artifacts, authorship, and optional branch-merge coordinates. Mixed human/agent lineage cannot commit without a key ID and an HMAC-SHA256 signing key of at least 32 bytes. Verification succeeds for the original attestation and fails for a changed reason or undersized key.
resumeTransactionalInterventionByThread loads one atomic file snapshot and
returns checkpoint-replayed canonical state, lifecycle authority, and the
intervention journal together. A fresh store instance resumes the committed
mixed artifact and lineage. Reusing the exact command is idempotent and does not
append another run event. A separately keyed acknowledgment of an already
recorded effect digest is also a no-op; a different digest fails closed.
Required adversarial matrix#
| Required scenario | Enforced result |
|---|---|
| Restart | Fresh store process resumes canonical checkpoint, lifecycle, and journal together. |
| Race | Two same-version claims produce one commit and one optimistic conflict. |
| Stale approval | Human edit stales dependency-bound approval; execution with it is refused. |
| Duplicate effect | Same effect/digest does not append; changed digest conflicts. |
| Unauthorized edit | Customer canonical edit is rejected with no durable-head movement. |
| Abandoned claim | Explicit and lease-expired claims resolve before reassignment. |
| Merge conflict | Stale base or branch digest prevents a merge and leaves history unchanged. |
| Rollback | Current artifact and downstream authorities invalidate; retained prior artifact becomes canonical. |
| Partial write | Injected pre-write crash leaves run, lifecycle, and journal at their prior revisions. |
Automated verification#
- Focused HITL-003 suite: 12/12 passing. Parameterized agent/human/mixed coverage proves exact required-gate equality for all three authorship modes.
- Complete affected run-protocol regression set: 67/67 passing across 6/6 files: run model, durable run, durable effect, atomic lifecycle, adapter conformance, and transactional intervention.
- Production contracts TypeScript typecheck: zero errors.
- Production contracts TypeScript build: zero errors and current emitted JavaScript/declarations.
- Focused ESLint over every changed source/spec file: zero errors.
git diff --checkpasses.- A broad
tsconfig.spec.jsonprobe remains red on pre-existing unrelated test typing debt in other contract domains; no HITL-003 file appears in the remaining diagnostic set after its two local diagnostics were fixed. The applicable affected test set above is fully green.
Artifact identity#
| Artifact | SHA-256 |
|---|---|
libs/contracts/src/run-protocol/transactional-intervention.ts |
7dd3c6adef0abb12cd440a7dc3162bde440dce3c6bd9413133929b269db1812e |
libs/contracts/src/run-protocol/transactional-intervention.spec.ts |
6a3f86f360ed7042655921700835380048762fd0047d22861085cc5d8789775f |
libs/contracts/src/run-protocol/file-durable-run-store.ts |
87a0a9842622eaecfcde4e56f4e5a6247b607817d021ce58824e9cdbd792bb71 |
libs/contracts/src/run-protocol/run-model.ts |
74bbf6e50dd0f36ca8d53e88a10482e6d2d34a0dc0849efd1cb400628e6a72c4 |
libs/contracts/src/run-protocol/index.ts |
1dfe5e493ffbcf5f0b77a3b53b94c1e1a63bd0b8f6939784ab9f91e2a1cbc1c2 |
Resource-safe verification#
The final resource probe reported 15 GiB RAM, 31 GiB swap, about 10 GiB available RAM, and 38 GiB free disk. No competing Vitest, TypeScript, Nx, Playwright, or packaging gate was active. Tests, typecheck, lint, and build ran sequentially and stayed scoped to the contracts/run-protocol boundary. No full-workspace sweep was attempted.
Scope and negative proof#
- This is the portable transaction protocol plus crash-recoverable reference adapter. Product database adapters can implement the same interface but are not claimed here.
- HITL-004 still owns V1 BFF/common-store binding and the composition of Lilith, Yemaya, and Studio Authoring primitives. No HTTP endpoint or UI changed in this package, so Playwright and mobile UI automation are inapplicable.
- HMAC lineage proves possession of the named runtime signing key. It is not a public-key C2PA signature or evidence of an externally deployed key service.
- No production traffic, provider effect, external publication, media/model pipeline, mobile-native flow, or Unreal asset was changed or exercised.
Publication identity#
- Transactional intervention source commit:
10f8aa6505384232602c879de91572643f7a3e5d - Closure evidence commit:
2d67fe50c01fdc2bc23804ca1a048423eab85a63