Merge pull request #36 from engineeredsoftware/v30/gate-4-btd-assetpack-mint-read-receipts

V30 Gate 4: BTD AssetPack Mint And Read Receipts

Author: geraldarthurdavis

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

@@ -82,6 +82,7 @@ jobs:
             node scripts/check-v30-gate1-roadmap-and-gating.mjs --skip-branch-check
             node scripts/check-v30-gate2-protocol-package-api-boundaries.mjs --skip-branch-check
             node scripts/check-v30-gate3-bitcoin-taproot-psbt-fee-rigor.mjs --skip-branch-check
+            node scripts/check-v30-gate4-btd-assetpack-mint-read-receipts.mjs --skip-branch-check
           else
             echo "Unexpected BITCODE_SPEC.txt pointer: $POINTER" >&2
             exit 1

BITCODE_SPEC_V30.md

@@ -209,6 +209,18 @@ V30 closes through ten gates:
 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.
 
+Gate 4 receipt precision:
+
+- Mint receipts are source-safe by construction. They may bind a paid unlock
+  root later, but their own `protectedSourceVisible` posture is always false.
+- Read receipts can represent preview, blocked, or paid-unlocked reading. Any
+  paid delivery admission must include a paid unlock root, delivery admission
+  root, read right, and ledger projection root.
+- Rights-transfer receipts require confirmed BTC fee finality before the BTD
+  right/license transfer can admit protected source visibility to the Reader.
+  Prepared, signed, broadcast, replaced, reorged, and failed fee receipts do
+  not unlock protected source.
+
 ## V30 whole Bitcode operator chain
 
 The V30 Terminal operator chain is:

BITCODE_SPEC_V30_DELTA.md

@@ -143,6 +143,30 @@ Closure acceptance:
 - protected source remains hidden before settlement;
 - receipts are stored, streamed, and rendered through existing execution and Terminal surfaces.
 
+Gate 4 implementation centers on `packages/btd/src/receipts.ts` and the
+package API boundary in `packages/btd/src/api-boundaries.ts`.
+`BtdAssetPackMintReceipt` extends mint evidence with depositor identity,
+source-safe preview root, Finding Fits result root, settlement conservation
+root, paid unlock root, delivery admission root, and ledger projection root.
+`BtdReadReceipt` records the Reader/Depositor boundary for source-safe preview
+or paid unlock and rejects protected source visibility before paid unlock.
+`BtdRightsTransferReceipt` requires confirmed BTC fee finality, a read license,
+paid unlock, delivery admission, range projection, and ledger projection before
+protected source can cross to the Reader.
+
+The Sandbox harness now stores typed mint/read receipt payloads in settlement
+evidence and emits receipt roots in readback telemetry. Terminal detail
+snapshots coerce mint/read/rights-transfer receipts from settlement payloads,
+and the Terminal transaction read model counts those receipts in closure and
+journal surfaces so operators can inspect them through the existing rich
+execution detail UI.
+
+Gate 4 evidence is covered by
+`packages/btd/__tests__/api-boundaries.test.ts`,
+`uapi/tests/terminalTransactionDetailSnapshot.test.ts`,
+`uapi/tests/terminalTransactionReadModel.test.ts`, and
+`scripts/check-v30-gate4-btd-assetpack-mint-read-receipts.mjs`.
+
 ### Gate 5: Testnet Ledger Projection Hardening
 
 Gate 5 hardens ledger/database/object-storage projection and repair.

BITCODE_SPEC_V30_NOTES.md

@@ -108,6 +108,35 @@ failure. Signed receipt advancement requires a signed PSBT. Broadcast,
 confirmed, replaced, and reorged observations require transaction id evidence.
 Server-custody signer posture remains rejected before PSBT handoff.
 
+## Gate 4 BTD AssetPack mint and read receipt notes
+
+Gate 4 moves BTD receipt posture from route/runtime convention into package
+owned primitives:
+
+- `BtdAssetPackMintReceipt` binds the deposited AssetPack id, BTD range,
+  depositor wallet, source manifest root, source-safe preview root, Finding
+  Fits result root, proof root, settlement conservation root, access policy,
+  and ledger projection root. It is always source-safe and never exposes
+  protected source.
+- `BtdReadReceipt` binds the Reader wallet, Depositor wallet, accepted Need
+  root, Finding Fits root, source-safe preview root, paid unlock state, read
+  right state, delivery admission state, and ledger projection root. It rejects
+  protected source visibility unless the read is paid-unlocked.
+- `BtdRightsTransferReceipt` binds the settled BTD range and read license to a
+  confirmed BTC fee receipt, paid unlock root, delivery admission root, ledger
+  anchor, ledger projection root, and Reader/Depositor identities. It is the
+  receipt boundary where protected source can become visible to the paying
+  Reader.
+
+The package API boundary exposes builders for mint receipts, read-receipt
+settlements, and rights-transfer receipts so API routes and harness code do not
+reimplement receipt policy. The Sandbox harness emits mint/read receipt payloads
+and receipt roots inside ledger settlement evidence; rights-transfer receipts
+remain absent until BTC fee finality is confirmed. Terminal detail snapshots
+coerce receipt payloads under camelCase or database-style snake_case keys, and
+the transaction read model counts receipt payloads in closure and journal
+availability.
+
 4. **Gate 4: BTD AssetPack Mint And Read Receipts**
    - Make BTD mint, read, and rights-transfer receipts typed, proof-rooted, stored, streamed, and source-safe.
 

BITCODE_SPEC_V30_PARITY_MATRIX.md

@@ -57,7 +57,7 @@ No `_legacy/` source is active source truth.
 | Roadmap truth | Gate 1 | `SPECIFICATIONS_ROADMAP.md`, README, PR template, workflow posture | drafted | Roadmap states V29 active, V30 draft, and coherent V31-V37 responsibilities. |
 | Protocol package API boundaries | Gate 2 | `packages/btd/src/api-boundaries.ts`, `packages/api/src/routes/btd-crypto.ts`, package READMEs/tests | drafted | Shared Protocol/BTD objects have package-owned builders, parsers, validators, JSON-safe serializers, and tests. |
 | Bitcoin Taproot PSBT fee rigor | Gate 3 | `packages/btd/src/btc-fee-operation.ts`, `packages/btd/src/bitcoin-fees.ts`, BTD/API tests, gate checker | drafted | BTC fee and signer states are typed, testnet/mainnet-safe, no-custody, Taproot/PSBT aware, and proof-rooted. |
-| BTD AssetPack mint/read receipts | Gate 4 | BTD receipt primitives, asset-pack postprocess, harness evidence, Terminal/API readback | pending | Mint, read, and rights-transfer receipts bind BTD range, preview, paid unlock, delivery, and ledger projection. |
+| BTD AssetPack mint/read receipts | Gate 4 | `packages/btd/src/receipts.ts`, `packages/btd/src/api-boundaries.ts`, asset-pack harness evidence, Terminal detail snapshot/read model tests, gate checker | drafted | Mint, read, and rights-transfer receipts bind BTD range, preview, paid unlock, delivery, and ledger projection. |
 | Testnet ledger projection hardening | Gate 5 | BTD reconciliation, Supabase readback, object-storage evidence, repair tests | pending | Ledger/database/object-storage projections are synchronized or blocked with deterministic repair posture. |
 | Source-to-shares proof cleanup | Gate 6 | BTD/source-to-shares proof primitives, settlement conservation tests | pending | Measurement contribution, fee allocation, zero-cell/refit tail, and conservation invariants are testable. |
 | Bridge-readiness research boundaries | Gate 7 | Protocol/BTD research notes, policy posture tests, docs | pending | Bridge paths are documented as research until admitted by explicit future proof and policy. |
@@ -93,6 +93,9 @@ No `_legacy/` source is active source truth.
 
 - Gate 1 does not implement Protocol/BTD package hardening.
 - Gate 1 does not create `BITCODE_SPEC_V30_PROVEN.md`.
+- Gate 1 does not promote `BITCODE_SPEC.txt` to V30.
+- Gate 1 may retarget workflows to active V29 / draft V30 so later gates are greenable.
+- Gate 1 may update roadmap scope for V31-V37 to align with V28/V29 promotion learning without opening those versions.
 
 ## Gate 2 Parity
 
@@ -132,9 +135,28 @@ No `_legacy/` source is active source truth.
 - Gate 3 does not implement a bridge chain-of-record path.
 - Gate 3 does not custody Reader private keys or sign PSBTs server-side.
 - Gate 3 does not replace later Gate 4 BTD mint, read, and rights-transfer receipts.
-- Gate 1 does not promote `BITCODE_SPEC.txt` to V30.
-- Gate 1 may retarget workflows to active V29 / draft V30 so later gates are greenable.
-- Gate 1 may update roadmap scope for V31-V37 to align with V28/V29 promotion learning without opening those versions.
+
+## Gate 4 Parity
+
+| Requirement | Source evidence | Current V30 judgment |
+| --- | --- | --- |
+| BTD package owns typed AssetPack mint, read, and rights-transfer receipts | `packages/btd/src/receipts.ts` exports `BtdAssetPackMintReceipt`, `BtdReadReceipt`, `BtdRightsTransferReceipt`, and their builders/assertions | drafted |
+| Receipts bind AssetPack ids, BTD ranges, Reader/Depositor identities, source-safe preview roots, paid unlock, delivery admission, and ledger projection roots | Receipt interfaces/builders require those roots and identities, with BTD range conservation checks | drafted |
+| Protected source remains hidden before paid unlock | `assertReadDisclosureBoundary` rejects protected source visibility before `paid_unlocked`; `BtdAssetPackMintReceipt` is always `source_safe_preview` | drafted |
+| Rights transfer requires confirmed BTC finality before protected source unlock | `buildBtdRightsTransferReceipt` and API-boundary tests require `btcFeeFinalityState: 'confirmed'` | drafted |
+| API boundary exposes package-owned receipt construction | `buildBtdMintDraft`, `buildBtdReadReceiptBoundarySettlement`, and `buildBtdAssetPackExchangeSettlement` compose receipt builders | drafted |
+| Sandbox harness stores and streams receipt evidence | `packages/pipeline-hosts/src/asset-pack-harness.ts` stores mint/read receipt payloads in ledger settlement evidence and emits receipt roots in readback telemetry | drafted |
+| Terminal renders receipt readback through existing detail surfaces | `terminal-transaction-detail-snapshot.ts` coerces receipt payloads and `terminal-transaction-read-model.ts` counts them in closure/journal sections | drafted |
+| Tests cover package and Terminal receipt posture | `packages/btd/__tests__/api-boundaries.test.ts`, `uapi/tests/terminalTransactionDetailSnapshot.test.ts`, and `uapi/tests/terminalTransactionReadModel.test.ts` | drafted |
+| Gate checker protects the receipt surface | `scripts/check-v30-gate4-btd-assetpack-mint-read-receipts.mjs`, `pnpm run check:v30-gate4`, gate-quality workflow | drafted |
+
+## Gate 4 accepted boundaries
+
+- Gate 4 does not require production-mainnet BTC settlement.
+- Gate 4 does not broadcast Bitcoin transactions or custody wallet keys.
+- Gate 4 does not make protected source visible before paid unlock and delivery admission.
+- Gate 4 does not harden all ledger/database/object-storage projection repair; Gate 5 owns that.
+- Gate 4 does not finish source-to-shares contribution cleanup; Gate 6 owns that.
 
 ## completion condition
 

package.json

@@ -57,6 +57,7 @@
     "check:v30-gate1": "node scripts/check-v30-gate1-roadmap-and-gating.mjs",
     "check:v30-gate2": "node scripts/check-v30-gate2-protocol-package-api-boundaries.mjs",
     "check:v30-gate3": "node scripts/check-v30-gate3-bitcoin-taproot-psbt-fee-rigor.mjs",
+    "check:v30-gate4": "node scripts/check-v30-gate4-btd-assetpack-mint-read-receipts.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/btd/README.md

@@ -11,6 +11,10 @@ This package owns:
 - contributor allocation, access evaluation, ancestry review, and revenue routing
 - wallet-signed BTC fee receipts, ledger anchors, Exchange rights transfers,
   Terminal journals, reconciliation, telemetry, and upgrade receipts
+- typed AssetPack mint/read/rights-transfer receipts that bind BTD ranges,
+  Reader and Depositor identities, source-safe preview roots, paid unlock,
+  delivery admission, and ledger projection roots without leaking protected
+  source before settlement
 - BTC fee operation posture, including quote lifecycle, signer recovery,
   no-server-custody PSBT handoff, Taproot/script posture, broadcast/finality
   observation, replacement/reorg repair, and testnet/mainnet network policy
@@ -37,6 +41,8 @@ import {
   BTD_MAX_MINTABLE_SUPPLY,
   applyBtdMeasureMint,
   buildBtdMintDraft,
+  buildBtdReadReceiptBoundarySettlement,
+  buildBtdRightsTransferReceipt,
   buildBtdRegistrySnapshot,
   toBtdJsonSafe,
   calculateLlmBtcFeeEstimate,

packages/btd/__tests__/api-boundaries.test.ts

@@ -1,6 +1,8 @@
 import {
+  buildBtdAssetPackExchangeSettlement,
   buildBtdMintDraft,
   buildBtdReadAccessDecision,
+  buildBtdReadReceiptBoundarySettlement,
   buildBtdRegistrySnapshot,
   createBtdMeasureMintState,
   parseBtdOptionalBigInt,
@@ -38,10 +40,26 @@ describe('BTD API boundaries', () => {
       exchangeSequence: 1n,
       actorId: 'actor-boundary-1',
       issuedAt,
+      depositorWalletId: 'wallet-depositor-boundary',
+      sourceSafePreviewRoot: 'source-safe-preview-root-boundary',
+      findingFitsResultRoot: 'finding-fits-root-boundary',
+      settlementConservationRoot: 'settlement-conservation-root-boundary',
+      ledgerProjectionRoot: 'ledger-projection-root-boundary',
     });
 
     expect(draft.kind).toBe('btd_mint_draft');
     expect(draft.measureMint.tokenCount).toBe(10_500_000);
+    expect(draft.assetPackMintReceipt).toMatchObject({
+      kind: 'btd.asset_pack_mint_receipt',
+      depositorWalletId: 'wallet-depositor-boundary',
+      sourceSafePreviewRoot: 'source-safe-preview-root-boundary',
+      findingFitsResultRoot: 'finding-fits-root-boundary',
+      ledgerProjectionRoot: 'ledger-projection-root-boundary',
+      protectedSourceVisible: false,
+    });
+    expect(draft.terminalJournalEntry.receiptRoots).toContain(
+      draft.assetPackMintReceipt?.receiptRoot,
+    );
     expect(draft.terminalJournalEntry.transactionKind).toBe('asset_pack_mint');
     expect(draft.terminalJournalEntry.actorId).toBe('actor-boundary-1');
   });
@@ -119,4 +137,124 @@ describe('BTD API boundaries', () => {
     expect(decision.decision.decision).toBe('licensed_read');
     expect(decision.policyDisclosure.accessPolicyHash).toBe('policy-boundary-hash');
   });
+
+  it('binds source-safe read receipts and paid rights-transfer receipts at package boundaries', () => {
+    const preview = buildBtdReadReceiptBoundarySettlement({
+      actorId: 'actor-boundary-1',
+      assetPackId: 'asset-pack-boundary-1',
+      readId: 'read-boundary-1',
+      readRequestId: 'read-request-boundary-1',
+      acceptedNeedRoot: 'accepted-need-root-boundary',
+      findingFitsResultRoot: 'finding-fits-root-boundary',
+      readerWalletId: 'wallet-reader-boundary',
+      depositorWalletId: 'wallet-depositor-boundary',
+      rangeStart: 0,
+      rangeEndExclusive: 10,
+      sourceManifestRoot: 'source-root-boundary',
+      sourceSafePreviewRoot: 'source-safe-preview-root-boundary',
+      accessPolicyHash: 'policy-boundary-hash',
+      disclosureState: 'source_safe_preview',
+      readRightState: 'none',
+      deliveryAdmissionState: 'blocked',
+      ledgerProjectionRoot: 'ledger-projection-root-boundary',
+      exchangeSequence: 4n,
+      issuedAt,
+    });
+
+    expect(preview.readReceipt).toMatchObject({
+      kind: 'btd.read_receipt',
+      disclosureState: 'source_safe_preview',
+      deliveryAdmissionState: 'blocked',
+      protectedSourceVisible: false,
+      paidUnlockRoot: null,
+    });
+    expect(preview.terminalJournalEntry.transactionKind).toBe('read_submission');
+    expect(preview.terminalJournalEntry.receiptRoots).toContain(preview.readReceipt.receiptRoot);
+
+    expect(() =>
+      buildBtdReadReceiptBoundarySettlement({
+        ...preview.readReceipt,
+        actorId: 'actor-boundary-1',
+        exchangeSequence: 5n,
+        protectedSourceVisible: true,
+      }),
+    ).toThrow('Protected source cannot be visible before paid unlock.');
+
+    const created = buildBtdAssetPackExchangeSettlement({
+      action: 'create_order',
+      orderId: 'order-boundary-1',
+      orderKind: 'sell',
+      assetPackId: 'asset-pack-boundary-1',
+      rangeStart: 0,
+      rangeEndExclusive: 10,
+      makerWalletId: 'wallet-depositor-boundary',
+      priceSats: '1200',
+      accessPolicyHash: 'policy-boundary-hash',
+      createdAtExchangeSequence: 6n,
+      actorId: 'actor-boundary-1',
+      issuedAt,
+    });
+    const accepted = buildBtdAssetPackExchangeSettlement({
+      action: 'accept_order',
+      previousOrder: created.order,
+      takerWalletId: 'wallet-reader-boundary',
+      actorId: 'actor-boundary-1',
+      issuedAt,
+    });
+    const settled = buildBtdAssetPackExchangeSettlement({
+      action: 'settle_order',
+      previousOrder: accepted.order,
+      settledAtExchangeSequence: 7n,
+      ledgerAnchorId: 'ledger-anchor-boundary-1',
+      actorId: 'actor-boundary-1',
+      issuedAt,
+    });
+    const transferred = buildBtdAssetPackExchangeSettlement({
+      action: 'transfer_rights',
+      previousOrder: settled.order,
+      receiptId: 'legacy-transfer-boundary-1',
+      fromWalletId: 'wallet-depositor-boundary',
+      toWalletId: 'wallet-reader-boundary',
+      btcFeeReceiptId: 'btc-fee-boundary-1',
+      btcFeeFinalityState: 'confirmed',
+      readLicenseId: 'read-license-boundary-1',
+      sourceSafePreviewRoot: 'source-safe-preview-root-boundary',
+      paidUnlockRoot: 'paid-unlock-root-boundary',
+      deliveryAdmissionRoot: 'delivery-admission-root-boundary',
+      ledgerProjectionRoot: 'ledger-projection-root-boundary',
+      actorId: 'actor-boundary-1',
+      issuedAt,
+    });
+
+    expect(transferred.btdRightsTransferReceipt).toMatchObject({
+      kind: 'btd.rights_transfer_receipt',
+      readerWalletId: 'wallet-reader-boundary',
+      depositorWalletId: 'wallet-depositor-boundary',
+      btcFeeFinalityState: 'confirmed',
+      deliveryAdmissionState: 'admitted',
+      protectedSourceVisible: true,
+    });
+    expect(transferred.terminalJournalEntry.receiptRoots).toContain(
+      transferred.btdRightsTransferReceipt?.receiptRoot,
+    );
+
+    expect(() =>
+      buildBtdAssetPackExchangeSettlement({
+        action: 'transfer_rights',
+        previousOrder: settled.order,
+        receiptId: 'legacy-transfer-boundary-2',
+        fromWalletId: 'wallet-depositor-boundary',
+        toWalletId: 'wallet-reader-boundary',
+        btcFeeReceiptId: 'btc-fee-boundary-2',
+        btcFeeFinalityState: 'broadcast',
+        readLicenseId: 'read-license-boundary-2',
+        sourceSafePreviewRoot: 'source-safe-preview-root-boundary',
+        paidUnlockRoot: 'paid-unlock-root-boundary',
+        deliveryAdmissionRoot: 'delivery-admission-root-boundary',
+        ledgerProjectionRoot: 'ledger-projection-root-boundary',
+        actorId: 'actor-boundary-1',
+        issuedAt,
+      }),
+    ).toThrow('Rights transfer receipt requires confirmed BTC fee finality.');
+  });
 });