# AUTH-002 evidence pack — governed V1 executed route

> **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.
