[object Object]

← back to Dw Sku Integrity

TK-10896 add exact ledger provenance join harness

9978a1244c2d0893ecd0b00513d04c6c77e1f88a · 2026-08-30 11:31:36 -0700 · codex-10896

Files touched

Diff

commit 9978a1244c2d0893ecd0b00513d04c6c77e1f88a
Author: codex-10896 <steve@designerwallcoverings.com>
Date:   Sun Aug 30 11:31:36 2026 -0700

    TK-10896 add exact ledger provenance join harness
---
 README.md                                        | 24 +++++-
 evidence/LEDGER-JOIN-HARNESS-2026-08-30.md       | 33 ++++++++
 provenance-ledger-join.mjs                       | 96 ++++++++++++++++++++++++
 test/fixtures/phase4-ledger.jsonl                |  2 +
 test/fixtures/phase4-ledger.manifest.json        |  6 ++
 test/fixtures/provenance-plan.jsonl              |  4 +
 test/provenance-ledger.test.mjs                  | 56 ++++++++++++++
 verification/TK-10896-ledger-join-e2e-proof.json | 50 ++++++++++++
 8 files changed, 270 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 60a83fd..83d9322 100644
--- a/README.md
+++ b/README.md
@@ -35,7 +35,10 @@ existing `sku`.
 
 - `classify.mjs` — pure classifier: `stripUnitSuffix()`, `classifyRow()`, `RECOVERY_GROUP`.
 - `dwsku-backlog-scan.mjs` — read-only DB scanner → segmentation summary + plan JSONL.
-- `test/classify.test.mjs` — 27 unit tests (`node --test`).
+- `provenance-ledger-join.mjs` — local-only, fail-closed join for a future exact
+  `sku_repair_p4_20260826` JSONL export; requires a completeness manifest, row count,
+  and SHA-256 before releasing any mixed-prefix candidate.
+- `test/*.test.mjs` — 32 unit tests (`node --test`).
 - `evidence/` — committed scan outputs + the analysis writeup.
 
 ## Usage
@@ -54,6 +57,25 @@ DWSKU_PSQL='ssh <kamatera-host> psql' node dwsku-backlog-scan.mjs \
 `--plan` also writes a `*.plan.jsonl` (one row → class → recovered candidate →
 collision flag), suitable as the dry-run input to a *gated* apply step elsewhere.
 
+### Join a separately authorized undo-ledger export
+
+The importer never connects to PostgreSQL or Kamatera. A future read-only export
+must be JSONL with one unique `assigned_dw_sku` per line and travel with a manifest:
+
+```json
+{"backup_table":"sku_repair_p4_20260826","complete":true,"row_count":11725,"sha256":"<sha256-of-ledger-file>"}
+```
+
+```bash
+node provenance-ledger-join.mjs \
+  --ledger phase4-ledger.jsonl --manifest phase4-ledger.manifest.json \
+  --plan mirror.plan.jsonl --out mirror.joined.jsonl
+```
+
+Exact ledger matches remain mint residue. Only mixed-prefix codes excluded by the
+attested-complete ledger become `SELF_COPY_DW_PROVEN_NATIVE`. Missing/incomplete,
+wrong-table, count-mismatched, hash-mismatched, duplicate, or malformed ledgers fail.
+
 ## Classes → recovery group
 
 | class | meaning | group |
diff --git a/evidence/LEDGER-JOIN-HARNESS-2026-08-30.md b/evidence/LEDGER-JOIN-HARNESS-2026-08-30.md
new file mode 100644
index 0000000..884b9d4
--- /dev/null
+++ b/evidence/LEDGER-JOIN-HARNESS-2026-08-30.md
@@ -0,0 +1,33 @@
+# TK-10896 — exact-ledger join harness
+
+Local discovery found no export of `sku_repair_p4_20260826`. The table name exists
+only in canonical ticket history; neither Spotlight, bounded filename search, nor
+targeted repository/queue search found a local artifact. No Kamatera or canonical
+database access followed.
+
+`provenance-ledger-join.mjs` is the fixture-proven drop-in consumer for a future,
+separately authorized read-only export. It has no database or network imports. It
+requires all of the following before ledger exclusion can prove a mixed-prefix code
+native:
+
+- exact `backup_table: sku_repair_p4_20260826`
+- explicit `complete: true`
+- positive exact row count
+- SHA-256 matching the ledger bytes
+- valid, unique `assigned_dw_sku` values
+
+Join behavior is deterministic:
+
+- exact ledger code match → `MINT_RESIDUE_RESCRAPE`, candidate remains null
+- mixed-prefix code excluded by an attested-complete ledger →
+  `SELF_COPY_DW_PROVEN_NATIVE`, candidate recovered from the row
+- non-provenance classes → unchanged
+- malformed or unrecognized provenance rows → hard failure
+
+Fixture E2E passed 4 rows: one exact minted residue, one ledger-excluded native
+code, one existing greenfield residue, and one existing safe self-copy. Negative
+tests prove incomplete/wrong-table/count/hash/duplicate/unrecognized inputs fail
+closed. Total suite: 32/32 passing.
+
+No database access or write, minting, Shopify call, deploy, or external action was
+performed. `/tmp/TK-10896-fixture-joined.jsonl` is disposable fixture output only.
diff --git a/provenance-ledger-join.mjs b/provenance-ledger-join.mjs
new file mode 100644
index 0000000..26615dc
--- /dev/null
+++ b/provenance-ledger-join.mjs
@@ -0,0 +1,96 @@
+#!/usr/bin/env node
+// Fixture-safe join for a future read-only export of sku_repair_p4_20260826.
+// No database client and no network API are imported. Inputs are local files;
+// output is a local decision plan. A ledger must be explicitly attested complete
+// and pass row-count + SHA-256 checks before exclusion can prove a code native.
+
+import { createHash } from 'node:crypto';
+import { readFileSync, writeFileSync } from 'node:fs';
+import { MIXED_USE_MINT_PREFIXES, stripUnitSuffix } from './classify.mjs';
+
+export const REQUIRED_BACKUP_TABLE = 'sku_repair_p4_20260826';
+
+function sha256(buffer) {
+  return createHash('sha256').update(buffer).digest('hex');
+}
+
+function readJsonLines(buffer, label) {
+  const text = buffer.toString('utf8').trim();
+  if (!text) return [];
+  return text.split('\n').map((line, index) => {
+    try { return JSON.parse(line); }
+    catch (error) { throw new Error(`${label}:${index + 1}: invalid JSON: ${error.message}`); }
+  });
+}
+
+function candidatePrefix(code) {
+  return (/^(DW[A-Z0-9]{1,6})-/i.exec(code || '') || [])[1]?.toUpperCase() || null;
+}
+
+export function loadVerifiedLedger(ledgerPath, manifestPath) {
+  const buffer = readFileSync(ledgerPath);
+  const manifest = JSON.parse(readFileSync(manifestPath, 'utf8'));
+  if (manifest.backup_table !== REQUIRED_BACKUP_TABLE) throw new Error(`wrong backup_table: ${manifest.backup_table || 'missing'}`);
+  if (manifest.complete !== true) throw new Error('ledger manifest must attest complete=true');
+  if (!Number.isSafeInteger(manifest.row_count) || manifest.row_count < 1) throw new Error('manifest row_count must be a positive integer');
+  const digest = sha256(buffer);
+  if (manifest.sha256 !== digest) throw new Error(`ledger SHA-256 mismatch: expected ${manifest.sha256}, got ${digest}`);
+
+  const rows = readJsonLines(buffer, 'ledger');
+  if (rows.length !== manifest.row_count) throw new Error(`ledger row_count mismatch: expected ${manifest.row_count}, got ${rows.length}`);
+  const assignedCodes = new Set();
+  for (const [index, row] of rows.entries()) {
+    const code = String(row.assigned_dw_sku || '').trim().toUpperCase();
+    if (!/^DW[A-Z0-9]{1,6}-.+/.test(code)) throw new Error(`ledger:${index + 1}: invalid assigned_dw_sku`);
+    if (assignedCodes.has(code)) throw new Error(`ledger:${index + 1}: duplicate assigned_dw_sku ${code}`);
+    assignedCodes.add(code);
+  }
+  return { manifest, assignedCodes, digest };
+}
+
+export function joinPlanRows(planRows, verifiedLedger) {
+  const stats = { rows: planRows.length, minted_residue: 0, proven_native: 0, unchanged: 0 };
+  const rows = planRows.map((row) => {
+    if (row.class !== 'PROVENANCE_REVIEW') { stats.unchanged += 1; return { ...row }; }
+    const candidate = stripUnitSuffix(String(row.sku || '').trim());
+    const prefix = candidatePrefix(candidate);
+    if (!prefix || !MIXED_USE_MINT_PREFIXES.has(prefix)) {
+      throw new Error(`PROVENANCE_REVIEW row has no recognized mixed-use candidate: ${row.sku || '<blank>'}`);
+    }
+    if (verifiedLedger.assignedCodes.has(candidate.toUpperCase())) {
+      stats.minted_residue += 1;
+      return {
+        ...row,
+        class: 'MINT_RESIDUE_RESCRAPE', candidate: null, collides: false,
+        group: 'rescrape_program_TK10900', provenance: 'exact_phase4_undo_ledger_match',
+      };
+    }
+    stats.proven_native += 1;
+    return {
+      ...row,
+      class: 'SELF_COPY_DW_PROVEN_NATIVE', candidate, collides: false,
+      group: 'recoverable_now_self_copy', provenance: 'excluded_by_complete_phase4_undo_ledger',
+    };
+  });
+  return { rows, stats };
+}
+
+function arg(name) {
+  const index = process.argv.indexOf(name);
+  return index >= 0 ? process.argv[index + 1] : null;
+}
+
+if (process.argv[1] && import.meta.url === new URL(`file://${process.argv[1]}`).href) {
+  const ledgerPath = arg('--ledger');
+  const manifestPath = arg('--manifest');
+  const planPath = arg('--plan');
+  const outPath = arg('--out');
+  if (!ledgerPath || !manifestPath || !planPath) {
+    throw new Error('usage: node provenance-ledger-join.mjs --ledger ledger.jsonl --manifest manifest.json --plan plan.jsonl [--out joined.jsonl]');
+  }
+  const ledger = loadVerifiedLedger(ledgerPath, manifestPath);
+  const planRows = readJsonLines(readFileSync(planPath), 'plan');
+  const joined = joinPlanRows(planRows, ledger);
+  if (outPath) writeFileSync(outPath, joined.rows.map(JSON.stringify).join('\n') + '\n');
+  process.stdout.write(JSON.stringify({ ok: true, backup_table: ledger.manifest.backup_table, ledger_sha256: ledger.digest, ...joined.stats, output: outPath || null }, null, 2) + '\n');
+}
diff --git a/test/fixtures/phase4-ledger.jsonl b/test/fixtures/phase4-ledger.jsonl
new file mode 100644
index 0000000..f9b1f24
--- /dev/null
+++ b/test/fixtures/phase4-ledger.jsonl
@@ -0,0 +1,2 @@
+{"assigned_dw_sku":"DWKN-900001","vendor":"Knoll"}
+{"assigned_dw_sku":"DWTT-900002","vendor":"Thibaut"}
diff --git a/test/fixtures/phase4-ledger.manifest.json b/test/fixtures/phase4-ledger.manifest.json
new file mode 100644
index 0000000..ea76b5f
--- /dev/null
+++ b/test/fixtures/phase4-ledger.manifest.json
@@ -0,0 +1,6 @@
+{
+  "backup_table": "sku_repair_p4_20260826",
+  "complete": true,
+  "row_count": 2,
+  "sha256": "82128560bf73313aa56cad266a1c76d443fcd1280ed6553e2adf6add2d9bffec"
+}
diff --git a/test/fixtures/provenance-plan.jsonl b/test/fixtures/provenance-plan.jsonl
new file mode 100644
index 0000000..096c190
--- /dev/null
+++ b/test/fixtures/provenance-plan.jsonl
@@ -0,0 +1,4 @@
+{"vendor":"Knoll","sku":"DWKN-900001-Sample","class":"PROVENANCE_REVIEW","candidate":null,"collides":false,"group":"provenance_review_TK10896"}
+{"vendor":"Knoll","sku":"DWKN-250001-Sample","class":"PROVENANCE_REVIEW","candidate":null,"collides":false,"group":"provenance_review_TK10896"}
+{"vendor":"Carnegie","sku":"DWAG-100001-Sample","class":"MINT_RESIDUE_RESCRAPE","candidate":null,"collides":false,"group":"rescrape_program_TK10900"}
+{"vendor":"Phillip Jeffries","sku":"DWPP-200001-Sample","class":"SELF_COPY_DW","candidate":"DWPP-200001","collides":false,"group":"recoverable_now_self_copy"}
diff --git a/test/provenance-ledger.test.mjs b/test/provenance-ledger.test.mjs
new file mode 100644
index 0000000..7875547
--- /dev/null
+++ b/test/provenance-ledger.test.mjs
@@ -0,0 +1,56 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { createHash } from 'node:crypto';
+import { mkdtempSync, readFileSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { loadVerifiedLedger, joinPlanRows, REQUIRED_BACKUP_TABLE } from '../provenance-ledger-join.mjs';
+
+const fixture = (name) => new URL(`./fixtures/${name}`, import.meta.url);
+const ledgerBuffer = readFileSync(fixture('phase4-ledger.jsonl'));
+const ledgerSha = createHash('sha256').update(ledgerBuffer).digest('hex');
+const validManifest = { backup_table: REQUIRED_BACKUP_TABLE, complete: true, row_count: 2, sha256: ledgerSha };
+
+function tempManifest(overrides = {}) {
+  const dir = mkdtempSync(join(tmpdir(), 'tk10896-ledger-'));
+  const path = join(dir, 'manifest.json');
+  writeFileSync(path, JSON.stringify({ ...validManifest, ...overrides }));
+  return path;
+}
+
+test('verified complete ledger releases only codes excluded from exact mint set', () => {
+  const ledger = loadVerifiedLedger(fixture('phase4-ledger.jsonl'), tempManifest());
+  const plan = readFileSync(fixture('provenance-plan.jsonl'), 'utf8').trim().split('\n').map(JSON.parse);
+  const joined = joinPlanRows(plan, ledger);
+  assert.deepEqual(joined.stats, { rows: 4, minted_residue: 1, proven_native: 1, unchanged: 2 });
+  assert.equal(joined.rows[0].class, 'MINT_RESIDUE_RESCRAPE');
+  assert.equal(joined.rows[0].candidate, null);
+  assert.equal(joined.rows[1].class, 'SELF_COPY_DW_PROVEN_NATIVE');
+  assert.equal(joined.rows[1].candidate, 'DWKN-250001');
+  assert.equal(joined.rows[2].class, 'MINT_RESIDUE_RESCRAPE');
+  assert.equal(joined.rows[3].class, 'SELF_COPY_DW');
+});
+
+test('manifest must attest exact backup table and completeness', () => {
+  assert.throws(() => loadVerifiedLedger(fixture('phase4-ledger.jsonl'), tempManifest({ complete: false })), /complete=true/);
+  assert.throws(() => loadVerifiedLedger(fixture('phase4-ledger.jsonl'), tempManifest({ backup_table: 'other' })), /wrong backup_table/);
+});
+
+test('manifest row count and digest fail closed', () => {
+  assert.throws(() => loadVerifiedLedger(fixture('phase4-ledger.jsonl'), tempManifest({ row_count: 3 })), /row_count mismatch/);
+  assert.throws(() => loadVerifiedLedger(fixture('phase4-ledger.jsonl'), tempManifest({ sha256: '0'.repeat(64) })), /SHA-256 mismatch/);
+});
+
+test('duplicate assigned codes fail closed', () => {
+  const dir = mkdtempSync(join(tmpdir(), 'tk10896-ledger-'));
+  const ledgerPath = join(dir, 'ledger.jsonl');
+  const body = '{"assigned_dw_sku":"DWKN-1"}\n{"assigned_dw_sku":"DWKN-1"}\n';
+  writeFileSync(ledgerPath, body);
+  const sha256 = createHash('sha256').update(body).digest('hex');
+  assert.throws(() => loadVerifiedLedger(ledgerPath, tempManifest({ row_count: 2, sha256 })), /duplicate assigned_dw_sku/);
+});
+
+test('unrecognized provenance-review rows fail closed', () => {
+  const ledger = loadVerifiedLedger(fixture('phase4-ledger.jsonl'), tempManifest());
+  assert.throws(() => joinPlanRows([{ sku: 'DWPP-1', class: 'PROVENANCE_REVIEW' }], ledger), /no recognized mixed-use candidate/);
+});
diff --git a/verification/TK-10896-ledger-join-e2e-proof.json b/verification/TK-10896-ledger-join-e2e-proof.json
new file mode 100644
index 0000000..e86769d
--- /dev/null
+++ b/verification/TK-10896-ledger-join-e2e-proof.json
@@ -0,0 +1,50 @@
+{
+  "ticket": "TK-10896",
+  "intent": "Build a deterministic fail-closed local importer/join for a future separately authorized exact Phase-4 undo-ledger export.",
+  "risk_tier": "R1 local code and fixture files",
+  "environment": "Mac2 local repository; fixture inputs only; canonical/Kamatera untouched",
+  "baseline_commit": "189503094317db04e8be38ac2ff7da7b30b18ab6",
+  "timestamp_utc": "2026-08-30T18:30:58Z",
+  "precondition": "No local/exported sku_repair_p4_20260826 artifact found through Spotlight, bounded filename search, or targeted content search.",
+  "checks": [
+    {
+      "boundary": "unit and negative inputs",
+      "command": "npm test",
+      "assertion": "32/32 pass; wrong table, incomplete manifest, row-count mismatch, digest mismatch, duplicate codes, and unrecognized provenance rows all fail closed",
+      "verdict": "PASS"
+    },
+    {
+      "boundary": "fixture CLI journey",
+      "command": "node provenance-ledger-join.mjs --ledger test/fixtures/phase4-ledger.jsonl --manifest test/fixtures/phase4-ledger.manifest.json --plan test/fixtures/provenance-plan.jsonl --out /tmp/TK-10896-fixture-joined.jsonl",
+      "assertion": "4 rows processed: 1 exact minted residue, 1 ledger-excluded proven native, 2 unchanged; output has exactly 4 JSONL records",
+      "verdict": "PASS"
+    },
+    {
+      "boundary": "provenance",
+      "assertions": [
+        "exact ledger matches retain candidate=null and route to rescrape",
+        "only exclusion by an attested-complete exact ledger releases a mixed-prefix candidate",
+        "released candidate is derived by suffix stripping from the existing row SKU"
+      ],
+      "verdict": "PASS"
+    },
+    {
+      "boundary": "side effects",
+      "assertions": [
+        "module imports only local crypto/fs and classifier code",
+        "no database client, SSH, network, mint, Shopify, deploy, or cleanup path exists",
+        "only fixture output was written under /tmp"
+      ],
+      "verdict": "PASS"
+    },
+    {
+      "boundary": "syntax and diff",
+      "command": "node --check provenance-ledger-join.mjs && git diff --check",
+      "verdict": "PASS"
+    }
+  ],
+  "critical_path_skips": [],
+  "scope_limit": "A real export remains separately approval-gated; this phase proves only the local consumer contract.",
+  "cleanup": "Fixture output in /tmp is non-canonical and disposable; no persistent external state was created.",
+  "overall": "PASS"
+}

← 1895030 TK-10896 fail closed on mixed SKU provenance  ·  back to Dw Sku Integrity  ·  Record canonical SKU provenance join 07b0236 →