sememe 0.0.0-stage → 0.4.22

package/src/lock.mjs

@@ -0,0 +1,440 @@
+// sememe.lock — the fingerprint lockfile the README's contract promised and
+// the tree never shipped.
+//
+// What this module is NOT: not distribution, not an update path, not a second
+// acquisition channel. It records what a store ANSWERED with, so a project
+// can commit one document that says "my decode calls answered with these
+// fingerprints" and have CI refuse silent drift. The store reader
+// (src/store-read.mjs) already refuses a tampered object on every read; the
+// lock adds the cross-time check no single read can make: the store's answer
+// is still THE answer it was pinned at.
+//
+// The document is canonical JSON with a trailing newline (the same
+// serialization `pull`/`adopt` fingerprint their objects with), so diffs are
+// stable and the file is reproducible from the store alone. Refusals are
+// named, never guessed around:
+//   lock-v1-parse       the file is not JSON
+//   lock-v1-shape       the document is not a v1 lock (programs map etc.)
+//   lock-v1-fingerprint a pinned fingerprint is not sha256:<64 hex>
+//   lock-pins-nothing   the lock pins ZERO programs, so it can never detect
+//                       drift — a green gate over a check that never ran
+//                       (measured 2026-11-09: `sememe lock` on a store with
+//                       no receipts wrote `{"lockVersion":1,"programs":{}}`
+//                       and exited 0, and `sememe verify --mode error` over
+//                       that lock exited 0 with `pinned: 0, violations: 0`
+//                       against a real 18-program store)
+// Violations checkLock reports (each with the program named):
+//   drifted     the store answers the program with a DIFFERENT fingerprint
+//   missing     the store has no verified receipt for a pinned program
+//   unverified  an object fails the store reader's own re-hash check. The
+//               entry carries a `scope`: `pinned` (the lock names this
+//               program) or `extra` (the lock does NOT — the store gained the
+//               program later, and its receipt is damaged). The scope is part
+//               of the repair, so the two are never reported alike.
+//   relabelled  a pinned or stored DECLARED origin changed after the fact —
+//               the receipt says "declared" about bytes whose label no longer
+//               matches what was pinned (see src/receipt-digest.mjs)
+//   unbound     the store declares an origin the lock does NOT pin, so the
+//               gate cannot say whether that label changed. A lock written
+//               before origin pinning (every existing user's committed lock)
+//               pins no origin; a legacy receipt carries no self-digest, so
+//               nothing covers the label at all. Reported instead of passing,
+//               because "verified" over a claim that was never checked is the
+//               green lie this gate exists to prevent. Repair: `sememe lock`. 
+// Extra store programs are reported, never a violation: the lock pins
+// minimums, not store equality — a pull that ADDS a program must not fail
+// someone else's CI. writeLock refuses to write a lock over a store it cannot
+// fully verify: every receipt is re-checked through the store reader first,
+// so a lock is a snapshot of VERIFIED answers, never of filenames. The lock
+// pins each program's DECLARED origin next to its fingerprint: the fingerprint
+// binds the bytes, the origin pins the label the store answered with, and
+// neither may change silently.
+
+import { writeFile, readFile, readdir } from 'node:fs/promises';
+import path from 'node:path';
+import { canonicalJson } from './canonical.mjs';
+import { readVerified } from './store-read.mjs';
+import { compareReceiptNames } from './receipt-order.mjs';
+import { classifyReceiptFiles, isReceiptFile } from './receipt-name.mjs';
+
+const LOCK_VERSION = 1;
+const HEX64 = /^[a-f0-9]{64}$/;
+
+/** The program a receipt filename belongs to. Base58 program ids contain no
+ * `-`, so the first dash-terminated run is the program; the source label may
+ * contain dashes, the fingerprint never does (it is the last segment). */
+function programOfReceiptName(name) {
+  return name.split('-')[0];
+}
+
+/** Newest-selection rule, identical to `findStoredIdl`: sort by the ONE
+ * shared ordering (numeric slot, filename tiebreak), take last. A plain
+ * string sort here would pin "99999999" over "123456789" — two answers from
+ * one store, measured 2026-11-07 (test/slot-order-store.test.mjs O2). */
+async function newestReceipt(storeDir, program) {
+  const receipts = path.join(storeDir, 'receipts');
+  const names = (await readdir(receipts)).filter((name) => name.startsWith(`${program}-`) && isReceiptFile(name));
+  if (!names.length) return null;
+  names.sort(compareReceiptNames);
+  return readVerified(storeDir, program, names[names.length - 1]);
+}
+
+/** Every receipt of `program`, re-checked through the store reader.
+ *
+ * Measured 2026-11-07 (this host): a store may hold SEVERAL receipts for one
+ * program — a pull plus a published copy, or two published copies. `writeLock`
+ * re-checked only the NEWEST of them, so a DAMAGED second copy was skipped in
+ * silence: `sememe lock` exited 0 and `sememe verify` reported 0 violations
+ * over a store whose union decode refused to decode. The README's claim
+ * ("every receipt is re-checked through the store reader first, so a store the
+ * reader refuses produces NO lock, never a lock over damage") was therefore
+ * true of one receipt out of several.
+ *
+ * Every receipt is checked here, so a lock is a snapshot of VERIFIED answers
+ * over the WHOLE store, not of the receipt that happened to sort last.
+ *
+ * ONE helper for BOTH lock paths on purpose: `writeLock` (refuse to write) and
+ * `checkLock` (name the damage) must agree about what a clean store is. Two
+ * separate loops is how the store ended up "locked clean" and "verified
+ * damaged" in the same run. */
+async function verifyEveryReceipt(storeDir, program, names) {
+  for (const name of names) {
+    try {
+      await readVerified(storeDir, program, name);
+    } catch (error) {
+      // The failure KIND decides which bucket checkLock reports it in: a
+      // rewritten declared origin is a relabel, not an unreadable object.
+      return {
+        ok: false,
+        receipt: name,
+        reason: String(error?.message ?? error).slice(0, 300),
+        code: error?.code ?? null,
+      };
+    }
+  }
+  return { ok: true, receipt: null, reason: null, code: null };
+}
+
+/** Snapshot every verified receipt of `storeDir` into a lock document.
+ * Returns the document; `outPath` receives exactly its canonical bytes. */
+export async function writeLock(storeDir, outPath) {
+  const receipts = path.join(storeDir, 'receipts');
+  let names;
+  try { names = await readdir(receipts); }
+  catch (error) {
+    if (error?.code === 'ENOENT') {
+      throw Error(`no sememe store at ${storeDir}: run "sememe pull" first`);
+    }
+    throw error;
+  }
+  const programs = [...new Set(names.filter(isReceiptFile).map(programOfReceiptName))].sort();
+  // A lock that pins NOTHING is not a lock: it can never detect a drifted
+  // fingerprint, a missing receipt or a rewritten origin. Measured
+  // 2026-11-09: `sememe lock` over a store whose receipts/ directory holds
+  // no receipt wrote `{"lockVersion":1,"programs":{}}` and exited 0 — and
+  // `sememe verify --mode error` over that lock exited 0 with
+  // `pinned: 0, violations: 0` against a REAL 18-program store, reporting
+  // every program as an `extra` (extras are never violations). The gate was
+  // green over a check that never ran, and it LOOKED informative. So a lock
+  // over an empty store is REFUSED and no file is written: the repair is to
+  // pull a program first, not to commit a lock that certifies nothing.
+  if (programs.length === 0) {
+    throw Error(
+      `the store at ${storeDir} pins nothing: it holds no receipt, so a lock over it could never detect drift `
+      + `(lock-pins-nothing) — run "sememe pull <program-id> --store ${storeDir}" first, then lock again`,
+    );
+  }
+  const doc = { lockVersion: LOCK_VERSION, programs: {} };
+  for (const program of programs) {
+    // Full verification through the store reader: a tampered object or a
+    // dangling receipt must fail the LOCK, not silently enter it — and that
+    // holds for EVERY receipt of the program, not only the newest one.
+    const candidates = names.filter((name) => name.startsWith(`${program}-`) && isReceiptFile(name));
+    const verdict = await verifyEveryReceipt(storeDir, program, candidates);
+    if (!verdict.ok) {
+      // Refuse the lock: a store the reader refuses must produce NO lock.
+      throw Error(verdict.reason);
+    }
+    const { idl, receipt, receiptName } = await newestReceipt(storeDir, program);
+    doc.programs[program] = {
+      fingerprint: receipt.fingerprint,
+      source: receipt.source ?? 'unknown',
+      slot: receipt.slot ?? null,
+      receipt: receiptName,
+      instructions: Array.isArray(idl.instructions) ? idl.instructions.length : 0,
+      // The DECLARED origin, pinned beside the fingerprint. Absent for an
+      // on-chain receipt (it names no file) and for a legacy adopted receipt
+      // without one; `null` never appears — a pinned origin is a string.
+      ...(receipt.origin === undefined || receipt.origin === null ? {} : {
+        origin: receipt.origin,
+        originStatus: receipt.originStatus ?? 'declared',
+      }),
+    };
+  }
+  const bytes = Buffer.from(`${canonicalJson(doc)}\n`);
+  if (outPath !== undefined && outPath !== null) {
+    await writeFile(outPath, bytes);
+  }
+  return doc;
+}
+
+/** Parse and shape-check a lock document. Every failure names its reason. */
+export async function readLock(lockPath) {
+  let raw;
+  try { raw = await readFile(lockPath, 'utf8'); }
+  catch (error) {
+    throw Error(`sememe lock file ${lockPath} is unreadable: ${String(error?.message ?? error).slice(0, 140)}`);
+  }
+  let doc;
+  try { doc = JSON.parse(raw); }
+  catch {
+    throw Error(`sememe lock file ${lockPath} is not JSON (lock-v1-parse)`);
+  }
+  if (!doc || typeof doc !== 'object' || Array.isArray(doc)) {
+    throw Error(`sememe lock file ${lockPath} is not a lock document (lock-v1-shape)`);
+  }
+  if (doc.lockVersion !== LOCK_VERSION) {
+    throw Error(`sememe lock file ${lockPath} has unsupported lockVersion ${JSON.stringify(doc.lockVersion)} — expected ${LOCK_VERSION} (lock-v1-shape)`);
+  }
+  if (!doc.programs || typeof doc.programs !== 'object' || Array.isArray(doc.programs)) {
+    throw Error(`sememe lock file ${lockPath} has no programs map (lock-v1-shape)`);
+  }
+  // A lock that pins ZERO programs certifies nothing: there is no pinned
+  // answer a drifted store could contradict, so every store would pass it.
+  // Measured 2026-11-09 (this host, published v0.4.13 AND main): an empty
+  // `programs` map made `sememe verify --mode error` exit 0 with
+  // `pinned: 0, violations: 0` against a real 18-program store — a green CI
+  // gate over a check that never ran. The refusal is about the DOCUMENT, not
+  // about the store, so it applies in `--mode warn` too: warn mode exists to
+  // downgrade STORE violations, not to certify a lock that pins nothing.
+  if (Object.keys(doc.programs).length === 0) {
+    throw Error(
+      `sememe lock file ${lockPath} pins no program (lock-pins-nothing): a lock over zero answers can never `
+      + `detect drift — re-create it with "sememe lock" over a store that holds at least one receipt`,
+    );
+  }
+  for (const [program, entry] of Object.entries(doc.programs)) {
+    if (!entry || typeof entry !== 'object') {
+      throw Error(`sememe lock file ${lockPath} pins ${program} with a non-object entry (lock-v1-shape)`);
+    }
+    const fingerprint = typeof entry.fingerprint === 'string' ? entry.fingerprint.replace(/^sha256:/, '') : '';
+    if (!HEX64.test(fingerprint)) {
+      throw Error(`sememe lock file ${lockPath} pins ${program} with a malformed fingerprint ${JSON.stringify(entry.fingerprint)} (lock-v1-fingerprint)`);
+    }
+    if (entry.origin !== undefined && typeof entry.origin !== 'string') {
+      throw Error(`sememe lock file ${lockPath} pins ${program} with a malformed origin ${JSON.stringify(entry.origin)} (lock-v1-origin)`);
+    }
+  }
+  return doc;
+}
+
+/** Re-check a store against a lock document. Returns the full report.
+ * `mode: 'error'` (the CI-gate default) throws after the report is complete
+ * when any violation exists; `mode: 'warn'` never throws on violations. */
+export async function checkLock(storeDir, lockPath, { mode = 'error' } = {}) {
+  const doc = await readLock(lockPath);
+  const pinnedPrograms = Object.keys(doc.programs).sort();
+
+  let receiptNames = [];
+  try { receiptNames = (await readdir(path.join(storeDir, 'receipts'))); }
+  catch (error) {
+    if (error?.code === 'ENOENT') {
+      throw Error(`no sememe store at ${storeDir}: run "sememe pull" first`);
+    }
+    throw error;
+  }
+  // The same ONE ordering the writer and both readers use, so "newest" means
+  // the same receipt on every side of a lock comparison.
+  // Stray files (sememe's own uncommitted .tmp- debris from a crash, or a
+  // file that carries no slot segment) are partitioned off: they are not
+  // receipts and reading them as receipts would fail the gate over a clean
+  // store (measured 2026-11-07). Malformed receipts (a slot segment but bad
+  // hex/suffix) stay in `receiptNames` and are refused by name — they are
+  // damage to the store, not uncommitted writes.
+  const { receipts: validReceipts, stray } = classifyReceiptFiles(receiptNames);
+  validReceipts.sort(compareReceiptNames);
+  const storePrograms = [...new Set(validReceipts.map(programOfReceiptName))].sort();
+
+  const report = {
+    lock: path.resolve(lockPath),
+    store: path.resolve(storeDir),
+    mode,
+    pinned: pinnedPrograms.length,
+    verified: [],
+    drifted: [],
+    missing: [],
+    unverified: [],
+    // A declared origin that is no longer the one that was pinned, or a
+    // receipt whose own declared label no longer matches its digest.
+    relabelled: [],
+    // A declared origin the lock does not pin at all: the gate cannot
+    // certify a label it never recorded.
+    unbound: [],
+    extra: storePrograms.filter((program) => !doc.programs[program]),
+    // Non-receipt files found in receipts/ (sememe's own .tmp- crash debris,
+    // foreign files): reported by name and kind, never a violation — an
+    // uncommitted write is safe to ignore.
+    stray,
+  };
+
+  for (const program of pinnedPrograms) {
+    const pinnedFingerprint = doc.programs[program].fingerprint.replace(/^sha256:/, '');
+    const candidates = validReceipts.filter((name) => name.startsWith(`${program}-`));
+    if (!candidates.length) {
+      report.missing.push(program);
+      continue;
+    }
+    const newest = candidates[candidates.length - 1];
+    // Every receipt of this program is re-checked, not only the newest: a
+    // damaged SECOND copy is a damaged store, and reporting it as clean is the
+    // green lie this gate exists to prevent. The SAME helper the writer uses,
+    // so "lock" and "verify" cannot disagree about the store.
+    const verdict = await verifyEveryReceipt(storeDir, program, candidates);
+    if (!verdict.ok) {
+      if (verdict.code === 'receipt-relabelled') {
+        // The declared origin in the receipt no longer matches its own digest:
+        // the label was rewritten after the receipt was written. Reported as
+        // its own violation kind so a caller can see that the BYTES are fine
+        // and the PROVENANCE claim is not.
+        report.relabelled.push({ program, receipt: verdict.receipt, reason: verdict.reason, scope: 'receipt' });
+      } else {
+        report.unverified.push({ program, receipt: verdict.receipt, reason: verdict.reason });
+      }
+      continue;
+    }
+    let source;
+    try {
+      source = await readVerified(storeDir, program, newest);
+    } catch (error) {
+      if (error?.code === 'receipt-relabelled') {
+        report.relabelled.push({
+          program,
+          receipt: newest,
+          reason: String(error?.message ?? error).slice(0, 300),
+          scope: 'receipt',
+        });
+      } else {
+        report.unverified.push({ program, receipt: newest, reason: String(error?.message ?? error).slice(0, 200) });
+      }
+      continue;
+    }
+    const storeFingerprint = source.receipt.fingerprint.replace(/^sha256:/, '');
+    if (storeFingerprint !== pinnedFingerprint) {
+      report.drifted.push({
+        program,
+        pinned: `sha256:${pinnedFingerprint}`,
+        store: `sha256:${storeFingerprint}`,
+        storeReceipt: newest,
+      });
+      continue;
+    }
+    // Fingerprint matches: now the DECLARED ORIGIN must still be the pinned
+    // one. The receipt's own digests catch an edited receipt; this catches a
+    // receipt that was rewritten AND re-digested after the lock was written —
+    // the layer a self-digest alone cannot cover, because the attacker holds
+    // the same hashing function.
+    const pinnedOrigin = doc.programs[program].origin;
+    const storeOrigin = source.receipt.origin ?? null;
+    if (typeof pinnedOrigin === 'string') {
+      if (storeOrigin !== pinnedOrigin) {
+        report.relabelled.push({
+          program,
+          receipt: newest,
+          pinned: pinnedOrigin,
+          store: storeOrigin,
+          reason: `the store no longer declares origin ${JSON.stringify(pinnedOrigin)} for ${program} — the store answers ${storeOrigin === null ? 'no origin' : JSON.stringify(storeOrigin)}`,
+          scope: 'lock',
+        });
+        continue;
+      }
+    } else if (storeOrigin !== null) {
+      // The store answers with a DECLARED origin this lock does not pin. For
+      // a legacy receipt there is no self-digest either, so this label is
+      // covered by nothing: a rewrite of it would look exactly like the
+      // untouched case. Say so, and name the one command that binds it —
+      // writeLock already pins `receipt.origin`, so the repair really works.
+      report.unbound.push({
+        program,
+        receipt: newest,
+        store: storeOrigin,
+        reason: `the store declares origin ${JSON.stringify(storeOrigin)} for ${program}, but sememe.lock does not pin it — this lock predates origin pinning, so a rewritten origin here cannot be detected; re-run "sememe lock" to bind it`,
+        scope: 'lock',
+      });
+      continue;
+    }
+    report.verified.push(program);
+  }
+
+  // EXTRA programs are re-checked too. The lock pins MINIMUMS, so a program
+  // the store gained is still only reported (presence is never a violation —
+  // that contract is G1 in test/extra-program-damage.test.mjs and must not
+  // move). But DAMAGE is not presence: measured 2026-11-07 on this tree
+  // (pre-fix 61df87b), a store whose LATER-PULLED extra program carried an
+  // object that no longer re-hashed to its receipt gave
+  //
+  //     sememe lock   -> EXIT 1, no lock written  (writeLock re-checks extras)
+  //     sememe verify -> EXIT 0, violations 0     (checkLock never read them)
+  //
+  // Two commands, two verdicts about ONE store, and a green CI gate over a
+  // program the store reader refuses: `sememe decode` on that same program
+  // exits 1 with "object and receipt disagree, refusing to decode". The
+  // shared helper existed; only the PINNED loop ever called it — the same
+  // "one store, two strengths" class this repo killed for the newest-receipt
+  // path on 2026-11-07, one level down.
+  //
+  // So extras run through the SAME helper, and only their FAILURES are
+  // reported (as `unverified`/`relabelled` with scope `extra`, so pin drift is
+  // not misread as the cause). What is NOT checked for an extra: binding it
+  // against the lock's origin pin — an unpinned program has no pin to bind
+  // to, and demanding one would turn "someone pulled a program" into a CI
+  // failure, which is exactly the equality rule the lock rejects.
+  for (const program of report.extra) {
+    const candidates = validReceipts.filter((name) => name.startsWith(`${program}-`));
+    if (!candidates.length) continue; // no receipt left to check
+    const verdict = await verifyEveryReceipt(storeDir, program, candidates);
+    if (verdict.ok) continue;
+    const entry = {
+      program,
+      receipt: verdict.receipt,
+      reason: verdict.reason,
+      scope: 'extra',
+    };
+    if (verdict.code === 'receipt-relabelled') {
+      report.relabelled.push({ ...entry, scope: 'extra' });
+    } else {
+      report.unverified.push(entry);
+    }
+  }
+
+  const violations = report.drifted.length + report.missing.length
+    + report.unverified.length + report.relabelled.length + report.unbound.length;
+  report.violations = violations;
+  if (mode === 'error' && violations > 0) {
+    const parts = [];
+    if (report.drifted.length) {
+      parts.push(`drifted: ${report.drifted.map((d) => `${d.program} pinned ${d.pinned} vs store ${d.store}`).join('; ')}`);
+    }
+    if (report.missing.length) parts.push(`missing: ${report.missing.join(', ')}`);
+    if (report.unverified.length) {
+      // The scope is part of the repair: `extra` means the LOCK is fine and
+      // the STORE holds a damaged receipt for a program the lock never pinned
+      // (re-pull or drop that receipt) — while a pinned name means the pin no
+      // longer describes the store (re-run `sememe lock`). One list, two very
+      // different repairs; the refusal must not make them look alike.
+      // For an extra, the RECEIPT is named too: it is the file in the store
+      // that has to be re-pulled, and its name carries the fingerprint the
+      // receipt claims — the number a reader needs to look the damage up.
+      parts.push(`unverified: ${report.unverified.map((u) => (u.scope === 'extra'
+        ? `${u.program} (extra, receipt ${u.receipt})`
+        : u.program)).join(', ')}`);
+    }
+    if (report.relabelled.length) {
+      parts.push(`relabelled (declared origin changed): ${report.relabelled.map((r) => (r.scope === 'extra' ? `${r.program} (extra)` : r.program)).join(', ')}`);
+    }
+    if (report.unbound.length) {
+      parts.push(`unbound (declared origin not pinned by the lock): ${report.unbound.map((r) => r.program).join(', ')} — re-run "sememe lock"`);
+    }
+    throw Error(`store does not match sememe.lock (${report.drifted.length} drifted, ${report.missing.length} missing, ${report.unverified.length} unverified, ${report.relabelled.length} relabelled, ${report.unbound.length} unbound) — ${parts.join(' | ')}`);
+  }
+  return report;
+}

package/src/native-audit.mjs

@@ -0,0 +1,56 @@
+/**
+ * native-audit.mjs — THE DERIVATION AUDIT, callable by a consumer.
+ *
+ * tools/native-interface.mjs --check answers "is the committed interface artifact exactly
+ * what the vendored upstream Rust derives to today?" — but as a subprocess in sememe's own
+ * checkout. A consumer that installed the package has no checkout and no tools/ directory
+ * (deliberately: the qualification harness does not ship), so this module carries the same
+ * verdict as an import: re-derive both pinned native interfaces from vendor/ and compare
+ * against the shipped interface/ artifacts byte-for-byte.
+ *
+ * This is the same audit sememe's own suite runs (test/native-interface.test.mjs), moved to
+ * a package surface. It exists so a consumer can falsify the table it was handed instead of
+ * trusting it: the verdict is derived in the consumer's process from the shipped upstream
+ * bytes, not read from a log the producer wrote about itself.
+ */
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { deriveAll } from './native-interface.mjs';
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+const INTERFACE_DIR = path.resolve(HERE, '..', 'interface');
+
+/**
+ * Re-derive every pinned native interface from the vendored upstream sources and compare
+ * with the shipped artifacts.
+ *
+ * Returns `{ ok, checked, stale, missing, error }` where `checked` is the number of
+ * artifacts compared and `stale` names each artifact whose bytes differ from a fresh
+ * derivation. `ok === false` with a non-empty `stale` is the interesting failure: the
+ * derivation rules or the vendored bytes moved without the committed artifact following.
+ */
+export function auditNativeInterface() {
+  const stale = [];
+  const missing = [];
+  let checked = 0;
+  let docs;
+  try {
+    docs = deriveAll();
+  } catch (error) {
+    return { ok: false, checked, stale, missing, error: `derivation failed: ${error.message}` };
+  }
+  for (const doc of docs) {
+    const file = path.join(INTERFACE_DIR, `native-${doc.program}.json`);
+    let current;
+    try {
+      current = readFileSync(file, 'utf8');
+    } catch {
+      missing.push(path.basename(file));
+      continue;
+    }
+    checked += 1;
+    if (current !== `${JSON.stringify(doc, null, 2)}\n`) stale.push(path.basename(file));
+  }
+  return { ok: stale.length === 0 && missing.length === 0, checked, stale, missing, error: null };
+}

package/src/native-corpus.mjs

@@ -0,0 +1,57 @@
+/**
+ * native-corpus.mjs — sememe's REAL MAINNET NATIVE-PROGRAM CORPUS, shipped with the package.
+ *
+ * The two harvests here are the measured traffic the native decoder was qualified against
+ * (2026-10-31): every System and ComputeBudget payload pulled from live mainnet blocks,
+ * with the bytes the chain actually carried. A decoder can be checked against invented
+ * bytes; these are not invented — each carries its own provenance (slot, block, index)
+ * inside the harvest document.
+ *
+ * Why this ships instead of staying a test fixture: sememe's first in-tree consumer
+ * (solana-tx-remix) falsifies its own native path against the SAME corpus — "the table I
+ * consume names the chain's traffic" is a claim about the consumer, and the bytes it is
+ * judged on must be the producer's, not a stale copy. A copy in the consumer's tree is
+ * exactly the drift this package exists to end. The corpus is addressed by its sha256, so
+ * the consumer can pin and re-hash what it was given.
+ *
+ * `default` returns the whole document; `payloads(program)` flattens the wire bytes to
+ * Buffers. Neither decodes anything: reading is this module's whole job.
+ */
+import { readFileSync } from 'node:fs';
+import { createHash } from 'node:crypto';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+
+export const SYSTEM_PROGRAM = '11111111111111111111111111111111';
+export const COMPUTE_BUDGET_PROGRAM = 'ComputeBudget111111111111111111111111111111';
+
+export const CORPUS = {
+  system: { file: 'harvest-system-2026-10-31.json', sha256: 'sha256:75c7052ebc8e1f18a0e2cb3fb1fb70b9963141f86b5994b3f1e64b4d9c64fd7d' },
+  computeBudget: { file: 'harvest-compute-budget-2026-10-31.json', sha256: 'sha256:25354bf24977ee52371cf307db2edab9fa7108662d68018db2aba63ba8172295' },
+};
+
+/** One harvest document, byte-hashed on every read. */
+export function corpus(which) {
+  const entry = CORPUS[which];
+  if (!entry) throw Error(`unknown corpus ${String(which)}; expected one of ${Object.keys(CORPUS).join(', ')}`);
+  const raw = readFileSync(path.join(HERE, 'corpus', entry.file));
+  const actual = `sha256:${createHash('sha256').update(raw).digest('hex')}`;
+  if (actual !== entry.sha256) {
+    throw Error(`corpus ${which} re-hashes to ${actual}, expected ${entry.sha256} — the shipped bytes are not the qualified ones`);
+  }
+  return JSON.parse(raw);
+}
+
+/** Every wire payload in one harvest, as Buffers (payload.dataHex). */
+export function payloads(which) {
+  const document = corpus(which);
+  const out = [];
+  for (const transaction of document.transactions ?? []) {
+    for (const payload of transaction.payloads ?? []) {
+      if (typeof payload.dataHex === 'string') out.push(Buffer.from(payload.dataHex, 'hex'));
+    }
+  }
+  return out;
+}