# RUN-004 evidence pack — common-model runtime adapters

## Work-package charter

- **Task ID:** `RUN-004`
- **Owner:** Oshun common run-protocol adapter 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:** Critical semantic-drift, authority-widening, false-success,
  evidence-loss, and premature-envelope-deprecation risk
- **Dependencies:** RUN-001 common aggregate, RUN-002 durable record semantics,
  RUN-003 effect boundary, V1 AgentRun and creative-autonomy records, V8
  StageJournal, V9 Metis orchestration plan, and V6 cognition envelope
- **Affected schemas and runtime:** Portable adapter conformance record and
  snapshot builder; V1, V8, V9, and V6 source-specific adapters; package
  exports, dependency manifests, focused CI gate, and conformance tests
- **Rollout strategy:** Keep every product envelope authoritative. Produce a
  digest-bound common snapshot plus an accounting record that maps every
  declared source field exactly once or names it as unsupported.
- **Rollback strategy:** Revert the common conformance contract, all four source
  adapters, tests, exports, dependency links, CI expansion, audit qualification,
  and ledger closure together. No product store or migration consumes the
  adapters yet, so there is no product-data rollback.
- **Evidence-pack location:** This file

## Shared conformance contract

`RunProtocolAdapterRecord` binds one source identity and canonical source
SHA-256 to one validated RUN-001 snapshot. Its field inventory must cover every
top-level source field. Every inventory path must then appear exactly once in a
semantic mapping or an explicit unsupported-field record. Nested field paths are
supported for source subobjects such as V1 token accounting.

Exact mappings cannot name a normalizer. Normalized and aggregated mappings must
name one. The record builder independently hashes the source and target semantic
projections and refuses publication when the hashes differ. Every mapped target
path must exist in the common snapshot. Unsupported fields carry a reason,
preservation mode, and follow-up task.

Every adapter snapshot contains a designated audit artifact whose content hash
equals the complete canonical source digest. The conformance digest covers the
adapter/schema identity, complete field accounting, semantic mappings,
unsupported declarations, and common run. Schema validation rejects a changed
run, source audit artifact, field accounting, semantic digest, or conformance
digest.

The common snapshot builder derives immutable RUN-001 identity from the source
identity and source digest boundary, constructs legal run and step transition
paths, and validates the result with `RunProtocolV1Schema`. It does not invent
attempts, tool grants, side-effect receipts, or product-store events.

## V1 AgentRun and creative-autonomy mapping

V1 intentionally uses three adapters under one conformance ID because the
canonical AgentRun, creative-director cycle, and review item are independent
source identities. The adapter never fuses an unrelated cycle or review record
into an AgentRun.

- `adaptV1AgentRunToCommonRun` validates the canonical AgentRun schema and
  top-level field inventory. It maps tenant/actor/purpose/risk identity, status,
  plan DAG, intermediate artifacts, evidence verdict, USD-micros and token
  measurements, output release lifecycle, and captured workflow/model/prompt/
  policy bindings.
- Raw inputs, tool calls, structured error, decision rationale, snapshot-only
  start/completion timestamps, parent/replay/successor UUIDs, workspace, tags,
  and free-form metadata remain explicit unsupported fields. In particular,
  legacy tool calls are not relabeled as common tool events because AgentRun
  lacks authoritative resolved-grant and reconciliation records.
- `adaptV1CreativeCycleToCommonRun` maps finished/aborted status, cycle time,
  token usage, production/publication/selection/governor/pruning audit
  artifacts, and complete source identity. Studio spend units remain unsupported
  because no authoritative USD conversion exists; LLM call count remains
  unsupported because the common measurement union has no counter.
- `adaptV1CreativeReviewToCommonRun` maps autonomy and lifecycle status,
  compellingness gate verdict and full gate audit, human/system review actions
  as interventions, creative provenance binding, variant artifact, lifecycle
  metadata audit, and publication release. It preserves the full review history
  and tweak directive digest.

## V8 StageJournal and case-gate mapping

`adaptV8StageJournalToCommonRun` requires one case/seed journal with contiguous
sequence from one, monotonic valid timestamps, non-negative integer attempts and
costs, known event/key/cost fields, and valid lowercase output hashes. It maps
the deterministic seed binding, latest state for every observed stage, stage
output hashes as common artifacts, token measurements, and run/step status
without treating a partial pipeline as success.

The common run succeeds only when publish succeeded and every latest stage is
succeeded, repaired, or skipped. Latest `verify`, `eval`, and `hitl` states
become typed gate verdicts with their output artifact or journal evidence;
failed gates block and escalated gates remain pending. Free-form detail, the
complete attempt timeline, and job-count costs remain explicitly unsupported
pending product-store event consumption and authoritative cost conversion.

## V9 dependency, governance, and agent-plan mapping

`adaptV9AgentPlanToCommonRun` is locked to the checked-in Python service OpenAPI
`AgentOrchestrationPlanResponse` property inventory. It validates source
hash/time identity, unique selected agents, exact selected-agent/DAG agreement,
positive node stages, unique node/edge/evidence/gate IDs, known references,
complete dependency-edge pairs, and an acyclic graph.

The adapter maps the Metis build/tenant/actor/objective identity, planning or
execution status, DAG nodes and dependencies, evidence-ledger artifacts, pending
approval gates, and registry/plan/source/agent version bindings. It normalizes
arbitrary storage locators into stable common references while retaining content
hashes. Event-topic transport configuration, armed kill-switch declarations, and
the replay manifest remain explicit unsupported fields until the product runtime
emits executed events, interventions, and durable checkpoints under RUN-005.

## V6 cognition events and child authority

`adaptV6CognitionRunToCommonRun` validates the AgentRunEnvelope field and usage
inventories, non-negative usage counters and costs, unique allowed tools,
bounded and monotonic event times, and outcome timestamps. Every cognition event
becomes a content-hashed common audit artifact; final text becomes an output
artifact; provider/model and allowed-tool authority become versioned bindings;
tokens, run cost, and reserved child cost become measurements.

A child requires an explicit source-parent/common-parent mapping. Its allowed
tools must be a subset of the parent's tools before adaptation. The common
parent identity, delegated actor evidence, and authority binding are retained; a
missing mapping or widened child authority fails loud. Executing, completed,
killed, quarantined/budget-exceeded, and truncated/failed/max-iteration states
normalize without inventing success. LLM/tool call counts remain explicit
unsupported counter fields.

## Automated scenario matrix

| Scenario                  | Conformance result                                                                                |
| ------------------------- | ------------------------------------------------------------------------------------------------- |
| Complete field accounting | Hidden, missing, duplicate, or unaccounted source fields fail.                                    |
| Semantic equivalence      | Source and target semantic digests must match before record creation.                             |
| Target drift              | A mapping to a nonexistent common path fails.                                                     |
| Source preservation       | Every adapter retains the full source SHA-256 in its designated audit artifact.                   |
| Tamper resistance         | Changed common data, source audit identity, or conformance digest fails validation.               |
| V1 independence           | AgentRun, creative cycle, and review lifecycle receive separate common identities.                |
| V1 review                 | Gate, human approval, provenance, lifecycle audit, and publication release survive normalization. |
| V8 gate evidence          | Latest verify/eval/HITL outcome becomes a typed verdict linked to hash/journal evidence.          |
| V8 false success          | Publish plus complete healthy latest-stage state is required for success.                         |
| V9 schema drift           | OpenAPI response properties must equal the adapter inventory.                                     |
| V9 dependency integrity   | Unknown, unmatched, duplicate, or cyclic DAG relationships fail.                                  |
| V6 child authority        | Missing parent mapping or tool widening fails before a child common run is emitted.               |
| Outcome normalization     | Kill, quarantine, failure, timeout, and truncation never become success.                          |
| Determinism               | Repeated source input yields the same record; semantic source change changes its digests.         |

## Artifact identity

| Artifact                                                       | SHA-256                                                            |
| -------------------------------------------------------------- | ------------------------------------------------------------------ |
| `libs/contracts/src/run-protocol/adapter-conformance.ts`       | `3bb90afb91ce2a38c7e7430c056bb6bc68bc4162b24106f37b0327b86ba0920c` |
| `libs/contracts/src/run-protocol/adapter-conformance.spec.ts`  | `476b5264ede6798b0f76a3f88da2128f162fa648e3252380fbfd54fb8ac2d57b` |
| `libs/oshun/creative-autonomy/src/common-run-adapter.ts`       | `96a2b5667de6773760e00a2646d05c8080cff866bd3530ed93390f6d951149c2` |
| `libs/oshun/creative-autonomy/src/common-run-adapter.test.ts`  | `57c24dc57fe1ae20d832dbe187fe3cd96625f4c81a494b94b6c51946b16a6fda` |
| `libs/yemaya/case-pipeline/src/common-run-adapter.ts`          | `3cf752b6255fc244a4954a01f8c68350fb8e03dcba5b3dfb457357023ce79bb1` |
| `libs/yemaya/case-pipeline/src/common-run-adapter.test.ts`     | `5a321dd25cd4381582494cf3db7f1cf35e4fae5b3bd388107490aea8b00b7a3a` |
| `libs/metis/api-client/src/common-run-adapter.ts`              | `7dc421403efaf011ef753b05afb58b23162e02adb1fd6e17fba24243e55768bc` |
| `libs/metis/api-client/src/common-run-adapter.test.ts`         | `dc3d6b25886a166b1b2d397964ffd6977cdb463ca59840bc7b6229832aa617ec` |
| `libs/iris/agents/core/src/agentic/common-run-adapter.ts`      | `0cb98c262332bb4b63fa84d8e0f30abc66927d90cd9bdc48c0fbeddb8451f4a4` |
| `libs/iris/agents/core/src/agentic/common-run-adapter.test.ts` | `517aa3621073a3522f91fc8d1d6c70a66418406c76894b075b9e4d20bc04e4fd` |
| `package.json`                                                 | `e7d9bf89abf451ac36f88586fc9fff85a578ec3783be856358a4cd60e020898d` |
| `pnpm-lock.yaml`                                               | `627422a4715c85693b8fccf921ee7c615f0f002911f8506758769e5f6bbbc04e` |

## Automated and adversarial verification

- `pnpm run verify:contracts:run-protocol` passes targeted ESLint with zero
  warnings, **49/49** common protocol cases with one worker, and contracts
  source typechecking. RUN-004 contributes four shared conformance cases.
- Focused adapter suites pass **19/19** cases: V1 **5/5**, V8 **4/4**, V9
  **5/5**, and V6 **5/5**. They cover deterministic mapping, source/target
  digests, unsupported accounting, source and OpenAPI drift, invalid hashes,
  broken/cyclic DAGs, false-success outcomes, token dishonesty, time regression,
  parent lineage, and child authority widening.
- Full affected-package regressions pass sequentially with one worker: V1
  creative autonomy **253/253**, V8 case pipeline **26/26**, V9 Metis API client
  **738/738**, and V6 Iris agents core **206/206** (**1,223/1,223** total).
- Production TypeScript checks pass for contracts, V1 creative autonomy, V8 case
  pipeline, V9 API client, and V6 agents core. The V9 package-wide spec
  typecheck still reports pre-existing Vitest mock-generic errors in unrelated
  auth/http/cache/error tests; the new adapter source typecheck and full 738-
  case runtime suite pass.
- Changed production files and the common protocol gate pass ESLint with zero
  warnings. Package-wide lint discovery exposes existing unrelated debt: seven
  V8 non-null warnings; two V6 non-null warnings and two existing module-
  boundary errors; three V9 non-null warnings; and 87 V1 non-null warnings. No
  changed adapter file contributes an error or warning.
- `NX_DAEMON=false pnpm exec nx run @oshun/contracts:build --parallel=1 --outputStyle=static`
  succeeds, and runtime probes confirm the adapter schema through the root flat
  export, `RunProtocolContracts` namespace, and `@oshun/contracts/run-protocol`
  subpath.
- `pnpm install --frozen-lockfile --lockfile-only --offline --ignore-scripts`
  passes after the three local workspace dependency links were recorded.
- The broader gates ran sequentially after the required resource check. The host
  had 15 GiB RAM, 31 GiB swap, about 10 GiB available RAM, and 38 GiB free disk.
  No broad build matrix or parallel package verification was run.

## Deprecation boundary and negative proof

- No existing V1, V8, V9, or V6 envelope is deprecated. The adapters are
  one-way, in-memory conformance functions; product records remain the source of
  truth.
- Several adapters deliberately report unsupported fields. No product store
  writes a common record, no migration or dual-write has run, no product replay
  has compared a migrated record with the source runtime, and no rollback has
  restored a product from common state. The conditional deprecation gate is
  therefore closed.
- Tests and artifact hashes are synthetic repository evidence, not a deployed
  run, production migration, live provider receipt, learner interaction, case
  release, or operational rollback drill.
- RUN-005 owns product consumption, atomic approval/execution lifecycle, and
  replay/rollback integration. Envelope deprecation remains prohibited until
  migration, replay, and rollback evidence passes with no unsupported semantic
  loss.
- No user-facing UI, mobile flow, media/model pipeline, database migration, or
  Unreal asset changed. Playwright/mobile/browser accessibility,
  provider/media/database, and Unreal verification are inapplicable.

## Publication identity

- **Implementation and first remote-integrated tested source commit:**
  `0f68a5e5a6a72cef4f32fbc3e96db8e732c5c00c`
- **Publication metadata commit:** `a70125182c315d6560c9a9fddefa2bb364476f17`
