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-001throughRUN-005,HITL-001throughHITL-005,AUTH-001, andAUTH-002 - Affected routes:
POST /api/agent-runtime/orchestration-runs,GET /api/agent-runtime/orchestration-runs/{run_id}, andPOST /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:
- allocates deterministic source and RUN-001 identities from tenant, actor, build, and idempotency inputs;
- validates the immutable plan and registry snapshot, creates registry-bound node states, and schedules only dependency-reachable nodes;
- persists a model intent before calling the exact registry provider/model/ version/region binding;
- validates model-reported usage, charges the private run budget, and persists the ledger before the first requested tool can dispatch;
- resolves the requested tool against the node's actual registry grants, permission set, tenant isolation boundary, required human gate, and data scopes;
- recursively rejects nested cross-tenant arguments, persists tool intent, dispatches with the stable effect key, and validates tenant-bound effect receipts and write authority;
- writes a content-addressed node output, evidence record, and checkpoint after every successful node; and
- 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-clientNx 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-clientlint and typecheck targets: passing. - Targeted
metis-api-clientand@oshun/contractsproduction 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-001throughV9-005andREL-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