Merge pull request #217 from engineeredsoftware/v45/gate-14-btc-settlement-rights-delivery-readback

V45 Gate 14: BTC Settlement Rights Delivery Readback

Author: geraldarthurdavis

.bitcode/v39-settlement-rights-delivery.json

@@ -464,6 +464,7 @@
     "sourceSafetyVerdict": "source-safe-settlement-rights-delivery",
     "runtimeType": "AssetPackSettlementRightsDeliveryBoundary",
     "paymentType": "AssetPackSettlementPaymentObservation",
+    "btcSettlementReadbackType": "AssetPackBtcSettlementReadback",
     "finalityType": "AssetPackSettlementFinalityReceipt",
     "rightsTransferType": "BtdRightsTransferReceipt",
     "readReceiptType": "BtdReadReceipt",
@@ -473,6 +474,7 @@
     "replayType": "AssetPackSettlementRightsDeliveryReplayReceipt",
     "storageRecordKinds": [
       "btc_payment_observation",
+      "btc_settlement_readback",
       "settlement_finality",
       "source_to_shares_compensation",
       "btd_read_receipt",
@@ -506,5 +508,5 @@
     "failedPredicateIds": []
   },
   "passed": true,
-  "artifactRoot": "v39-settlement-rights-delivery:ef0207da866bfb8375772f46"
+  "artifactRoot": "v39-settlement-rights-delivery:ac368ea9dcc45bda1c5ef73d"
 }

.bitcode/v40-ledger-storage-sync.json

@@ -11,7 +11,7 @@
     "rowCount": 10,
     "synchronizationSurfaceCount": 6,
     "failClosedStateCount": 4,
-    "storageRecordKindCount": 9,
+    "storageRecordKindCount": 10,
     "requiredReadbackCount": 5,
     "walletAuthorityBoundaryCount": 4,
     "deliveryUnlockConditionCount": 5
@@ -595,7 +595,7 @@
       "rowCount": 10,
       "synchronizationSurfaceCount": 6,
       "failClosedStateCount": 4,
-      "storageRecordKindCount": 9,
+      "storageRecordKindCount": 10,
       "requiredReadbackCount": 5,
       "walletAuthorityBoundaryCount": 4,
       "deliveryUnlockConditionCount": 5
@@ -619,8 +619,8 @@
   "proofRoots": {
     "rowSetRoot": "sha256:bb6d02003baa62525f760c53",
     "predicateRoot": "sha256:f4ca6728fac60849d7140424",
-    "coverageRoot": "sha256:3b6c32dec61478478438ef74",
-    "artifactRoot": "sha256:84e6aae8d9795dcb9dd757a1"
+    "coverageRoot": "sha256:a15ad35380e94dcf91814adc",
+    "artifactRoot": "sha256:a68d8a8ea5ff7c19827537d5"
   },
   "sourceSafety": {
     "sourceSafeMetadataOnly": true,

.bitcode/v42-settlement-rights-delivery.json

@@ -551,6 +551,7 @@
     "sourceSafetyVerdict": "source-safe-v42-settlement-rights-delivery-metadata",
     "runtimeType": "AssetPackSettlementRightsDeliveryBoundary",
     "paymentType": "AssetPackSettlementPaymentObservation",
+    "btcSettlementReadbackType": "AssetPackBtcSettlementReadback",
     "finalityType": "AssetPackSettlementFinalityReceipt",
     "rightsTransferType": "BtdRightsTransferReceipt",
     "readReceiptType": "BtdReadReceipt",
@@ -583,5 +584,5 @@
     "failedPredicateIds": []
   },
   "passed": true,
-  "artifactRoot": "v42-settlement-rights-delivery:6866f71624c147178c383189"
+  "artifactRoot": "v42-settlement-rights-delivery:03357cba132e98e24c3c6b23"
 }

BITCODE_SPEC_V45_PARITY_MATRIX.md

@@ -167,6 +167,12 @@ Acceptance:
 - Repair tests cover underpayment, stale quote, missing finality, projection drift, missing delivery, and compensation conservation failure.
 - `check:v45-gate14` passes locally and in gate-quality CI.
 
+Gate 14 implementation readback:
+
+- BTC settlement, rights, delivery, repair, and source-to-shares readback binding: `packages/pipelines/asset-pack/src/asset-pack-settlement-rights-delivery.ts`.
+- Settlement success, non-finality, stale quote, underpayment, compensation failure, projection drift, missing delivery, persistence, and source-safety coverage: `packages/pipelines/asset-pack/src/__tests__/asset-pack-settlement-rights-delivery.test.ts`.
+- Closure checker: `check:v45-gate14`.
+
 ### Gate 15: Interface Disclosure, Route Vocabulary, And Public Documentation
 
 Gate class: `interface-only`.

package.json

@@ -399,6 +399,7 @@
     "check:v45-gate11": "node scripts/check-v45-gate11-implementation-parity-audit.mjs",
     "check:v45-gate12": "node scripts/check-v45-gate12-state-vocabulary-commodity-model.mjs",
     "check:v45-gate13": "node scripts/check-v45-gate13-btd-scalar-volume-quote-conservation.mjs",
+    "check:v45-gate14": "node scripts/check-v45-gate14-btc-settlement-rights-delivery-readback.mjs",
     "generate:v38-inference-surface-inventory": "node scripts/generate-v38-inference-surface-inventory.mjs",
     "check:v38-inference-surface-inventory": "node scripts/generate-v38-inference-surface-inventory.mjs --check",
     "check:v38-gate2": "node scripts/check-v38-gate2-inference-surface-inventory.mjs",

packages/pipelines/asset-pack/src/__tests__/asset-pack-settlement-rights-delivery.test.ts

@@ -180,6 +180,19 @@ describe('AssetPack settlement rights delivery boundary', () => {
       finalityReceipt: {
         finalityState: 'confirmed',
       },
+      btcSettlementReadback: {
+        quoteAcceptanceState: 'accepted',
+        walletReadinessState: 'wallet_ready_non_custodial',
+        psbtPreparationState: 'psbt_prepared_source_safe',
+        psbtSignatureState: 'psbt_signed_by_reader_wallet',
+        settlementFinalizationState: 'settlement_finalized',
+        rightsTransferState: 'rights_transferred',
+        deliveryState: 'source_unlocked_delivery',
+        compensationRoutingState: 'compensation_routable',
+        sourceUnlockAdmissible: true,
+        serverCustody: false,
+        walletPrivateMaterialVisible: false,
+      },
       deliveryUnlock: {
         state: 'source_bearing_pull_request_ready',
         sourceBearingDeliveryVisibleToReader: true,
@@ -204,6 +217,7 @@ describe('AssetPack settlement rights delivery boundary', () => {
     expect(boundary.storageProjection.map((record) => record.recordKind)).toEqual(
       expect.arrayContaining([
         'btc_payment_observation',
+        'btc_settlement_readback',
         'settlement_finality',
         'source_to_shares_compensation',
         'btd_read_receipt',
@@ -240,25 +254,83 @@ describe('AssetPack settlement rights delivery boundary', () => {
     expect(boundary.replayReceipt.verified.paymentMatchesQuote).toBe(false);
   });
 
-  it('fails closed until BTC finality is confirmed', () => {
+  it.each(['prepared', 'signed', 'broadcast', 'observed'] as const)(
+    'fails closed for %s BTC state before finality',
+    (finalityState) => {
+      const boundary = buildAssetPackSettlementRightsDeliveryBoundary({
+        previewBoundary: previewBoundary(),
+        finality: {
+          finalityState,
+          confirmations: 0,
+          blockHeight: null,
+        },
+        createdAt: '2026-05-22T00:00:00.000Z',
+      });
+
+      expect(boundary.state).toBe('blocked_until_payment_finality');
+      expect(boundary.rightsTransferReceipt).toBeNull();
+      expect(boundary.btdReadReceipt).toBeNull();
+      expect(boundary.deliveryUnlock.sourceBearingDeliveryVisibleToReader).toBe(false);
+      expect(boundary.btcSettlementReadback).toMatchObject({
+        finalityState,
+        settlementFinalizationState: 'not_finalized',
+        rightsTransferState: 'rights_withheld',
+        deliveryState: 'delivery_withheld',
+        sourceUnlockAdmissible: false,
+        rightsTransferAdmissible: false,
+      });
+      expect(boundary.repairPosture.nextActions).toEqual(
+        expect.arrayContaining(['observe_btc_payment', 'wait_for_btc_finality']),
+      );
+    },
+  );
+
+  it('fails closed when payment references a stale accepted BTC quote', () => {
+    const preview = previewBoundary();
     const boundary = buildAssetPackSettlementRightsDeliveryBoundary({
-      previewBoundary: previewBoundary(),
-      finality: {
-        finalityState: 'broadcast',
-        confirmations: 0,
-        blockHeight: null,
+      previewBoundary: preview,
+      paymentObservation: {
+        expectedSats: preview.quoteReceipt.sats - 10,
+        observedDebitSats: preview.quoteReceipt.sats - 10,
+        observedCreditSats: preview.quoteReceipt.sats - 10,
       },
       createdAt: '2026-05-22T00:00:00.000Z',
     });
 
-    expect(boundary.state).toBe('blocked_until_payment_finality');
+    expect(boundary.state).toBe('blocked_until_compensation_conservation');
     expect(boundary.rightsTransferReceipt).toBeNull();
     expect(boundary.deliveryUnlock.sourceBearingDeliveryVisibleToReader).toBe(false);
+    expect(boundary.btcSettlementReadback.quoteAcceptanceState).toBe('stale_quote_repair_required');
+    expect(boundary.btcSettlementReadback.blockerCodes).toContain('stale_btc_quote_or_payment_mismatch');
+    expect(boundary.repairPosture.blockers).toContain('stale_btc_quote_or_payment_mismatch');
     expect(boundary.repairPosture.nextActions).toEqual(
-      expect.arrayContaining(['observe_btc_payment', 'wait_for_btc_finality']),
+      expect.arrayContaining(['refresh_stale_btc_quote', 'observe_btc_payment']),
     );
   });
 
+  it('fails closed when contributor compensation conservation fails after debit observation', () => {
+    const preview = previewBoundary();
+    const boundary = buildAssetPackSettlementRightsDeliveryBoundary({
+      previewBoundary: preview,
+      paymentObservation: {
+        observedDebitSats: preview.quoteReceipt.sats,
+        observedCreditSats: preview.quoteReceipt.sats - 1,
+      },
+      createdAt: '2026-05-22T00:00:00.000Z',
+    });
+
+    expect(boundary.state).toBe('blocked_until_compensation_conservation');
+    expect(boundary.sourceToSharesProof).toMatchObject({
+      settlementConservation: {
+        state: 'underpayment',
+        settlementAdmissible: false,
+      },
+    });
+    expect(boundary.rightsTransferReceipt).toBeNull();
+    expect(boundary.btcSettlementReadback.compensationRoutingState).toBe('compensation_withheld');
+    expect(boundary.repairPosture.blockers).toContain('source_to_shares_conservation_failed');
+  });
+
   it('withholds delivery when ledger, database, or object storage projections drift', () => {
     const boundary = buildAssetPackSettlementRightsDeliveryBoundary({
       previewBoundary: previewBoundary(),
@@ -274,6 +346,28 @@ describe('AssetPack settlement rights delivery boundary', () => {
     expect(boundary.repairPosture.nextActions).toContain('repair_ledger_database_storage_projection');
   });
 
+  it('withholds source unlock and rights delivery when repository delivery is missing', () => {
+    const boundary = buildAssetPackSettlementRightsDeliveryBoundary({
+      previewBoundary: previewBoundary(),
+      pullRequestTarget: null,
+      createdAt: '2026-05-22T00:00:00.000Z',
+    });
+
+    expect(boundary.state).toBe('blocked_until_pull_request_delivery');
+    expect(boundary.rightsTransferReceipt?.kind).toBe('btd.rights_transfer_receipt');
+    expect(boundary.deliveryUnlock).toMatchObject({
+      state: 'withheld',
+      sourceBearingDeliveryVisibleToReader: false,
+      pullRequestTarget: null,
+      blockerCodes: expect.arrayContaining(['pull_request_target_missing']),
+    });
+    expect(boundary.btcSettlementReadback).toMatchObject({
+      deliveryState: 'delivery_withheld',
+      sourceUnlockAdmissible: false,
+    });
+    expect(boundary.repairPosture.blockers).toContain('pull_request_delivery_missing');
+  });
+
   it('persists settlement and rights delivery records onto execution state', () => {
     const execution = new Execution('asset-pack-settlement-test');
     const boundary = buildAssetPackSettlementRightsDeliveryBoundary({
@@ -293,5 +387,9 @@ describe('AssetPack settlement rights delivery boundary', () => {
     expect(execution.get('asset-pack/settlement', 'deliveryUnlock')).toMatchObject({
       state: 'source_bearing_pull_request_ready',
     });
+    expect(execution.get('asset-pack/settlement', 'btcSettlementReadback')).toMatchObject({
+      schema: 'bitcode.asset-pack.btc-settlement-readback',
+      settlementFinalizationState: 'settlement_finalized',
+    });
   });
 });