@nullsquare/agent-authority 0.4.2 → 0.4.3

package/README.md

@@ -10,7 +10,7 @@
 
 [Task Leases](docs/task-leases.md) · [Validate](docs/validation.md) · [Google proof](docs/live-google-validation.md) · [Integration contract](docs/integration-contract.md) · [CLI](docs/cli.md) · [Architecture](docs/architecture.md) · [Roadmap](ROADMAP.md) · [Contributing](CONTRIBUTING.md)
 
-> **Status: public pre-alpha / v0.4.1 Developer Preview.** Published on npm as `@nullsquare/agent-authority`. The repository has a working policy runtime, protocol-neutral guard, Task Lease prototype with provenance-bound derived facts, approvals, revocation, idempotency, credential isolation, MCP v2 gateway, GitHub and Google provider integrations, CI and CodeQL. It is not production-ready yet.
+> **Status: public pre-alpha / v0.4.2 Developer Preview.** Published on npm as `@nullsquare/agent-authority`. The repository has a working policy runtime, protocol-neutral guard, Task Lease prototype, execution-bound derived facts, approvals, revocation, idempotency, credential isolation, MCP v2 gateway, GitHub and Google provider integrations, CI and CodeQL. It is not production-ready yet.
 
 </div>
 
@@ -97,6 +97,12 @@ Human-approved task
   Gmail thread #91
         |
  authorized read
+        |
+        +--> ALLOW receipt
+        +--> exact output hash evidence
+        |
+        v
+ reviewed adapter extractor
         |
         v
  derived fact
@@ -152,7 +158,7 @@ The demo performs this flow without provider credentials:
 
 The side-effect callbacks for blocked actions never run.
 
-The repository also includes a real Gmail → Calendar validation path and a reusable Google provider adapter. See [Live Gmail → Calendar validation](docs/live-google-validation.md).
+The repository also includes a real Gmail → Calendar validation path and a reusable Google provider adapter. The stricter v0.4.2 path binds the derived sender to the exact guarded output before it becomes authority. See [Live Gmail → Calendar validation](docs/live-google-validation.md) and [Executable Evidence](docs/evidence.md).
 
 ## Minimal developer API
 
@@ -160,6 +166,7 @@ The repository also includes a real Gmail → Calendar validation path and a reu
 import { AuthorityRuntime } from '@nullsquare/agent-authority';
 import { createTaskLease } from '@nullsquare/agent-authority/task-lease';
 import { createTaskLeaseGuard } from '@nullsquare/agent-authority/guard';
+import { gmailThreadSenderAuthorityExtractor } from '@nullsquare/agent-authority/providers/google';
 
 const lease = createTaskLease({
   mission,
@@ -171,7 +178,7 @@ const lease = createTaskLease({
     {
       service: 'calendar',
       action: 'event.create',
-      context_field: 'attendee',
+      context_field: 'attendee_email',
       fact_id: 'fact:sender-email'
     }
   ]
@@ -185,25 +192,30 @@ const guard = createTaskLeaseGuard({
 const read = await guard.run({
   service: 'gmail',
   action: 'thread.read',
-  context: { thread: 'thread:demo-91' }
+  context: { thread_id: 'thread:demo-91' }
 }, () => gmail.readThread('thread:demo-91'));
 
-lease.derive({
+const senderFact = lease.deriveFromEvidence({
   fact_id: 'fact:sender-email',
   kind: 'email.address',
-  value: read.output.sender,
   from: ['fact:thread'],
   receipt: read.receipt,
-  selector: 'output.sender'
+  evidence: read.evidence,
+  output: read.output,
+  extractor: gmailThreadSenderAuthorityExtractor
 });
 
 await guard.run({
   service: 'calendar',
   action: 'event.create',
-  context: { attendee: read.output.sender }
-}, () => calendar.createEvent({ attendee: read.output.sender }));
+  context: { attendee_email: senderFact.value }
+}, () => calendar.createEvent({ attendee: senderFact.value }));
 ```
 
+`deriveFromEvidence()` does not accept the authority value. The reviewed extractor selects a normalized output field, and Task Lease resolves that value only after verifying that the output still matches the exact allowed execution evidence.
+
+The older `derive()` API remains available as the explicitly **host-trusted compatibility path**.
+
 The host keeps its existing SDK, connector and authentication. Agent Authority controls whether the effect may happen.
 
 ## Three integration modes, one authority model
@@ -249,7 +261,11 @@ The long-term validation target is the **same Task Lease and authority lineage a
 - Task Lease prototype
 - explicit authority roots
 - same-lease provenance-bound derived facts
-- required parent lineage and trusted extraction selector
+- execution evidence binding an allowed receipt, request and exact output hash
+- strict `deriveFromEvidence()` path where the caller cannot provide the authority value
+- reviewed Gmail sender authority extractor bound to `gmail:thread.read`
+- legacy host-trusted `derive()` compatibility path
+- required parent lineage and extraction selector
 - exact context-field bindings
 - authority-delta step-up signal
 - immediate task completion/expiry enforcement
@@ -259,6 +275,7 @@ The long-term validation target is the **same Task Lease and authority lineage a
 
 - protocol-neutral `guard.run()` wrapper
 - blocked side effects never invoke their callback
+- successful guarded effects return separate execution evidence
 - one-time human approvals bound to exact request
 - mutation idempotency
 - conservative uncertain-state handling
@@ -278,10 +295,12 @@ The long-term validation target is the **same Task Lease and authority lineage a
 ### Engineering quality
 
 - adversarial authorization tests
+- execution-evidence substitution, tampering, replay, cross-lease and selector tests
 - Node 20 and Node 22 CI
 - coverage run
 - package checks
 - clean-consumer npm registry verification
+- live GitHub read and mutation proofs
 - CodeQL
 
 ## What is different from OAuth, IAM and MCP authorization?
@@ -337,7 +356,7 @@ Allow a natural workflow across mail, calendar, CRM and internal systems without
 1. **Task before credential.** A provider token is not task authority.
 2. **Mission is the ceiling.** Task Leases cannot override explicit denies.
 3. **No side effect before authorization.** Denied and step-up actions never execute.
-4. **Authority lineage matters.** Derived facts require an authorized receipt from the same Task Lease, at least one existing parent fact, and a recorded extraction selector.
+4. **Authority lineage matters.** Provider-derived authority should bind the exact allowed receipt and guarded output to a reviewed extractor; legacy host-trusted derivation remains identifiable in provenance.
 5. **No silent resource expansion.** A different concrete resource becomes an authority delta.
 6. **Task authority ends with the task.** Completion and expiry are independent from provider credential lifetime.
 7. **Authority may shrink, never silently grow.** Delegation and transport changes must preserve non-amplification.
@@ -352,7 +371,9 @@ See [SECURITY.md](SECURITY.md).
 This is still a validation implementation.
 
 - Task Lease state is currently process-local.
-- Derived-value extraction is trusted to the host/adapter; v0.4 records the source receipt and selector but does not yet cryptographically prove extraction from the provider response.
+- `deriveFromEvidence()` proves consistency with the exact output returned through the trusted Agent Authority guard, but the output is not cryptographically attested by Gmail, GitHub, or another remote provider.
+- The legacy `derive()` API remains host-trusted for compatibility; audit provenance distinguishes it from `execution-evidence-v1` derivation.
+- Source-data changes do not yet automatically invalidate already-derived authority facts.
 - Bindings currently target top-level request context fields.
 - Approved authority deltas are surfaced but not automatically applied back into a live lease.
 - GitHub token-stdin is a developer bridge, not final browser OAuth onboarding.

package/ROADMAP.md

@@ -77,7 +77,7 @@ Build only what the real M1 workflow proves necessary.
 
 **Success criterion:** a Task Lease survives daemon/process restarts without gaining authority or losing its provenance lineage.
 
-## M3 — Trustworthy derived facts — first slice in progress
+## 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.
 
@@ -85,14 +85,17 @@ The first real Gmail -> Calendar integration showed that recording a host-suppli
 - [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
-- [ ] conformance fixtures for reviewed operation -> authority-field mappings across multiple providers
 - [ ] define freshness/invalidation rules when a source resource changes
 
+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 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. Stronger provider attestation and source invalidation remain separate follow-on problems.
+**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.
 
 ## M4 — Same task, multiple transports
 

package/docs/authority-extractor-conformance.md

@@ -0,0 +1,95 @@
+# Authority extractor conformance
+
+Agent Authority treats provider-derived authority as a small adapter contract, not a general semantic policy language.
+
+The strict path is:
+
+```text
+authorized request
+      |
+      v
+reviewed provider adapter
+      |
+      v
+normalized provider output
+      |
+      +--> ALLOW receipt
+      +--> execution output hash
+      |
+      v
+adapter.authorityExtractor(request, factKind)
+      |
+      v
+{ extractor_id, selector }
+      |
+      v
+TaskLease.deriveFromEvidence()
+      |
+      v
+derived authority fact
+```
+
+## Adapter requirements
+
+A provider mapping intended to establish downstream authority SHOULD satisfy all of these:
+
+1. **Reviewed operation mapping.** The adapter owns the mapping from Agent Authority `service` + `action` to the external provider operation.
+2. **Normalized authority field.** Provider data is normalized into a small output shape before authority extraction. Credentials and unrelated raw payloads should not be copied into the authority result.
+3. **Fail-closed extractor advertisement.** `adapter.authorityExtractor(request, factKind)` returns an extractor only for an explicitly supported operation/fact-kind pair. Unsupported mappings return `null`.
+4. **Selector, never value.** The extractor returns `{ extractor_id, selector }`. It must not return the derived authority value itself.
+5. **Operation binding.** The extractor rejects receipts from another provider action.
+6. **Canonical output.** The extractor rejects malformed, ambiguous, or non-canonical normalized output.
+7. **Task lineage.** `TaskLease.deriveFromEvidence()` requires an ALLOW receipt from the same mission and Task Lease plus at least one existing parent fact.
+8. **Exact-output integrity.** The output passed to derivation must still hash to the output bound into the execution evidence.
+
+This is an integrity contract inside the trusted Agent Authority host/adapter boundary. It is not provider-signed remote attestation.
+
+## Current fixtures
+
+### Google Gmail sender
+
+```text
+gmail:thread.read
+  -> normalized sender_email
+  -> google.gmail.thread.sender-email.v1
+  -> email.address
+```
+
+The Gmail extractor accepts only canonical normalized `sender_email` output and selects `output.sender_email`.
+
+### GitHub selected issue
+
+```text
+github:issue.list
+  + root-bound repository
+  + root-bound fixture_marker
+  -> exactly one normalized marker match
+  -> github.issue.list.selected-number.v1
+  -> github.issue.number
+```
+
+The GitHub adapter performs marker matching against the provider response, does not expose issue bodies in the normalized output, and the extractor selects only `output.selected_issue_number` when exactly one non-pull-request issue matched.
+
+## Shared adversarial conformance suite
+
+`test/provider-authority-conformance.test.js` applies the same strict-path checks to both provider fixtures:
+
+- positive derivation obtains the value from the evidence-bound output rather than caller input;
+- modified output under unchanged evidence is rejected;
+- execution evidence cannot be replayed under a second ALLOW receipt;
+- receipt/evidence from one Task Lease cannot establish authority in another lease;
+- an extractor cannot be reused with evidence from another provider operation.
+
+Provider-specific tests additionally verify canonical normalization, exact REST mappings, extractor advertisement, and ambiguity failure.
+
+## What conformance does not prove
+
+Passing this contract does not prove that:
+
+- a provider cryptographically signed the normalized result;
+- the trusted host itself is non-malicious;
+- a source resource has not changed since the read;
+- a derived fact is automatically invalidated when provider data changes;
+- an agent cannot bypass Agent Authority through a separate credential or unguarded provider path.
+
+Those are separate trust, freshness, and deployment-boundary problems and should not be hidden inside the extractor API.

package/docs/evidence.md

@@ -12,7 +12,7 @@ The guarantee applies to effects that actually pass through the Agent Authority
 
 ## Execution-bound derived authority
 
-The strict derived-authority path now binds provider-derived authority to the exact output returned by an authorized `guard.run()` effect.
+The strict derived-authority path binds provider-derived authority to the exact output returned by an authorized `guard.run()` effect.
 
 A successful guarded effect returns three relevant records:
 
@@ -56,6 +56,36 @@ Execution evidence is an integrity mechanism inside the trusted host/runtime bou
 
 It does **not** prove that Gmail, GitHub, or another provider cryptographically signed that output, and it does not protect a malicious host that bypasses or replaces the Agent Authority enforcement path. Stronger provider/transport attestation remains open M3 work.
 
+## Two-provider authority-extractor conformance
+
+The same strict primitive is now exercised by two independent provider mappings:
+
+```text
+Google Gmail
+thread.read
+   -> sender_email
+   -> reviewed extractor
+   -> email.address authority
+
+GitHub
+issue.list
+   -> selected_issue_number
+   -> reviewed extractor
+   -> github.issue.number authority
+```
+
+`test/provider-authority-conformance.test.js` applies the same contract to both mappings:
+
+- positive derivation gets its value from the evidence-bound output rather than caller input;
+- modifying the selected output under unchanged evidence is rejected;
+- evidence replay under another ALLOW receipt is rejected;
+- cross-Task-Lease receipt/evidence reuse is rejected;
+- an extractor rejects evidence from another operation.
+
+Provider-specific tests additionally verify canonical normalization and fail-closed extractor advertisement. The contract is documented in [Authority extractor conformance](authority-extractor-conformance.md).
+
+This is the current evidence that execution-bound derived authority is a reusable provider primitive rather than a Gmail-only special case.
+
 ## Cross-provider derived authority — Gmail → Calendar
 
 Agent Authority includes a real Google provider mapping, an adversarial cross-provider test, a live validation script, and an opt-in GitHub Actions workflow.
@@ -158,13 +188,13 @@ Taken together, the deterministic Task Lease tests plus the controlled provider
 
 See [Live Gmail → Calendar validation](live-google-validation.md).
 
-## Live derived-authority mutation — GitHub
+## Live evidence-derived mutation — GitHub
 
 Public fixture: [issue #9](https://github.com/Null-Square/agent-authority/issues/9)
 
 Validation workflow: CI job `live-derived-github-mutation`
 
-Passing run: [CI run 136](https://github.com/Null-Square/agent-authority/actions/runs/32517381668)
+Passing evidence-derived run: [CI run 262](https://github.com/Null-Square/agent-authority/actions/runs/32600963479)
 
 The job uses a GitHub Actions token with:
 
@@ -173,25 +203,40 @@ contents: read
 issues: write
 ```
 
-The Task Lease itself starts with only the repository as an authority root.
+The Task Lease begins with two explicit authority roots:
+
+```text
+repository = Null-Square/agent-authority
+fixture_marker = agent-authority-live-fixture-v1
+```
+
+Both values are bound to the `issue.list` request. The brokered GitHub provider adapter owns the external issue-list operation and normalizes the provider response. Issue bodies are used internally for marker matching but are not copied into the normalized authority output.
 
 ### Executed path
 
 ```text
-Task root
-Null-Square/agent-authority
+Task roots
+repository + fixture marker
         |
         v
-ALLOW live issue-list request
+ALLOW github:issue.list
+through reviewed provider adapter
+        |
+        +--> exact output-bound execution evidence
+        |
+        v
+adapter selects exactly one marker match
+selected_issue_number = 9
         |
         v
-discover issue #9 from GitHub response
+reviewed GitHub issue-number extractor
         |
         v
-derive fact: issue_number = 9
+TaskLease.deriveFromEvidence()
+issue_number = 9
         |
         v
-ALLOW one real comment mutation on #9
+ALLOW one real github:issue.comment on #9
         |
         +--> attempt comment on #1
         |      -> authority_delta_required
@@ -208,38 +253,41 @@ complete Task Lease
 The passing job recorded:
 
 ```text
-ALLOW -> discovered issue #9
-Derived authority -> issue #9
+ALLOW -> selected issue #9: Agent Authority live validation fixture — do not close
+Evidence-verified authority -> issue #9
 ALLOW -> real GitHub comment mutation executed
 STEP-UP -> unrelated issue #1 blocked before provider mutation
 DENY -> post-completion mutation blocked for issue #9
+PASS -> GitHub provider output became downstream authority only through execution evidence and a reviewed extractor
 Provider calls observed before cleanup: reads=1, task_mutations=1
 ```
 
-The temporary validation comment is deleted by test-harness cleanup after the proof. Cleanup is intentionally outside the agent authority path and counted separately.
+The temporary validation comment was deleted by harness cleanup after the proof. Cleanup remains intentionally outside the Task Lease authority path and is counted separately.
 
 ### What this proves
 
-- a concrete resource can be discovered from a real provider response during authorized execution;
-- that resource can become same-lease derived authority;
-- a real provider mutation can be limited to the derived resource;
-- asking for another resource does not silently inherit the same authority;
-- a blocked resource causes zero additional task-side provider mutation calls;
-- completing the Task Lease prevents reuse of the previously authorized resource;
-- the provider credential can still exist after task authority disappears.
+- the same execution-evidence + reviewed-extractor primitive used for Gmail works against a second real provider;
+- the brokered GitHub adapter, rather than arbitrary host extraction code, owns provider response normalization;
+- the caller does not provide the issue number to `deriveFromEvidence()`;
+- repository and discovery marker are explicit Task Lease roots;
+- a real provider mutation is limited to the issue selected from the authorized provider result;
+- another issue causes zero additional task-side provider mutation calls;
+- completing the Task Lease prevents reuse of the previously authorized issue;
+- the provider credential can remain valid after task authority disappears.
 
 ### What this does not prove
 
-- the current GitHub example has migrated to a reviewed evidence extractor contract;
+- GitHub cryptographically attests the normalized Agent Authority output;
+- source issue changes automatically invalidate a derived fact;
 - an agent cannot bypass Agent Authority if it independently possesses the provider credential or another unguarded provider path;
 - Task Lease state is durable across process failure;
 - the current prototype is ready for adversarial production use.
 
 ## Live provider read boundary — GitHub
 
-CI also runs `demo:live-github` against the public GitHub API.
+CI also runs `demo:live-github` against the GitHub API.
 
-It proves that one repository permitted by the Task Lease causes one live `fetch()` while another repository produces `authority_delta_required` before a second fetch occurs.
+It proves that one repository permitted by the Task Lease causes one live provider read while another repository produces `authority_delta_required` before a second provider request occurs.
 
 ## Network-boundary integration test
 
@@ -263,6 +311,7 @@ The test suite also covers:
 - parent lineage is required;
 - legacy host-trusted derivation records its extraction selector;
 - strict execution-evidence derivation rejects substitution/replay/tampering cases;
+- the shared provider conformance suite applies the same attacks to Google and GitHub mappings;
 - explicit mission deny rules remain the ceiling;
 - lease expiry and mission expiry are enforced against a consistent evaluation clock.
 
@@ -277,8 +326,8 @@ Current pull requests run:
 - package checks;
 - coverage;
 - live GitHub read validation;
-- live derived GitHub mutation validation for trusted in-repository branches;
-- Google provider, extractor, cross-provider and execution-evidence adversarial tests;
+- live evidence-derived GitHub mutation validation for trusted in-repository branches;
+- Google and GitHub provider/extractor conformance and execution-evidence adversarial tests;
 - CodeQL.
 
 The live Google provider mutation workflow is manual because it requires repository-owned Google OAuth secrets. It should be added to the public evidence list after its first successful run.

package/docs/npm-release.md

@@ -13,19 +13,19 @@ Before any publication:
 After publication, verify from a fresh project with:
 
 ```bash
-npm install @nullsquare/agent-authority@0.4.1
+npm install @nullsquare/agent-authority@0.4.2
 ```
 
 Then run the same consumer smoke flow through the registry-installed package. Registry verification is part of the release gate; a successful `npm publish` command alone is not sufficient.
 
-The repository also includes `.github/workflows/verify-npm-registry.yml`, which verifies registry visibility and a clean consumer install. For v0.4.1 it additionally verifies the public `@nullsquare/agent-authority/providers/google` export.
+The repository also includes `.github/workflows/verify-npm-registry.yml`, which verifies registry visibility and a clean consumer install. For v0.4.2 it additionally verifies the public `@nullsquare/agent-authority/authority-evidence` export plus the Google provider and Gmail authority-extractor exports.
 
 ## npm vs GitHub release surfaces
 
 Publishing to the public npm registry does not automatically create either a GitHub Release or a GitHub Packages entry.
 
 - **npm registry** — `npm publish --access public` publishes `@nullsquare/agent-authority` to `registry.npmjs.org` / npmjs.com. This is the package users install with `npm install`.
-- **GitHub Releases** — a separate GitHub object, normally backed by a Git tag such as `v0.4.1`. A release must be created explicitly or by release automation.
+- **GitHub Releases** — a separate GitHub object, normally backed by a Git tag such as `v0.4.2`. A release must be created explicitly or by release automation.
 - **GitHub Packages** — a separate package registry. It only appears when the package is published to GitHub's npm registry (`npm.pkg.github.com`); publishing to npmjs.com does not populate it.
 
 Agent Authority currently uses npmjs.com as its public package registry. Therefore an empty GitHub **Packages** section is expected unless the project intentionally adopts dual publication. A GitHub **Release** is still useful for source-release discoverability and should track published versions, but it is independent from npm publication.

package/examples/live-github-derived-mutation.js

@@ -1,9 +1,11 @@
+import { CredentialBroker } from '../src/connections.js';
 import { AuthorityRuntime } from '../src/index.js';
 import {
   AuthorityApprovalRequiredError,
   AuthorityDeniedError,
   createTaskLeaseGuard
 } from '../src/guard.js';
+import { createGitHubProviderAdapter } from '../src/providers/github.js';
 import { createTaskLease } from '../src/task-lease.js';
 
 const repository = process.env.AA_VALIDATION_REPOSITORY || 'Null-Square/agent-authority';
@@ -43,6 +45,12 @@ const lease = createTaskLease({
       kind: 'github.repository',
       value: repository,
       source: 'validation-task'
+    },
+    {
+      fact_id: 'fact:fixture-marker',
+      kind: 'github.issue.marker',
+      value: marker,
+      source: 'validation-task'
     }
   ],
   bindings: [
@@ -52,6 +60,12 @@ const lease = createTaskLease({
       context_field: 'repository',
       fact_id: 'fact:repository'
     },
+    {
+      service: 'github',
+      action: 'issue.list',
+      context_field: 'fixture_marker',
+      fact_id: 'fact:fixture-marker'
+    },
     {
       service: 'github',
       action: 'issue.comment',
@@ -68,10 +82,20 @@ const lease = createTaskLease({
 });
 
 const guard = createTaskLeaseGuard({ lease, runtime: new AuthorityRuntime() });
-const headers = {
+const broker = new CredentialBroker();
+broker.connect({
+  principal_id: mission.principal.id,
+  service: 'github',
+  auth_kind: 'github-actions-token',
+  credential: { access_token: token },
+  scopes: ['contents:read', 'issues:write']
+});
+const adapter = createGitHubProviderAdapter({ broker });
+
+const cleanupHeaders = {
   accept: 'application/vnd.github+json',
   authorization: `Bearer ${token}`,
-  'user-agent': 'agent-authority-derived-mutation-validation',
+  'user-agent': 'agent-authority-derived-mutation-validation-cleanup',
   'x-github-api-version': '2022-11-28'
 };
 
@@ -80,90 +104,83 @@ let providerMutationCalls = 0;
 let cleanupCalls = 0;
 let createdCommentId = null;
 
-async function githubJson(url, options = {}) {
-  const response = await fetch(url, {
-    ...options,
-    headers: { ...headers, ...(options.headers || {}) }
-  });
-  if (!response.ok) {
-    const body = await response.text();
-    throw new Error(`GitHub ${response.status}: ${body.slice(0, 300)}`);
-  }
-  if (response.status === 204) return null;
-  return response.json();
+function discoveryRequest() {
+  return {
+    service: 'github',
+    action: 'issue.list',
+    context: {
+      repository,
+      fixture_marker: marker,
+      state: 'open',
+      per_page: 100
+    }
+  };
 }
 
 async function discoverFixtureIssue() {
-  return guard.run(
-    {
-      service: 'github',
-      action: 'issue.list',
-      context: { repository }
-    },
-    async () => {
-      providerReadCalls += 1;
-      const issues = await githubJson(
-        `https://api.github.com/repos/${owner}/${repo}/issues?state=open&per_page=100`
-      );
-      const fixture = issues.find((issue) => !issue.pull_request && issue.body?.includes(marker));
-      if (!fixture) throw new Error(`validation fixture with marker ${marker} was not found`);
-      return { number: fixture.number, title: fixture.title };
-    }
-  );
+  const request = discoveryRequest();
+  return guard.run(request, async () => {
+    providerReadCalls += 1;
+    return adapter.execute({ mission, request });
+  });
 }
 
 async function commentOnIssue(issueNumber, body) {
-  return guard.run(
-    {
-      service: 'github',
-      action: 'issue.comment',
-      context: { repository, issue_number: issueNumber }
-    },
-    async () => {
-      providerMutationCalls += 1;
-      const comment = await githubJson(
-        `https://api.github.com/repos/${owner}/${repo}/issues/${issueNumber}/comments`,
-        {
-          method: 'POST',
-          headers: { 'content-type': 'application/json' },
-          body: JSON.stringify({ body })
-        }
-      );
-      return { id: comment.id, html_url: comment.html_url };
-    }
-  );
+  const request = {
+    service: 'github',
+    action: 'issue.comment',
+    context: { repository, issue_number: issueNumber, body }
+  };
+
+  return guard.run(request, async () => {
+    providerMutationCalls += 1;
+    return adapter.execute({ mission, request });
+  });
 }
 
 async function cleanupComment(commentId) {
   cleanupCalls += 1;
-  await githubJson(
+  const response = await fetch(
     `https://api.github.com/repos/${owner}/${repo}/issues/comments/${commentId}`,
-    { method: 'DELETE' }
+    { method: 'DELETE', headers: cleanupHeaders }
   );
+  if (!response.ok && response.status !== 404) {
+    const body = await response.text();
+    throw new Error(`GitHub cleanup ${response.status}: ${body.slice(0, 300)}`);
+  }
 }
 
 try {
   console.log(`Task root repository: ${repository}`);
-  console.log('1. Discover fixture through an authorized live GitHub issue-list call');
+  console.log(`Task root fixture marker: ${marker}`);
+  console.log('1. Discover fixture through the reviewed GitHub provider adapter');
   const discovered = await discoverFixtureIssue();
-  console.log(`   ALLOW -> discovered issue #${discovered.output.number}: ${discovered.output.title}`);
 
-  lease.derive({
+  if (discovered.output.selected_issue_match_count !== 1) {
+    throw new Error(`expected exactly one fixture marker match, got ${discovered.output.selected_issue_match_count}`);
+  }
+  console.log(`   ALLOW -> selected issue #${discovered.output.selected_issue_number}: ${discovered.output.selected_issue_title}`);
+
+  const extractor = adapter.authorityExtractor(discoveryRequest(), 'github.issue.number');
+  if (!extractor) throw new Error('GitHub provider did not advertise the issue-number authority extractor');
+
+  const issueFact = lease.deriveFromEvidence({
     fact_id: 'fact:discovered-issue-number',
     kind: 'github.issue.number',
-    value: discovered.output.number,
-    from: ['fact:repository'],
+    from: ['fact:repository', 'fact:fixture-marker'],
     receipt: discovered.receipt,
-    selector: 'output.number'
+    evidence: discovered.evidence,
+    output: discovered.output,
+    extractor
   });
-  console.log(`2. Derived authority -> issue #${discovered.output.number}`);
+  console.log(`2. Evidence-verified authority -> issue #${issueFact.value}`);
 
-  const validationBody = `Agent Authority live derived-authority validation (${new Date().toISOString()}). Temporary comment; CI removes it after the proof.`;
-  const allowedMutation = await commentOnIssue(discovered.output.number, validationBody);
-  createdCommentId = allowedMutation.output.id;
+  const validationBody = `Agent Authority live evidence-derived authorization validation (${new Date().toISOString()}). Temporary comment; CI removes it after the proof.`;
+  const allowedMutation = await commentOnIssue(issueFact.value, validationBody);
+  createdCommentId = allowedMutation.output.comment_id;
   console.log(`3. ALLOW -> real GitHub comment mutation executed (comment ${createdCommentId})`);
 
-  const unrelatedIssue = discovered.output.number === 1 ? 2 : 1;
+  const unrelatedIssue = issueFact.value === 1 ? 2 : 1;
   try {
     await commentOnIssue(unrelatedIssue, 'THIS MUST NEVER REACH GITHUB');
     throw new Error('unrelated issue mutation unexpectedly executed');
@@ -178,15 +195,15 @@ try {
     throw new Error(`expected exactly one task-side provider mutation before completion, got ${providerMutationCalls}`);
   }
 
-  lease.complete('live derived-mutation validation complete');
+  lease.complete('live evidence-derived mutation validation complete');
   try {
-    await commentOnIssue(discovered.output.number, 'THIS MUST NOT RUN AFTER TASK COMPLETION');
+    await commentOnIssue(issueFact.value, 'THIS MUST NOT RUN AFTER TASK COMPLETION');
     throw new Error('post-completion mutation unexpectedly executed');
   } catch (error) {
     if (!(error instanceof AuthorityDeniedError) || error.code !== 'task_lease_completed') {
       throw error;
     }
-    console.log(`5. DENY -> post-completion mutation blocked for issue #${discovered.output.number}`);
+    console.log(`5. DENY -> post-completion mutation blocked for issue #${issueFact.value}`);
   }
 
   if (providerReadCalls !== 1) {
@@ -196,7 +213,7 @@ try {
     throw new Error(`expected exactly one provider mutation after blocked attempts, got ${providerMutationCalls}`);
   }
 
-  console.log('PASS -> dynamic resource was discovered from GitHub, derived into the Task Lease, and mutated exactly once');
+  console.log('PASS -> GitHub provider output became downstream authority only through execution evidence and a reviewed extractor');
   console.log('PASS -> unrelated and post-completion mutations produced zero additional provider mutation calls');
 } finally {
   if (createdCommentId) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nullsquare/agent-authority",
-  "version": "0.4.2",
+  "version": "0.4.3",
   "description": "Task-bounded authority runtime for AI agents: give agents tasks, not standing account permissions.",
   "license": "Apache-2.0",
   "type": "module",

package/src/providers/github.js

@@ -1,12 +1,19 @@
 import { brokeredProviderAdapter } from '../connections.js';
 
-const MUTATING_ACTIONS = new Set(['issue.create', 'pull_request.create', 'repo.contents.write']);
+const MUTATING_ACTIONS = new Set(['issue.create', 'issue.comment', 'pull_request.create', 'repo.contents.write']);
+const ISSUE_STATES = new Set(['open', 'closed', 'all']);
 
 function required(value, name) {
   if (value === undefined || value === null || value === '') throw new Error(`${name} is required`);
   return value;
 }
 
+function providerError(code, message) {
+  const error = new Error(message);
+  error.code = code;
+  return error;
+}
+
 function repoParts(context = {}) {
   const repository = required(context.repository, 'context.repository');
   const [owner, repo, ...extra] = String(repository).split('/');
@@ -22,6 +29,26 @@ function encodedPath(path) {
     .join('/');
 }
 
+function issueNumber(value) {
+  const number = Number(value);
+  if (!Number.isSafeInteger(number) || number <= 0) {
+    throw providerError('invalid_issue_number', 'context.issue_number must be a positive integer');
+  }
+  return number;
+}
+
+function issueListQuery(context = {}) {
+  const state = context.state || 'open';
+  if (!ISSUE_STATES.has(state)) {
+    throw providerError('invalid_issue_state', 'context.state must be open, closed, or all');
+  }
+  const perPage = context.per_page === undefined ? 100 : Number(context.per_page);
+  if (!Number.isSafeInteger(perPage) || perPage < 1 || perPage > 100) {
+    throw providerError('invalid_issue_page_size', 'context.per_page must be an integer between 1 and 100');
+  }
+  return new URLSearchParams({ state, per_page: String(perPage) }).toString();
+}
+
 function buildOperation(request) {
   const context = request.context || {};
   const { owner, repo } = repoParts(context);
@@ -37,6 +64,9 @@ function buildOperation(request) {
       return { method: 'GET', path: `${root}/contents/${encodedPath(path)}${query}` };
     }
 
+    case 'issue.list':
+      return { method: 'GET', path: `${root}/issues?${issueListQuery(context)}` };
+
     case 'issue.create':
       return {
         method: 'POST',
@@ -49,6 +79,13 @@ function buildOperation(request) {
         }
       };
 
+    case 'issue.comment':
+      return {
+        method: 'POST',
+        path: `${root}/issues/${issueNumber(context.issue_number)}/comments`,
+        body: { body: required(context.body, 'context.body') }
+      };
+
     case 'pull_request.create':
       return {
         method: 'POST',
@@ -77,11 +114,8 @@ function buildOperation(request) {
       };
     }
 
-    default: {
-      const error = new Error(`GitHub action ${request.action} has no provider operation mapping`);
-      error.code = 'unsupported_action';
-      throw error;
-    }
+    default:
+      throw providerError('unsupported_action', `GitHub action ${request.action} has no provider operation mapping`);
   }
 }
 
@@ -94,6 +128,91 @@ function sanitizeBody(body) {
   return clone;
 }
 
+function normalizeIssueList(request, body) {
+  if (!Array.isArray(body)) {
+    throw providerError('github_issue_list_invalid', 'GitHub issue.list response must be an array');
+  }
+
+  const issues = body.map((issue) => ({
+    number: issueNumber(issue?.number),
+    title: typeof issue?.title === 'string' ? issue.title : null,
+    is_pull_request: Boolean(issue?.pull_request)
+  }));
+
+  const marker = request.context?.fixture_marker;
+  if (typeof marker !== 'string' || marker.trim() === '') {
+    return { issues, selected_issue_number: null, selected_issue_title: null, selected_issue_match_count: 0, selected_issue_marker: null };
+  }
+
+  const matches = body
+    .map((issue, index) => ({ issue, index }))
+    .filter(({ issue }) => !issue?.pull_request && typeof issue?.body === 'string' && issue.body.includes(marker));
+
+  const selected = matches.length === 1 ? issues[matches[0].index] : null;
+  return {
+    issues,
+    selected_issue_number: selected?.number || null,
+    selected_issue_title: selected?.title || null,
+    selected_issue_match_count: matches.length,
+    selected_issue_marker: marker
+  };
+}
+
+function normalizedOutput(request, response, body) {
+  const common = {
+    provider: 'github',
+    status: response.status,
+    ok: response.ok,
+    request_id: response.headers?.get?.('x-github-request-id') || null
+  };
+
+  if (request.action === 'issue.list') {
+    return { ...common, ...normalizeIssueList(request, body) };
+  }
+
+  if (request.action === 'issue.comment') {
+    return {
+      ...common,
+      comment_id: body?.id || null,
+      html_url: body?.html_url || null,
+      issue_number: issueNumber(request.context?.issue_number)
+    };
+  }
+
+  return { ...common, body: sanitizeBody(body) };
+}
+
+/**
+ * Reviewed authority extractor for an issue selected by the normalized
+ * issue.list mapping using the request's root-bound fixture_marker.
+ *
+ * The extractor returns a selector only. TaskLease resolves the issue number
+ * from the evidence-bound output after verifying the ALLOW receipt.
+ */
+export function githubIssueListSelectedNumberAuthorityExtractor({ receipt, output } = {}) {
+  if (receipt?.service !== 'github' || receipt?.action !== 'issue.list') {
+    throw providerError(
+      'trusted_extractor_operation_mismatch',
+      'GitHub issue-number authority extractor only accepts github:issue.list receipts'
+    );
+  }
+  if (output?.provider !== 'github' || output?.selected_issue_match_count !== 1) {
+    throw providerError(
+      'trusted_extractor_output_invalid',
+      'normalized GitHub output must contain exactly one selected issue'
+    );
+  }
+  issueNumber(output.selected_issue_number);
+  if (typeof output.selected_issue_marker !== 'string' || output.selected_issue_marker.trim() === '') {
+    throw providerError('trusted_extractor_output_invalid', 'normalized GitHub output is missing the selection marker');
+  }
+
+  return {
+    extractor_id: 'github.issue.list.selected-number.v1',
+    selector: 'output.selected_issue_number'
+  };
+}
+
 export function createGitHubProviderAdapter({ broker, fetchImpl = globalThis.fetch, baseUrl = 'https://api.github.com' } = {}) {
   if (!broker) throw new Error('credential broker is required');
   if (typeof fetchImpl !== 'function') throw new Error('fetch implementation is required');
@@ -114,7 +233,7 @@ export function createGitHubProviderAdapter({ broker, fetchImpl = globalThis.fet
           authorization: `Bearer ${token}`,
           'content-type': 'application/json',
           'x-github-api-version': '2022-11-28',
-          'user-agent': 'nullsquare-agent-authority/0.3'
+          'user-agent': 'nullsquare-agent-authority/0.4'
         },
         body: operation.body ? JSON.stringify(operation.body) : undefined
       });
@@ -125,25 +244,36 @@ export function createGitHubProviderAdapter({ broker, fetchImpl = globalThis.fet
         try { body = JSON.parse(text); } catch { /* preserve text */ }
       }
 
-      const output = {
-        provider: 'github',
-        status: response.status,
-        ok: response.ok,
-        body: sanitizeBody(body),
-        request_id: response.headers?.get?.('x-github-request-id') || null
-      };
-
       if (!response.ok) {
-        const error = new Error(`GitHub API ${response.status}`);
-        error.code = 'provider_error';
+        const output = {
+          provider: 'github',
+          status: response.status,
+          ok: false,
+          body: sanitizeBody(body),
+          request_id: response.headers?.get?.('x-github-request-id') || null
+        };
+        const error = providerError('provider_error', `GitHub API ${response.status}`);
         error.provider_output = output;
         throw error;
       }
 
-      return output;
+      return normalizedOutput(request, response, body);
     }
   });
 
+  adapter.validateRequest = (request) => buildOperation(request);
   adapter.isMutation = (request) => MUTATING_ACTIONS.has(request?.action);
+  adapter.authorityExtractor = (request, kind = 'opaque') => {
+    if (
+      request?.service === 'github' &&
+      request?.action === 'issue.list' &&
+      kind === 'github.issue.number' &&
+      typeof request?.context?.fixture_marker === 'string' &&
+      request.context.fixture_marker.trim() !== ''
+    ) {
+      return githubIssueListSelectedNumberAuthorityExtractor;
+    }
+    return null;
+  };
   return adapter;
 }