sememe 0.0.0-stage → 0.4.22

package/src/account.mjs

@@ -0,0 +1,199 @@
+// Decode a program's account state from the stored, verified on-chain IDL.
+//
+// Why this file exists: instructions are only half of a program's interface.
+// An account carries state, and the meaning of that state lives in the same
+// IDL — but the IDL describes it differently:
+//   - a newer IDL lists accounts as `{ name, discriminator, type }`
+//   - a legacy IDL lists accounts as `{ name, type }` with no discriminator
+// Anchor's own rule for the account discriminator is
+//   sha256("account:" + PascalCase(name))[0..8]
+// (anchor-ts `BorshAccountsCoder.accountDiscriminator`). The rule is filled in
+// only where the IDL stores no discriminator; a stored value always wins and a
+// conflict is reported, never silently overridden.
+//
+// An account's bytes are NOT a discriminator + a fixed struct in the general
+// case. Two shapes occur on mainnet and both are handled here:
+//   1. Anchor accounts: 8-byte discriminator ++ borsh(struct fields)
+//   2. Accounts whose data starts with the struct itself (no discriminator):
+//      the first bytes are the first fields, so the struct may simply not
+//      fit in the account (a `vec` at the end is truncated) and the decode
+//      stops at the first field that needs bytes the account does not have.
+//
+// The decoder is strict about what it can prove: it reports which bytes it
+// consumed, whether the re-encoded bytes reproduce the account exactly, and
+// any bytes the IDL does not explain. A decode that consumed fewer bytes than
+// the account holds is NOT a failure — it means the account is larger than the
+// struct the IDL describes, which is normal for accounts with a trailing
+// `vec` that grew.
+
+import { createHash } from 'node:crypto';
+import {
+  decodeTypePartial, encodeType, toJsonSafe, CodecError,
+} from './codec.mjs';
+
+const ACCOUNT_DISCRIMINATOR_SIZE = 8;
+
+const sha256 = (text) => createHash('sha256').update(text).digest();
+
+/** Anchor's account discriminator for a name: sha256("account:" + PascalCase). */
+export function accountDiscriminator(name) {
+  if (typeof name !== 'string' || !name) throw new CodecError('account name must be a non-empty string', null);
+  const preimage = `account:${name}`;
+  return Array.from(sha256(preimage).subarray(0, ACCOUNT_DISCRIMINATOR_SIZE));
+}
+
+/**
+ * Fill in missing account discriminators with Anchor's rule.
+ * Stored discriminators are never changed; a conflict is returned.
+ *
+ * @returns {{ idl: object, filled: number, conflicts: object[] }}
+ */
+export function withDerivedAccountDiscriminators(idl) {
+  const copy = structuredClone(idl);
+  let filled = 0;
+  const conflicts = [];
+  for (const account of copy.accounts ?? []) {
+    const stored = account?.discriminator;
+    const isStored = Array.isArray(stored) && stored.length === ACCOUNT_DISCRIMINATOR_SIZE
+      && stored.every((byte) => Number.isInteger(byte) && byte >= 0 && byte <= 255);
+    const derived = accountDiscriminator(account.name);
+    if (isStored) {
+      const same = derived.every((byte, index) => byte === stored[index]);
+      if (!same) {
+        conflicts.push({ name: account.name, stored: stored.slice(), derived });
+      }
+      continue;
+    }
+    account.discriminator = derived;
+    filled++;
+  }
+  return { idl: copy, filled, conflicts };
+}
+
+/**
+ * The IDL's account type definition (a struct shape) for one account name.
+ * Two IDL shapes exist and both occur on mainnet:
+ *   - newer IDL: `accounts: [{ name, discriminator }]` with the struct under
+ *     `types: [{ name, type: { kind: 'struct', fields } }]`
+ *   - legacy IDL: `accounts: [{ name, type: { fields } }]` inline
+ */
+function accountType(idl, name) {
+  const account = (idl.accounts ?? []).find((candidate) => candidate?.name === name);
+  if (!account) {
+    const known = (idl.accounts ?? []).map((candidate) => candidate?.name).filter(Boolean);
+    throw new CodecError(
+      `unknown account ${JSON.stringify(name)}; this IDL has ${known.length} account(s)`, null);
+  }
+  if (account.type && typeof account.type === 'object') return { account, type: account.type };
+  const typedef = (idl.types ?? []).find((candidate) => candidate?.name === name);
+  if (!typedef || !typedef.type) {
+    throw new CodecError(`account ${name} has no type in this IDL (neither inline nor in types)`, null);
+  }
+  return { account, type: typedef.type };
+}
+
+function typeContext(idl) {
+  const types = new Map();
+  for (const typedef of idl?.types ?? []) {
+    if (typedef && typeof typedef.name === 'string') types.set(typedef.name, typedef);
+  }
+  return { types };
+}
+
+/**
+ * Decode one account's raw data with the stored IDL.
+ *
+ * `data` is the account's byte content (the value behind `getMultipleAccounts`,
+ * already base64-decoded).
+ *
+ * @returns {{ name, discriminator, args, consumed, total, trailing,
+ *             roundTripByteExact, describedRoundTripByteExact, hasDiscriminator }}
+ */
+export function decodeAccountData(idl, data, name, options = {}) {
+  if (!(data instanceof Uint8Array)) throw new CodecError('account data must be a Uint8Array/Buffer', null);
+  const { trailing = 'report' } = options;
+  if (trailing !== 'report' && trailing !== 'error') {
+    throw new CodecError(`unknown trailing policy ${trailing}`, null);
+  }
+  const { account, type } = accountType(idl, name);
+  const ctx = typeContext(idl);
+  const bytes = Buffer.from(data);
+
+  // Does this account carry the Anchor account discriminator? Compare the
+  // first 8 bytes with the discriminator the IDL names (stored or derived).
+  const expected = Array.isArray(account.discriminator) && account.discriminator.length === ACCOUNT_DISCRIMINATOR_SIZE
+    ? Buffer.from(account.discriminator)
+    : null;
+  const hasDiscriminator = expected ? bytes.subarray(0, ACCOUNT_DISCRIMINATOR_SIZE).equals(expected) : false;
+
+  // With a discriminator the struct starts after it; without one the struct
+  // starts at byte 0 (a non-Anchor or legacy account).
+  //
+  // The offset follows the IDL, not the bytes: if the IDL names a
+  // discriminator for this account type, the struct starts after 8 bytes even
+  // when the bytes in hand carry a different discriminator (a corrupted or
+  // foreign account). `hasDiscriminator` records whether the bytes actually
+  // carry the expected one.
+  const offset = expected ? ACCOUNT_DISCRIMINATOR_SIZE : 0;
+  const body = bytes.subarray(offset);
+
+  let decoded;
+  let consumed = 0;
+  try {
+    const result = decodeTypePartial(type, body, ctx, `${name}`);
+    decoded = result.value;
+    consumed = result.consumed;
+  } catch (error) {
+    // A truncated account is a normal mainnet condition: the struct's last
+    // field is often a `vec` that grew past the account size, or the account
+    // is smaller than the struct. Report it instead of pretending it decoded.
+    if (!(error instanceof CodecError)) throw error;
+    throw new CodecError(
+      `account ${name}: ${error.message} (account holds ${body.length} byte(s) after the discriminator)`, name);
+  }
+
+  const trailingCount = body.length - consumed;
+  if (trailingCount > 0 && trailing === 'error') {
+    throw new CodecError(
+      `account ${name}: ${trailingCount} byte(s) after the described struct are not described by the IDL`, name);
+  }
+
+  // Re-encoding the decoded struct must reproduce the bytes it came from.
+  let reencoded = null;
+  try {
+    reencoded = encodeType(type, decoded, ctx, `${name}`);
+  } catch {
+    reencoded = null;
+  }
+  const described = body.subarray(0, consumed);
+  return {
+    name,
+    discriminator: expected ? expected.toString('hex') : null,
+    hasDiscriminator,
+    args: toJsonSafe(decoded),
+    consumed: consumed + offset,
+    total: bytes.length,
+    trailing: { count: trailingCount, hex: trailingCount > 0 ? body.subarray(consumed).toString('hex') : '' },
+    roundTripByteExact: reencoded ? reencoded.equals(body) : false,
+    describedRoundTripByteExact: reencoded ? reencoded.equals(described) : false,
+  };
+}
+
+/**
+ * Identify which account type a blob of account data belongs to, using the
+ * discriminator table the IDL provides (stored or derived).
+ *
+ * @returns {{ name, discriminator } | null}
+ */
+export function identifyAccount(idl, data) {
+  if (!(data instanceof Uint8Array) || data.length < ACCOUNT_DISCRIMINATOR_SIZE) return null;
+  const head = Buffer.from(data.subarray(0, ACCOUNT_DISCRIMINATOR_SIZE)).toString('hex');
+  for (const account of idl?.accounts ?? []) {
+    const discriminator = account?.discriminator;
+    if (!Array.isArray(discriminator) || discriminator.length !== ACCOUNT_DISCRIMINATOR_SIZE) continue;
+    if (Buffer.from(discriminator).toString('hex') === head) {
+      return { name: account.name, discriminator: head };
+    }
+  }
+  return null;
+}

package/src/acquire.mjs

@@ -0,0 +1,145 @@
+// The acquisition path: find and decode a program's IDL account from chain.
+//
+// This module moved out of `tools/measure.mjs` on 2026-11-01 so that
+// `src/pull.mjs` never reaches OUT of the shipped package (it used to import
+// `../tools/measure.mjs`, which forced a consumer either to miss files or to
+// download the whole qualification harness). `tools/measure.mjs` now imports
+// these helpers back from here; the CLI/manifest logic stays in tools/.
+//
+// Everything here touches the network and the ed25519 curve, so src/peer.mjs
+// is the ONLY place a third-party specifier may appear (allowlisted in
+// test/deps.test.mjs). It is deliberately NOT reachable from the package
+// entry (`index.mjs`): a decoder-only consumer installs zero packages, and
+// the acquisition subpath (`sememe/pull`) declares web3.js as an optional
+// peer — pull users install it themselves.
+//
+// 2026-11-06: the peer is loaded through src/peer.mjs, which refuses with a
+// sentence when it is absent (measured: a bare tarball install without the
+// peer used to surface a raw ERR_MODULE_NOT_FOUND from THIS file's import).
+// Importing sememe/pull or sememe/gap still refuses — it now refuses in
+// sememe's voice, at import time, naming the install command.
+import { gunzipSync, inflateSync } from 'node:zlib';
+import { createHash } from 'node:crypto';
+import { PublicKey } from './peer.mjs';
+
+export const METADATA_PROGRAM = new PublicKey('ProgM6JCCvbYkfKqJYHePx4xxSUSqJp7rh8Lyv7nk7S');
+const ANCHOR_DISCRIMINATOR = Buffer.from([24, 70, 98, 191, 58, 144, 123, 158]);
+const MAX_BYTES = 16 << 20;
+const sleep = (ms) => new Promise(resolve => setTimeout(resolve, ms));
+
+/** The two account addresses a program's interface can live at. */
+export async function addresses(id) {
+  const program = new PublicKey(id);
+  const seed = Buffer.alloc(16); seed.write('idl');
+  const [metadata] = PublicKey.findProgramAddressSync([program.toBuffer(), seed], METADATA_PROGRAM);
+  const [base] = PublicKey.findProgramAddressSync([], program);
+  const anchor = await PublicKey.createWithSeed(base, 'anchor:idl', program);
+  return { metadata: metadata.toBase58(), anchor: anchor.toBase58() };
+}
+
+function bodyDecode(bytes, compression) {
+  if (bytes.length > MAX_BYTES) throw Error('body exceeds maximum');
+  let decoded;
+  if (compression === 0) decoded = bytes;
+  else if (compression === 1) decoded = gunzipSync(bytes, { maxOutputLength: MAX_BYTES });
+  else if (compression === 2) decoded = inflateSync(bytes, { maxOutputLength: MAX_BYTES });
+  else throw Error(`unsupported compression: ${compression}`);
+  if (decoded.length > MAX_BYTES) throw Error('decompressed body exceeds maximum');
+  return JSON.parse(decoded.toString('utf8'));
+}
+
+/** Decode a raw IDL account (canonical Program Metadata or legacy anchor:idl). */
+export function decodeAccount(account, source, programId) {
+  if (!account) throw Error('missing account');
+  const expectedOwner = source === 'metadata' ? METADATA_PROGRAM.toBase58() : programId;
+  if (account.owner !== expectedOwner) throw Error(`wrong owner: ${account.owner}`);
+  if (!Array.isArray(account.data) || account.data[1] !== 'base64') throw Error('invalid encoding');
+  const bytes = Buffer.from(account.data[0], 'base64');
+  let idl;
+  if (source === 'metadata') {
+      const seed = Buffer.alloc(16); seed.write('idl');
+      if (bytes.length < 96 || bytes[0] !== 2 || !bytes.subarray(1,33).equals(new PublicKey(programId).toBuffer()) ||
+          bytes[66] === 0 || !bytes.subarray(67,83).equals(seed) || bytes[83] !== 1 || bytes[85] > 1 || bytes[86] !== 0)
+        throw Error('invalid metadata header, binding, source or format');
+      const len = bytes.readUInt32LE(87);
+      if (len > MAX_BYTES || bytes.length < 96 + len) throw Error('invalid metadata length');
+      idl = bodyDecode(bytes.subarray(96, 96 + len), bytes[84]);
+  } else if (source === 'anchor') {
+    if (bytes.length < 44 || !bytes.subarray(0,8).equals(ANCHOR_DISCRIMINATOR)) throw Error('invalid Anchor header');
+    const len = bytes.readUInt32LE(40);
+    if (len > MAX_BYTES || bytes.length < 44 + len) throw Error('invalid Anchor length');
+    idl = bodyDecode(bytes.subarray(44, 44 + len), 2);
+  } else throw Error(`unknown source: ${source}`);
+  if (!idl || typeof idl !== 'object' || !Array.isArray(idl.instructions) || !idl.instructions.length ||
+      idl.instructions.some(x => !x || typeof x.name !== 'string' || !x.name))
+    throw Error('no usable instruction schema');
+  if (idl.address && idl.address !== programId) throw Error('IDL declares another program');
+  return idl;
+}
+
+/** Batched `getMultipleAccounts` with bounded retry; never throws — returns {error} instead. */
+/**
+ * Classify ONE IDL account: is there a usable schema behind it?
+ *
+ * "Usable" must mean a decoder can USE the schema, not that the schema names
+ * things. A discriminator-less IDL names every instruction and still decodes
+ * nothing: measured on Kamino Lend (66 instructions, 0 discriminators), 0 of
+ * 1,432 real mainnet payloads decoded.
+ *
+ * This moved here from tools/measure.mjs on 2026-11-04: the gap classifier
+ * (src/gap.mjs) needs it, and the classifier has to work from an INSTALLED
+ * package — tools/ is not shipped.
+ */
+export function inspect(account, source, programId) {
+  if (!account) return { state: 'missing' };
+  const expectedOwner = source === 'metadata' ? METADATA_PROGRAM.toBase58() : programId;
+  if (account.owner !== expectedOwner) return { state: 'wrong_owner', owner: account.owner };
+  try {
+    const idl = decodeAccount(account, source, programId);
+    const digest = createHash('sha256').update(JSON.stringify(idl)).digest('hex');
+    const stored = idl.instructions.filter((ix) => Array.isArray(ix.discriminator)).length;
+    const derived = idl.instructions.length - stored;
+    const decodable = stored + derived > 0;
+    return {
+      state: 'usable',
+      instructions: idl.instructions.length,
+      fingerprint: digest,
+      // A strict, honest split for the coverage claim:
+      //   storedDiscriminators  - the program itself published the bytes
+      //   derivedDiscriminators - Anchor's rule can supply them from the name
+      //   decodableStoredOnly    - usable with the published bytes alone
+      storedDiscriminators: stored,
+      derivedDiscriminators: derived,
+      decodableStoredOnly: stored > 0,
+      decodableWithDerivation: decodable,
+    };
+  } catch (error) {
+    return { state: 'undecodable', error: String(error?.message ?? error).slice(0, 150) };
+  }
+}
+
+export async function rpcAccounts(url, keys, fetcher = fetch, tries = 3) {
+  const payload = { jsonrpc: '2.0', id: 1, method: 'getMultipleAccounts',
+    params: [keys, { encoding: 'base64', commitment: 'finalized' }] };
+  for (let attempt = 0; attempt < tries; attempt++) {
+    try {
+      const response = await fetcher(url, { method: 'POST', headers: { 'content-type': 'application/json' },
+        body: JSON.stringify(payload), signal: AbortSignal.timeout(15000) });
+      if (!response.ok) {
+        if (response.status === 429 || response.status >= 500) {
+          const retry = Number(response.headers.get('retry-after'));
+          if (attempt < tries - 1) { await sleep(Number.isFinite(retry) && retry > 0 ? Math.min(retry * 1000, 10000) : (attempt + 1) * 1500); continue; }
+        }
+        throw Error(`HTTP ${response.status}`);
+      }
+      const data = await response.json();
+      if (data.error) throw Error(`RPC error ${data.error.code ?? 'unknown'}`);
+      if (!Array.isArray(data.result?.value) || data.result.value.length !== keys.length) throw Error('malformed RPC response');
+      return { slot: data.result.context?.slot ?? null, accounts: data.result.value };
+    } catch (error) {
+      if (attempt === tries - 1) return { error: String(error?.message ?? error).slice(0, 150) };
+      await sleep((attempt + 1) * 1500);
+    }
+  }
+  return { error: 'exhausted retries' };
+}

package/src/adopt.mjs

@@ -0,0 +1,206 @@
+// `sememe adopt <program> <file>` — put a first-party PUBLISHED interface copy
+// into the store so union decode has a second verified source to read.
+//
+// What adopt does and does not claim. `pull` gets its authority from the chain:
+// the account is fetched at a finalized slot and bound to the program id.
+// `adopt` gets its authority from a FILE the caller names: it is content-
+// addressed and fingerprinted exactly like a pull, and every reader re-hashes
+// it — but its receipt says `source: published` and carries the origin the
+// caller declared. It is provenance of BYTES, not proof the bytes describe the
+// deployed program. That distinction is why the two receipts stay separate and
+// why union decode must keep naming which source answered.
+//
+// The ORIGIN is a DECLARED label and sememe says so on every surface
+// (`originStatus: 'declared'`, the reader label, the CLI note): nothing checks
+// that the named repository, commit or file exists. Measured 2026-11-07 (this
+// host, published v0.4.10): a caller could name a repository that does not
+// exist and every reader would repeat it as the origin, and `sememe verify`
+// stayed green after the origin was rewritten in the receipt — because the
+// fingerprint covers the OBJECT and the label next to it was covered by
+// nothing. The receipt now carries `originDigest` (binds the declared label)
+// and `receiptDigest` (binds the whole receipt body), see
+// src/receipt-digest.mjs; readers refuse a receipt whose digest disagrees.
+// The origin is still NOT verified — it is bound, so it cannot change
+// silently. Checked provenance remains first-party adoption with a recorded
+// commit and the on-chain pull, which needs no label at all.
+//
+// Why slot 0 in the receipt filename: receipts sort as
+// `<program>-<slot>-<source>-<fingerprint>.json` and `findStoredIdl` picks the
+// last name. Adopted copies must NEVER win the default single-source selection
+// over an on-chain receipt — otherwise adopting a published copy would silently
+// switch what plain `sememe decode` reads (measured hazard: pump's published
+// copy disagrees with its on-chain account on 4 shared instructions). The
+// receipt carries `slot: null` to say the truth about where it did NOT come
+// from; the filename segment only orders it before every real slot.
+
+import { createHash } from 'node:crypto';
+import { mkdir, readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { canonicalJson } from './canonical.mjs';
+import { writeOnce } from './store-write.mjs';
+import { originDigestOf, receiptDigestOf } from './receipt-digest.mjs';
+import { assertIdlShape, assertReadableDialect, declaredProgram } from './dialect.mjs';
+
+const sha256 = (data) => createHash('sha256').update(data).digest('hex');
+
+/** What `sememe adopt` prints about the origin it recorded. It lives in the
+ * receipt body for new receipts and in the CLI output always. */
+export const ORIGIN_NOTE = 'declared origin, not verified: sememe did not check that this repository, commit or file exists, and the bytes were not proven to come from it — provenance of bytes, not proof they describe the deployed program';
+
+/** Fields that identify WHICH object a receipt points at. Two receipts of one
+ * filename that agree on these make the same claim; only a differing declared
+ * origin makes them two claims about one set of bytes. */
+const IDENTITY_FIELDS = ['program', 'source', 'slot', 'fingerprint', 'instructionCount'];
+
+const safeLabel = (value, what) => {
+  if (typeof value !== 'string' || !value.trim()) throw Error(`${what} must be a non-empty string`);
+  const cleaned = value.trim().replace(/[^A-Za-z0-9._:-]+/g, '-').slice(0, 64);
+  if (!/^[A-Za-z0-9._:-]+$/.test(cleaned)) throw Error(`${what} is not usable in a receipt filename: ${JSON.stringify(value)}`);
+  return cleaned;
+};
+
+/**
+ * Store a published IDL file under a content-addressed object plus a receipt.
+ *
+ * Validation mirrors what `pull` enforces on fetched content: JSON, an
+ * instructions array, and — when the file declares an address — agreement with
+ * the program the receipt binds. A file that declares a DIFFERENT program is
+ * refused rather than re-labelled.
+ *
+ * Returns the receipt (same shape family as `pull`, plus `origin`).
+ */
+export async function adopt(programInput, filePath, storeDir, { source = 'published', origin } = {}) {
+  if (typeof programInput !== 'string' || !programInput.trim()) throw Error('program id required');
+  const program = programInput.trim();
+  if (!/^[1-9A-HJ-NP-Za-km-z]{32,44}$/.test(program)) throw Error('program id must be base58');
+  if (typeof storeDir !== 'string' || !storeDir.trim()) throw Error('explicit --store path required');
+  const sourceLabel = safeLabel(source, '--source');
+  const originLabel = safeLabel(origin ?? path.basename(filePath), '--origin');
+
+  let idl;
+  let raw;
+  try {
+    raw = await readFile(filePath);
+  } catch (error) {
+    throw Error(`cannot read ${filePath}: ${String(error?.message ?? error).slice(0, 140)}`);
+  }
+  try {
+    idl = JSON.parse(raw.toString('utf8'));
+  } catch (error) {
+    throw Error(`${filePath} is not JSON: ${String(error?.message ?? error).slice(0, 140)}`);
+  }
+  if (!idl || typeof idl !== 'object' || Array.isArray(idl)) throw Error(`${filePath} is not an IDL object`);
+  if (!Array.isArray(idl.instructions)) throw Error(`${filePath} has no instructions array — not an interface copy`);
+  // Two INDEPENDENT gates, each with its own named voice, checked in the
+  // order the faces were measured — an integrity question first (does this
+  // file claim to be about THIS program?), a capability question second
+  // (can the codec read this dialect at all?). Collapsing them would hide
+  // one face behind the other.
+  //
+  // Gate 1 — declared-program agreement. A file may declare its program
+  // under `address` (Anchor), `metadata.address` (shank) or `program_id`
+  // (raw dialects). Whatever the field is called, a DECLARED program that
+  // differs from the receipt's program is a re-labelling: measured
+  // 2026-11-12, the diabloarb file declares `program_id` only, and the old
+  // address-only check adopted it under WSOL's program id unchanged.
+  if (idl.address !== undefined && typeof idl.address !== 'string') {
+    throw Error(`${filePath} declares a malformed address field`);
+  }
+  const declared = declaredProgram(idl);
+  if (declared && declared !== program) {
+    if (idl.address === undefined) {
+      // The declaration rides a field the old check never read — name the
+      // field so the repair is obvious (this is the measured diabloarb face).
+      const field = idl.program_id !== undefined ? 'program_id'
+        : idl?.metadata?.address !== undefined ? 'metadata.address' : 'declared program';
+      throw Error(`${filePath} declares program ${declared} via ${field}, not ${program} — refusing to re-label a foreign interface`);
+    }
+    throw Error(`${filePath} declares program ${declared}, not ${program} — refusing to re-label a foreign interface`);
+  }
+  // Gate 2 — the dialect gate at the store's WRITE path: a dialect NO
+  // engine of the product can read is refused HERE by name, before
+  // adoption can store an undecodable interface. SINCE THE PULS-Z WIRING
+  // a raw-LE file passes (the codec serves it from src/rawle.mjs),
+  // everything else keeps the named refusal (measured 2026-11-12:
+  // diabloarb's dict `types` was the face of that refusal).
+  assertReadableDialect(idl, (reason) => Error(`${filePath}: ${reason}`));
+
+  const json = Buffer.from(canonicalJson(idl) + '\n');
+  const fingerprint = sha256(json);
+  const directory = path.resolve(storeDir);
+  const objects = path.join(directory, 'objects');
+  const receipts = path.join(directory, 'receipts');
+  await mkdir(objects, { recursive: true, mode: 0o700 });
+  await mkdir(receipts, { recursive: true, mode: 0o700 });
+  await writeOnce(path.join(objects, `${fingerprint}.json`), json);
+
+  const receipt = {
+    program,
+    source: sourceLabel,
+    origin: originLabel,
+    originStatus: 'declared',
+    originNote: ORIGIN_NOTE,
+    originDigest: originDigestOf(originLabel),
+    // null, not 0: this receipt did not come from a slot. The filename uses 0
+    // purely so it sorts before every real slot in findStoredIdl's selection.
+    slot: null,
+    fingerprint: `sha256:${fingerprint}`,
+    instructionCount: idl.instructions.length,
+  };
+  // The digest covers the whole body INCLUDING the declared label — a receipt
+  // that is edited afterwards fails this check on every read, not only under
+  // a lock.
+  receipt.receiptDigest = receiptDigestOf(receipt);
+  const bytes = Buffer.from(canonicalJson(receipt) + '\n');
+
+  const plainPath = path.join(receipts, `${program}-0-${sourceLabel}-${fingerprint}.json`);
+  let receiptPath = plainPath;
+  const existing = await readReceiptIfPresent(plainPath);
+  if (existing) {
+    const sameClaim = IDENTITY_FIELDS
+      .every((field) => (existing[field] ?? null) === (receipt[field] ?? null));
+    if (sameClaim && existing.origin === receipt.origin) {
+      // Re-adopting the SAME bytes under the SAME declared origin changes
+      // nothing — including a legacy body written before the digest fields
+      // existed: an old receipt is never rewritten in place, its origin is
+      // then merely DECLARED without a binding.
+      return {
+        ...existing,
+        originStatus: existing.originStatus ?? 'declared',
+        originNote: ORIGIN_NOTE,
+        path: path.join(objects, `${fingerprint}.json`),
+        receiptPath: plainPath,
+      };
+    }
+    if (!sameClaim) {
+      // The filename already names program/source/fingerprint, so a receipt
+      // that disagrees on these is not adopt's doing — refuse instead of
+      // layering a second claim over a file that means something else.
+      throw Error(`receipt ${plainPath} exists with different content for the same program, source and fingerprint — refusing to store this interface copy`);
+    }
+    // The SAME bytes under a DIFFERENT declared origin: two claims about one
+    // object, so two receipts. The disambiguator is a digest of the declared
+    // origin (12 hex chars), placed BEFORE the fingerprint so the filename
+    // keeps its `<program>-<slot>-<source>-<fingerprint>` tail that readers
+    // and tools parse the object id out of. The caller's TEXT never enters
+    // the filename, and both receipts carry the same fingerprint, so which of
+    // them sorts last cannot change a decoded byte — only which declared
+    // label is shown first.
+    const originKey = originDigestOf(originLabel).slice(7, 19);
+    receiptPath = path.join(receipts, `${program}-0-${sourceLabel}-${originKey}-${fingerprint}.json`);
+  }
+  await writeOnce(receiptPath, bytes);
+  return { ...receipt, path: path.join(objects, `${fingerprint}.json`), receiptPath };
+}
+
+async function readReceiptIfPresent(receiptPath) {
+  try {
+    return JSON.parse(await readFile(receiptPath, 'utf8'));
+  } catch (error) {
+    if (error?.code === 'ENOENT') return null;
+    if (error instanceof SyntaxError) {
+      throw Error(`receipt ${receiptPath} is not JSON — refusing to build a second claim over it`);
+    }
+    throw error;
+  }
+}