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-001portfolio 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, andPOST /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, andRUN-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:
- refreshes the persisted run so pause/cancel/terminal state is current;
- calls
PortfolioCapabilityBroker.authorizeUsewith exact agent, actor, tenant, run, tool, purpose, resource, action, trust-zone, risk, argument, secret, egress, and sandbox dimensions; - refreshes operator kill switches and admits against private mutable budget meters;
- for network authority, requires the adapter's actual URL, method, and socket address and revalidates them against the broker's SSRF/DNS pin;
- persists a pending call before dispatch;
- 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.