Eve library

HITL-003 evidence pack — transactional provenance-bearing intervention

Evidence

Revision 1

On this page

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 interventions field 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:

  1. a new canonical RunProtocolV1 state event;
  2. the hash-chained transactional intervention event;
  3. the dependency-mutated atomic approval lifecycle;
  4. 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 --check passes.
  • A broad tsconfig.spec.json probe 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