sememe 0.0.0-stage → 0.4.22

package/src/drift.mjs

@@ -0,0 +1,172 @@
+// Which differences between two decoded argument trees are LAYOUT differences?
+//
+// Why this file exists (measured 2026-11-09): two verified copies of the same
+// program can spell the same field differently — the on-chain copy of
+// meteora-damm-v1 says `lpMint`, its published copy says `lp_mint`. The union
+// reported that as a LAYOUT DRIFT and listed the fields one by one, so a
+// reader was told "the two copies disagree about the data" about a field that
+// both copies decoded to the SAME value.
+//
+// The measurement (tools/measure-drift-naming.mjs, research/drift-naming-2026-11-09.json)
+// over every program in the repo that holds two verified copies:
+//
+//   pump.fun          88 instruction drift rows, 6 account drift rows: all real differences
+//   meteora-damm-v1  643 instruction drift rows on the pre-fix tree, ALL of them
+//                    NOTHING BUT spelling differences (`inAmount` vs `in_amount`,
+//                    `claimFee` vs `claim_fee`) that raw JSON equality turned
+//                    into `layout_drift`
+//   meteora-damm-v1   11 account drift rows, every row hitting the 20-path cap (220 paths);
+//                     33 REAL differences were crowded out by spelling paths
+//
+// The rule this file applies is the one the declared-layout report already
+// states in the README: NAMING STYLE IS NOT A LAYOUT DIFFERENCE. Fields are
+// paired by normalised spelling (`_padding0` and `padding0` are the same
+// field; `totalAmount` and `total_amount` are the same field), and only a
+// difference in the VALUE or in the SHAPE of a paired field is a difference
+// in the data.
+//
+// Two things this file does NOT do:
+//
+//   * it does not change WHICH source won — arbitration is by bytes, and this
+//     file only describes what the disagreement was;
+//   * it does not hide the spelling difference — it is reported, in its own
+//     list, under `spellingOnly`. The reader learns that the two copies call
+//     the same field different things; they just do not get told the two
+//     copies disagree about the data when they do not.
+//
+// A field only one side declares is still a real difference and is still
+// reported: pairing by name does not make a missing field present.
+
+/** The bound on how many differences one report lists. */
+export const MAX_DRIFT_PATHS = 20;
+
+/**
+ * Normalise a field name so that spelling styles pair up:
+ * leading underscores are dropped and `snake_case` becomes `camelCase`.
+ * `totalAmount` / `total_amount` / `_total_amount` all normalise to
+ * `totalAmount`.
+ */
+export function normaliseFieldName(name) {
+  return String(name)
+    .replace(/^_+/, '')
+    .replace(/_+([a-z0-9])/g, (m, c) => c.toUpperCase());
+}
+
+/** Pair two sides' keys by normalised spelling, in declaration order. */
+function pairKeys(a, b) {
+  const group = (obj) => {
+    const map = new Map();
+    for (const key of Object.keys(obj)) {
+      const nk = normaliseFieldName(key);
+      if (!map.has(nk)) map.set(nk, []);
+      map.get(nk).push(key);
+    }
+    return map;
+  };
+  const aMap = group(a);
+  const bMap = group(b);
+  const pairs = [];
+  const seen = new Set();
+  for (const nk of [...aMap.keys(), ...bMap.keys()]) {
+    if (seen.has(nk)) continue;
+    seen.add(nk);
+    const aKeys = aMap.get(nk) ?? [];
+    const bKeys = bMap.get(nk) ?? [];
+    const n = Math.min(aKeys.length, bKeys.length);
+    for (let i = 0; i < n; i += 1) pairs.push({ a: aKeys[i], b: bKeys[i], paired: true });
+    for (let i = n; i < aKeys.length; i += 1) pairs.push({ a: aKeys[i], b: null, paired: false });
+    for (let i = n; i < bKeys.length; i += 1) pairs.push({ a: null, b: bKeys[i], paired: false });
+  }
+  return pairs;
+}
+
+const isPlainObject = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
+const sameValue = (a, b) => JSON.stringify(a) === JSON.stringify(b);
+
+/**
+ * Compare two decoded argument trees.
+ *
+ * @returns {{
+ *   paths: string[],
+ *   truncated: boolean,
+ *   differs: boolean,
+ *   spellingOnly: Array<{ path: string, primary: string, secondary: string }>,
+ *   details: Array<Record<string, unknown>>,
+ * }}
+ *   `paths` are the REAL differences (value or shape), named in the primary's
+ *   spelling where the field exists on both sides; `spellingOnly` are the
+ *   fields both sides declare under different names. `differs` is the verdict
+ *   input: true only when `paths` is non-empty, so a spelling difference can
+ *   never make the union say the two copies disagree about the data.
+ */
+export function diffArgsByNormalisedName(primaryArgs, secondaryArgs, { max = MAX_DRIFT_PATHS } = {}) {
+  const paths = [];
+  const details = [];
+  const spellingOnly = [];
+  let truncated = false;
+
+  const push = (path, detail) => {
+    if (paths.length >= max) { truncated = true; return; }
+    paths.push(path);
+    details.push(detail);
+  };
+
+  const compareArrays = (a, b, path) => {
+    const n = Math.min(a.length, b.length);
+    let differing = 0;
+    for (let i = 0; i < n; i += 1) {
+      if (!sameValue(a[i], b[i])) differing += 1;
+    }
+    const extra = Math.abs(a.length - b.length);
+    if (differing === 0 && extra === 0) return;
+    push(path || '(root)', {
+      path: path || '(root)',
+      kind: 'array',
+      primaryLength: a.length,
+      secondaryLength: b.length,
+      differingElements: differing + extra,
+    });
+  };
+
+  const walk = (a, b, path) => {
+    if (truncated) return;
+    if (Array.isArray(a) || Array.isArray(b)) {
+      if (Array.isArray(a) && Array.isArray(b)) { compareArrays(a, b, path); return; }
+      push(path || '(root)', { path: path || '(root)', kind: 'shape' });
+      return;
+    }
+    if (!isPlainObject(a) || !isPlainObject(b)) {
+      if (!sameValue(a, b)) {
+        push(path || '(root)', { path: path || '(root)', kind: 'value', primary: a, secondary: b });
+      }
+      return;
+    }
+    for (const { a: aKey, b: bKey, paired } of pairKeys(a, b)) {
+      if (truncated) return;
+      const display = aKey ?? bKey;
+      const childPath = path ? `${path}.${display}` : display;
+      if (!paired) {
+        push(childPath, { path: childPath, kind: 'missing', side: aKey === null ? 'secondary' : 'primary' });
+        continue;
+      }
+      if (aKey !== bKey) {
+        // Same field, different spelling. It is still reported as a naming
+        // difference; it only counts as a difference in the DATA when the
+        // values behind the two names are not the same.
+        spellingOnly.push({ path: childPath, primary: aKey, secondary: bKey });
+        if (sameValue(a[aKey], b[bKey])) continue;
+      }
+      walk(a[aKey], b[bKey], childPath);
+    }
+  };
+
+  walk(primaryArgs, secondaryArgs, '');
+
+  return {
+    paths,
+    truncated,
+    differs: paths.length > 0,
+    spellingOnly,
+    details,
+  };
+}

package/src/gap.mjs

@@ -0,0 +1,205 @@
+// `sememe gap <program>` — why is there no interface here? Asked BEFORE pull.
+//
+// WHY THIS FILE EXISTS
+//
+// The full foreign sweep (research/step-ingestooor-full-sweep-2026-11-04.json)
+// ended with 306 no-interface payloads across 70 programs, and the reflex is to
+// call them all "acquisition gaps ... next derivation candidates". That label
+// conflates two problems that need OPPOSITE fixes:
+//
+//   - a program that PUBLISHES an on-chain IDL at one of the two addresses
+//     sememe can read is a NEVER-PULLED gap: `sememe pull` closes it, no
+//     derivation exists to do;
+//   - a program with neither address answering publishes nothing: pulling it
+//     forever cannot help (it needs `sememe adopt` of a first-party published
+//     copy, or a pinned upstream derivation, or a vendored wire table).
+//
+// Measured 2026-11-04 against live mainnet over all 70 gap programs:
+// 34 publish an IDL (177 payloads) — including Jupiter DCA, which the card had
+// listed as a derivation candidate — and 36 publish nothing (129 payloads),
+// among them the largest single gap (L2TExM, 42 payloads, Lighthouse).
+//
+// WHY IT IS A TOOL AND NOT A PARAGRAPH
+//
+// 1. An RPC failure is NEVER recorded as "publishes nothing". The crates.io
+//    403 incident (signerd, 2026-11-03) is the standing example: a client
+//    failure that reads like an absence. Unknown rows are counted separately
+//    and the verdict is withheld (`no-verdict`) so a partial probe cannot be
+//    quoted as a complete one.
+// 2. A program sememe answers WITHOUT an IDL (System, ComputeBudget, SPL Token,
+//    Token-2022, Raydium AMM v4) is `vendored`, not a gap: telling a reader to
+//    pull it would send them after a receipt that can never exist.
+// 3. An account that EXISTS but cannot be decoded is `present-undecodable`, its
+//    own verdict, never folded into "publishes nothing": an unusable interface
+//    is a different finding from an absent one.
+// 4. Payload counts come from the committed sweep report, and its
+//    `noInterface` headline must equal the sum of the per-program counts —
+//    a hand-edited artifact is refused before it can be probed.
+//
+// This file lives in src/ so the shipped CLI can offer it: tools/ is not part
+// of the published package (see "files" in package.json), and a consumer who
+// hits `no stored IDL for program X` must be able to ask WHY from the same
+// install they run `sememe decode` from. The acquisition dependency
+// (@solana/web3.js, via ./acquire.mjs) is loaded lazily by the caller exactly
+// like `pull`, so the decode-only install path stays dependency-free.
+
+import { addresses, inspect, rpcAccounts } from './acquire.mjs';
+import { LIGHTHOUSE_PROGRAM } from './lighthouse.mjs';
+import { isNativeProgram } from './native.mjs';
+import { isTokenProgram } from './token.mjs';
+import { isRaydiumProgram } from './raydium.mjs';
+import { isAtaProgram } from './ata.mjs';
+
+const VENDORED = 'vendored';
+
+/** Programs sememe answers with a pinned wire table, so there is no IDL to fetch. */
+export function vendoredProgram(program) {
+  if (isNativeProgram(program)) return 'native';
+  if (isTokenProgram(program)) return 'token';
+  if (isRaydiumProgram(program)) return 'raydium';
+  if (isAtaProgram(program)) return 'ata';
+  return null;
+}
+
+/**
+ * Classify ONE gap program from its two probe accounts (metadata, anchor).
+ *
+ * Every path returns a verdict; nothing throws on bad data, so a caller can
+ * aggregate instead of losing a whole run to one malformed account.
+ */
+export function classify(program, accounts, hints = {}) {
+  const vendored = vendoredProgram(program);
+  if (vendored) return { program, verdict: VENDORED, kind: vendored };
+  const c = hints.canonical ?? inspect(accounts?.[0], 'metadata', program);
+  const l = hints.legacy ?? inspect(accounts?.[1], 'anchor', program);
+  const usable = c.state === 'usable' ? 'metadata' : l.state === 'usable' ? 'anchor' : null;
+  if (usable) {
+    const chosen = usable === 'metadata' ? c : l;
+    return {
+      program, verdict: 'pullable', source: usable,
+      instructions: chosen.instructions,
+      decodableStoredOnly: chosen.decodableStoredOnly,
+      canonical: c.state, legacy: l.state,
+    };
+  }
+  if (c.state === 'missing' && l.state === 'missing') {
+    return { program, verdict: 'no-interface-published', canonical: c.state, legacy: l.state };
+  }
+  return {
+    program, verdict: 'present-undecodable',
+    canonical: c.state, legacy: l.state,
+    error: c.state === 'undecodable' ? c.error : l.state === 'undecodable' ? l.error : undefined,
+  };
+}
+
+const chunk = (items, size) => {
+  const out = [];
+  for (let i = 0; i < items.length; i += size) out.push(items.slice(i, i + size));
+  return out;
+};
+
+/**
+ * Probe a list of `{ program, payloads }` entries against the chain.
+ *
+ * 25 programs per request = 50 keys; the public endpoint rejects larger
+ * getMultipleAccounts batches (-32602), measured while building this.
+ */
+export async function probeGap(programs, options = {}) {
+  const {
+    url = 'https://api.mainnet-beta.solana.com',
+    fetcher = fetch,
+    batchSize = 25,
+    tries = 3,
+  } = options;
+  if (!Array.isArray(programs) || !programs.length) throw Error('programs required');
+  const rows = [];
+  let slot = null;
+  for (const group of chunk(programs, batchSize)) {
+    const locations = await Promise.all(group.map(async ({ program }) => addresses(program)));
+    const keys = locations.flatMap(({ metadata, anchor }) => [metadata, anchor]);
+    const response = await rpcAccounts(url, keys, fetcher, tries);
+    if (response.error) {
+      // The whole batch is UNKNOWN — and unknown must never become absence.
+      for (const { program, payloads } of group) {
+        rows.push({ program, payloads, verdict: 'unknown', error: response.error });
+      }
+      continue;
+    }
+    slot = response.slot ?? slot;
+    group.forEach(({ program, payloads }, index) => {
+      const accounts = [response.accounts[2 * index], response.accounts[2 * index + 1]];
+      rows.push({ program, payloads, slot, ...classify(program, accounts) });
+    });
+  }
+  return { rows, summary: summarize(rows), slot };
+}
+
+export function summarize(rows) {
+  const byVerdict = {};
+  const payloadsByVerdict = {};
+  for (const row of rows) {
+    byVerdict[row.verdict] = (byVerdict[row.verdict] ?? 0) + 1;
+    payloadsByVerdict[row.verdict] = (payloadsByVerdict[row.verdict] ?? 0) + (row.payloads ?? 0);
+  }
+  const unknown = byVerdict.unknown ?? 0;
+  return {
+    programs: rows.length,
+    payloads: rows.reduce((sum, row) => sum + (row.payloads ?? 0), 0),
+    byVerdict, payloadsByVerdict,
+    unknown,
+    // Withhold the verdict when any probe failed: a partial probe is not a
+    // statement about the rows it failed on, and must not be quoted as one.
+    verdict: unknown > 0 ? 'no-verdict' : 'measured',
+    pullablePrograms: byVerdict.pullable ?? 0,
+    pullablePayloads: payloadsByVerdict.pullable ?? 0,
+    publishesNothingPrograms: byVerdict['no-interface-published'] ?? 0,
+    publishesNothingPayloads: payloadsByVerdict['no-interface-published'] ?? 0,
+    undecodablePrograms: byVerdict['present-undecodable'] ?? 0,
+    vendoredPrograms: byVerdict[VENDORED] ?? 0,
+    knownPrograms: rows.length - unknown,
+  };
+}
+
+/**
+ * Turn a committed sweep report's `noInterfaceByProgram` map into the entries
+ * probeGap takes. The report is the denominator: its headline must equal the
+ * sum of the per-program counts, or the artifact has been hand-edited.
+ */
+export function programsFromReport(report) {
+  const perProgram = report?.noInterfaceByProgram;
+  if (!perProgram || typeof perProgram !== 'object' || Array.isArray(perProgram)) {
+    throw Error('report has no noInterfaceByProgram map');
+  }
+  const programs = Object.entries(perProgram).map(([program, payloads]) => ({ program, payloads }));
+  if (!programs.length) throw Error('report has no gap programs');
+  const sum = programs.reduce((total, { payloads }) => total + payloads, 0);
+  if (sum !== report.noInterface) {
+    throw Error(`gap counts sum to ${sum} but report.noInterface says ${report.noInterface} — hand-edited artifact`);
+  }
+  return programs;
+}
+
+/** The `next` line for one verdict — the fix that actually applies. */
+export function nextStep(row, program) {
+  switch (row.verdict) {
+    case 'pullable':
+      return `sememe pull ${program}`;
+    case 'no-interface-published':
+      // Lighthouse is the one measured case where sememe SHIPS the verified
+      // first-party copy (vendor/lighthouse, hash-pinned): the general advice
+      // would send the user off to find a file the package already carries.
+      if (program === LIGHTHOUSE_PROGRAM) {
+        return 'this program publishes no on-chain interface at either address — pulling it can never succeed. '
+          + 'sememe ships its first-party published copy (Jac0xb/lighthouse, MIT, hash-pinned): '
+          + 'use sememe adopt-lighthouse --store <dir>, then sememe decode --union.';
+      }
+      return 'this program publishes no on-chain interface at either address — pulling it can never succeed. '
+        + 'Use sememe adopt <program> <file> with a first-party published copy, or a pinned upstream derivation.';
+    case 'present-undecodable':
+      return 'an interface account exists but its schema is unusable — pull it to inspect; decode will refuse by name';
+    case VENDORED:
+      return 'answered by the pinned wire table shipped with sememe; there is no IDL to store';
+    default:
+      return 'the RPC did not answer — absence is NOT established; retry before believing anything about the chain';
+  }
+}

package/src/lighthouse.mjs

@@ -0,0 +1,168 @@
+// The Lighthouse acquisition: a pinned, hash-verified first-party published
+// IDL for the program that was the LARGEST remaining acquisition gap after
+// ATA (measured 2026-11-11: L2TExMFKdjpN9kozasaurPirfHy9P8sbXoAN1qA3S95,
+// 1,214 payloads in 6 finalized blocks, no IDL account at either pullable
+// address — research/ecosystem-coverage-2026-11-11.json, acquisitionQueue[0]).
+//
+// WHY THIS FILE EXISTS
+//
+// `sememe adopt` stores any file the caller names, and its origin is DECLARED,
+// never verified (src/adopt.mjs says so on every surface). For ATA the answer
+// was a derived wire table pinned to the vendored upstream Rust. For Lighthouse
+// the answer already exists as a FIRST-PARTY PUBLISHED COPY: the program's own
+// repository ships programs/lighthouse/lighthouse.json (shank dialect, which
+// src/shank.mjs decodes — measured 2026-11-04 on 42 payloads of the foreign
+// sweep). The gap was never "no interface exists"; it was "no one can adopt it
+// reproducibly". This module makes the adoption checkable:
+//
+//   - the copy is VENDORED under vendor/lighthouse/<commit>/ with the commit
+//     it was read at and the sha256 of every file (license MIT, LICENSE
+//     vendored beside it);
+//   - loadVendoredLighthouse() re-hashes the vendored bytes against the pin
+//     and REFUSES by name on any mismatch, missing file, unparseable JSON, a
+//     declared address that disagrees, or a non-shank instruction table —
+//     the same two-check contract src/native.mjs / src/token.mjs /
+//     src/raydium.mjs / src/ata.mjs prove;
+//   - the shank discriminants themselves are checked for self-consistency
+//     (every instruction declares {type:'u8',value:N}; N must be the
+//     declaration index) so a doctored IDL cannot claim 0x00 for two
+//     instructions.
+//
+// What is deliberately NOT claimed: the vendored bytes are not proven to come
+// from the commit by this module (GitHub blobs are content-addressed, git
+// commits are not signed here); the receipt will say originStatus 'declared'
+// and name repo + commit + file. Chain proof stays with the decode: every
+// payload must still re-encode byte-exactly or the union refuses.
+
+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 REPO_ROOT = path.resolve(HERE, '..');
+
+export const LIGHTHOUSE_PROGRAM = 'L2TExMFKdjpN9kozasaurPirfHy9P8sbXoAN1qA3S95';
+
+export const LIGHTHOUSE_PIN = {
+  repo: 'Jac0xb/lighthouse',
+  commit: '4c579479c98635e419b1b167f08be02a71604a71',
+  license: 'MIT',
+  // sha256 of the bytes AS PUBLISHED at the commit, read via the GitHub
+  // contents API at that ref (not from a mutable working tree).
+  files: [
+    {
+      file: 'programs/lighthouse/lighthouse.json',
+      role: 'first-party published IDL (shank dialect: per-instruction u8 discriminant)',
+      sha256: '9c54749abd27c09cf8d61e50016b625b5ae4aeb5cb1b8baf295199a1d7ecfd48',
+    },
+    {
+      file: 'LICENSE',
+      role: 'the license the vendored copy ships under',
+      sha256: '64d73100cafc1f5cb148cbbd5b3c7fc74bafc46f156646b0861c698570d02327',
+    },
+  ],
+  origin: `github.com/${'Jac0xb/lighthouse'}@4c579479c98635e419b1b167f08be02a71604a71:programs/lighthouse/lighthouse.json`,
+};
+
+export function vendoredLighthousePath(file, root = REPO_ROOT) {
+  return path.join(root, 'vendor', 'lighthouse', LIGHTHOUSE_PIN.commit, path.basename(file));
+}
+
+export function sha256File(filePath) {
+  return createHash('sha256').update(readFileSync(filePath)).digest('hex');
+}
+
+export class LighthousePinError extends Error {
+  constructor(reason, detail) {
+    super(detail ? `${reason}: ${detail}` : reason);
+    this.name = 'LighthousePinError';
+    this.reason = reason;
+  }
+}
+
+/**
+ * Read the vendored IDL and verify it against the pin. Every refusal is
+ * NAMED — a caller can tally failure faces without parsing prose.
+ * Returns { idl, path, sha256, bytes } on success.
+ */
+export function loadVendoredLighthouse(root = REPO_ROOT, pin = LIGHTHOUSE_PIN) {
+  const pinned = pin.files.find((f) => f.file.endsWith('lighthouse.json'));
+  const vendoredPath = path.join(root, 'vendor', 'lighthouse', pin.commit, path.basename(pinned.file));
+  let raw;
+  try {
+    raw = readFileSync(vendoredPath);
+  } catch (error) {
+    throw new LighthousePinError(
+      'lighthouse-vendor-missing',
+      `${vendoredPath} is not present (${error.code ?? error.message})`,
+    );
+  }
+  const now = createHash('sha256').update(raw).digest('hex');
+  if (now !== pinned.sha256) {
+    throw new LighthousePinError(
+      'lighthouse-vendor-hash-mismatch',
+      `pinned ${pinned.sha256}, hashed now ${now} — refusing to adopt bytes that are not the reviewed copy`,
+    );
+  }
+  let idl;
+  try {
+    idl = JSON.parse(raw.toString('utf8'));
+  } catch (error) {
+    throw new LighthousePinError('lighthouse-vendor-unparseable', String(error.message ?? error));
+  }
+  if (!idl || typeof idl !== 'object' || Array.isArray(idl)) {
+    throw new LighthousePinError('lighthouse-vendor-unparseable', 'not an IDL object');
+  }
+  // Address binding: this file claims Lighthouse by its own metadata, and the
+  // program id this module pins is the one the measurement saw. A file that
+  // declares a different program refuses, it is never re-labelled.
+  const declared = idl.metadata?.address ?? idl.address ?? null;
+  if (declared !== LIGHTHOUSE_PROGRAM) {
+    throw new LighthousePinError(
+      'lighthouse-address-disagrees',
+      `vendored file declares ${declared}, pin binds ${LIGHTHOUSE_PROGRAM}`,
+    );
+  }
+  if (!Array.isArray(idl.instructions) || idl.instructions.length === 0) {
+    throw new LighthousePinError('lighthouse-no-instructions', 'not an interface copy');
+  }
+  // Shank table integrity: every instruction must declare a u8 discriminant
+  // equal to its declaration index (measured truth at the pin: 0..17 in
+  // order). This is the IDL checking ITSELF, not a transcription.
+  idl.instructions.forEach((instruction, index) => {
+    const disc = instruction?.discriminant;
+    if (!disc || disc.type !== 'u8' || disc.value !== index) {
+      throw new LighthousePinError(
+        'lighthouse-discriminant-table',
+        `instruction ${index} (${instruction?.name}) discriminant ` +
+        JSON.stringify(disc ?? null) + ` is not the shank u8 value ${index}`,
+      );
+    }
+  });
+  return { idl, path: vendoredPath, sha256: now, bytes: raw.length };
+}
+
+/** The origin label adopt records for a load that passed the pin checks. */
+export function lighthouseOriginLabel() {
+  return `github.com/${LIGHTHOUSE_PIN.repo}@${LIGHTHOUSE_PIN.commit}:programs/lighthouse/lighthouse.json`;
+}
+
+/**
+ * Adopt the verified first-party copy into a store, through the PRODUCT's one
+ * write path (src/adopt.mjs — the same path `sememe adopt` uses).
+ *
+ * Order matters and is the point of this function: the pin is checked FIRST,
+ * so a tampered or missing vendored file means NOTHING was written. The
+ * receipt's origin stays `declared` (adopt's own rule): the pin binds the
+ * BYTES to a commit, not the bytes to the deployed program.
+ */
+export async function adoptLighthouse(storeDir, { adopt } = {}) {
+  if (typeof adopt !== 'function') throw Error('adoptLighthouse needs the product write path (src/adopt.mjs)');
+  const loaded = loadVendoredLighthouse();
+  const receipt = await adopt(LIGHTHOUSE_PROGRAM, loaded.path, storeDir, {
+    source: 'published',
+    origin: lighthouseOriginLabel(),
+  });
+  return { receipt, loaded };
+}