Merge pull request #38 from engineeredsoftware/v30/gate-6-source-to-shares-proof-cleanup

V30 Gate 6: Source-To-Shares Proof Cleanup

Author: geraldarthurdavis

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

@@ -84,6 +84,7 @@ jobs:
             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
             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
           else
             echo "Unexpected BITCODE_SPEC.txt pointer: $POINTER" >&2
             exit 1

BITCODE_SPEC_V30.md

@@ -218,6 +218,27 @@ Gate 4 receipt precision:
   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.
+
+Gate 6 source-to-shares precision:
+
+- `SourceToSharesProof` is package-owned in `@bitcode/btd` and is the reusable
+  accounting boundary for later Exchange work.
+- Proof inputs bind accepted Need root, Finding Fits result root, admitted fit
+  deposits, per-deposit measurement roots, normalized measurement units,
+  fit/provenance quality basis points, BTD range projection, accepted BTC fee
+  quote, payment observation, and optional ancestry review.
+- Contribution weights are deterministic largest-remainder basis points over
+  measured fit-deposit weights. The trace records total clipped weight,
+  remainder order, tie-break policy, and provisional/final shares.
+- BTD range slices and BTC fee allocations are both derived from the same
+  contribution weights. Range slices may be zero-cell/refit-tail slices when the
+  measuremint tail or small range leaves a contributor with no cell.
+- Settlement conservation carries distinct no-overpayment and no-underpayment
+  theorem verdicts, exact allocation conservation, blocker reasons, a
+  conservation root, and a reconciliation-compatible check.
+- A source-to-shares proof may represent balanced, overpayment, underpayment, or
+  drifted state, but only balanced state is settlement-admissible for protected
+  source unlock and delivery.
   Prepared, signed, broadcast, replaced, reorged, and failed fee receipts do
   not unlock protected source.
 
@@ -688,9 +709,9 @@ Terminal renders those roots with blockers and decision rows so operators can un
 - current member verdict shape: prepared, signed, broadcast, confirmed, blocked, reconciled.
 - current theorem-by-theorem closure reading: no paid source unlock without fee and right-transfer readback.
 - current theorem-to-replay grouping: quote root, payment path, ledger observation, BTD state, reconciliation.
-- minimum artifact/replay binding set: fee quote root, txid or blocked receipt, range id, license id, journal id.
-- current proof-object fields: quote, payment, range, license, reconciliation, blocker.
-- generated-artifact and test bindings: BTD tests, settlement route tests, staging readback.
+- minimum artifact/replay binding set: fee quote root, payment receipt root, txid or blocked receipt, BTD range slice roots, contribution weights, conservation root, license id, journal id.
+- current proof-object fields: quote, payment observation, fit deposits, contribution weights, range slices, settlement allocations, no-overpayment, no-underpayment, zero-cell/refit tail, ancestry evidence, reconciliation check, blocker.
+- generated-artifact and test bindings: BTD source-to-shares tests, settlement route tests, staging readback.
 - fail-closed conditions: settlement conservation drift, stale quote, or chain reorg.
 
 ### Disclosure-boundary

BITCODE_SPEC_V30_DELTA.md

@@ -221,6 +221,29 @@ Closure acceptance:
 - no-overpayment and no-underpayment invariants are testable;
 - later Exchange work can reuse the proof without reinterpreting V30 accounting.
 
+Gate 6 implementation centers on `packages/btd/src/source-to-shares.ts`.
+`SourceToSharesProof` is package-owned and binds accepted Need roots, Finding
+Fits result roots, admitted fit deposits, per-deposit measurement roots,
+normalized measurement units, fit/provenance basis points, deterministic
+largest-remainder contribution weights, BTD range slices, accepted BTC fee
+quote, payment observation, exact source credit allocation, settlement
+conservation, zero-cell/refit tail posture, and ancestry review evidence when
+available.
+
+The proof separates conservation from settlement admission. It can represent a
+balanced, overpayment, underpayment, or drifted settlement without losing the
+proof roots needed for repair. `noOverpayment` and `noUnderpayment` are separate
+theorem verdicts, while `allocationConserved` proves that source credit
+allocation sums to the accepted BTC fee quote. Only a balanced proof is
+settlement-admissible. The proof exposes a reconciliation-compatible
+`SettlementConservationCheck` so ledger/database repair can consume the same
+accounting without route-local reinterpretation.
+
+Gate 6 evidence is covered by `packages/btd/__tests__/source-to-shares.test.ts`,
+`packages/api/src/routes/__tests__/btd-crypto.test.ts`,
+`uapi/app/api/btd/source-to-shares-proof/route.ts`, and
+`scripts/check-v30-gate6-source-to-shares-proof-cleanup.mjs`.
+
 ### Gate 7: Bridge Readiness Research Boundaries
 
 Gate 7 records bridge-readiness without false chain-of-record claims.

BITCODE_SPEC_V30_NOTES.md

@@ -167,6 +167,30 @@ persists schema-compatible repair receipts; richer drift classes, repair
 actions, readback receipts, and proof roots remain in the report payload until a
 future schema expansion admits more columns.
 
+## Gate 6 source-to-shares cleanup notes
+
+Gate 6 moves settlement-source-to-shares accounting into the BTD package instead
+of relying on older protocol-local artifact builders. The package primitive
+normalizes accepted fit deposits into contribution weights through a deterministic
+largest-remainder method, allocates BTD range slices with zero-cell/refit-tail
+posture when a fit receives no cell, allocates BTC fee credits exactly by the
+same contribution weights, and emits one proof root that binds the fee quote,
+payment observation, measurements, fit deposits, range slices, allocation roots,
+settlement conservation, and ancestry evidence.
+
+The proof intentionally keeps no-overpayment and no-underpayment as distinct
+theorem verdicts. This lets a repair cockpit distinguish a Reader overpayment
+from an inadmissible underpayment instead of collapsing both into generic
+conservation drift. The same proof emits a reconciliation-compatible settlement
+conservation check so Gate 5 ledger/database repair can pause unlock or delivery
+from the source-to-shares proof directly.
+
+The source-to-shares API route does not write a new registry table in Gate 6.
+It returns a JSON-safe proof settlement and a Terminal journal entry. Later
+Exchange work may persist richer proof rows after schema admission, but it must
+reuse the package proof rather than recomputing contribution weights, range
+slices, or BTC fee allocations.
+
 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

@@ -59,7 +59,7 @@ No `_legacy/` source is active source truth.
 | 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 | `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 | `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 | BTD/source-to-shares proof primitives, settlement conservation tests | pending | Measurement contribution, fee allocation, zero-cell/refit tail, and conservation invariants are testable. |
+| 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 | Protocol/BTD research notes, policy posture tests, docs | pending | Bridge paths are documented as research 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. |
 | Interface integration regression | Gate 9 | Terminal/API/MCP/ChatGPT App adapters and tests | pending | Existing interfaces consume package-owned objects without regressing V29 behavior. |
@@ -175,6 +175,23 @@ No `_legacy/` source is active source truth.
 - Gate 5 does not implement source-to-shares contribution accounting; Gate 6 owns that.
 - Gate 5 does not promote V30 or change the active canon pointer.
 
+## Gate 6 Parity
+
+| Requirement | Source evidence | Current V30 judgment |
+| --- | --- | --- |
+| Source-to-shares proof is package-owned | `packages/btd/src/source-to-shares.ts`, `packages/btd/src/api-boundaries.ts` | drafted |
+| Contribution weights, range slices, BTC fee allocation, and conservation are deterministic | `packages/btd/__tests__/source-to-shares.test.ts` | drafted |
+| API and Next route consume the package proof without route-local accounting | `packages/api/src/routes/btd-crypto.ts`, `uapi/app/api/btd/source-to-shares-proof/route.ts`, `packages/api/src/routes/__tests__/btd-crypto.test.ts` | drafted |
+| Gate checker protects source-to-shares cleanup | `scripts/check-v30-gate6-source-to-shares-proof-cleanup.mjs`, `pnpm run check:v30-gate6`, gate-quality workflow | drafted |
+
+## Gate 6 accepted boundaries
+
+- Gate 6 does not create a new physical source-to-shares registry table; the API route returns proof payloads and Terminal journal entries until schema admission.
+- Gate 6 does not expose protected source before paid unlock and delivery admission.
+- Gate 6 does not alter `$BTD` supply law or measureminting curve.
+- Gate 6 does not admit bridge chain-of-record semantics; Gate 7 owns bridge-readiness boundaries.
+- Gate 6 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

@@ -59,6 +59,7 @@
     "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: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: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,6 +25,7 @@ import {
   buildBtdMintDraft,
   buildBtdOrganizationInterfaceAuthorityDecision,
   buildBtdReadAccessDecision,
+  buildBtdSourceToSharesProofSettlement,
   buildBtdTerminalJournalSettlement,
   buildBtcFeeQuote,
   createBtdMeasureMintState,
@@ -41,6 +42,7 @@ import {
   buildPostBtdMintDraftRoute,
   buildPostBtdOrganizationInterfaceAuthorityRoute,
   buildPostBtdReadAccessRoute,
+  buildPostBtdSourceToSharesProofRoute,
   buildPostBtdTerminalJournalRoute,
 } from '../btd-crypto';
 
@@ -147,6 +149,63 @@ function mintDraftRequestBody(overrides: Record<string, unknown> = {}) {
   };
 }
 
+function sourceToSharesProofBody(overrides: Record<string, unknown> = {}) {
+  return {
+    readId: 'read-api-source-to-shares-1',
+    assetPackId: 'asset-pack-api-source-to-shares-1',
+    acceptedNeedRoot: 'accepted-need-api-root',
+    findingFitsResultRoot: 'finding-fits-api-root',
+    fitDeposits: [
+      {
+        depositId: 'deposit-api-a',
+        assetPackId: 'fit-asset-api-a',
+        depositorWalletId: 'wallet-depositor-api-a',
+        sourceManifestRoot: 'source-api-root-a',
+        findingFitsResultRoot: 'finding-fits-api-root-a',
+        measurementRoot: 'measurement-api-root-a',
+        normalizedMeasurementUnits: '20000',
+        fitQualityBps: 10000,
+        provenanceBps: 10000,
+        accepted: true,
+      },
+      {
+        depositId: 'deposit-api-b',
+        assetPackId: 'fit-asset-api-b',
+        depositorWalletId: 'wallet-depositor-api-b',
+        sourceManifestRoot: 'source-api-root-b',
+        findingFitsResultRoot: 'finding-fits-api-root-b',
+        measurementRoot: 'measurement-api-root-b',
+        normalizedMeasurementUnits: '10000',
+        fitQualityBps: 10000,
+        provenanceBps: 10000,
+        accepted: true,
+      },
+    ],
+    btdRange: {
+      assetPackId: 'asset-pack-api-source-to-shares-1',
+      rangeStart: 40,
+      rangeEndExclusive: 43,
+      tokenCount: 3,
+      measureMintReceiptRoot: 'measuremint-api-root',
+    },
+    feeQuote: {
+      quoteId: 'quote-api-source-to-shares-1',
+      quoteRoot: 'quote-api-source-root',
+      grossSats: '9000',
+    },
+    paymentObservation: {
+      paymentReceiptRoot: 'payment-api-source-root',
+      observedDebitSats: '9000',
+      observedCreditSats: '9000',
+      finalityState: 'confirmed',
+      txid: 'txid-api-source-to-shares',
+    },
+    exchangeSequence: '18',
+    issuedAt,
+    ...overrides,
+  };
+}
+
 describe('BTD crypto API builders', () => {
   it('builds a deterministic mint draft from accepted Read-Fit semantic units', () => {
     const draft = buildBtdMintDraft(mintDraftInput());
@@ -879,6 +938,35 @@ describe('BTD crypto API builders', () => {
     );
   });
 
+  it('builds source-to-shares proof settlements with exact conservation roots', () => {
+    const settlement = buildBtdSourceToSharesProofSettlement({
+      actorId: 'user-1',
+      ...sourceToSharesProofBody(),
+      exchangeSequence: 18n,
+    } as any);
+
+    expect(settlement.kind).toBe('btd_source_to_shares_proof_settlement');
+    expect(settlement.proof.contributionWeights.map((entry) => entry.shareBps)).toEqual([
+      6667,
+      3333,
+    ]);
+    expect(settlement.proof.settlementConservation).toMatchObject({
+      state: 'balanced',
+      settlementAdmissible: true,
+      allocationConserved: true,
+    });
+    expect(
+      settlement.proof.settlementAllocations.reduce(
+        (sum, route) => sum + route.allocatedSats,
+        0n,
+      ),
+    ).toBe(9000n);
+    expect(settlement.terminalJournalEntry.transactionKind).toBe('settlement_finalization');
+    expect(settlement.terminalJournalEntry.receiptRoots).toContain(
+      settlement.proof.settlementConservation.conservationRoot,
+    );
+  });
+
   it('builds deployment readiness, telemetry, and upgrade settlements', () => {
     const readiness = buildBtdDeploymentReadinessSettlement({
       actorId: 'user-1',
@@ -1425,6 +1513,28 @@ describe('BTD crypto API builders', () => {
     );
   });
 
+  it('returns JSON-safe source-to-shares proofs from the route boundary', async () => {
+    const route = buildPostBtdSourceToSharesProofRoute({
+      resolveAuthenticatedUser: async () => ({ userId: 'user-1' }),
+    });
+    const response = await route(
+      new Request('https://bitcode.test/api/btd/source-to-shares-proof', {
+        method: 'POST',
+        body: JSON.stringify(sourceToSharesProofBody()),
+      }),
+    );
+    const body = await response.json();
+
+    expect(response.status).toBe(200);
+    expect(body.kind).toBe('btd_source_to_shares_proof_settlement');
+    expect(body.committed).toBe(false);
+    expect(body.proof.feeQuote.priceAsset).toBe('BTC');
+    expect(body.proof.feeQuote.grossSats).toBe('9000');
+    expect(body.proof.settlementConservation.noOverpayment.passed).toBe(true);
+    expect(body.proof.settlementConservation.noUnderpayment.passed).toBe(true);
+    expect(body.terminalJournalEntry.exchangeSequence).toBe('18');
+  });
+
   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

@@ -28,6 +28,8 @@ import {
   type BtdReadAccessDecision,
   type BtdReadLicense,
   type BtdOwnershipClaim,
+  type BtdSourceToSharesProofInput,
+  type BtdSourceToSharesProofSettlement,
   type BtdTerminalJournalInput,
   type BtdTerminalJournalSettlement,
   type TerminalJournalEntry,
@@ -46,6 +48,7 @@ import {
   buildBtdOrganizationInterfaceAuthorityDecision,
   buildBtdReadAccessDecision,
   buildBtdRegistrySnapshot,
+  buildBtdSourceToSharesProofSettlement,
   buildBtdStableId as stableId,
   buildBtdTerminalJournalSettlement,
   buildLicensedReadRevenueRoute,
@@ -67,6 +70,7 @@ export {
   buildBtdOrganizationInterfaceAuthorityDecision,
   buildBtdReadAccessDecision,
   buildBtdRegistrySnapshot,
+  buildBtdSourceToSharesProofSettlement,
   buildBtdTerminalJournalSettlement,
 };
 
@@ -564,6 +568,39 @@ export function buildPostBtdLedgerDatabaseReconciliationRoute(options: BtdRouteO
   });
 }
 
+export function buildPostBtdSourceToSharesProofRoute(options: BtdRouteOptions = {}) {
+  return traceRoute('/btd/source-to-shares-proof', async (request: Request) => {
+    const user = await (options.resolveAuthenticatedUser ?? defaultResolveAuthenticatedUser)(
+      request,
+    );
+    if (!user) {
+      return createJsonResponse({ error: 'Unauthorized' }, 401);
+    }
+
+    let body: Omit<BtdSourceToSharesProofInput, 'actorId' | 'exchangeSequence'> & {
+      exchangeSequence: string | number;
+    };
+    try {
+      body = await request.json();
+    } catch {
+      return createJsonResponse({ error: 'Invalid JSON body' }, 400);
+    }
+
+    let settlement: BtdSourceToSharesProofSettlement;
+    try {
+      settlement = buildBtdSourceToSharesProofSettlement({
+        ...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)(
@@ -623,6 +660,7 @@ export const postBtdAssetPackExchange = buildPostBtdAssetPackExchangeRoute();
 export const postBtdTerminalJournal = buildPostBtdTerminalJournalRoute();
 export const postBtdLedgerDatabaseReconciliation =
   buildPostBtdLedgerDatabaseReconciliationRoute();
+export const postBtdSourceToSharesProof = buildPostBtdSourceToSharesProofRoute();
 export const postBtdDeploymentReadiness = buildPostBtdDeploymentReadinessRoute();
 
 function toBadRequestMessage(error: unknown): string {