Merge pull request #52 from engineeredsoftware/v31/gate-9-auxillaries-telemetry-proof-recovery-runs

V31 Gate 9: Auxillaries Telemetry Proof And Recovery Runs

Author: geraldarthurdavis

.github/workflows/bitcode-gate-quality.yml

@@ -103,6 +103,7 @@ jobs:
             node scripts/check-v31-gate6-organization-team-role-policy-authority.mjs --skip-branch-check
             node scripts/check-v31-gate7-interfaces-pane-admission-cross-surface-contracts.mjs --skip-branch-check
             node scripts/check-v31-gate8-auxillaries-ux-accessibility-responsive-proof.mjs --skip-branch-check
+            node scripts/check-v31-gate9-auxillaries-telemetry-proof-recovery-runs.mjs --skip-branch-check
           else
             echo "Unexpected BITCODE_SPEC.txt pointer: $POINTER" >&2
             exit 1

BITCODE_SPEC_V31.md

@@ -288,6 +288,8 @@ Gate 9 telemetry/recovery precision:
 - Auxillaries telemetry subjects are profile, account, provider connection, interface admission, wallet, BTD pane, organization authority, policy decision, readiness diagnostic, and recovery run.
 - Proof hooks bind theorem id, replay step id, evidence root, telemetry root, source-safety class, and blocker/repair outcome.
 - Recovery runs are executions; they may call tools, but the stored evidence must be source-safe and secret-free.
+- `AuxillariesTelemetryProofHook` is the package-owned readback object for that proof. It carries subject, subject id, pane, theorem id, replay step id, evidence root, telemetry root, blocker id, repair outcome, source-safety class, and proof root, and is emitted beside the route contract rather than derived by the UI.
+- Externals may render compact telemetry proof-hook rows for operator diagnosis, but only theorem/replay/evidence/telemetry roots and classified outcomes may be visible. Raw provider credentials, service keys, wallet secrets, private prompts, and protected source remain prohibited.
 
 V30 Protocol/BTD carryforward precision:
 
@@ -455,6 +457,7 @@ The canonical diagnostic and recovery model is produced from:
 - wallet/BTD facts: signer posture, no-custody posture, BTD range/read-right/treasury summary, and settlement-readiness blockers;
 - organization facts: organization, team, role, grant set, policy id/hash, wallet binding requirement, decision, denial reason, and recovery route;
 - source-safe telemetry facts: execution id, before/after readiness roots, evidence root, blocker, repair outcome, and retry policy.
+- proof-hook facts: telemetry subject, theorem id, replay step id, evidence root, telemetry root, source-safety class, blocker id, repair outcome, and proof root.
 
 Readiness is classified before repair:
 
@@ -484,6 +487,7 @@ Repair actions are canonical and auditable:
 
 The readiness state is one of ready, incomplete, retryable, repairable, approval-required, denied, or blocked.
 Recovery runs are executions and must store source-safe before/after evidence.
+They also carry evidence roots and telemetry roots so recovery readback can be joined to `AuxillariesTelemetryProofHook` without replaying private route internals.
 They must never store service-role JWTs, Supabase secret keys, OpenAI keys, database passwords, wallet secrets, provider tokens, private prompts, or protected AssetPack source in tracked code, telemetry, UI metadata, or persisted proof payloads.
 
 ## V31 canonical subsystem surfaces

BITCODE_SPEC_V31_DELTA.md

@@ -215,6 +215,12 @@ Closure acceptance:
 - proof hooks bind theorem id, replay step id, evidence root, telemetry root, source-safety class, and blocker/repair outcome;
 - recovery runs are executions with source-safe before/after evidence and route/UI readback.
 
+Implementation center:
+
+- `packages/api/src/routes/auxillaries-contract.ts` owns `AuxillariesTelemetrySubject`, `AuxillariesTelemetryProofHook`, `buildAuxillariesTelemetryProofHooks`, and recovery-run evidence/telemetry roots.
+- `/api/auxillaries/data`, `useUserData`, and the Externals pane surface the same source-safe hook records for route and UI readback.
+- Gate tests assert subject coverage, theorem/replay/evidence/telemetry root binding, recovery-run hook generation, and secret/protected-source exclusion.
+
 ### Gate 10: V31 Promotion Readiness
 
 Gate 10 owns final local/staging proof, generated artifacts, and V31 promotion workflow support.

BITCODE_SPEC_V31_NOTES.md

@@ -122,3 +122,17 @@ Exchange and Conversations may appear as source-safe hooks, but their market and
 Gate 8 is closed only when Auxillaries UX is usable before audit expansion and provable after expansion.
 The contained support plane must expose a named main landmark, keyboard skip link, named pane navigation, active-pane state announcement, readable loading/ready posture, and expandable audit detail for every pane without raw JSON.
 The panel controls must be keyboard-native, focus-visible, labelled, and state-described, and route-scoped CSS must prove responsive mobile/desktop layout, no horizontal overflow pressure, contrast-preserving readiness chips, and reduced-motion posture.
+
+## Gate 9 closure note
+
+Gate 9 is closed only when Auxillaries telemetry is a package-owned proof
+surface rather than an ad hoc console trace.
+`AuxillariesTelemetryProofHook` must cover profile, account, provider
+connection, interface admission, wallet, BTD pane, organization authority,
+policy decision, readiness diagnostic, and recovery run subjects.
+Each hook binds theorem id, replay step id, evidence root, telemetry root,
+source-safety class, blocker id, repair outcome, and proof root.
+Recovery runs must carry source-safe before/after readiness roots plus
+evidence/telemetry roots and must be readable through the API route, shared
+client hook, and Externals UI without exposing credentials, prompts, wallet
+secrets, service keys, database credentials, or protected AssetPack source.

BITCODE_SPEC_V31_PARITY_MATRIX.md

@@ -62,9 +62,9 @@ No `_legacy/` source is active source truth.
 | Connects provider readiness and recovery | Gate 4 | Provider packages, connection routes, readiness/recovery tests | drafted | Provider readiness names credential posture without secrets, scopes class, readback status, blocker, repair action, and before/after roots. |
 | Wallet and BTD pane readiness | Gate 5 | `packages/btd`, Wallet/BTD panes, settlement/read-right tests | drafted | Wallet and BTD panes consume V30 no-custody, signer, read-right, treasury, and settlement-readiness primitives. |
 | Organization team role policy authority | Gate 6 | `packages/btd/src/authority.ts`, `packages/api/src/routes/auxillaries-contract.ts`, `uapi/app/auxillaries/components/AuxillariesProfilePane.tsx`, `uapi/app/terminal/terminal-organization-authority.ts`, focused BTD/API/UI tests | drafted | Organization, team, role, grants, multi-sig readiness, policy decisions, denials, and recovery routes are typed and fail closed. |
-| Interfaces pane admission and cross-surface contracts | Gate 7 | Interfaces pane, API/MCP/ChatGPT App interface records, tests | pending | Interface admission records name auth mode, supported actions, policy constraints, source-safety class, blockers, and readiness. |
-| Auxillaries UX accessibility and responsive proof | Gate 8 | Auxillaries components, focused Jest/Playwright/a11y evidence | pending | Guided low-detail and expandable audit UX works across Profile, Connects, Interfaces, Wallet/BTD, and organization panes. |
-| Auxillaries telemetry proof and recovery runs | Gate 9 | Telemetry/proof packages, recovery routes, readback tests | pending | Profile, connection, interface, wallet, BTD, organization, policy, readiness, and recovery events emit source-safe proof hooks. |
+| Interfaces pane admission and cross-surface contracts | Gate 7 | Interfaces pane, API/MCP/ChatGPT App interface records, tests | closed | Interface admission records name auth mode, supported actions, policy constraints, source-safety class, blockers, and readiness. |
+| Auxillaries UX accessibility and responsive proof | Gate 8 | Auxillaries components, focused Jest/Playwright/a11y evidence | closed | Guided low-detail and expandable audit UX works across Profile, Connects, Interfaces, Wallet/BTD, and organization panes. |
+| Auxillaries telemetry proof and recovery runs | Gate 9 | `packages/api/src/routes/auxillaries-contract.ts`, `/api/auxillaries/data`, `useUserData`, Externals UI, route/API/UI tests, Gate 9 checker | closed | Profile, connection, interface, wallet, BTD, organization, policy, readiness, and recovery events emit source-safe proof hooks. |
 | Promotion readiness | Gate 10 | V31 promotion workflow, generated `.bitcode/v31-*`, `BITCODE_SPEC_V31_PROVEN.md` | pending | `version/v31` can promote to `main` only after all V31 gates pass and promotion automation commits generated canon. |
 
 ## V31 implementation checklist
@@ -154,9 +154,9 @@ No `_legacy/` source is active source truth.
 
 | Requirement | Source evidence | Current V31 judgment |
 | --- | --- | --- |
-| Auxillaries telemetry subjects are typed | telemetry/proof hook package and tests | pending |
-| Recovery runs are executions with source-safe before/after evidence | recovery route/UI readback tests | pending |
-| Proof hooks bind theorem, replay, evidence, telemetry, blocker, and repair outcome roots | proof-hook tests and generated artifact | pending |
+| Auxillaries telemetry subjects are typed | `AuxillariesTelemetrySubject` and `AuxillariesTelemetryProofHook` in `packages/api/src/routes/auxillaries-contract.ts`; `packages/api/src/routes/__tests__/auxillaries-contract.test.ts` asserts all required subjects | closed |
+| Recovery runs are executions with source-safe before/after evidence | `AuxillariesRecoveryRun` carries blocker id, retry policy, before/after roots, execution id, evidence root, telemetry root, outcome, and source-safety class; route/UI tests read those records | closed |
+| Proof hooks bind theorem, replay, evidence, telemetry, blocker, and repair outcome roots | `buildAuxillariesTelemetryProofHooks` derives hooks from profile, account, provider, interface, wallet, BTD, organization, policy, readiness, and recovery objects; Externals renders compact source-safe hook readback | closed |
 
 ## Gate 10 Parity
 

SPECIFICATIONS_ROADMAP.md

@@ -5,7 +5,7 @@
 - Current active canonical pointer: `BITCODE_SPEC.txt` -> `V30`
 - Current active canon: `BITCODE_SPEC_V30.md`
 - Current draft target: `BITCODE_SPEC_V31.md`
-- Current working gate: V31 Gate 8 Auxillaries UX Accessibility And Responsive Proof, which makes the Auxillaries support plane low-detail by default with a named main landmark, keyboard skip link, named pane navigation, active-pane state announcements, expandable audit detail, responsive mobile/desktop layout, focus/label/contrast posture, and reduced-motion proof.
+- Current working gate: V31 Gate 9 Auxillaries Telemetry Proof And Recovery Runs, which binds Profile, account, provider connection, interface admission, Wallet, BTD pane, organization authority, policy decision, readiness diagnostic, and recovery-run subjects to source-safe theorem/replay/evidence/telemetry proof hooks and UI readback.
 - Purpose: concise running index of Bitcode/ENGI specification history, current work, and planned work.
 
 This roadmap is not an active system specification.

package.json

@@ -72,6 +72,7 @@
     "check:v31-gate6": "node scripts/check-v31-gate6-organization-team-role-policy-authority.mjs",
     "check:v31-gate7": "node scripts/check-v31-gate7-interfaces-pane-admission-cross-surface-contracts.mjs",
     "check:v31-gate8": "node scripts/check-v31-gate8-auxillaries-ux-accessibility-responsive-proof.mjs",
+    "check:v31-gate9": "node scripts/check-v31-gate9-auxillaries-telemetry-proof-recovery-runs.mjs",
     "check:spec-quality": "node scripts/run-bitcode-spec-quality.mjs --mode basic",
     "check:spec-quality:title": "node scripts/run-bitcode-spec-quality.mjs --mode strict-from-title",
     "check:spec-quality:v24": "node scripts/run-bitcode-spec-quality.mjs --mode strict-version --version V24",

packages/api/README.md

@@ -23,8 +23,9 @@ objects must be built through `buildAuxillariesContractSnapshot` and
 `AuxillariesProfileState`, `AuxillariesConnectionReadiness`,
 `AuxillariesInterfaceAdmission`, `AuxillariesWalletBtdPaneState`,
 `OrganizationPolicyAuthority`, `AuxillariesReadinessDiagnostic`, and
-`AuxillariesRecoveryRun` values. They redact provider tokens, API keys, wallet
-secrets, private prompts, protected source, service keys, and database
+`AuxillariesRecoveryRun` values, plus source-safe
+`AuxillariesTelemetryProofHook` records. They redact provider tokens, API keys,
+wallet secrets, private prompts, protected source, service keys, and database
 credentials before UI, telemetry, or proof-hook consumption.
 
 Profile/account state is also package-owned. `AuxillariesProfileState` binds
@@ -39,7 +40,11 @@ classifies provider id/name, installation state, credential posture, token
 presence, scopes, last readback, blocker, repair action, source-safe metadata,
 and a readiness root. Routes may validate credentials privately, but API
 responses, UI metadata, telemetry, and recovery proof hooks must only serialize
-classified readiness and `AuxillariesRecoveryRun` before/after roots.
+classified readiness and `AuxillariesRecoveryRun` before/after roots. Gate 9
+telemetry hooks bind each support subject to theorem id, replay step id,
+evidence root, telemetry root, source-safety class, blocker, and repair outcome
+so Auxillaries readback can be audited without exposing credentials or
+protected source.
 
 Wallet/BTD support state is package-owned through `@bitcode/btd` and mapped
 here as `AuxillariesWalletBtdPaneState`. Route payloads may include wallet

packages/api/src/routes/__tests__/auxillaries-contract.test.ts

@@ -322,6 +322,31 @@ describe('Auxillaries package route contracts', () => {
       expect(admission.interfaceAdmissionRoot).toMatch(/^[0-9a-f]{64}$/);
       expect(admission.policyConstraints).toEqual(admission.policyRequirements);
     }
+    const telemetrySubjects = payload.telemetryProofHooks.map((hook) => hook.subject);
+    expect(telemetrySubjects).toEqual(expect.arrayContaining([
+      'profile',
+      'account',
+      'provider_connection',
+      'interface_admission',
+      'wallet',
+      'btd_pane',
+      'organization_authority',
+      'policy_decision',
+      'readiness_diagnostic',
+    ]));
+    for (const hook of payload.telemetryProofHooks) {
+      expect(hook).toMatchObject({
+        kind: 'AuxillariesTelemetryProofHook',
+        sourceSafetyClass: 'source_safe',
+      });
+      expect(hook.theoremId).toMatch(/^auxillaries\./);
+      expect(hook.replayStepId.length).toBeGreaterThan(0);
+      expect(hook.evidenceRoot.length).toBeGreaterThan(0);
+      expect(hook.telemetryRoot).toMatch(/^[0-9a-f]{64}$/);
+      expect(hook.proofRoot).toMatch(/^[0-9a-f]{64}$/);
+    }
+    expect(payload.auxillariesContract.telemetryProofHooks)
+      .toEqual(payload.telemetryProofHooks);
     expect(payload.auxillariesContract.contractVersion).toBe(AUXILLARIES_CONTRACT_VERSION);
     expect(validateAuxillariesContractSnapshot(payload.auxillariesContract)).toEqual({
       valid: true,
@@ -334,6 +359,7 @@ describe('Auxillaries package route contracts', () => {
     expect(JSON.stringify(payload)).not.toContain('wallet-secret');
     expect(JSON.stringify(payload)).not.toContain('repository source');
     expect(JSON.stringify(payload)).not.toContain('private prompt body');
+    expect(JSON.stringify(payload.telemetryProofHooks)).not.toContain('provider-token');
     expect(JSON.stringify(payload.walletBtdPaneState)).not.toContain('asset pack source');
     expect(JSON.stringify(payload.connectionReadiness[0].metadata)).not.toContain('provider-token');
     expect(assertAuxillariesJsonSafe(payload)).toBeUndefined();
@@ -398,10 +424,14 @@ describe('Auxillaries package route contracts', () => {
     const recoveryRun = buildAuxillariesRecoveryRun({
       targetPane: 'externals',
       repairAction: 'reauthorize_provider',
+      blockerId: 'connects.github.reauthorize_provider',
       beforeReadinessRoot: 'before-root',
       afterReadinessRoot: 'after-root',
       executionId: 'execution-1',
       outcome: 'succeeded',
+      retryPolicy: 'after_repair',
+      startedAt: '2026-05-21T00:00:00.000Z',
+      completedAt: '2026-05-21T00:01:00.000Z',
     });
     const payload = buildAuxillaryDataPayload({
       profile: { id: 'user-2', username: 'reviewer' },
@@ -414,15 +444,59 @@ describe('Auxillaries package route contracts', () => {
       btcFeeBalance: null,
       recentBtdAssetPacks: [],
       modelPreferences: null,
+      recoveryRuns: [recoveryRun],
       onboardedSteps: ['profile'],
     });
-    const snapshot = {
-      ...payload.auxillariesContract,
-      recoveryRuns: [recoveryRun],
-    };
+    const snapshot = payload.auxillariesContract;
 
     expect(parseAuxillariesContractSnapshot(snapshot).recoveryRuns[0].recoveryRoot)
       .toMatch(/^[0-9a-f]{64}$/);
+    expect(snapshot.recoveryRuns[0]).toMatchObject({
+      blockerId: 'connects.github.reauthorize_provider',
+      retryPolicy: 'after_repair',
+      sourceSafetyClass: 'source_safe',
+    });
+    expect(snapshot.recoveryRuns[0].evidenceRoot).toMatch(/^[0-9a-f]{64}$/);
+    expect(snapshot.recoveryRuns[0].telemetryRoot).toMatch(/^[0-9a-f]{64}$/);
+    expect(snapshot.telemetryProofHooks).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({
+          subject: 'recovery_run',
+          subjectId: 'execution-1',
+          pane: 'externals',
+          theoremId: 'auxillaries.recovery_run.execution_evidence',
+          evidenceRoot: recoveryRun.evidenceRoot,
+          telemetryRoot: recoveryRun.telemetryRoot,
+          blockerId: 'connects.github.reauthorize_provider',
+          repairOutcome: 'succeeded',
+          sourceSafetyClass: 'source_safe',
+        }),
+      ]),
+    );
+    expect(validateAuxillariesContractSnapshot({
+      ...snapshot,
+      telemetryProofHooks: [
+        {
+          ...snapshot.telemetryProofHooks[0],
+          subject: 'unknown_subject',
+        },
+      ],
+    })).toMatchObject({
+      valid: false,
+      errors: expect.arrayContaining(['telemetryProofHooks[0].subject is invalid']),
+    });
+    expect(validateAuxillariesContractSnapshot({
+      ...snapshot,
+      recoveryRuns: [
+        {
+          ...snapshot.recoveryRuns[0],
+          outcome: 'unknown_outcome',
+        },
+      ],
+    })).toMatchObject({
+      valid: false,
+      errors: expect.arrayContaining(['recoveryRuns[0].outcome is invalid']),
+    });
     expect(JSON.stringify(snapshot.recoveryRuns)).not.toContain('access_token');
     expect(JSON.stringify(snapshot.recoveryRuns)).not.toContain('oauth_token');
     expect(validateAuxillariesContractSnapshot({ kind: 'wrong' })).toMatchObject({