Merge pull request #40 from engineeredsoftware/v30/gate-8-protocol-telemetry-proof-hooks

V30 Gate 8: Protocol Telemetry And Proof Hooks

Author: geraldarthurdavis

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

@@ -86,6 +86,7 @@ jobs:
             node scripts/check-v30-gate5-testnet-ledger-projection-hardening.mjs --skip-branch-check
             node scripts/check-v30-gate6-source-to-shares-proof-cleanup.mjs --skip-branch-check
             node scripts/check-v30-gate7-bridge-readiness-research-boundaries.mjs --skip-branch-check
+            node scripts/check-v30-gate8-protocol-telemetry-proof-hooks.mjs --skip-branch-check
           else
             echo "Unexpected BITCODE_SPEC.txt pointer: $POINTER" >&2
             exit 1

BITCODE_SPEC_V30.md

@@ -205,7 +205,7 @@ V30 closes through ten gates:
 5. **Gate 5: Testnet Ledger Projection Hardening** hardens ledger/database/object-storage projection, repair classes, and staging-testnet readback.
 6. **Gate 6: Source-To-Shares Proof Cleanup** cleans contribution measurement, settlement conservation, zero-cell/refit tail, ancestry, and no-overpayment/no-underpayment proof.
 7. **Gate 7: Bridge Readiness Research Boundaries** records bridge research without admitting any bridge as chain-of-record truth.
-8. **Gate 8: Protocol Telemetry And Proof Hooks** adds source-safe telemetry and proof hooks for receipts, fee states, projection, and source-to-shares facts.
+8. **Gate 8: Protocol Telemetry And Proof Hooks** adds source-safe telemetry and proof hooks for receipts, fee states, projection, source-to-shares facts, and bridge-readiness posture.
 9. **Gate 9: Interface Integration And Regression Proof** proves current interfaces consume package-owned objects without V29 behavior regression.
 10. **Gate 10: V30 Promotion Readiness** validates local/staging proof, generated artifacts, V30 promotion workflow support, and post-promotion V30 active / V31 draft posture.
 
@@ -262,6 +262,31 @@ Gate 7 bridge-readiness research boundaries:
   research evidence, but they must fail closed on any payload attempting to
   set `chainOfRecordAdmitted` or to mark a bridge as current BTD truth.
 
+Gate 8 Protocol telemetry proof hooks:
+
+- `BtdProtocolTelemetryEnvelope` is the package-owned source-safe carrier for
+  Protocol/BTD observability that V32 provation and V35 documentation can
+  replay without reading protected source or secrets.
+- `BtdProtocolTelemetryRecord` rows cover exactly these V30 subjects:
+  `btd_receipt`, `btc_fee_state`, `ledger_projection`,
+  `source_to_shares_proof`, and `bridge_readiness_posture`.
+- `BtdProtocolProofHook` binds each record to theorem ids, replay step ids,
+  witness artifact paths, optional generated artifact paths, the evidence root,
+  and the telemetry root.
+- Telemetry events must match subject kinds; a BTC fee event cannot be emitted
+  as a receipt, a ledger projection cannot be emitted as a bridge posture, and
+  every mismatch fails closed.
+- Telemetry metadata is scalar and source-safe. Payloads with protected source,
+  private source text, API keys, service-role keys, JWT-looking secrets, or
+  private keys fail closed before becoming Terminal, API, or generated proof
+  evidence.
+- The BTD API exposes `/btd/protocol-telemetry` as the source-safe boundary for
+  these records. It returns a Terminal journal `proof_admission` entry and does
+  not commit generated proof artifacts or source-bearing material.
+- Gate 8 creates the generated-artifact inventory slot
+  `.bitcode/v30-protocol-telemetry-proof-hooks.json`; promotion may generate
+  it only from source-safe telemetry/proof-hook facts.
+
 ## V30 whole Bitcode operator chain
 
 The V30 Terminal operator chain is:
@@ -783,6 +808,7 @@ V30 continues operator-quality proof: Terminal workflow claims must be backed by
 | `.bitcode/v30-spec-family-report.json` | yes | yes | validates the hand-authored V30 family shape |
 | `.bitcode/v30-canonical-input-report.json` | yes | yes | records canonical input closure for active V29 plus V30 draft |
 | `.bitcode/v30-canon-posture-drift-report.json` | gate-dependent | yes | proves runtime/docs active/draft posture |
+| `.bitcode/v30-protocol-telemetry-proof-hooks.json` | gate-dependent | yes | records source-safe Protocol telemetry and proof-hook inventory for provation/documentation |
 | `BITCODE_SPEC_V30_PROVEN.md` | no | yes | generated proof appendix for promoted V30 |
 
 ### V30 specifying generated artifacts

BITCODE_SPEC_V30_DELTA.md

@@ -277,6 +277,24 @@ Closure acceptance:
 - telemetry avoids protected source and secrets;
 - proof hooks are compatible with V32 provation and V35 documentation/observability work.
 
+Gate 8 implementation centers:
+
+- `packages/btd/src/telemetry.ts` owns `BtdProtocolTelemetryEnvelope`,
+  `BtdProtocolTelemetryRecord`, `BtdProtocolProofHook`, source-safety checks,
+  event/subject matching, and V32/V35 proof compatibility markers.
+- `packages/btd/src/api-boundaries.ts` owns
+  `buildBtdProtocolTelemetrySettlement`, binding telemetry envelopes into a
+  Terminal journal `proof_admission` row without committing source-bearing
+  artifacts.
+- `packages/api/src/routes/btd-crypto.ts` and
+  `/btd/protocol-telemetry` expose the JSON-safe route boundary.
+- `packages/btd/__tests__/telemetry.test.ts` and the BTD crypto route tests
+  prove typed emission, source/secret rejection, proof-hook replay facts, and
+  route JSON safety.
+- `.bitcode/v30-protocol-telemetry-proof-hooks.json` is reserved as a
+  generated source-safe inventory artifact for promotion proof; it is not a
+  protected-source carrier.
+
 ### Gate 9: Interface Integration And Regression Proof
 
 Gate 9 proves existing interfaces can consume the hardened Protocol/BTD rails.

BITCODE_SPEC_V30_NOTES.md

@@ -231,6 +231,26 @@ No Gate 7 code may mint, wrap, transfer, settle, or unlock BTD through a bridge.
 The only current chain-of-record posture is `bitcoin_btd_registry` plus
 `no_bridge_chain_of_record`.
 
+## Gate 8 Protocol telemetry notes
+
+Gate 8 turns Protocol/BTD observability into package-owned typed telemetry
+instead of leaving receipts, fee states, ledger projections, source-to-shares
+proofs, and bridge-readiness posture as unrelated payload fragments.
+
+The accepted implementation is `BtdProtocolTelemetryEnvelope` in
+`packages/btd/src/telemetry.ts`. It contains source-safe telemetry records and
+`BtdProtocolProofHook` rows that name theorem ids, replay step ids, witness
+artifact paths, generated artifact paths, evidence roots, and telemetry roots.
+The envelope is compatible with V32 provation and V35 documentation/
+observability because it carries replayable source-safe proof facts without
+requiring protected source.
+
+Gate 8 rejects event/subject mismatches and secret-shaped metadata before a row
+can reach Terminal, API, generated proof, or persistence surfaces. The API
+boundary exposes `/btd/protocol-telemetry` as a JSON-safe proof-admission route;
+it does not commit source-bearing artifacts, and it does not replace existing
+crypto telemetry rows used for deployment readiness health.
+
 ## Gate 1 working notes
 
 Gate 1 is complete only when the V30 family exists, validates in draft mode over active V29, and makes the roadmap truthful enough to drive V31 through V37 without stale V27/V28/V29 posture.

BITCODE_SPEC_V30_PARITY_MATRIX.md

@@ -61,7 +61,7 @@ No `_legacy/` source is active source truth.
 | Testnet ledger projection hardening | Gate 5 | `packages/btd/src/reconciliation.ts`, API route tests, asset-pack harness evidence, Terminal journal reconciliation UI/tests, gate checker | drafted | Ledger/database/object-storage/private facts are distinct; staging-testnet readback is secret-free; drift, quarantine, retry, and unlock blocking are tested. |
 | Source-to-shares proof cleanup | Gate 6 | `packages/btd/src/source-to-shares.ts`, API route boundary, focused BTD/API tests, gate checker | drafted | Measurement contribution, fee allocation, zero-cell/refit tail, ancestry evidence, and conservation invariants are testable. |
 | Bridge-readiness research boundaries | Gate 7 | `packages/btd/src/bridge-readiness.ts`, BTD/API tests, route boundary, docs, gate checker | drafted | Bridge paths are typed research-only records until admitted by explicit future proof and policy. |
-| Protocol telemetry/proof hooks | Gate 8 | telemetry schema, proof hooks, generated-artifact inventory, tests | pending | Receipts, fee states, projections, and source-to-shares facts emit source-safe telemetry and proof hooks. |
+| Protocol telemetry/proof hooks | Gate 8 | `packages/btd/src/telemetry.ts`, API route boundary, focused BTD/API tests, gate checker | drafted | Receipts, fee states, projections, source-to-shares proofs, and bridge-readiness posture emit source-safe telemetry and proof hooks. |
 | Interface integration regression | Gate 9 | Terminal/API/MCP/ChatGPT App adapters and tests | pending | Existing interfaces consume package-owned objects without regressing V29 behavior. |
 | Promotion readiness | Gate 10 | V30 promotion workflow, generated `.bitcode/v30-*`, `BITCODE_SPEC_V30_PROVEN.md` | pending | `version/v30` can promote to `main` only after all V30 checks pass and promotion automation can commit generated canon. |
 
@@ -210,6 +210,25 @@ No `_legacy/` source is active source truth.
 - Gate 7 may expose source-safe research posture to Terminal/API callers for operator review.
 - Gate 7 does not promote V30 or change the active canon pointer.
 
+## Gate 8 Parity
+
+| Requirement | Source evidence | Current V30 judgment |
+| --- | --- | --- |
+| Protocol telemetry is package-owned | `packages/btd/src/telemetry.ts`, `packages/btd/src/index.ts` | drafted |
+| Receipt, BTC fee, ledger projection, source-to-shares, and bridge-readiness subjects are typed | `BTD_PROTOCOL_TELEMETRY_SUBJECT_KINDS`, `packages/btd/__tests__/telemetry.test.ts` | drafted |
+| Telemetry rows and proof hooks reject protected source and secrets | `sourceSafety`, metadata source-safety tests | drafted |
+| Proof hooks carry theorem, replay, witness, generated artifact, evidence, and telemetry roots | `BtdProtocolProofHook`, `buildBtdProtocolProofHook`, focused tests | drafted |
+| API and Terminal boundary expose JSON-safe proof-admission telemetry | `buildBtdProtocolTelemetrySettlement`, `buildPostBtdProtocolTelemetryRoute`, `uapi/app/api/btd/protocol-telemetry/route.ts` | drafted |
+| Gate checker protects telemetry/proof-hook boundaries | `scripts/check-v30-gate8-protocol-telemetry-proof-hooks.mjs`, `pnpm run check:v30-gate8`, gate-quality workflow | drafted |
+
+## Gate 8 accepted boundaries
+
+- Gate 8 does not expose protected source, prompt bodies, private source text, private keys, service-role keys, OpenAI keys, JWT-looking secrets, or database passwords in telemetry.
+- Gate 8 does not replace deployment-readiness crypto telemetry persistence; it adds Protocol/BTD source-safe proof hooks that later V32 and V35 work can consume.
+- Gate 8 does not generate promotion artifacts yet; it reserves `.bitcode/v30-protocol-telemetry-proof-hooks.json` as a source-safe generated inventory.
+- Gate 8 may expose telemetry/proof hooks to Terminal/API callers for operator review.
+- Gate 8 does not promote V30 or change the active canon pointer.
+
 ## completion condition
 
 Gate 1 is complete when the V30 draft family validates, `check:v30-gate1` passes, workflow posture is V30-aware, README and roadmap reflect V30 initiation, V31-V37 scopes are current enough to guide future gates, diff hygiene passes, and the gate branch is committed and pushed for review into `version/v30`.

package.json

@@ -61,6 +61,7 @@
     "check:v30-gate5": "node scripts/check-v30-gate5-testnet-ledger-projection-hardening.mjs",
     "check:v30-gate6": "node scripts/check-v30-gate6-source-to-shares-proof-cleanup.mjs",
     "check:v30-gate7": "node scripts/check-v30-gate7-bridge-readiness-research-boundaries.mjs",
+    "check:v30-gate8": "node scripts/check-v30-gate8-protocol-telemetry-proof-hooks.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/src/routes/__tests__/btd-crypto.test.ts

@@ -25,9 +25,11 @@ import {
   buildBtdLicensedReadRevenueSettlement,
   buildBtdMintDraft,
   buildBtdOrganizationInterfaceAuthorityDecision,
+  buildBtdProtocolTelemetrySettlement,
   buildBtdReadAccessDecision,
   buildBtdSourceToSharesProofSettlement,
   buildBtdTerminalJournalSettlement,
+  buildBtdProtocolTelemetryRecord,
   buildBtcFeeQuote,
   createBtdMeasureMintState,
 } from '@bitcode/btd';
@@ -43,6 +45,7 @@ import {
   buildPostBtdLicensedReadRevenueRoute,
   buildPostBtdMintDraftRoute,
   buildPostBtdOrganizationInterfaceAuthorityRoute,
+  buildPostBtdProtocolTelemetryRoute,
   buildPostBtdReadAccessRoute,
   buildPostBtdSourceToSharesProofRoute,
   buildPostBtdTerminalJournalRoute,
@@ -217,6 +220,45 @@ function bridgeReadinessResearchBody(overrides: Record<string, unknown> = {}) {
   };
 }
 
+function protocolTelemetryBody(overrides: Record<string, unknown> = {}) {
+  const telemetry = {
+    event: 'btd.source_to_shares_proof.emitted' as const,
+    subjectKind: 'source_to_shares_proof' as const,
+    subjectId: 'source-to-shares-api-1',
+    root: 'source-to-shares-api-root',
+    receiptRoot: 'source-to-shares-api-receipt-root',
+    proofRoot: 'source-to-shares-api-proof-root',
+    artifactPath: '.bitcode/source-to-shares-api-proof.json',
+    metadata: {
+      sourceSafe: true,
+      settlementAdmissible: true,
+    },
+    issuedAt,
+  };
+  const record = buildBtdProtocolTelemetryRecord(telemetry);
+
+  return {
+    telemetry: [telemetry],
+    proofHooks: [
+      {
+        proofFamily: 'source_to_shares' as const,
+        subjectKind: 'source_to_shares_proof' as const,
+        subjectId: 'source-to-shares-api-1',
+        evidenceRoot: 'source-to-shares-api-root',
+        telemetryRoot: record.telemetryRoot,
+        theoremIds: ['source-safe', 'settlement-conserved'],
+        replayStepIds: ['emit-telemetry', 'bind-source-to-shares-proof'],
+        witnessArtifactPaths: ['.bitcode/source-to-shares-api-proof.json'],
+        generatedArtifactPath: '.bitcode/generated/source-to-shares-api-proof.json',
+        issuedAt,
+      },
+    ],
+    exchangeSequence: '20',
+    issuedAt,
+    ...overrides,
+  };
+}
+
 describe('BTD crypto API builders', () => {
   it('builds a deterministic mint draft from accepted Read-Fit semantic units', () => {
     const draft = buildBtdMintDraft(mintDraftInput());
@@ -1002,6 +1044,32 @@ describe('BTD crypto API builders', () => {
     expect(settlement.terminalJournalEntry.receiptRoots).toContain(settlement.posture.proofRoot);
   });
 
+  it('builds Protocol telemetry settlements with source-safe proof hooks', () => {
+    const settlement = buildBtdProtocolTelemetrySettlement({
+      actorId: 'user-1',
+      ...protocolTelemetryBody(),
+      exchangeSequence: 20n,
+    } as any);
+
+    expect(settlement.kind).toBe('btd_protocol_telemetry_settlement');
+    expect(settlement.committed).toBe(false);
+    expect(settlement.envelope.compatibleWith).toEqual(['V32', 'V35']);
+    expect(settlement.envelope.sourceSafety.sourceSafe).toBe(true);
+    expect(settlement.envelope.telemetry[0]).toMatchObject({
+      event: 'btd.source_to_shares_proof.emitted',
+      subjectKind: 'source_to_shares_proof',
+    });
+    expect(settlement.envelope.telemetry[0].sourceSafety.containsProtectedSource).toBe(false);
+    expect(settlement.envelope.proofHooks[0]).toMatchObject({
+      proofFamily: 'source_to_shares',
+      subjectKind: 'source_to_shares_proof',
+    });
+    expect(settlement.terminalJournalEntry.transactionKind).toBe('proof_admission');
+    expect(settlement.terminalJournalEntry.receiptRoots).toContain(
+      settlement.envelope.telemetryRoot,
+    );
+  });
+
   it('builds deployment readiness, telemetry, and upgrade settlements', () => {
     const readiness = buildBtdDeploymentReadinessSettlement({
       actorId: 'user-1',
@@ -1592,6 +1660,28 @@ describe('BTD crypto API builders', () => {
     expect(body.terminalJournalEntry.exchangeSequence).toBe('19');
   });
 
+  it('returns JSON-safe Protocol telemetry proof hooks from the route boundary', async () => {
+    const route = buildPostBtdProtocolTelemetryRoute({
+      resolveAuthenticatedUser: async () => ({ userId: 'user-1' }),
+    });
+    const response = await route(
+      new Request('https://bitcode.test/api/btd/protocol-telemetry', {
+        method: 'POST',
+        body: JSON.stringify(protocolTelemetryBody()),
+      }),
+    );
+    const body = await response.json();
+
+    expect(response.status).toBe(200);
+    expect(body.kind).toBe('btd_protocol_telemetry_settlement');
+    expect(body.committed).toBe(false);
+    expect(body.envelope.compatibleWith).toEqual(['V32', 'V35']);
+    expect(body.envelope.sourceSafety.containsSecret).toBe(false);
+    expect(body.envelope.telemetry[0].event).toBe('btd.source_to_shares_proof.emitted');
+    expect(body.envelope.proofHooks[0].proofFamily).toBe('source_to_shares');
+    expect(body.terminalJournalEntry.exchangeSequence).toBe('20');
+  });
+
   it('returns JSON-safe deployment readiness settlements and persists telemetry or upgrades', async () => {
     const insertCryptoTelemetryEvent = jest.fn(async (row) => ({
       event: row.event,

packages/api/src/routes/btd-crypto.ts

@@ -26,6 +26,8 @@ import {
   type BtdMintDraft,
   type BtdMintDraftInput,
   type BtdOrganizationInterfaceAuthorityRouteInput,
+  type BtdProtocolTelemetryBoundaryInput,
+  type BtdProtocolTelemetrySettlement,
   type BtdReadAccessInput,
   type BtdReadAccessDecision,
   type BtdReadLicense,
@@ -49,6 +51,7 @@ import {
   buildBtdLicensedReadRevenueSettlement,
   buildBtdMintDraft,
   buildBtdOrganizationInterfaceAuthorityDecision,
+  buildBtdProtocolTelemetrySettlement,
   buildBtdReadAccessDecision,
   buildBtdRegistrySnapshot,
   buildBtdSourceToSharesProofSettlement,
@@ -72,6 +75,7 @@ export {
   buildBtdLicensedReadRevenueSettlement,
   buildBtdMintDraft,
   buildBtdOrganizationInterfaceAuthorityDecision,
+  buildBtdProtocolTelemetrySettlement,
   buildBtdReadAccessDecision,
   buildBtdRegistrySnapshot,
   buildBtdSourceToSharesProofSettlement,
@@ -638,6 +642,39 @@ export function buildPostBtdBridgeReadinessResearchRoute(options: BtdRouteOption
   });
 }
 
+export function buildPostBtdProtocolTelemetryRoute(options: BtdRouteOptions = {}) {
+  return traceRoute('/btd/protocol-telemetry', async (request: Request) => {
+    const user = await (options.resolveAuthenticatedUser ?? defaultResolveAuthenticatedUser)(
+      request,
+    );
+    if (!user) {
+      return createJsonResponse({ error: 'Unauthorized' }, 401);
+    }
+
+    let body: Omit<BtdProtocolTelemetryBoundaryInput, 'actorId' | 'exchangeSequence'> & {
+      exchangeSequence: string | number;
+    };
+    try {
+      body = await request.json();
+    } catch {
+      return createJsonResponse({ error: 'Invalid JSON body' }, 400);
+    }
+
+    let settlement: BtdProtocolTelemetrySettlement;
+    try {
+      settlement = buildBtdProtocolTelemetrySettlement({
+        ...body,
+        actorId: user.userId,
+        exchangeSequence: parseBtdRequiredBigInt(body.exchangeSequence, 'exchangeSequence'),
+      });
+    } catch (error) {
+      return createJsonResponse({ error: toBadRequestMessage(error) }, 400);
+    }
+
+    return createJsonResponse(toJsonSafe(settlement));
+  });
+}
+
 export function buildPostBtdDeploymentReadinessRoute(options: BtdRouteOptions = {}) {
   return traceRoute('/btd/deployment-readiness', async (request: Request) => {
     const user = await (options.resolveAuthenticatedUser ?? defaultResolveAuthenticatedUser)(
@@ -699,6 +736,7 @@ export const postBtdLedgerDatabaseReconciliation =
   buildPostBtdLedgerDatabaseReconciliationRoute();
 export const postBtdSourceToSharesProof = buildPostBtdSourceToSharesProofRoute();
 export const postBtdBridgeReadinessResearch = buildPostBtdBridgeReadinessResearchRoute();
+export const postBtdProtocolTelemetry = buildPostBtdProtocolTelemetryRoute();
 export const postBtdDeploymentReadiness = buildPostBtdDeploymentReadinessRoute();
 
 function toBadRequestMessage(error: unknown): string {