# AUTH-003 evidence pack — governed V9 agent DAG executor

## Work-package charter

- **Task ID:** `AUTH-003`
- **Owner:** Metis agent-runtime and common-run maintainers; implementation
  owner: Codex
- **Accountable product:** V9 Metis agent orchestration runtime
- **Priority:** P0
- **Target milestone:** 2026-07-15 SOTA gap-closure program
- **Risk tier:** Critical model/tool authority, tenant isolation, budget,
  intervention, durability, and publication risk
- **Dependencies:** `RUN-001` through `RUN-005`, `HITL-001` through `HITL-005`,
  `AUTH-001`, and `AUTH-002`
- **Affected routes:** `POST /api/agent-runtime/orchestration-runs`,
  `GET /api/agent-runtime/orchestration-runs/{run_id}`, and
  `POST /api/agent-runtime/orchestration-runs/{run_id}/interventions`
- **Rollback strategy:** Revert the source commit. This introduces additive
  OpenAPI fields/routes and file-backed runtime records without a database
  migration; the pre-existing planning-only route remains separate.
- **Evidence-pack location:** This file

## Separate planning and execution modes

The original deterministic planner remains side-effect free and is now
explicitly labeled `mode: planning_only`. A plan can only enter executable mode
through the new start route with `execution_mode: executable`; the executor
rejects any other mode or a plan outside `planned` state. The execution response
uses its own status, node, invocation, effect, budget, checkpoint, intervention,
and publication records. The common-run planning adapter explicitly reports
planning as unsupported for execution, so a plan cannot satisfy this task by
being relabeled.

Every authority-bearing persisted plan field—including registry identity,
tenant/region, release channel, nodes, edges, evidence declarations, approval
gates, and kill switches—is covered by `plan_hash`. The executor recomputes that
hash before the first invocation and on every continuation, and also verifies
the registry snapshot. The adversarial suite modifies a persisted approval role
without updating the digest and proves execution stops before any provider call
or run allocation.

## Governed DAG execution boundary

`GovernedAgentDagExecutor` is the authoritative V9 executable boundary. It:

1. allocates deterministic source and RUN-001 identities from tenant, actor,
   build, and idempotency inputs;
2. validates the immutable plan and registry snapshot, creates registry-bound
   node states, and schedules only dependency-reachable nodes;
3. persists a model intent before calling the exact registry provider/model/
   version/region binding;
4. validates model-reported usage, charges the private run budget, and persists
   the ledger before the first requested tool can dispatch;
5. resolves the requested tool against the node's actual registry grants,
   permission set, tenant isolation boundary, required human gate, and data
   scopes;
6. recursively rejects nested cross-tenant arguments, persists tool intent,
   dispatches with the stable effect key, and validates tenant-bound effect
   receipts and write authority;
7. writes a content-addressed node output, evidence record, and checkpoint after
   every successful node; and
8. persists publication intent, atomically calls the publication sink once per
   stable key, then records the receipt and terminal success together.

The storage resolver rejects absolute/traversing provider-result references. The
default model and tool adapters fail closed instead of manufacturing output;
deployment composition injects adapters implementing the typed idempotent
boundaries. The default local publication sink uses fsync plus atomic replace.

## Durable idempotency and recovery

Run starts, model invocations, tool calls, interventions, and publication each
have stable idempotency keys. Provider-result receipts are durably written under
the run before invocation/tool success and budget consumption are committed.
After worker loss the scheduler recognizes the persisted `running` attempt,
reuses the same provider key, loads an already-written receipt when present, and
does not allocate another attempt or charge the ledger twice.

The conformance suite injects process death after a model provider accepts its
key, after a tool provider accepts its effect key, and after publication commits
but before its acknowledgement is recorded. Fresh service instances resume the
same records. The resulting run contains one invocation/tool identity per
operation, one charge per successful call, one publication receipt, and no
duplicate provider mutation. Receipt content, reported usage, requested tools,
and effects are checked for idempotency drift.

## Human authority and runtime control

Approval gates stop the scheduler before the gated node. Approvals, pause,
resume, and cancel commands retain actor, normalized role, rationale, gate,
stable key, result status, and timestamp. Role ordering is enforced against the
plan's gate declaration. Only the run owner or an admin/operator may intervene;
this still permits an admin distinct from the instructor owner to authorize
publication. Pause/resume preserves an outstanding human gate instead of
accidentally bypassing or failing it, and cancel is terminal and publication
free.

The end-to-end course-build case runs the real scheduler through model and tool
boundaries, observable effect receipts, per-node evidence/checkpoints, an expert
gate, process restart, a distinct admin publication gate, atomic publication,
and completion. Persisted node records are compared with the live registry to
prove the model, tool, and data-scope bindings were enforced rather than copied
only into a plan.

## Common-run integration

`adaptV9AgentExecutionToCommonRun` is the exact source-to-common-spine adapter
registered as `v9-agent-orchestration-execution`. It validates the Python
OpenAPI field inventory and the source's pre-derived common identity, then maps:

- DAG/node states and dependencies to RUN-001 steps and attempts;
- registry model and authority snapshots to versioned bindings;
- tool requests, grants, invocations, results, and side effects to tool events;
- node outputs, evidence, and checkpoints to lineage-bearing artifacts;
- human commands and approvals to interventions and gate verdicts;
- measured input/output tokens to measurements; and
- publication intent/receipt to the transactional release lifecycle.

It rejects planning records, unknown source fields, identity drift, cross-tenant
or authority-escalating effects, incomplete provider records, ledger/call-count
drift, and a false successful run without complete nodes and publication
receipt. The original planning adapter remains deterministic and explicitly
unsupported as an execution substitute.

## Adversarial and conformance proof

The executor suite proves:

- full governed course execution through expert and admin intervention;
- duplicate start/approval replay without repeated work;
- model and tool crash recovery without duplicate accounting;
- lost publication acknowledgement recovery with one receipt;
- undeclared tool denial;
- nested cross-tenant argument denial;
- cross-tenant effect-receipt denial;
- read-to-write effect escalation denial;
- output-token budget exhaustion before downstream work;
- insufficient publication role denial without state mutation;
- peer-instructor run-control denial;
- pause/resume/cancel behavior around an outstanding gate; and
- persisted plan-authority tamper rejection before execution.

## Automated verification

- Complete Metis agent-runtime/helper/OpenAPI regression after final remote
  integration: **61/61** across **10/10** files.
- Authoritative executable-runtime conformance/adversarial suite: **13/13**.
- Metis planning and execution common-run adapters: **8/8** across **2/2**
  files; complete `metis-api-client` Nx test target passing.
- Shared RUN-001 through RUN-005 protocol regression: **67/67** across **6/6**
  files.
- Strict MyPy on all five changed Metis source modules: zero errors.
- Exact changed-source Ruff lint and formatting: passing.
- Official `metis-api-client` lint and typecheck targets: passing.
- Targeted `metis-api-client` and `@oshun/contracts` production TypeScript
  builds: passing; contracts lint passing.
- Checked-in FastAPI OpenAPI equivalence and route inventory: passing.
- Metis OpenAPI TypeScript generation/drift check: current.
- Exact changed TypeScript Prettier and final diff whitespace checks: passing.

## Artifact identity

| Artifact                                                         | SHA-256                                                            |
| ---------------------------------------------------------------- | ------------------------------------------------------------------ |
| `services/metis/src/metis/services/agent_dag_executor.py`        | `100f48bd9b1c523e702bcac5485e37d45d79767fd0ffe179f0703f4a01eb74ab` |
| `services/metis/src/metis/schemas/agent_runtime.py`              | `d94209440e37c443db349c8aee3cca4cf1b18d7dbdefb8c1def4e6b24870f8b2` |
| `services/metis/src/metis/services/agent_runtime_service.py`     | `c52e1a2aea6e754018c272fbed93f5503c99b5abc5dfe63324e818f679f2ca38` |
| `services/metis/src/metis/api/agent_runtime.py`                  | `fa81fa5d079b22a60f1d5668040384d3988b1fc93aff26bd11154006d5de6342` |
| `services/metis/src/metis/services/agent_runtime_helpers.py`     | `c025eec5de335423acaaa3681f278964986f51ff05f4c1fa1ac6c4c00a8adf5b` |
| `services/metis/tests/test_agent_dag_executor.py`                | `5aedc3a613f4fe70f1d7bbfc4efb1a23182dd12d4dfcf500d71ceb6b526019af` |
| `libs/metis/api-client/src/execution-common-run-adapter.ts`      | `7473e18658b538ca7dac1cb359f9bc4d2673e7ad9cad6c05d16bf2e1f418aa65` |
| `libs/metis/api-client/src/execution-common-run-adapter.test.ts` | `ec5e0a6db1d42c6768e8dcfb839dfeef882acd5e59f8d686e6c98a8055f6344b` |
| `libs/metis/api-client/src/common-run-adapter.ts`                | `6c29a103108992a3cf4ca020d8a5150ecc6f8b33336892f193fbf6bd7a77161c` |
| `libs/contracts/src/run-protocol/adapter-conformance.ts`         | `9e28e5c68a1213efe05a987c2416558e79d1e1780ef03037c03370f1ef5b6e45` |
| `services/metis/openapi/metis.openapi.json`                      | `71209e394697c00bb50e949e931bae288c40a25828f0aa71378a9ea850d5e954` |
| `libs/openapi/src/generated/metis.ts`                            | `bf39ceaebac113274000015ba0ca4b1a5fd51d909a02ae7c407563d5b157dd7f` |

## Resource-safe verification

The host reported 15 GiB RAM, 31 GiB swap, 13 GiB available memory, and 38 GiB
free disk before final targets. All Vitest work used one worker where directly
invoked. Metis tests and the two targeted library builds ran sequentially; no
full-workspace Nx sweep, Next/Expo/Tauri packaging, native release build, or
Unreal build was attempted.

## Scope and negative proof

- AUTH-003 changes backend execution, contracts, and generated API types. It
  does not change rendered customer/admin/PWA/mobile/Unreal UI, so the frontend
  skill and UI/mobile/Unreal automation are inapplicable.
- The production-safe default deliberately fails when no model/tool adapter is
  configured. This pack proves the governed executor and concrete conformance
  adapter boundary; it does not claim a live OpenAI credential, a production
  provider receipt, or a released V9 course. Those product/provider/release
  proofs remain in `V9-001` through `V9-005` and `REL-001`.
- The measured executor ledger covers model/tool units and tokens available at
  this boundary. Full provider price-table, dollar, GPU, storage, and egress
  reconciliation remains `COST-001`/`COST-002`.
- This provides API-driven human gates and controls, not the human-facing
  operator UI required by `HITL-005`/`V9-004`.

## Publication identity

- **Authoritative boundary source commit:**
  `b8107e5841c48b100ceca1f116608d8c39f97ecf`
- **Source publication tip on `origin/main`:**
  `9b4439f77bdafdaf5b82da4139ba69f31901e86d`
- **Closure evidence commit:** `ac77031d3c631c1e1e7bf58792ee45edf9854a35`
