Eve library

AUTH-002 evidence pack — governed V1 executed route

Evidence

Revision 1

On this page

Status: repository-complete / closed. The V1 executed route now resolves server-owned authority at every reached tool boundary, persists attempt/result telemetry and cost before the next admission, refreshes operator and grant state between calls, and fails closed for undeclared or unapproved authority. This closure does not claim that a production broker, provider credential, live billing system, or the separate V9 DAG executor is deployed.

Work-package charter#

  • Task ID: AUTH-002
  • Owner: Agentic Studio and Oshun BFF runtime maintainers; implementation owner: Elikem Agudogo
  • Accountable product: V1 Agentic Studio executed route
  • Priority: P0
  • Target milestone: 2026-07-15 SOTA gap-closure program
  • Risk tier: Critical delegated-tool, tenant-boundary, secret, egress, isolation, budget, and operator-control risk
  • Dependencies: AUTH-001 portfolio capability broker; RUN-001 common run identity/lifecycle; server-owned runtime tool catalogs and policy; durable V1 lifecycle snapshots
  • Affected schemas and content slots: V1 RunInputs, RunToolCallRecord, category budget and cost-ledger maps, capability audit trail, lifecycle snapshot projection, and POST /v1/agentic/runs/execute. No rendered customer content, media artifact, prompt body, or UI content slot changed.
  • Linked task IDs: AUTH-001, AUTH-002, AUTH-003, COST-001, COST-002, RUN-003, and RUN-005
  • Affected route: POST /v1/agentic/runs/execute
  • Rollout strategy: additive strict contracts and lifecycle serialization; bounded low/medium in-process tools receive exact server-created per-run grants, while higher authority stays fail-closed until deployment injects a pre-approved broker.
  • Rollback strategy: Revert the source commit. This adds fields and a new execution boundary without a persistence migration; the lifecycle restore path remains backward-compatible with legacy map/object cost ledgers.
  • Evidence-pack location: This file

One authoritative per-tool boundary#

runGovernedToolPlan is the executed route's boundary. For every reached plan step, in order, it:

  1. refreshes the persisted run so pause/cancel/terminal state is current;
  2. calls PortfolioCapabilityBroker.authorizeUse with exact agent, actor, tenant, run, tool, purpose, resource, action, trust-zone, risk, argument, secret, egress, and sandbox dimensions;
  3. refreshes operator kill switches and admits against private mutable budget meters;
  4. for network authority, requires the adapter's actual URL, method, and socket address and revalidates them against the broker's SSRF/DNS pin;
  5. persists a pending call before dispatch;
  6. dispatches once, records the measured or policy-defined outcome charge, and persists the updated run before another step can be admitted.

The old runGuardedToolPlan/dispatcher remains a lower-level primitive. The V1 route no longer uses it as its execution seam.

Server-owned authority and policy#

Every registered tool must have an AgentToolRuntimePolicy. The request body cannot declare capability dimensions, grant breadth, secret IDs, egress rules, sandbox authority, measured usage, evidence, or effects. Studio and creative generator catalogs now publish policies alongside handlers and kill-switch targets.

Bounded low/medium in-process catalog tools receive exact five-minute per-run grants created from server policy. High/critical authority, operator/two-person approval, capability modifiers, secrets, credentials, egress, or widened sandbox authority fails closed unless the deployment injects a pre-approved portfolio broker. Server budgets are additive and cannot be loosened by a larger request-body cap; the route test proves the server cap still stops the second call.

Pre-dispatch security enforcement#

The AUTH-001 broker runs before the tool receives dispatch authority. The focused adversarial suite proves:

  • token passthrough and missing secret scope are denied before dispatch;
  • filesystem escape is denied by the grant sandbox;
  • integer-encoded loopback is rejected by the SSRF guard;
  • a public but unpinned socket address is rejected as DNS rebinding;
  • a correctly pinned public connection reaches the tool;
  • a network permit without an actual connection-revalidation adapter fails closed.

The complete hash-chained capability trail—including grant request/policy creation and every use, result, denial, revocation, and attempted bypass reached by the run—is retained in capabilityAuditTrail and verified in the route test.

Attempt and result telemetry#

Every reached call becomes a durable RunToolCallRecord. A pending record is written before dispatch and then replaced with ok, partial, error, or denied telemetry. Records retain stage, attempt/retry linkage, redacted arguments, unredacted-argument digest, redacted result or bounded error, denial reason, resolved grant, capability audit IDs, usage, evidence, effects, and emitted artifacts. Tool-produced evidence is also appended to the run's evidence trail. Tools that emit no evidence retain an honest empty list.

The BFF returns the same telemetry-bearing run using an explicit JSON projection for map-backed stage/tool totals. Lifecycle snapshots serialize those maps as entry arrays and restore legacy maps, arrays, or records. Snapshot writes are serialized so a pending state cannot overwrite a later completed state; a failed write does not poison later save attempts.

Actual budget and ledger ordering#

Success, partial, thrown/retry, and denied attempts use measured usage or the server policy's failed/denied charge. Before the loop can reach the next admission, that usage:

  • consumes every matching budget category (cost-units, input/output tokens, GPU minutes, voice/avatar seconds, retrievals, external calls, and storage bytes);
  • updates total cost, per-stage totals, per-tool totals, and every durable category counter; and
  • is persisted with the attempt.

The stale-balance tests use two 10-unit calls under a 15-unit cap. The first call executes and consumes 10. The second admission sees that consumption, does not dispatch, records its one-unit denial policy charge, and ends with 11 units in both the meter and ledger. No API exposes the original meter for reuse.

Live control and concurrency behavior#

Pause, cancel, terminal state, current kill switches, and grants are refreshed at every boundary. Tests change pause/cancel state or revoke/expire a grant after the first dispatch and prove the second tool cannot run. An active run ID cannot be dispatched concurrently, and another user's run ID remains an ownership conflict. If control state changes during a call, terminal local failure cannot be overwritten by an older persisted running snapshot.

Automated verification#

Current admitted refresh#

The current refresh ran against repository commit 24ae90ca8d896c5e1829c19f654c6fabb02979b0 with lockfile SHA-256 08b055786e9b8a6104d5313601d7eef3205dedcf395066fd9a8264c9859d690f on host app-dev-server, Ubuntu 24.04.4 LTS, Linux 6.8.0-134-generic x86_64. The relevant toolchain was Node.js v24.15.0, pnpm 10.25.0, TypeScript 6.0.3, Vitest 4.1.7, and esbuild 0.28.0.

No customer data, production secret, live provider, external egress target, or deployed capability broker was used. The tests use deterministic in-process tools and local lifecycle stores. They prove repository authority ordering and durability, not production provider execution.

UTC interval Exit Exact command and result
2026-07-29T12:18:42.324Z–2026-07-29T12:18:43.272Z 0 pnpm exec vitest run --config libs/oshun/agentic-studio/vitest.config.ts libs/oshun/agentic-studio/src/runs/governed-orchestrator.test.ts --maxWorkers=1 — authoritative boundary and adversarial authority ordering passed 7/7
2026-07-29T12:18:49.578Z–2026-07-29T12:19:03.545Z 0 pnpm exec vitest run --config apps/oshun/bff/vitest.config.ts apps/oshun/bff/src/agentic/runs-route.test.ts apps/oshun/bff/src/agentic/run-lifecycle-store.test.ts apps/oshun/bff/src/agentic/studio-tool-catalog.test.ts apps/oshun/bff/src/agentic/creative-generator-tools.test.ts apps/oshun/bff/src/agentic/agentic-governance-gate.test.ts --maxWorkers=1 — 53/53
2026-07-29T12:19:11.232Z–2026-07-29T12:19:11.632Z 0 pnpm verify:audit:machine-adjacent-docs — contract tests passed 3/3 and the source/comment/schema/umbrella drift verifier passed
2026-07-29T12:19:21.030Z–2026-07-29T12:19:51.315Z 0 pnpm exec tsc -p libs/oshun/agentic-studio/tsconfig.lib.json --noEmit followed by pnpm exec tsc -p libs/oshun/agentic-studio/tsconfig.spec.json --noEmit — both owning source/spec configurations passed
2026-07-29T12:20:06.922Z–2026-07-29T12:21:23.709Z 0 NODE_OPTIONS=--max-old-space-size=8192 node tools/typecheck/ratchet.mjs --app apps/oshun/bff --tsconfig tsconfig.typecheck.json — no new app-owned errors and 0 known backlog

The admitted current AUTH-specific value suites therefore passed 63/63 assertions across seven files, both Agentic Studio typechecks, the BFF's official app-owned typecheck ratchet, and the machine-adjacent drift verifier. The route suite covers grant refresh, pause/cancel and kill-switch refresh, budget reuse prevention, pending-before-dispatch persistence, retry and denied charges, ownership conflicts, secret and sandbox denial, encoded-loopback and DNS-pin enforcement, redaction, audit-chain linkage, and exact returned telemetry.

Refresh-discovered regression and remediation#

The first current BFF ratchet run, from 2026-07-29T12:05:06.949Z through 2026-07-29T12:06:34.257Z, correctly exited 1 with five new app-owned errors. The errors were an unused test helper, omission of V10 from the autonomous-content product contract, a sync-only drill-fixture type for an async implementation, two obsolete synthetic service roles, and lost contextual typing in a content-graph fixture. No ratchet baseline was widened.

Commit 24ae90ca8d896c5e1829c19f654c6fabb02979b0 corrected those defects and added an exact V1–V10 contract assertion. The affected contract suite passed 7/7; the four affected BFF files passed 26/26; exact changed-file ESLint passed with zero warnings; Prettier and git diff --check passed; the contracts production typecheck and uncached targeted build passed; and a Node 22 ESM BFF production esbuild bundle passed. The official ratchet then passed before publication and again from the exact published commit in the table above. This refresh therefore records the initially red gate and its verified source correction instead of suppressing or relabeling the failure.

Historical implementation verification#

The source-publication record reports the full Agentic Studio regression at 330/330 across 23 files, the then-current focused BFF set at 50/50 across five files, and V1 lifecycle/autonomy at 16/16 across two files. It also records passing Agentic Studio production build, BFF production esbuild bundle, exact changed-source lint, formatting, and whitespace checks. Those historical counts are retained as source-publication provenance; they are not presented as reruns from the current commit.

The BFF's dependency-aware Nx build expands into a large target graph. Under the repository small-host gate, the refresh used the official focused typecheck ratchet and the configured production bundler rather than starting a broad Nx matrix while another checkout's long-running Vitest worker was active.

Artifact identity#

Artifact SHA-256
libs/oshun/agentic-studio/src/runs/governed-orchestrator.ts f567f19e686e8b579f5d8642d09c0353a10741575af6ba12491d9e438216c56c
libs/oshun/agentic-studio/src/runs/governed-orchestrator.test.ts 973580bee6a8e89b86f370e8ee42f3bfa1be3f9bd1de8aedc2b8f60a0b2969e0
apps/oshun/bff/src/agentic/runs-route.ts 5683995ae3154ab03b0c68efdda36f4d09440b085edbd7f972089acf088ab9f6
apps/oshun/bff/src/agentic/runs-route.test.ts 7d345529572705e3d6336a449d386e3555dea119d5efcd76d77f00d5cf569331
apps/oshun/bff/src/agentic/run-lifecycle-store.ts 704b11e12261a4c6d08dd8a4deb94f010234060542244a42a4d3036d501a3f77
libs/oshun/agentic-studio/src/runs/agent-run.ts e5f1318b9dacee1b9fd98f388d06f3b9022ed5976601e32c8fd618df8dc0a600
scripts/audit/machine-adjacent-doc-contract.json 4cce745e9979b24c962bdae3f2c013f2d29f586bc749a4fd6d9e8f040bd5da5e

Resource-safe verification#

The refresh host reported 15 GiB RAM, 31 GiB swap, 12 GiB initially available memory, and 16 GiB free disk. Vitest used one worker. An unrelated checkout's long-running Vitest worker and this checkout's Nx daemon were active, so no full-workspace or broad dependency matrix was started. The BFF ratchet ran alone with its declared 8 GiB ceiling and was polled at intervals below 30 seconds; available memory remained at least 5.6 GiB, above the 2 GiB stop threshold. No Next, Expo, Tauri, native release, Unreal, or UI build was attempted.

Human authority and external deployment boundary#

Repository publication of this contract and evidence pack does not itself require a human signature, and no approval was fabricated. At runtime, low/medium in-process tools can receive the exact short-lived server grant described above. High/critical tools, operator-approval or two-person capabilities, secrets, credentials, egress, or widened sandbox authority require a deployment-injected, pre-approved broker and corresponding human authority. In the absence of that authority, execution fails closed before dispatch.

Production broker configuration, durable external grant state, provider credentials, secret-manager bindings, egress adapters with connection revalidation, and live billing reconciliation remain deployment/operations inputs. AUTH-003 remains the owner for the separate governed V9 DAG, checkpoint, and publication executor. COST-001 and COST-002 remain the owners for complete provider and monetary reconciliation.

Scope and negative proof#

  • AUTH-002 changes backend runtime, policy, durability, and machine-adjacent documentation. It does not change rendered customer/admin/PWA/mobile/Unreal UI, so the frontend skill and UI/mobile/Unreal automation are inapplicable.
  • This closes the sequential V1 executed route. It does not claim to implement the V9 DAG/model/checkpoint/publication executor; that remains AUTH-003.
  • This meters declared usage and binds injected authoritative budgets. Complete live monetary/provider billing reconciliation remains COST-001/COST-002.
  • Generated green status is not hand-edited. The machine-adjacent verifier derives its result from the versioned contract, real-path source assertions, enforcement comments, schemas, and umbrella documentation.
  • Current drift after the source-publication commit is disclosed through the current hashes and current verification-source identity above.

Publication identity#

  • Authoritative boundary source commit: e659629be3beab421e254a6082171410393547b1
  • Historical source publication tip on origin/main: 798d0065063bb56f550e149ac0a5fc59e513be56
  • Historical closure evidence commit: 4bb405a66c8298a2a9fa1522188cd8ba841d1385
  • Current admitted verification source and remediation commit: 24ae90ca8d896c5e1829c19f654c6fabb02979b0
  • Current evidence-refresh commit: recorded by the task-scoped commit that contains this file.