Close Gate 12 settlement rights delivery

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

@@ -48,6 +48,7 @@ jobs:
           node scripts/check-v28-gate9-depository-evidence.mjs
           node scripts/check-v28-gate10-read-need-comprehension.mjs
           node scripts/check-v28-gate11-read-fits-finding-preview.mjs
+          node scripts/check-v28-gate12-settlement-rights-delivery.mjs
           node scripts/promote-bitcode-canon.mjs --version V28 --commit HEAD --dry-run
 
       - name: Validate source casing and imports
@@ -57,11 +58,13 @@ jobs:
 
       - name: Type-check gate packages
         run: |
+          pnpm --filter @bitcode/btd typecheck
           pnpm --filter @bitcode/pipeline-asset-pack typecheck
           pnpm --filter @bitcode/pipeline-hosts typecheck
 
       - name: Test gate packages
         run: |
+          pnpm --filter @bitcode/btd test
           pnpm --filter @bitcode/pipeline-asset-pack exec jest --config jest.config.cjs --passWithNoTests --forceExit
           pnpm --filter @bitcode/pipeline-hosts exec jest --config jest.config.cjs --passWithNoTests --forceExit
 

BITCODE_SPEC_V28.md

@@ -881,6 +881,31 @@ Gate 12 owns BTC settlement, depositor/reader ownership boundaries, read-license
 rows, ledger/database synchronization, protected-source unlock, and PR delivery
 of the purchased AssetPack into the Reading repository.
 
+Gate 12 acceptance requires:
+
+- settlement is represented as a typed unlock decision, not as UI inference:
+  the `bitcode.asset-pack.settlement-unlock` envelope keeps source-bearing
+  AssetPack material unavailable unless ledger settlement status is `settled`,
+  settlement is admissible, required readback rows are all present, and
+  pull-request delivery readback exists when delivery is required;
+- BTC payment posture is reader-paid and server-noncustodial. The fee receipt,
+  wallet authorization/session, network, sats, finality state, and receipt id
+  remain visible before unlock and must not imply server custody of private
+  keys;
+- depositor/reader boundaries stay separate: the depositor owns the minted BTD
+  range for the deposited source evidence, while the reader receives a
+  policy-matching read license only after payment/readback;
+- required readback covers semantic measurement, measure-mint receipt,
+  AssetPack range, BTD cell, ownership event, read license, mint receipt, BTC
+  fee transaction, ledger anchor, Terminal journal rows, and crypto telemetry;
+- source-safe preview is upgraded only by settlement readback. After settlement,
+  the preview access state becomes `licensed_read`, unlock reports
+  `sourceAvailable=true`, and delivery points at the pull request. Before that,
+  the preview stays `pending_settlement` or `denied`;
+- Terminal exposes ledger status, unlock state, read-license id, BTC fee receipt
+  id, and PR target in the five-step Reading flow, while expandable stream
+  metadata retains full settlement and readback evidence.
+
 ### Gate 13: Commercial Product Closure And Promotion Readiness
 
 Gate 13 owns final commercial-product closure: website application UX, package

BITCODE_SPEC_V28_PARITY_MATRIX.md

@@ -196,6 +196,16 @@ boundary, settlement boundary, and BTC quote before settlement. Gate 12 remains
 responsible for paid unlock, rights transfer, ledger reconciliation, and PR
 delivery.
 
+Gate 12 closure narrows the two Gate 12 carryforward rows to paid-unlock
+readiness: settlement must produce a typed
+`bitcode.asset-pack.settlement-unlock` decision from ledger settlement evidence,
+readback booleans, and delivery posture. Protected source can become available
+only when BTC fee, BTD range, ownership event, read-license row, mint receipt,
+ledger anchor, Terminal journal, crypto telemetry, and pull-request delivery
+read back together. Terminal must show the unlock state, read-license id, BTC
+fee receipt id, ledger status, and PR target without treating unpaid preview
+metadata as source access.
+
 ## V28 implementation matrix
 
 | Area | Current source evidence | Judgment | Gate owner |

BITCODE_V28_QA.md

@@ -2144,3 +2144,39 @@ Expected evidence:
 - The preview must not expose protected source content, full patches,
   source-bearing manifest entries, licensed read payloads, or PR source changes
   before settlement. Gate 12 owns paid unlock, rights transfer, and delivery.
+
+### Gate 12 Settlement, Rights, Delivery, And Reconciliation QA
+
+Gate 12 local closure proves that paid AssetPack unlock is derived from typed
+settlement/readback evidence and never from source-safe preview metadata alone.
+
+Required local checks:
+
+```bash
+pnpm run check:v28-gate12
+pnpm --filter @bitcode/btd typecheck
+pnpm --filter @bitcode/btd test
+pnpm --filter @bitcode/pipeline-hosts typecheck
+pnpm --filter @bitcode/pipeline-hosts exec jest --config jest.config.cjs --passWithNoTests --forceExit
+pnpm --dir uapi exec jest --runTestsByPath \
+  tests/api/pipelineHarnessRoute.test.ts \
+  tests/terminalPipelineHarnessClient.test.ts \
+  tests/terminalDepositReadWorkbench.test.ts \
+  --runInBand
+```
+
+Expected evidence:
+
+- `packages/btd` exports `bitcode.asset-pack.settlement-unlock` construction
+  and preview application helpers. They return `licensed_read` and
+  `sourceAvailable=true` only after settlement is settled/admissible, all
+  required readback keys are true, and required pull-request delivery exists.
+- The sandbox harness applies settlement unlock after ledger settlement
+  readback, stores `asset-pack/settlement.unlock`, and embeds
+  `ledgerSettlement.protectedSourceUnlock` plus the updated source-safe preview
+  in evidence.
+- Route and Terminal stream summaries surface ledger status, fee quote,
+  source-unlock state, read-license id, BTC fee receipt id, and PR target.
+- Missing read-license, BTC fee, ownership, journal, ledger anchor, telemetry,
+  or delivery readback leaves protected source withheld and records the blocking
+  readback key.

package.json

@@ -42,6 +42,7 @@
     "check:v28-gate9": "node scripts/check-v28-gate9-depository-evidence.mjs",
     "check:v28-gate10": "node scripts/check-v28-gate10-read-need-comprehension.mjs",
     "check:v28-gate11": "node scripts/check-v28-gate11-read-fits-finding-preview.mjs",
+    "check:v28-gate12": "node scripts/check-v28-gate12-settlement-rights-delivery.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/__tests__/btd.test.ts

@@ -9,8 +9,10 @@ import {
   BtdFungibleMutationRejectedError,
   BTD_MAX_MINTABLE_SUPPLY,
   BITCODE_FEE_ASSET,
+  applyAssetPackSettlementUnlockToPreview,
   assertBtdAccessPolicyTemplateCoverage,
   assertBtdMintableSupplyLimit,
+  buildAssetPackSettlementUnlock,
   buildBtdReadAccessProjectionFromRegistryRows,
   calculateLlmBtcFeeEstimate,
   calculateMeasuredBtdFromTokens,
@@ -44,6 +46,97 @@ describe('calculateLlmBtcFeeEstimate', () => {
   });
 });
 
+describe('AssetPack settlement unlock', () => {
+  const completeReadback = {
+    semanticMeasurement: true,
+    measureMintReceipt: true,
+    assetPackRange: true,
+    btdCell: true,
+    ownershipEvent: true,
+    readLicense: true,
+    mintReceipt: true,
+    btcFeeTransaction: true,
+    ledgerAnchor: true,
+    terminalJournal: true,
+    cryptoTelemetry: true,
+  };
+
+  it('unlocks protected source only after settlement, readback, license, and delivery agree', () => {
+    const unlock = buildAssetPackSettlementUnlock({
+      ledgerSettlement: {
+        status: 'settled',
+        settlementAdmissible: true,
+        assetPackId: 'asset-pack-1',
+        ledgerAnchorId: 'ledger-anchor-1',
+        btcFeeReceiptId: 'btc-fee-1',
+        ownershipEventId: 'ownership-1',
+        readLicenseId: 'license-1',
+        depositorWalletId: 'wallet-depositor',
+        readerWalletId: 'wallet-reader',
+        readback: completeReadback,
+      },
+      pullRequestTarget: 'https://github.com/engineeredsoftware/ENGI/pull/42',
+    });
+
+    expect(unlock).toMatchObject({
+      schema: 'bitcode.asset-pack.settlement-unlock',
+      state: 'licensed_read',
+      sourceAvailable: true,
+      settlementAdmissible: true,
+      deliveryAvailable: true,
+      assetPackId: 'asset-pack-1',
+      readLicenseId: 'license-1',
+      btcFeeReceiptId: 'btc-fee-1',
+      missingReadbackKeys: [],
+    });
+
+    const preview = applyAssetPackSettlementUnlockToPreview(
+      {
+        accessPolicy: { readRightState: 'pending_settlement' },
+        unlock: { state: 'pending_settlement', sourceAvailable: false },
+        delivery: { pullRequestTarget: null, availableAfterSettlement: true },
+      },
+      unlock,
+    );
+
+    expect(preview).toMatchObject({
+      accessPolicy: { readRightState: 'licensed_read' },
+      unlock: {
+        state: 'licensed_read',
+        sourceAvailable: true,
+      },
+      delivery: {
+        pullRequestTarget: 'https://github.com/engineeredsoftware/ENGI/pull/42',
+      },
+      settlementUnlock: unlock,
+    });
+  });
+
+  it('keeps protected source withheld when any settlement readback key is missing', () => {
+    const unlock = buildAssetPackSettlementUnlock({
+      ledgerSettlement: {
+        status: 'settled',
+        settlementAdmissible: true,
+        assetPackId: 'asset-pack-1',
+        readLicenseId: 'license-1',
+        readback: {
+          ...completeReadback,
+          readLicense: false,
+        },
+      },
+      pullRequestTarget: 'https://github.com/engineeredsoftware/ENGI/pull/42',
+    });
+
+    expect(unlock).toMatchObject({
+      state: 'pending_settlement',
+      sourceAvailable: false,
+      settlementAdmissible: false,
+      missingReadbackKeys: ['readLicense'],
+    });
+    expect(unlock.reason).toContain('readLicense');
+  });
+});
+
 describe('calculateMeasuredBtdFromTokens', () => {
   it('measures content amount without implying spend', () => {
     expect(calculateMeasuredBtdFromTokens({ inputTokens: 1200, outputTokens: 50 })).toBe(2);

packages/btd/src/index.ts

@@ -171,6 +171,7 @@ export * from './reconciliation';
 export * from './replay';
 export * from './revenue';
 export * from './semantic-volume';
+export * from './settlement';
 export * from './supply';
 export * from './telemetry';
 export * from './terminal-journal';