# HITL-003 evidence pack — transactional provenance-bearing intervention

## 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`
