Eve library

HITL-002 evidence pack — complete human-intervention domain API

Evidence

Revision 1

On this page

Work-package charter#

  • Task ID: HITL-002
  • Owner: Oshun 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 human-authority and non-overridable-policy risk
  • Dependencies: Agentic Studio AgentRunEnvelope and the existing pure run controls delivered before this work package
  • Affected runtime: @oshun/agentic-studio intervention domain API and its public package export
  • Rollback strategy: Revert the two implementation commits. No database, BFF route, wire contract, or user-facing surface changed in this package.
  • Evidence-pack location: This file

Canonical intervention surface#

intervention-api.ts now defines one exhaustive discriminated command union, one immutable workspace, one comprehensive observation projection, one result union with typed denials, and one audit record shape. Accepted commands return a new workspace without mutating their input. Denials return a stable reason and never change or emit state.

LiveInterventionSession makes observation an actual live API contract rather than only a point-in-time helper. Subscribers receive the full observation and the intervention record after every accepted mutation. The observation includes the plan and current step, all tool effects plus explicit pending and operator-only subsets, intermediate/node/output artifacts, source set and evidence trail, cost ledger, gates, run/output/publication lineage, active human claims, and the complete policy-law projection. Runtime adapters can map the listener to SSE or WebSocket when HITL-004 binds the domain API to the BFF.

Complete command vocabulary#

Capability family Implemented commands
Run control pause, resume, cancel, kill, choose branch, fork, rewind, retry with changes, and publication rollback
Discussion comments targeting a run, artifact, node, or rubric dimension, with attached reference IDs
Editing edit brief, plan, source set, tool arguments, and artifact node
Co-authoring claim step, author from blank, replace artifact, and merge human branch
Decisions approve, reject, veto, defer, reassign, require extra review, grant scoped exception, and change future autonomy level

The pause/resume/cancel/kill/branch/fork/retry behaviors use the existing Agentic Studio run-control functions, while rewind and publication rollback add the missing domain semantics. Plan replacement rejects duplicate, dangling, self-referential, and cyclic dependencies. Claims reject conflicts; artifact replacement updates intermediate and output references; human-branch merge marks resulting content as mixed and closes matching active claims.

Non-overridable platform laws#

The API names six platform laws as a closed type: safety, rights, child safety, crisis, identity, and irreversible action. A gate associated with any one of these laws can never receive a scoped exception. A blocking law finding also prevents progress-enabling interventions—resume, branch selection, fork, retry, merge, approval, and increased future autonomy—while still permitting remediation edits, rejection/veto/defer, cancellation/kill, comments, and publication rollback. Editing does not silently clear the finding; only a later governed evaluation can do that.

Role rules are fail-closed. Platform operators have the full vocabulary; tenant operators cannot grant exceptions; creators cannot kill, reassign, grant exceptions, or change future autonomy; customers are limited to comment, cancel, reject, and defer. Every command requires a non-empty rationale.

Automated and adversarial verification#

  • Focused intervention suite: 20/20 passing. It covers every command, immutable input behavior, all four comment dimensions, live accepted-only subscriptions, target/transition/claim/role/rationale failures, invalid DAGs, invalid/expired exceptions, and observation completeness.
  • Each of the six non-overridable laws is independently tested against an attempted exception. A blocked crisis finding is also tested against resume and raised-autonomy bypass attempts while remediation and rollback remain available.
  • Full @oshun/agentic-studio suite: 309/309 passing across 20/20 test files.
  • Focused ESLint over all changed TypeScript files: zero errors.
  • Production TypeScript typecheck: zero errors.
  • @oshun/agentic-studio:build emitted the implementation JavaScript, sourcemap, declarations, and declaration map under the package build output.
  • git diff --check passes.

Artifact identity#

Artifact SHA-256
libs/oshun/agentic-studio/src/interventions/intervention-api.ts 792c7c12f7f159361dfa4c5186f3f1f7d33d8a792d2d767df9a004e94b8b43c9
libs/oshun/agentic-studio/src/interventions/intervention-api.test.ts f0178affa54ab147c301083cc051c104905f2dd52d9d898fc5ba3f2ad34c9e7d
libs/oshun/agentic-studio/src/interventions/index.ts 425d0944b99f307eec1e693362977c033845799c46cc43fc32564534cd47a105
libs/oshun/agentic-studio/src/index.ts 0ab8d716e1e3432d53d1328a6ab02ce1c347efa2979117ece53c9a247a0d71a6

Resource-safe verification#

The host has 15 GiB RAM and 31 GiB swap. Verification stayed scoped to the Agentic Studio package and ran sequentially. The Nx build's project-graph phase briefly used about 1.4 GiB in its ESLint plugin worker; it was supervised with about 9–10 GiB memory still available and completed before another check began. No full-workspace sweep, Next production build, mobile export, or packaging matrix was attempted.

Scope and negative proof#

  • This work package implements the complete intervention domain API. It does not claim the optimistic concurrency, invalidation, signed mixed provenance, durable checkpoint, restart/race, or exactly-once guarantees owned by HITL-003.
  • It does not claim V1 BFF/common-store binding, Lilith override composition, Yemaya emergency takeover, or Studio Authoring composition owned by HITL-004.
  • The live session is an in-process subscription contract, not evidence of an externally deployed SSE/WebSocket route or production traffic.
  • No user-facing UI changed, so Playwright and mobile UI automation are inapplicable to HITL-002. No media/model pipeline or Unreal asset changed.

Publication identity#

  • Complete intervention API source commit: c6d53c2c25170209834d072b520ffbac2411d04b
  • Live observation feed source commit: cfa056db69aea4170c8211f3a23e08956252b0a8
  • Closure evidence commit: 3f21f7e7b183b1bcf209f5aad97aa3f494b18f2a