Eve library

AUTH-003 evidence pack — governed V9 agent DAG executor

Evidence

Revision 1

On this page

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