@nullsquare/agent-authority 0.4.5 → 0.4.7

package/ROADMAP.md

@@ -1,26 +1,79 @@
 # Agent Authority Roadmap
 
-Agent Authority is implementation-first. We are not trying to invent a new authentication protocol or policy language.
+Agent Authority is implementation-first, but the current bottleneck is now **product proof**, not another authorization subsystem.
 
-The product thesis we are validating is:
+The product thesis is:
 
 > **Give an agent a task, not standing account permissions.**
 
-A human-approved task becomes temporary execution authority. As the agent discovers concrete resources through authorized work, authority may follow those resources through provenance-bound facts, but it may never silently broaden.
+The differentiated mechanism is:
 
-## Current invariant
+> **Authority may follow exact resources discovered through already-authorized execution, without becoming ambient account authority.**
+
+## Core invariant
 
 ```text
 Task Lease authority <= Mission authority
 ```
 
-Across delegation and integrations:
+Across delegation, transports and durable state:
 
 ```text
 authority may stay the same or shrink
 never silently grow
 ```
 
+## P0 — Task-first product proof — current priority
+
+The engine has enough depth to test whether developers actually want this layer. Product work now outranks additional distributed/crypto infrastructure unless a real workflow proves the missing infrastructure is blocking adoption or safety.
+
+- [x] task-first facade over Mission + Task Lease + Guard
+- [x] explicit service permissions without requiring hand-authored Mission JSON
+- [x] named task authority roots
+- [x] `task.run()` guarded effect boundary
+- [x] `task.authorityFrom()` strict evidence-derived authority
+- [x] task-first binding of named authority to later effects
+- [x] human-readable authority-delta explanation
+- [x] same task-first calls can opt into durable local state by adding a store
+- [x] self-contained GitHub-shaped task-first demo
+- [x] deterministic utility regression benchmark
+- [x] first live provider proof through task-first API: GitHub issue discovery -> exact issue comment
+- [x] self-contained support/communications proof: Gmail thread -> exact Calendar attendee
+- [x] self-contained operations/finance proof: ticket -> order -> payment -> exact full refund
+- [x] automated blank-project quickstart against the current published npm package
+- [x] blank-project real-provider quickstart: broad standing `repo.read` -> one task-authorized public GitHub repository
+- [ ] coding workflow: issue -> branch -> files -> PR, with merge/deploy outside authority
+- [ ] support/communications expansion: customer -> meeting + reply/CRM, or live task-first Google Actions proof
+- [ ] bounded finance refund: derived payment amount can authorize a smaller refund without authorizing an over-refund
+- [ ] first-time developer can complete a meaningful integration in under 10 minutes
+- [ ] at least one external developer adopts the package without project-author assistance
+
+The live GitHub task-first proof selected issue #9 through the reviewed provider mapping, established that issue through `task.authorityFrom()`, executed exactly one real comment mutation, blocked unrelated issue #1 with `authority_delta_required`, surfaced the established-vs-requested explanation, denied the same issue after task completion, and observed `reads=1` / `task_mutations=1` before cleanup.
+
+The support/communications proof uses the same task-first API across Gmail and Calendar: one authorized `thread_id` establishes one canonical `sender_email` through the reviewed Google extractor; only that attendee can be used for the task-bound Calendar event, while another thread or attendee executes zero provider-shaped callbacks. The example mirrors the real Google adapter contract but does not replace the still-open public Google Actions evidence gate.
+
+The operations/finance proof keeps one evidence-derived chain from support ticket -> order -> payment -> exact refund. The exact payment ID, amount in minor units, and currency are all bound before the refund callback can execute. Unrelated payment, over-refund, wrong currency, partial refund under the current equality model, and post-completion refund all execute zero additional refund callbacks. This proof exposed a deliberate product gap: current bindings are exact equality, so a legitimate partial refund also steps up. Do not add a general expression language; add a narrow derived numeric ceiling only when real workflow/adoption evidence shows partial refunds are required.
+
+The fixture fresh-install quickstart is independently exercised from a blank Node 20 project against the latest public npm package. The passing proof installed `@nullsquare/agent-authority@0.4.6`, did not install the optional AI SDK, allowed the exact issue #42 effect, stepped up unrelated issue #7, and observed no unrelated callback. This is automated compatibility evidence, not a substitute for the still-open first-time-human under-10-minute test.
+
+The live fresh-install quickstart goes one step further from another blank Node 20 project: Mission-level `github:repo.read` remains broader than the task, Task authority binds that action to `Null-Square/agent-authority`, one real public GitHub API call succeeds, and `octocat/Hello-World` produces `authority_delta_required` before a second `fetch()` can run. No credential is required for the default public-repository path. Authenticated/private-repository onboarding remains separate follow-on work.
+
+Current utility regression metrics:
+
+```text
+normal task completion rate
+false approval rate
+true authority-delta step-up rate
+unauthorized effect rate
+provider effects per completed task
+```
+
+The deterministic fixture target is 100% normal completion, 0% false approvals, 100% true-delta step-up and 0% unauthorized effects. It is a regression fixture, not a real-world benchmark.
+
+See `docs/product-proof.md`.
+
+**Product gate:** do not prioritize deeper distributed persistence, provider-attestation protocols, new token formats, broad OAuth platform work, A2A, a policy DSL, another MCP control plane, or connector-count expansion until the product proof moves or a concrete workflow shows one of those items is necessary.
+
 ## M0 — Enforcement foundation — complete
 
 - [x] mission validation
@@ -31,7 +84,7 @@ never silently grow
 - [x] delegation attenuation
 - [x] mission revocation
 - [x] action receipts and request hashes
-- [x] protocol-neutral `guard.run()` enforcement
+- [x] protocol-neutral guard enforcement
 - [x] one-time approvals
 - [x] mutation idempotency
 - [x] short-lived local agent-instance auth
@@ -41,143 +94,130 @@ never silently grow
 - [x] harness-managed connector grant proof
 - [x] Node 20/22 CI, coverage, package checks and CodeQL
 
-## M1 — Task Lease / derived-authority proof — current
+## M1 — Task Lease / derived-authority proof — implementation established
 
-- [x] Task Lease object around an existing mission
+- [x] Task Lease around an existing Mission
 - [x] explicit authority roots
-- [x] derived facts anchored to same-mission `ALLOW` receipts
+- [x] derived facts anchored to same-Mission ALLOW receipts
 - [x] parent-fact lineage
 - [x] exact context-field bindings
 - [x] unresolved facts fail closed
-- [x] resource mismatch becomes an authority-delta step-up signal
-- [x] explicit mission deny remains the ceiling
+- [x] resource mismatch becomes an authority-delta step-up
+- [x] explicit Mission deny remains the ceiling
 - [x] task completion immediately removes authority
-- [x] independent task-lease expiry
-- [x] task-lease ID/hash in receipts
-- [x] self-contained cross-system demo: Gmail-thread fact -> Calendar attendee
-- [x] reusable Google REST adapter for Gmail thread reads and Calendar event mutations
-- [x] adversarial Gmail -> Calendar test proving unrelated and post-completion effects never invoke provider callbacks
-- [x] real connected-account smoke: Gmail self-test fixture -> exact attendee -> temporary Calendar event -> cleanup
-- [ ] rerun the same proof as a public GitHub Actions job after repository Google OAuth secrets are configured
+- [x] independent Task Lease expiry
+- [x] Task Lease ID/hash in receipts
+- [x] self-contained Gmail-thread -> Calendar-attendee demo
+- [x] reusable Google Gmail/Calendar adapter
+- [x] adversarial Gmail -> Calendar zero-provider-call tests
+- [x] connected-account Gmail -> Calendar smoke proof
+- [ ] public GitHub Actions Gmail -> Calendar proof after repository OAuth secrets are configured
 
-**Success criterion:** a real multi-step agent workflow discovers a resource during an authorized read and can use exactly that resource in a later side effect, while an unrelated resource is technically blocked without requiring approval for every normal task step.
+**Success criterion:** an authorized read can establish exactly one later resource as task authority while an unrelated resource is technically blocked without requiring approval for every normal task step.
 
-The core cross-provider behavior is now implemented and exercised against connected Gmail and Calendar accounts. Public Actions reproducibility remains the final M1 evidence gate because GitHub cannot reuse an interactive ChatGPT connector credential; the manual workflow is committed and expects a refresh token stored only as repository secrets.
+The implementation criterion is met. Public Actions reproducibility remains a separate evidence gate because the interactive Google connector credential cannot be reused as repository secrets.
 
-## M2 — Durable task execution — durable session established
-
-Build only what the real Task Lease workflows prove necessary.
+## M2 — Durable task execution — local durable session established
 
 - [x] authenticated local Task Lease persistence/recovery
+- [x] exact Mission-hash binding on recovery
 - [x] atomic authenticated fact/binding/status transaction primitive
-- [x] stale-writer compare-and-swap protection for independent recovered worker views
-- [x] local per-lease transaction lock that fails closed on overlap
-- [x] ordinary running Task Lease mutations can use the durable transaction boundary through `DurableTaskLeaseSession`
-- [x] security-critical session evaluation refreshes current durable state before the next authority decision
-- [ ] approved authority delta can safely attenuate/update a live lease
-- [x] completion state survives process restart
-- [ ] durable lineage query: why was this exact action authorized?
-- [ ] multi-process stress/recovery tests for multiple agent workers operating under one lease
-- [ ] crash-safe coupling between remote provider side effects, receipts and durable Task Lease state
-
-`JsonFileTaskLeaseStore` writes the complete lease snapshot atomically and authenticates it with a purpose-derived HMAC key from the local Agent Authority master key. Recovery verifies the envelope before authority hydration, binds the snapshot to the exact mission hash, validates status/timestamps and the authority-fact DAG, restores evidence-derived provenance hashes, and verifies the reconstructed Task Lease hash.
-
-`JsonFileTaskLeaseStore.transact()` is the local durable mutation boundary: acquire one per-lease filesystem lock, reload authenticated current state, compare an optional expected lease hash, apply one synchronous Task Lease mutation, validate the complete authority graph, and atomically replace the authenticated snapshot. Stale writers receive `task_lease_state_conflict`; overlapping local transactions receive `task_lease_state_locked`.
-
-`DurableTaskLeaseSession` is the normal mutation facade over that primitive. `addRoot()`, legacy `derive()`, strict `deriveFromEvidence()`, `bind()` and `complete()` commit through compare-and-swap and update the session only after durable success. The session exposes detached mission/snapshot/fact views rather than its mutable internal Task Lease. It never auto-replays a stale semantic mutation after a conflict.
+- [x] stale-writer compare-and-swap protection
+- [x] local per-lease transaction lock
+- [x] mission-alias hardening inside transactions
+- [x] automatic durable Task Lease session
+- [x] security-critical session refresh before authority evaluation
+- [x] durable completion/expiry across restart
+- [ ] approved authority delta safely updates a live durable task
+- [ ] durable lineage query for one exact authorization decision
+- [ ] stronger multi-process stress/recovery tooling
+- [ ] crash-safe remote-effect/receipt/state coupling
 
-The session also implements the Task Lease `evaluate(runtime, request)` shape used by guard/MCP/broker paths. Evaluation refreshes authenticated durable state first, so another worker's already-committed completion or narrowing is observed before the next decision. Tests also prove that execution evidence captured at H0 cannot be automatically converted into a derived fact after another worker commits H1; derivation fails on CAS and requires explicit reconsideration.
+The existing local durability layer is sufficient for product proof. The unchecked items remain research/follow-on work unless a real workflow demonstrates that they block useful adoption or safety.
 
-This does **not** yet turn a remote provider side effect and a local Task Lease transition into one distributed transaction. A different worker can still change durable state after an ALLOW decision and before an asynchronous provider effect begins. That TOCTOU/effect-coupling problem remains explicit follow-on M2 work rather than being hidden behind the local filesystem lock. See `docs/durable-task-leases.md`.
-
-**Success criterion:** a Task Lease survives restart without gaining authority or losing provenance, cooperating local workers cannot silently overwrite newer authority, and ordinary durable mutations use the CAS boundary by default through the session API. Authenticated recovery, local transactions and the durable session are now demonstrated; approved deltas, stronger multi-process stress and remote-effect coupling remain open.
+**Success criterion:** restart and cooperating local workers do not expand authority or silently overwrite newer task state. This is established for the reference local backend.
 
 ## M3 — Trustworthy derived facts — two-provider proof established
 
-The first real Gmail -> Calendar integration showed that recording a host-supplied value plus selector was too weak for the strongest derived-authority claim. The compatibility `derive()` path remains host-trusted; new provider work should prefer execution-bound evidence and reviewed adapter extractors.
-
-- [x] define a small trusted-adapter extractor contract for authority-relevant normalized provider fields
-- [x] bind successful guarded outputs to the exact ALLOW receipt, request and output hash
-- [x] add `TaskLease.deriveFromEvidence()` so the caller cannot provide the authority value
-- [x] migrate Gmail sender -> Calendar attendee derivation to the evidence-verified path
-- [x] migrate the real GitHub issue discovery -> comment mutation proof to the same evidence-verified path
-- [x] adversarial tests for value substitution, output/evidence tampering, receipt replay, cross-lease reuse, wrong-operation extraction and dangerous selectors
-- [x] shared conformance fixtures for reviewed operation -> authority-field mappings across Google and GitHub
-- [ ] define provider/result attestation stronger than a trusted host output hash where practical
-- [ ] define freshness/invalidation rules when a source resource changes
+- [x] reviewed adapter extractor contract
+- [x] successful guarded output bound to exact ALLOW receipt/request/output hash
+- [x] strict `deriveFromEvidence()` where caller cannot provide the authority value
+- [x] Gmail sender -> Calendar attendee strict derivation
+- [x] GitHub issue discovery -> comment strict derivation
+- [x] substitution/tamper/replay/cross-lease/wrong-operation/dangerous-selector tests
+- [x] shared Google/GitHub authority-extractor conformance fixtures
+- [ ] stronger provider/result attestation where a real provider makes it practical
+- [ ] source freshness/invalidation semantics where a real workflow requires it
 
-The shared contract is documented in `docs/authority-extractor-conformance.md`. Google and GitHub now use the same `guard.run()` -> execution evidence -> reviewed extractor -> `deriveFromEvidence()` primitive, and the same conformance suite attacks both mappings.
+Do **not** build a general semantic policy language around this primitive.
 
-Do **not** build a general semantic policy language unless real integrations require it.
-
-**Success criterion:** provider-derived authority cannot be established through the strict path unless the exact guarded output, ALLOW receipt and reviewed extractor contract agree on the selected value. This behavior is now exercised across two provider mappings. Stronger provider attestation and source invalidation remain separate follow-on problems.
+**Success criterion:** strict provider-derived authority requires agreement between the exact guarded output, ALLOW receipt and reviewed extractor. This is demonstrated across Google and GitHub.
 
 ## M4 — Same task, multiple transports — complete
 
-Prove Agent Authority is not an MCP product or SDK wrapper.
-
-- [x] same Task Lease through ordinary `guard.run()` SDK call
+- [x] same Task Lease through direct guard/SDK execution
 - [x] same Task Lease through MCP gateway
 - [x] same Task Lease through brokered provider execution
-- [x] at least one harness/tool-middleware integration whose configured executable tool path cannot bypass the Task Lease
-- [x] interoperability test vectors across transports
+- [x] real Vercel AI SDK protected-tool path
+- [x] interoperability/adversarial vectors across transports
 
-`test/transport-invariance.test.js` establishes one `execution-evidence-v1` derived fact from brokered execution, then reuses that exact Task Lease and fact through direct SDK, MCP and brokered execution. The three paths produce the same `allow`, `authority_delta_required` and `task_lease_completed` outcomes, and blocked attempts execute zero host callbacks, MCP upstream calls or brokered provider operations.
+Changing transport or configured harness execution path does not expand task authority in the demonstrated paths.
 
-`test/integrations/ai-sdk.integration.mjs` drives the real Vercel AI SDK `ToolLoopAgent` through the protected tool set. An authorized task-bound tool executes once; an unrelated resource, an executable tool with no Agent Authority mapping, and a completed Task Lease are surfaced by the harness as `tool-error` results while the underlying side-effect counters remain zero. This proves the configured AI SDK tool execution path cannot silently bypass the Task Lease.
+## M5 — Adoption UX — follows product proof, not infrastructure breadth
 
-The harness claim is intentionally bounded: a malicious host that deliberately gives the model a separate unguarded executable channel remains outside Agent Authority's enforcement boundary.
+Prioritize only the UX needed by successful P0 workflows.
 
-Brokered Task Lease execution deliberately does not consume mission-level one-time approval to override a lease-level authority delta. Updating a live Task Lease after explicit approval remains separate M2 work.
-
-**Success criterion:** changing transport or the configured harness execution path does not expand the task's authority. This is now demonstrated across direct SDK, MCP, brokered execution and the Vercel AI SDK `ToolLoopAgent` protected-tool path.
-
-## M5 — Production credential and approval UX
-
-Only after the task-bound enforcement model is validated.
-
-- [ ] GitHub browser/App onboarding instead of token-stdin
-- [ ] reusable OAuth/OIDC connection engine
-- [ ] OS keychain / KMS-backed secret backend
-- [ ] automatic short-lived agent session bootstrap
+- [x] credential-free fresh-install quickstart validated against the current public npm package
+- [x] one low-friction real provider onboarding path: public GitHub read from a blank npm project
+- [ ] authenticated/private-provider onboarding path
 - [ ] compact approval UI showing the exact authority delta
-- [ ] signed receipt experiment
+- [ ] automatic short-lived agent session bootstrap where needed
+- [ ] framework integration starter focused on task-first API
+- [ ] external-developer quickstart feedback loop
 
-**Success criterion:** an external developer can install Agent Authority, connect one real provider, authorize one task, and complete it without exposing a long-lived credential to the model.
+Items such as reusable OAuth/OIDC engines, KMS backends and signed-receipt experiments remain optional until product usage justifies them.
 
-## M6 — Ecosystem and contribution layer
+**Success criterion:** an external developer can install Agent Authority, connect one real provider, authorize one meaningful task and complete it without exposing a long-lived credential to the model or learning the internal authority machinery first.
 
-- [ ] adapter/conformance starter template
-- [ ] framework integration examples
-- [ ] `good first issue` tasks based on real mappings/tests
-- [ ] independent contributor implementation of one adapter
-- [x] release packaging and npm publication
-- [ ] documentation site only when README/docs become too large
+## M6 — Ecosystem only after repeatable adoption
 
-## M7 — Standards interoperability
+- [ ] adapter/conformance starter template
+- [ ] framework examples driven by real user requests
+- [ ] good-first-issue tasks based on proven workflows
+- [ ] independent contributor implementation of one mapping/adapter
+- [x] npm release packaging and registry verification
+- [ ] documentation site only when the current README/docs become genuinely limiting
 
-Only after operational evidence.
+## M7 — Standards interoperability only after operational evidence
 
 - [ ] map Task Lease concepts to emerging task/intent authorization work
 - [ ] accept external authorization envelopes where useful
 - [ ] avoid creating a competing identity/token standard
-- [ ] publish stable test vectors for non-amplification and authority lineage
-- [ ] evaluate an appropriate standards venue only if multiple independent implementations exist
-
-## What we are not prioritizing
-
-- another agent harness
-- a new OAuth replacement
-- an MCP replacement
-- a giant connector marketplace
-- a proprietary universal policy DSL
-- a dashboard-first enterprise product
-- A2A support before task-bound tool execution is validated
+- [ ] publish stable non-amplification/authority-lineage test vectors
+- [ ] evaluate standards participation only after independent implementations/users exist
+
+## Freeze list
+
+Unless a real workflow proves one is necessary now:
+
+- distributed Task Lease databases
+- generic storage abstraction layers
+- provider-signed attestation protocol design
+- new token or identity formats
+- a general delegation protocol
+- proprietary universal policy DSL
+- broad OAuth platform work
+- another MCP control plane
+- A2A protocol implementation
+- connector-count expansion for its own sake
+- full distributed transactions across arbitrary remote providers
+- dashboard-first enterprise product work
 
 ## Research questions
 
-1. What provider-side or transport-side evidence can strengthen output integrity without turning Agent Authority into an attestation protocol?
-2. How should an approved authority delta update a running task without opening a broader wildcard permission?
-3. How should source-data changes invalidate downstream derived authority?
-4. What provider/tool metadata is required to map operations to resource context reliably?
-5. How should a local ALLOW decision be coupled to an asynchronous remote effect without holding a filesystem lease lock across network I/O?
+1. Can a first-time developer understand and integrate the task-first model in under 10 minutes?
+2. Which real workflows benefit enough from derived authority that an `if` statement is no longer sufficient?
+3. Where does Agent Authority create unnecessary approval friction or reduce useful task completion?
+4. How should an explicitly approved authority delta update a running task without opening wildcard authority?
+5. Which source-data changes actually require downstream authority invalidation in real workflows?
+6. What remote-effect coupling is necessary in practice, and which providers already offer idempotency/transaction primitives we can reuse instead of inventing our own protocol?

package/benchmarks/task-utility.mjs

@@ -0,0 +1,130 @@
+import { createTask } from '../src/task.js';
+import { AuthorityApprovalRequiredError } from '../src/guard.js';
+
+const NORMAL_TASKS = 40;
+const DELTA_ATTACKS = 10;
+
+function selectedItemExtractor({ receipt, output } = {}) {
+  if (receipt?.service !== 'demo' || receipt?.action !== 'item.discover') {
+    const error = new Error('wrong operation');
+    error.code = 'trusted_extractor_operation_mismatch';
+    throw error;
+  }
+  if (typeof output?.selected_item !== 'string') {
+    const error = new Error('invalid selected item');
+    error.code = 'trusted_extractor_output_invalid';
+    throw error;
+  }
+  return { extractor_id: 'benchmark.selected-item.v1', selector: 'output.selected_item' };
+}
+
+function newTask(index) {
+  const catalog = `catalog:${index}`;
+  return {
+    catalog,
+    task: createTask({
+      principal: 'user:benchmark',
+      agent: 'agent:benchmark',
+      request: `Discover and update the selected item for benchmark task ${index}`,
+      permissions: {
+        demo: {
+          allow: ['item.discover', 'item.update'],
+          deny: ['item.delete'],
+          constraints: { catalog: [catalog] }
+        }
+      },
+      authority: {
+        catalog: { kind: 'demo.catalog', value: catalog }
+      },
+      bindings: [
+        { service: 'demo', action: 'item.discover', field: 'catalog', authority: 'catalog' },
+        { service: 'demo', action: 'item.update', field: 'catalog', authority: 'catalog' }
+      ]
+    })
+  };
+}
+
+const metrics = {
+  normal_tasks: NORMAL_TASKS,
+  completed_normal_tasks: 0,
+  normal_approval_interruptions: 0,
+  delta_attacks: DELTA_ATTACKS,
+  delta_step_ups: 0,
+  unauthorized_effects: 0,
+  provider_effects: 0
+};
+
+for (let index = 0; index < NORMAL_TASKS; index += 1) {
+  const { task, catalog } = newTask(index);
+  const item = `item:${index}`;
+
+  const discovery = await task.run({
+    service: 'demo',
+    action: 'item.discover',
+    context: { catalog }
+  }, async () => {
+    metrics.provider_effects += 1;
+    return { selected_item: item };
+  });
+
+  task.authorityFrom(discovery, {
+    name: 'item',
+    kind: 'demo.item',
+    from: 'catalog',
+    extractor: selectedItemExtractor
+  });
+  task.bind({ service: 'demo', action: 'item.update', field: 'item', authority: 'item' });
+
+  try {
+    await task.run({
+      service: 'demo',
+      action: 'item.update',
+      context: { catalog, item }
+    }, async () => {
+      metrics.provider_effects += 1;
+      return { updated: item };
+    });
+    metrics.completed_normal_tasks += 1;
+  } catch (error) {
+    if (error instanceof AuthorityApprovalRequiredError) metrics.normal_approval_interruptions += 1;
+    else throw error;
+  }
+
+  if (index < DELTA_ATTACKS) {
+    try {
+      await task.run({
+        service: 'demo',
+        action: 'item.update',
+        context: { catalog, item: `unrelated:${index}` }
+      }, async () => {
+        metrics.provider_effects += 1;
+        metrics.unauthorized_effects += 1;
+        return { updated: `unrelated:${index}` };
+      });
+    } catch (error) {
+      if (error instanceof AuthorityApprovalRequiredError && error.code === 'authority_delta_required') {
+        metrics.delta_step_ups += 1;
+      } else {
+        throw error;
+      }
+    }
+  }
+}
+
+const percent = (numerator, denominator) => denominator === 0 ? 0 : (numerator / denominator) * 100;
+const report = {
+  ...metrics,
+  normal_task_completion_rate: percent(metrics.completed_normal_tasks, metrics.normal_tasks),
+  false_approval_rate: percent(metrics.normal_approval_interruptions, metrics.normal_tasks),
+  delta_step_up_rate: percent(metrics.delta_step_ups, metrics.delta_attacks),
+  unauthorized_effect_rate: percent(metrics.unauthorized_effects, metrics.delta_attacks)
+};
+
+console.log(JSON.stringify(report, null, 2));
+
+if (report.normal_task_completion_rate !== 100) throw new Error('normal task completion regressed');
+if (report.false_approval_rate !== 0) throw new Error('normal tasks were interrupted by approval');
+if (report.delta_step_up_rate !== 100) throw new Error('authority deltas were not consistently surfaced');
+if (report.unauthorized_effect_rate !== 0) throw new Error('an unrelated effect executed');
+
+console.log('PASS -> deterministic product utility benchmark preserved useful task completion and blocked unrelated effects');

package/docs/connected-execution-api.md

@@ -0,0 +1,60 @@
+# Task-owned vs broker-owned execution
+
+The task-first facade supports two effect ownership modes with the same Task Lease semantics.
+
+## Application-owned effect
+
+Use `task.run(request, callback)` when the application already owns the SDK or provider call:
+
+```js
+const result = await task.run(request, () => existingSdkCall());
+```
+
+The callback runs only after the Task Lease returns ALLOW. The task receives execution evidence for the exact callback output.
+
+## Agent Authority connected-provider effect
+
+Use `task.execute(request)` when the provider credential and provider adapter should stay behind Agent Authority's broker boundary:
+
+```js
+const result = await task.execute(request);
+```
+
+This requires the task to be created with an `ExecutingAuthorityRuntime`, such as the runtime produced by the local `createRuntimeEnvironment()` helper.
+
+The connected path performs:
+
+```text
+Task Lease evaluation
+      |
+      +--> DENY / STEP-UP -> stop before provider readiness or credential resolution
+      |
+      v
+connected-provider readiness
+      |
+      v
+credential broker resolves secret internally
+      |
+      v
+provider adapter executes
+      |
+      v
+sanitized output + ALLOW receipt + execution evidence
+```
+
+`task.execute()` converts broker runtime `deny` and `require_approval` results into the same `AuthorityDeniedError` and `AuthorityApprovalRequiredError` classes used by `task.run()`.
+
+Successful connected execution can therefore feed directly into `task.authorityFrom()` when a reviewed provider extractor exists.
+
+## Credential boundary
+
+The provider credential belongs to the broker/runtime, not the task request. It should not be copied into:
+
+- Mission or Task Lease authority facts;
+- model/tool arguments;
+- action receipts;
+- execution evidence;
+- provider-normalized output;
+- public connection listings.
+
+The local runtime's encrypted file vault is a developer/trusted-host reference implementation. Production applications should use an appropriate secret manager/KMS and provider-native credential lifecycle.