sememe 0.0.0-stage → 0.4.21

package/src/shank.mjs

@@ -0,0 +1,73 @@
+// Shank / Kinobi dialect support for IDL-driven decoding.
+//
+// Why this exists: not every published IDL is an Anchor IDL. Shank-generated
+// IDLs (and the Codama/Kinobi clients built from them) describe the SAME Borsh
+// field layouts but a DIFFERENT dispatch and length dialect:
+//   - instructions carry `discriminant: { type: "u8", value: N }` — a single
+//     variant-order byte — instead of an 8-byte Anchor sighash;
+//   - enums are Borsh 1-byte variant indexes (sememe already decoded these);
+//   - the lighthouse family encodes array/string lengths as LEB128
+//     (`CompactU64`, `CompactBytes`, `*Assertions` — custom types the IDL
+//     references but does not define; the wire form is pinned upstream in
+//     lighthouse_common::CompactU64 / LEB128Vec and mirrored by the program's
+//     own generated JS client, clients/js/src/hooked.ts at Jac0xb/lighthouse).
+//
+// Measured ground truth (2026-11-04): all 42 Lighthouse payloads in the
+// 156-fixture foreign sweep (step-ingestooor @001cf39) dispatch on their shank
+// discriminant byte (0x06 = AssertAccountInfoMulti, 0x0a =
+// AssertTokenAccountMulti — both present in the first-party IDL) and decode +
+// re-encode byte-exactly under this dialect.
+//
+// Rules, all falsifiable:
+// - A shank discriminant is NEVER overwritten by Anchor's sighash derivation:
+//   the two schemes are independent; deriving one from the other produces a
+//   table that matches no real wire. (The pre-fix behavior filled all 18
+//   lighthouse instructions with bogus sighashes — measured wrong.)
+// - The hooked LEB128 types engage only for an IDL in the shank dialect and
+//   only for a name the IDL does not define itself; a name defined in the
+//   IDL's own `types` always wins, and an unknown undefined name still
+//   refuses (`unknown defined type`). Nothing is guessed from shape.
+
+const isPlainObject = (value) => !!value && typeof value === 'object' && !Array.isArray(value);
+
+/** True when `instruction` carries a shank 1-byte discriminant. */
+export function isShankDiscriminant(instruction) {
+  const raw = instruction?.discriminant;
+  return isPlainObject(raw) && raw.type === 'u8'
+    && Number.isInteger(raw.value) && raw.value >= 0 && raw.value <= 255;
+}
+
+/** The 1-byte discriminator as a Buffer, or null when not shank-shaped. */
+export function shankDiscriminatorBytes(instruction) {
+  return isShankDiscriminant(instruction) ? Buffer.from([instruction.discriminant.value]) : null;
+}
+
+/**
+ * The hooked LEB128 types, pinned from lighthouse_common (Jac0xb/lighthouse,
+ * programs/lighthouse/src/instruction.rs: `CompactU64`, `LEB128Vec<T>`) and
+ * the program's generated clients/js/src/hooked.ts:
+ *   - scalar: unsigned LEB128 (7-bit groups, little-endian, max 10 bytes)
+ *   - bytes:  unsigned LEB128 length prefix + that many raw bytes
+ *   - vec:    unsigned LEB128 length prefix + that many Borsh elements
+ * The `*Assertions` element types stay in the IDL's own `types`; only the
+ * length dialect is hooked.
+ */
+export const SHANK_LEB128_TYPES = new Map([
+  ['CompactU64', { kind: 'scalar' }],
+  ['CompactBytes', { kind: 'bytes' }],
+  ['AccountInfoAssertions', { kind: 'vec', element: 'AccountInfoAssertion' }],
+  ['AccountDataAssertions', { kind: 'vec', element: 'AccountDataAssertion' }],
+  ['MintAccountAssertions', { kind: 'vec', element: 'MintAccountAssertion' }],
+  ['TokenAccountAssertions', { kind: 'vec', element: 'TokenAccountAssertion' }],
+  ['StakeAccountAssertions', { kind: 'vec', element: 'StakeAccountAssertion' }],
+  ['UpgradeableLoaderStateAssertions', { kind: 'vec', element: 'UpgradeableLoaderStateAssertion' }],
+]);
+
+/**
+ * Whether an IDL is in the shank dialect: declared via metadata.origin, or
+ * shaped so (at least one instruction carries a 1-byte discriminant).
+ */
+export function isShankIdl(idl) {
+  if (idl?.metadata?.origin === 'shank') return true;
+  return (idl?.instructions ?? []).some((instruction) => isShankDiscriminant(instruction));
+}

package/src/short-forms.mjs

@@ -0,0 +1,209 @@
+// Chain-verified short wire forms: payloads the DEPLOYED program executed that
+// the stored interface describes as one field LONGER than the bytes on the wire.
+//
+// Why this table exists, and why it is not simply "decode when a payload ends
+// at a field boundary":
+//
+// Byte-exact re-encoding is NOT sufficient evidence for an absent field. With
+// `trailing` it is: a complete described prefix that re-encodes exactly means
+// the extra bytes are extra, and the described part is whole. With `absent` it
+// is not — a payload truncated by a capture bug also ends on a field boundary
+// and also re-encodes byte-exactly to the shortened bytes. So offline, on bytes
+// alone, "the deployed program accepts a shorter form" and "this payload was
+// cut short" are indistinguishable. src/codec.mjs therefore keeps
+// `absent: 'error'` as the default and refuses both.
+//
+// What makes the shorter form KNOWABLE is a chain witness. Each entry below was
+// measured on mainnet by tools/short-form-wire-forms.mjs against
+// research/short-form-wire-forms-2026-11-03.json (the 4-block window) and
+// research/short-form-wire-forms-2026-11-04.json (the 32-block window):
+//
+//   - the transaction's `err` field is null (the chain accepted it),
+//   - the witness instruction bytes are byte-IDENTICAL to the fixture payload,
+//   - the program's own log line names the instruction the decode will report.
+//
+// On the 2026-11-03 12,572-payload sample that resolved 171 of the 172
+// refusals: 0 of them were genuine chain-rejected refusals. The 2026-11-04
+// 89,546-payload window resolved 350 of 350 refusals the same way, and found
+// three MORE short forms the first window had never seen — because the table
+// is keyed on program + discriminator + exact length, and the first window
+// simply did not contain them: pump.fun's bonding curve executes the 24-byte
+// `buy` form that had only been witnessed on PumpSwap, plus `buy_exact_sol_in`
+// and the 146-byte `create_v2`, which omits THREE declared fields.
+//
+// The table is the product form of those measurements — the evidence travels
+// with the decoder, so `absent: 'verified'` can name these forms while still
+// refusing every other payload that happens to end on a field boundary.
+//
+// A payload must match program + discriminator + EXACT wire length. Matching
+// the discriminator alone is not enough: the 25-byte form of
+// e1f7501ed5b38488 is a different, fully-described shape and must not be routed
+// through the absent path (it is not absent — both OptionBools are present).
+
+/**
+ * Verified short wire forms.
+ *
+ * `program`  deployed program address the witness belongs to
+ * `bytes`    exact payload length, discriminator included
+ * `absent`   declared fields the wire does not carry, in declaration order —
+ *            named here so a decode that reports a DIFFERENT absent set does
+ *            not silently count as verified
+ */
+const VERIFIED_SHORT_FORMS = [
+  {
+    program: '6EF8rrecthR5Dkzon8Nwu78hRvfCKubJ14M5uBEwF6P',
+    discriminator: 'e1f7501ed5b38488',
+    bytes: 24,
+    instruction: 'buy_exact_quote_in_v3',
+    absent: ['partial_fill'],
+    witnesses: 152,
+  },
+  {
+    program: '6EF8rrecthR5Dkzon8Nwu78hRvfCKubJ14M5uBEwF6P',
+    discriminator: '07051dc4f5176550',
+    bytes: 24,
+    instruction: 'buy_v3',
+    absent: ['partial_fill'],
+    witnesses: 1,
+  },
+  {
+    program: 'pAMMBay6oceH9fJKBRHGP5D4bD4sWpmSwMn52FMfXEA',
+    discriminator: 'c62e1552b4d9e870',
+    bytes: 24,
+    instruction: 'buy_exact_quote_in',
+    absent: ['track_volume'],
+    witnesses: 17,
+  },
+  {
+    program: 'pAMMBay6oceH9fJKBRHGP5D4bD4sWpmSwMn52FMfXEA',
+    discriminator: '66063d1201daebea',
+    bytes: 24,
+    instruction: 'buy',
+    absent: ['track_volume'],
+    witnesses: 1,
+  },
+  // --- 2026-11-04 window (research/short-form-wire-forms-2026-11-04.json) ---
+  // The same 24-byte `buy` form, on pump.fun's BONDING CURVE program. The
+  // discriminator and the length match the PumpSwap entry above, but the
+  // program is a different deployment, so the 2026-11-03 window could not
+  // witness it: the key is program + discriminator + exact length, and only
+  // one of the two programs was measured then.
+  {
+    program: '6EF8rrecthR5Dkzon8Nwu78hRvfCKubJ14M5uBEwF6P',
+    discriminator: '66063d1201daebea',
+    bytes: 24,
+    instruction: 'buy',
+    absent: ['track_volume'],
+    witnesses: 7,
+  },
+  {
+    program: '6EF8rrecthR5Dkzon8Nwu78hRvfCKubJ14M5uBEwF6P',
+    discriminator: '38fc74089edfcd5f',
+    bytes: 24,
+    instruction: 'buy_exact_sol_in',
+    absent: ['track_volume'],
+    witnesses: 1,
+  },
+  // The first short form that omits MORE THAN ONE declared field: the
+  // interface declares three, the wire carries none of them.
+  {
+    program: '6EF8rrecthR5Dkzon8Nwu78hRvfCKubJ14M5uBEwF6P',
+    discriminator: 'd6904cec5f8b31b4',
+    bytes: 146,
+    instruction: 'create_v2',
+    absent: ['is_cashback_enabled', 'creator_fee_bps', 'is_holder_reward'],
+    witnesses: 1,
+  },
+];
+
+export const SHORT_FORM_SOURCE =
+  'research/short-form-wire-forms-2026-11-03.json + research/short-form-wire-forms-2026-11-04.json '
+  + '(chain witnesses: err:null, byte-identical payload, matching program log line)';
+
+export const VERIFIED = VERIFIED_SHORT_FORMS;
+export { VERIFIED_SHORT_FORMS };
+
+/** Look up a payload in the chain-verified short-form table; null when absent. */
+export function verifiedShortForm(program, data) {
+  if (!program || !(data instanceof Uint8Array)) return null;
+  if (data.length < 8) return null;
+  const discriminator = Buffer.from(data.subarray(0, 8)).toString('hex');
+  return VERIFIED_SHORT_FORMS.find((entry) =>
+    entry.program === program
+    && entry.discriminator === discriminator
+    && entry.bytes === data.length) ?? null;
+}
+
+/**
+ * Resolve an `absent` policy into the codec policy for one payload.
+ *
+ *   'error'    never decode absent fields (the strict default)
+ *   'report'   decode any payload that ends on a field boundary (caller risk)
+ *   'verified' decode only forms in the chain-verified table; anything else
+ *              stays strict — the evidence-gated policy
+ */
+export function resolveAbsentPolicy(program, data, policy) {
+  if (policy === undefined || policy === null || policy === 'error') return { policy: 'error', form: null };
+  if (policy === 'report') return { policy: 'report', form: null };
+  if (policy !== 'verified') {
+    throw new Error(`unknown absent policy ${JSON.stringify(policy)}`);
+  }
+  const form = verifiedShortForm(program, data);
+  return { policy: form ? 'report' : 'error', form };
+}
+
+/**
+ * Assert that a completed decode reproduces the measured wire form.
+ *
+ * Throws when it does not. This is the single place the rule lives, so the
+ * product paths (single-source and union) cannot drift apart from it, and so
+ * the rule can be tested directly with synthetic decodes — a different missing
+ * set, a different name — instead of only through a fixture store.
+ */
+export function assertShortFormEvidence(form, decoded, bytes) {
+  const evidence = describeShortForm(form, decoded, bytes);
+  if (!evidence.verified) {
+    throw new Error(
+      `short-form evidence does not cover this decode: measured absent `
+      + `${JSON.stringify(form.absent)} for ${form.instruction}, decoded `
+      + `${JSON.stringify(evidence.decodeAbsence)} — refusing instead of trusting stale evidence`);
+  }
+  return evidence;
+}
+
+/**
+ * Does a completed decode reproduce the measured wire form?
+ *
+ * Pure on purpose: the rules for trusting old chain evidence are worth testing
+ * directly with synthetic decodes (a different missing set, a different name)
+ * rather than only through a fixture store. Returns the evidence object with
+ * `verified` set — it never throws, so a caller can choose to refuse.
+ *
+ * `decoded` may be a codec result (`instruction`/`event`) or a union result
+ * (`name`); both carry `absent`.
+ */
+export function describeShortForm(form, decoded, bytes) {
+  const named = decoded.absent ?? [];
+  const sameSet = named.length === form.absent.length
+    && form.absent.every((field) => named.includes(field));
+  const decodedName = decoded.name
+    ?? (decoded.kind === 'event' ? decoded.event : decoded.instruction);
+  return {
+    // Verified means: THIS decode named exactly the fields the chain witness
+    // saw missing, under the name the witness's log line carried. A decoder
+    // that reports a different absence has not reproduced the measured form —
+    // the IDL gained or lost a field since the witness was taken — and stale
+    // evidence must not be spent on a shape nobody measured.
+    verified: sameSet && (decodedName === undefined || decodedName === form.instruction),
+    program: form.program,
+    discriminator: form.discriminator,
+    bytes: form.bytes,
+    instruction: form.instruction,
+    absent: form.absent,
+    decodeAbsence: named,
+    decodedName,
+    witnesses: form.witnesses,
+    source: SHORT_FORM_SOURCE,
+    wireBytes: bytes.length,
+  };
+}

package/src/store-read.mjs

@@ -0,0 +1,250 @@
+// Read one stored IDL for a program, verified against its receipt.
+//
+// The store layout is the one produced by `sememe pull` / `sememe adopt`:
+//   <store>/receipts/<program>-<slot>-<source>-<fingerprint>.json
+//   <store>/objects/<fingerprint>.json
+// The receipt binds the program id to the object, so decoding is offline and
+// reproducible: same store + same payload => same result, no network call.
+//
+// The receipt is a claim; the recomputed hash is the check. Every step that can
+// lie on the way to a decode is refused with a named reason instead of being
+// tolerated:
+//   - a receipt whose program field is not the program asked for (a receipt
+//     swapped in from another program's file)
+//   - a receipt pointing at an object that is not in the store
+//   - an object that does not re-hash to the fingerprint the receipt claims
+//     (the defect measured 2026-10-30: before this check, a tampered object —
+//     valid JSON, one instruction renamed — was decoded happily and its
+//     tampered name reported as provenance)
+//   - an object declaring a different program than the receipt binds
+//   - a receipt whose DECLARED origin or body no longer matches its own
+//     digest (src/receipt-digest.mjs): the fingerprint covers the OBJECT, so
+//     before the receipt carried a digest, rewriting `origin` in the receipt
+//     left `sememe verify` green over a rewritten provenance label — measured
+//     2026-11-07: violations 0 after `origin` was changed to
+//     `attacker/rewritten-origin`. A legacy receipt without digests is read as
+//     it always was: its origin is then declared WITHOUT a binding.
+// An unreadable or tampered store must never become another source's names.
+
+import { createHash } from 'node:crypto';
+import { readFile, readdir } from 'node:fs/promises';
+import path from 'node:path';
+import { canonicalJson } from './canonical.mjs';
+import { compareReceiptNames } from './receipt-order.mjs';
+import { classifyReceiptFiles, isReceiptFile } from './receipt-name.mjs';
+import { receiptIntegrity } from './receipt-digest.mjs';
+import { assertIdlShape, declaredProgram } from './dialect.mjs';
+
+export { canonicalJson } from './canonical.mjs';
+
+/** Read and verify one receipt+object pair. Throws with a named reason.
+ *
+ * Exported for `src/lock.mjs`: the lock must re-check every receipt through
+ * THIS reader — a second, weaker copy of the checks would recreate the "one
+ * store, two strengths" failure the header warns about. */
+export async function readVerified(storeDir, program, receiptName) {
+  let receipt;
+  try {
+    receipt = JSON.parse(await readFile(path.join(storeDir, 'receipts', receiptName), 'utf8'));
+  } catch (error) {
+    throw Error(`store receipt ${receiptName} is unreadable: ${String(error?.message ?? error).slice(0, 140)}`);
+  }
+  if (receipt?.program !== program) {
+    throw Error(`store receipt ${receiptName} names program ${receipt?.program} — it is not a receipt for ${program}`);
+  }
+  // The receipt's OWN integrity, before it is allowed to name anything. A
+  // rewritten declared origin is refused HERE, on every read — decode, union
+  // and verify all see the same refusal, and the reason says which kind of
+  // rewrite happened (the lock reports the two differently).
+  const integrity = receiptIntegrity(receipt);
+  if (integrity) {
+    const error = Error(`store receipt ${receiptName}: ${integrity.reason}`);
+    error.code = integrity.code;
+    throw error;
+  }
+  const fingerprint = String(receipt.fingerprint).replace(/^sha256:/, '');
+  if (!/^[a-f0-9]{64}$/.test(fingerprint)) throw Error(`store receipt has a malformed fingerprint: ${receipt.fingerprint}`);
+  const objectPath = path.join(storeDir, 'objects', `${fingerprint}.json`);
+  let raw;
+  try { raw = await readFile(objectPath); }
+  catch (error) {
+    if (error?.code === 'ENOENT') {
+      throw Error(`store receipt ${receiptName} claims object ${fingerprint} but the store object is missing`);
+    }
+    throw Error(`store object ${fingerprint}.json is unreadable: ${String(error?.message ?? error).slice(0, 140)}`);
+  }
+  let idl;
+  try { idl = JSON.parse(raw); }
+  catch (error) {
+    throw Error(`store object ${fingerprint}.json is not JSON: ${String(error?.message ?? error).slice(0, 140)}`);
+  }
+  if (!Array.isArray(idl.instructions)) throw Error(`stored object for ${program} has no instructions`);
+  // Same two checks as the write path (src/adopt.mjs), applied on every
+  // read: a dialect the codec cannot read is refused by NAME before any
+  // decode can crash unnamed, and a declared program that differs from the
+  // receipt's program is a re-labelling no matter which field carries the
+  // declaration (`address`, `metadata.address` or `program_id`).
+  assertIdlShape(idl, (reason) => {
+    const error = Error(`stored object ${fingerprint} for ${program}: ${reason}`);
+    error.code = 'unsupported-idl-dialect';
+    return error;
+  });
+  const declared = declaredProgram(idl);
+  if (declared && declared !== program) {
+    throw Error(`stored object ${fingerprint} declares program ${declared}, not the receipt's ${program}`);
+  }
+  if (idl.address && idl.address !== program) {
+    throw Error(`stored object ${fingerprint} declares program ${idl.address}, not the receipt's ${program}`);
+  }
+  // `pull` writes sha256(canonicalJson(idl) + '\n'), so verify with the same
+  // canonicalizer rather than with JSON.stringify, whose key order is not the
+  // stored order. A receipt without this check is a filename, not provenance.
+  const actual = createHash('sha256').update(`${canonicalJson(idl)}\n`).digest('hex');
+  if (actual !== fingerprint) {
+    throw Error(
+      `stored object for ${program} re-hashes to sha256:${actual} but receipt ${receiptName} `
+      + `claims sha256:${fingerprint}: object and receipt disagree, refusing to decode`,
+    );
+  }
+  return { idl, receipt, receiptName, objectPath };
+}
+
+async function receiptNames(storeDir, program) {
+  const receipts = path.join(storeDir, 'receipts');
+  let names;
+  try { names = await readdir(receipts); }
+  catch (error) {
+    if (error?.code === 'ENOENT') {
+      // `code` names the KIND of failure so a caller can distinguish "this
+      // store does not exist" from the absence of "this program is not in it"
+      // WITHOUT parsing prose — src/conformance.mjs needs exactly that
+      // (measured 2026-11-10: it swallowed both and reported a green gate).
+      // The message is unchanged: it is quoted by bin/sememe.mjs, the README
+      // and several tests.
+      const missing = Error(`no sememe store at ${storeDir}: run "sememe pull" first`);
+      missing.code = 'no-sememe-store';
+      throw missing;
+    }
+    throw error;
+  }
+  const candidates = names.filter((name) => name.startsWith(`${program}-`) && isReceiptFile(name));
+  if (!candidates.length) {
+    // The store EXISTS and simply holds no receipt for this program: an
+    // acquisition gap, never damage. Callers must be able to report it as
+    // such instead of mistaking it for a reader refusal.
+    const absent = Error(`no stored IDL for program ${program} in ${storeDir}`);
+    absent.code = 'no-stored-idl';
+    throw absent;
+  }
+  // Numeric slot order, NOT byte order: the slot in the filename is a decimal
+  // NUMBER, and "99999999" sorts after "123456789" as a string — so a plain
+  // sort picks the OLDER receipt as "last = newest" whenever two slot strings
+  // differ in length (measured 2026-11-07: plain decode and lock said slot
+  // 99999999, the union path — which sorts by numeric slot — said 123456789).
+  // ONE ordering, shared with src/lock.mjs via src/receipt-order.mjs.
+  candidates.sort(compareReceiptNames);
+  return candidates;
+}
+
+/** Find the newest stored IDL for a program id, verified against its receipt. */
+export async function findStoredIdl(storeDir, program) {
+  const candidates = await receiptNames(storeDir, program);
+  return readVerified(storeDir, program, candidates[candidates.length - 1]);
+}
+
+/**
+ * Find the store's sources for a program, split by provenance.
+ *
+ * `primary` is the newest ON-CHAIN receipt (a real slot) and `secondary` is the
+ * newest ADOPTED receipt (a published copy, slot null). The split is what keeps
+ * the union honest: a published copy must never silently become the default
+ * single source, and an on-chain pull must never be dropped because a file was
+ * adopted later.
+ *
+ * TWO RULES THAT MUST NOT DIVERGE (measured 2026-11-07, this host):
+ *
+ *   1. Adopted copies are ordered by the SHARED receipt ordering
+ *      (src/receipt-order.mjs) — the exact rule `findStoredIdl` (the plain
+ *      decode) and `src/lock.mjs` apply. They used to be ordered by their
+ *      human-readable LABEL, which embeds the ORIGIN the caller typed: with
+ *      two adopted copies the union path read the copy the origin spelling
+ *      pointed at while the plain decode and the lock read the copy the
+ *      fingerprint pointed at. Same store, same bytes, two answers —
+ *      plain `decode` said `sell_v3`, `decode --union` refused the payload.
+ *   2. When the store holds NO on-chain receipt and MULTIPLE adopted copies,
+ *      the newest adopted copy is the `primary` and the next one the
+ *      `secondary`, so the union path arbitrates the copies the store actually
+ *      holds instead of consulting one and ignoring the rest. With exactly one
+ *      adopted copy and no pull, `primary` stays null (the sole-source case):
+ *      nothing on chain means there is no on-chain primary.
+ *
+ * Everything the pair does not consult is returned as `additional`, so the
+ * caller can NAME it instead of pretending the store holds two sources.
+ *
+ * Both are re-hashed against their receipts here; an unreadable or tampered
+ * object is refused by name, never skipped silently.
+ */
+export async function findStoredIdls(storeDir, program) {
+  const candidates = await receiptNames(storeDir, program);
+  const onChain = [];
+  const adopted = [];
+  for (const name of candidates) {
+    // The slot segment is the second field: `<program>-<slot>-<source>-<hash>`.
+    const rest = name.slice(`${program}-`.length);
+    const slotSegment = rest.split('-')[0];
+    const source = await readVerified(storeDir, program, name);
+    const entry = {
+      // Human-readable provenance; the receipt filename stays in idlMeta.receipt.
+      // An ADOPTED origin is DECLARED, never verified — the label says so, so no
+      // reader can present a caller-typed string as a checked fact. A legacy
+      // receipt without originStatus is declared too (adopt never verified it).
+      label: source.receipt.slot === null || source.receipt.slot === undefined
+        ? `${source.receipt.source} (adopted, declared origin: ${source.receipt.origin ?? source.receipt.fingerprint.slice(0, 12)})`
+        : `${source.receipt.source} @slot ${source.receipt.slot}`,
+      idl: source.idl,
+      idlMeta: {
+        fingerprint: source.receipt.fingerprint,
+        slot: source.receipt.slot ?? null,
+        source: source.receipt.source,
+        origin: source.receipt.origin ?? null,
+        originStatus: source.receipt.originStatus
+          ?? (source.receipt.origin !== undefined && source.receipt.origin !== null ? 'declared' : null),
+        receipt: source.receiptName,
+      },
+      objectPath: source.objectPath,
+    };
+    if (source.receipt.slot === null || source.receipt.slot === undefined) adopted.push(entry);
+    else if (/^\d+$/.test(slotSegment)) onChain.push(entry);
+    else adopted.push(entry);
+  }
+  // Ordered by the ONE shared rule (numeric slot, filename tiebreak) — the
+  // same order `candidates` already arrives in from `receiptNames`, and the
+  // same order `findStoredIdl` and src/lock.mjs apply. Never the label (it
+  // carries the origin string the caller typed) and never the raw string (it
+  // orders by digits, not by value).
+  onChain.sort((a, b) => compareReceiptNames(a.idlMeta.receipt, b.idlMeta.receipt));
+  // Adopted copies are ordered by the SAME shared rule — numeric slot first
+  // (they all carry filename segment 0), then the filename byte-wise. Never
+  // the label: it carries the origin string the caller typed, and two copies
+  // of one program then answered from two different orderings.
+  adopted.sort((a, b) => compareReceiptNames(a.idlMeta.receipt, b.idlMeta.receipt));
+
+  let primary = onChain.length ? onChain[onChain.length - 1] : null;
+  let secondary = adopted.length ? adopted[adopted.length - 1] : null;
+  if (!primary && adopted.length >= 2) {
+    // No pull in the store, but several verified published copies: they ARE the
+    // union's two sources. Ranking them by the shared rule keeps the primary
+    // equal to the copy `findStoredIdl` reads, so plain and union decode agree.
+    primary = adopted[adopted.length - 1];
+    secondary = adopted[adopted.length - 2];
+  }
+  const consulted = new Set([primary, secondary].filter(Boolean));
+  const additional = [...onChain, ...adopted].filter((entry) => !consulted.has(entry));
+  return {
+    primary,
+    secondary,
+    additional,
+    onChain,
+    adopted,
+  };
+}

package/src/store-write.mjs

@@ -0,0 +1,46 @@
+// Atomic no-replace writer for store objects and receipts.
+//
+// Extracted from src/pull.mjs so that `sememe adopt` (a published copy with no
+// RPC involved) can share the exact same write contract as `sememe pull`:
+//   - temp file created O_EXCL with 0600
+//   - fsync before install
+//   - hard-link install: another writer (or a symlink planted at the target)
+//     cannot be overwritten; a losing writer verifies the installed bytes
+//   - any existing destination with DIFFERENT bytes is an error, never replaced
+// A store entry is content-addressed: overwriting one digest with other bytes
+// would break every receipt that points at it.
+
+import { link, lstat, open, readFile, rm } from 'node:fs/promises';
+
+export async function writeOnce(destination, content) {
+  try {
+    const entry = await lstat(destination);
+    if (!entry.isFile() || entry.isSymbolicLink()) throw Error(`non-regular store entry: ${destination}`);
+    const current = await readFile(destination);
+    if (!current.equals(content)) throw Error(`digest collision or corrupted local object: ${destination}`);
+    return;
+  } catch (error) {
+    if (error?.code !== 'ENOENT') throw error;
+  }
+  const temporary = `${destination}.tmp-${process.pid}-${Math.random().toString(16).slice(2)}`;
+  let handle;
+  try {
+    handle = await open(temporary, 'wx', 0o600);
+    await handle.writeFile(content);
+    await handle.sync();
+    await handle.close(); handle = null;
+    // Atomic no-replace installation: hard-link fails if another writer won.
+    // Rename would overwrite a concurrently created or symlinked digest path.
+    try { await link(temporary, destination); }
+    catch (error) {
+      if (error?.code !== 'EEXIST') throw error;
+      const entry = await lstat(destination);
+      if (!entry.isFile() || entry.isSymbolicLink()) throw Error(`non-regular store entry: ${destination}`);
+      const current = await readFile(destination);
+      if (!current.equals(content)) throw Error(`digest collision or corrupted local object: ${destination}`);
+    }
+  } finally {
+    if (handle) await handle.close();
+    await rm(temporary, { force: true });
+  }
+}