sememe 0.0.0-stage → 0.4.22

package/src/decode.mjs

@@ -0,0 +1,286 @@
+// Decode a Solana instruction payload with a locally stored, verified IDL.
+//
+// The store layout is the one produced by `sememe pull`:
+//   <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.
+
+import { createHash } from 'node:crypto';
+import { readFile, readdir } from 'node:fs/promises';
+import path from 'node:path';
+import { canonicalJson } from './canonical.mjs';
+import {
+  decodeData,
+  decodeInstructionData,
+  encodeInstructionData,
+  encodeEventData,
+  toJsonSafe,
+} from './codec.mjs';
+import { decodeBase58 } from './base58.mjs';
+import { findStoredIdl, findStoredIdls } from './store-read.mjs';
+import { unionDecode, UnionRefusal } from './union.mjs';
+import { unionAccountDecode } from './account-union.mjs';
+import { withDerivedDiscriminators } from './discriminators.mjs';
+import { resolveAbsentPolicy, describeShortForm, assertShortFormEvidence } from './short-forms.mjs';
+import {
+  withDerivedAccountDiscriminators, identifyAccount, decodeAccountData,
+} from './account.mjs';
+
+// Kept as a re-export: callers of `src/decode.mjs` import `decodeBase58`
+// from here, and the implementation now lives in `src/base58.mjs` so the
+// decode core has no third-party import at all.
+export { decodeBase58 } from './base58.mjs';
+
+export function decodeHex(input) {
+  const cleaned = input.replace(/^0x/, '');
+  if (!/^[0-9a-fA-F]*$/.test(cleaned) || cleaned.length % 2 !== 0) {
+    throw Error('hex payload must have an even number of hex digits');
+  }
+  return Buffer.from(cleaned, 'hex');
+}
+
+export function parsePayload(input) {
+  if (typeof input !== 'string') throw Error('payload must be a string');
+  const trimmed = input.trim();
+  if (/^0x[0-9a-fA-F]+$/.test(trimmed)) return decodeHex(trimmed);
+  if (/^[0-9a-fA-F]{16,}$/.test(trimmed) && trimmed.length % 2 === 0) return decodeHex(trimmed);
+  return decodeBase58(trimmed);
+}
+
+/** Find the newest stored IDL for a program id, verified against its receipt.
+ *
+ * The verification contract lives in `src/store-read.mjs`, shared by the
+ * single-source and the union reader: receipt program binding, object
+ * presence, re-hash against the receipt's fingerprint, address agreement.
+ * Any violation is refused with a named reason, never tolerated.
+ */
+export { findStoredIdl, findStoredIdls } from './store-read.mjs';
+export { adopt } from './adopt.mjs';
+export { unionDecode, UnionRefusal } from './union.mjs';
+export { unionAccountDecode } from './account-union.mjs';
+export { verifiedShortForm, VERIFIED_SHORT_FORMS, SHORT_FORM_SOURCE, describeShortForm, resolveAbsentPolicy } from './short-forms.mjs';
+
+/**
+ * The provenance of the interface that answered — INCLUDING the declared
+ * origin and its status.
+ *
+ * The plain decode quoted only fingerprint/slot/source/receipt, so an ADOPTED
+ * copy's origin (a label the caller typed, never checked) never appeared on
+ * this surface at all: the union path showed it as a bare provenance claim
+ * and the plain path hid it. Both now name the same thing, and the status
+ * says the origin was DECLARED, not verified. An on-chain receipt names no
+ * file, so it carries no origin at all.
+ */
+function provenanceOf(receipt, receiptName) {
+  return {
+    fingerprint: receipt.fingerprint,
+    slot: receipt.slot,
+    source: receipt.source,
+    receipt: receiptName,
+    ...(receipt.origin === undefined || receipt.origin === null ? {} : {
+      origin: receipt.origin,
+      originStatus: receipt.originStatus ?? 'declared',
+    }),
+  };
+}
+
+/**
+ * Decode one payload with BOTH verified store sources for the program.
+ *
+ * Primary = newest on-chain receipt (real slot), secondary = newest adopted
+ * published copy. Without an adopted copy this is exactly the plain
+ * single-source decode, labelled `view.verdict: 'single_source'` so callers
+ * can tell the difference instead of assuming a union happened.
+ *
+ * Refusals from `unionDecode` are re-thrown with `view` attached: the caller
+ * gets BOTH sources' verdicts in the failure, not just an error string.
+ */
+export async function decodeUnionPayload(storeDir, program, payloadInput, options = {}) {
+  const { primary, secondary, additional } = await findStoredIdls(storeDir, program);
+  const bytes = parsePayload(payloadInput);
+  // 'verified' is evidence-gated: only payload shapes with a chain witness in
+  // src/short-forms.mjs may decode with an absent field; every other payload
+  // stays strict, including one that merely ends on a field boundary. The gate
+  // runs before either source is consulted so the policy cannot depend on which
+  // source happens to win.
+  const { policy, form } = resolveAbsentPolicy(program, bytes, options.absent);
+  try {
+    const result = unionDecode({ program, primary, secondary, additional, bytes, absent: policy });
+    if (form) {
+      // 'verified' is a promise about EVIDENCE, not a hint. If the decode did
+      // not reproduce the measured absence the witness supports, there is no
+      // evidence for this payload any more — so it is refused rather than
+      // decoded and quietly labelled unverified.
+      if (options.absent === 'verified') {
+        result.shortForm = assertShortFormEvidence(form, result, bytes);
+      } else {
+        result.shortForm = describeShortForm(form, result, bytes);
+      }
+    }
+    if (options.trailing === 'error' && result.trailing.count > 0) {
+      throw new Error(`payload carries ${result.trailing.count} unexplained byte(s) after ${result.name}`);
+    }
+    return result;
+  } catch (error) {
+    if (error instanceof UnionRefusal) error.view = error.details?.view;
+    throw error;
+  }
+}
+
+/**
+ * Decode one account's data with the locally stored, verified IDL.
+ *
+ * Same provenance guarantee as decodePayload: the receipt binds the program id
+ * to a fingerprinted object, so decoding is offline and reproducible.
+ * `name` skips identification (useful when the caller already knows); without
+ * it the account's discriminator picks the type.
+ */
+export async function decodeStoredAccount(storeDir, program, dataInput, { name, trailing } = {}) {
+  const { idl: storedIdl, receipt, receiptName, objectPath } = await findStoredIdl(storeDir, program);
+  const { idl, filled, conflicts } = withDerivedAccountDiscriminators(storedIdl);
+  const bytes = parseAccountBytes(dataInput);
+  const identified = name ? { name } : identifyAccount(idl, bytes);
+  if (!identified) {
+    throw Error(`no account type in the stored IDL matches the first 8 bytes of these ${bytes.length} byte(s)`);
+  }
+  const decoded = decodeAccountData(idl, bytes, identified.name, trailing ? { trailing } : {});
+  return {
+    program,
+    account: decoded.name,
+    args: decoded.args,
+    bytes: decoded.total,
+    consumed: decoded.consumed,
+    roundTripByteExact: decoded.roundTripByteExact,
+    discriminator: decoded.discriminator,
+    // True when the account bytes actually carry the discriminator the IDL
+    // names. False means the caller forced a type name onto bytes that
+    // belong to a different (or corrupted) account.
+    discriminatorMatches: decoded.hasDiscriminator,
+    trailing: decoded.trailing,
+    discriminator: decoded.discriminator,
+    discriminatorSource: filled > 0 ? (conflicts.length ? 'stored+derived' : 'derived') : 'stored',
+    discriminatorDerivation: { filledAccounts: filled, conflicts: conflicts.length },
+    idl: provenanceOf(receipt, receiptName),
+    object: objectPath,
+  };
+}
+
+/** Parse account bytes the way the CLI documents: base64 (as
+ *  `getMultipleAccounts` returns them) or hex. Kept in ONE place so the
+ *  single-source and union paths cannot disagree about what "account bytes"
+ *  means — two parsers for one input shape is how a caller ends up decoding
+ *  something other than the bytes they pasted. */
+function parseAccountBytes(dataInput) {
+  if (dataInput instanceof Uint8Array) return Buffer.from(dataInput);
+  if (typeof dataInput !== 'string') throw Error('account data must be a string or byte array');
+  return dataInput.startsWith('data:') || /[^0-9a-fA-F]/.test(dataInput.trim())
+    ? Buffer.from(dataInput.trim().replace(/^base64,/, ''), 'base64')
+    : decodeHex(dataInput);
+}
+
+/**
+ * Decode one account's data with BOTH verified store sources for the program.
+ *
+ * Primary = newest on-chain receipt (real slot), secondary = newest adopted
+ * published copy — the same pairing `decodeUnionPayload` reads, so the two
+ * union surfaces can never consult different copies of one store (measured
+ * hazard class: src/store-read.mjs, rules 1 and 2). Without a second source
+ * this is exactly the plain single-source decode, labelled
+ * `view.verdict: 'single_source'` so a caller can tell the difference instead
+ * of assuming arbitration happened.
+ *
+ * Refusals from `unionAccountDecode` are re-thrown with `view` attached: the
+ * caller gets BOTH sources' verdicts in the failure, not just an error string.
+ */
+export async function decodeUnionStoredAccount(storeDir, program, dataInput, { name, trailing } = {}) {
+  const { primary, secondary, additional } = await findStoredIdls(storeDir, program);
+  const bytes = parseAccountBytes(dataInput);
+  try {
+    return unionAccountDecode({ program, primary, secondary, additional, bytes, name, trailing });
+  } catch (error) {
+    if (error instanceof UnionRefusal) error.view = error.details?.view;
+    throw error;
+  }
+}
+
+/**
+ * Decode one program payload (instruction or Anchor event self-CPI).
+ * Returns the decoded instruction/event plus provenance and a byte-exactness check:
+ * re-encoding the decoded value must reproduce the input bytes.
+ *
+ * `trailing` selects what happens to bytes the stored IDL does not explain:
+ * 'report' (default) decodes the described prefix and reports the rest under
+ * `trailing`; 'error' refuses the payload. See src/codec.mjs for why 'report'
+ * is the default and what real mainnet bytes motivated it.
+ */
+export async function decodePayload(storeDir, program, payloadInput, { allowTrailing, trailing, absent } = {}) {
+  const { idl: storedIdl, receipt, receiptName, objectPath } = await findStoredIdl(storeDir, program);
+  const bytes = parsePayload(payloadInput);
+  // 'verified' is evidence-gated (src/short-forms.mjs): only shapes with a
+  // chain witness may decode with an absent field; every other payload stays
+  // strict. The gate runs before the store is consulted, so the policy cannot
+  // depend on which source happens to win.
+  const requestedAbsent = absent;
+  const { policy, form } = resolveAbsentPolicy(program, bytes, absent);
+  absent = policy;
+  // Legacy on-chain IDLs (measured: Kamino Lend, 66 instructions) carry no
+  // discriminators at all — they name instructions but cannot decode a byte.
+  // Fill the gaps with Anchor's own rule; stored discriminators are never
+  // touched, and any conflict with a stored value is reported back to the
+  // caller instead of being silently overridden.
+  const { idl, filled, conflicts } = withDerivedDiscriminators(storedIdl);
+  const decoded = decodeData(idl, bytes, { allowTrailing, trailing, absent });
+  let reencoded;
+  if (decoded.kind === 'instruction') {
+    // Re-encode omitting exactly the fields the decode reported absent, so a
+    // short-form payload still has to reproduce byte-for-byte to be trusted.
+    reencoded = encodeInstructionData(idl, decoded.instruction, decoded.args, { absent: decoded.absent });
+  } else {
+    reencoded = encodeEventData(idl, decoded.event, decoded.args, { tagged: decoded.tagged });
+  }
+  const described = bytes.subarray(0, decoded.consumed);
+  if (form) {
+    // 'verified' is a promise about EVIDENCE, not a hint: if the decode did
+    // not reproduce the measured absence the witness supports, there is no
+    // evidence for this payload any more — refuse instead of decoding and
+    // quietly labelling it unverified.
+    if (requestedAbsent === 'verified') {
+      assertShortFormEvidence(form, decoded, bytes);
+    }
+  }
+  return {
+    program,
+    kind: decoded.kind,
+    instruction: decoded.kind === 'instruction' ? decoded.instruction : undefined,
+    event: decoded.kind === 'event' ? decoded.event : undefined,
+    name: decoded.kind === 'instruction' ? decoded.instruction : decoded.event,
+    discriminator: decoded.discriminator,
+    tagged: decoded.tagged,
+    args: toJsonSafe(decoded.args),
+    // Declared fields the payload did not carry (see src/codec.mjs `absent`).
+    absent: decoded.absent ?? [],
+    bytes: bytes.length,
+    consumed: decoded.consumed,
+    // True when the re-encoded bytes equal the whole input. With unexplained
+    // trailing bytes this is false by construction, so the described prefix is
+    // checked separately: `describedRoundTripByteExact` says the IDL-described
+    // part reproduces exactly, `trailing.count` says how much was unexplained.
+    roundTripByteExact: reencoded.equals(bytes),
+    describedRoundTripByteExact: reencoded.equals(described),
+    trailing: decoded.trailing,
+    // Provenance of the discriminator that matched: stored = the bytes the
+    // program wrote on-chain; derived = Anchor's sha256 rule filled a gap.
+    discriminatorSource: conflicts.length === 0 && (filled.instructions + filled.events) > 0
+      ? 'derived'
+      : (filled.instructions + filled.events) > 0 ? 'stored+derived' : 'stored',
+    discriminatorDerivation: {
+      filledInstructions: filled.instructions,
+      filledEvents: filled.events,
+      conflicts: conflicts.length,
+    },
+    ...(form ? { shortForm: describeShortForm(form, decoded, bytes) } : {}),
+    idl: provenanceOf(receipt, receiptName),
+    object: objectPath,
+  };
+}

package/src/dialect.mjs

@@ -0,0 +1,180 @@
+// IDL dialect detection — the gate that turns a codec CRASH into a NAMED
+// REFUSAL for interfaces sememe does not speak.
+//
+// Why this exists: not every program publishes an Anchor or shank IDL.
+// Measured 2026-11-12 on DiabLokxisGR8P4Qqp2QL6PmBhhVsdzPstCE4WoLxc5z
+// (first-party interface: cryptodiablo/diabloarb, sdk/diabloarb-executor.
+// idl.json @ f5005ac4 — raw little-endian, "NOT Anchor/Borsh" by its own
+// description):
+//   - `types` is a DICT keyed by name ({Hop:…, Base:…, Route:…}), not the
+//     Anchor array — and context() iterated `idl.types ?? []`, so every one
+//     of the program's 102 sampled payloads died with the unnamed
+//     `TypeError: object is not iterable (cannot read property
+//     Symbol(Symbol.iterator))` instead of a refusal. Measured pre-fix:
+//     crash-voice 102/102, named-voice 0.
+//   - instructions dispatch on a 1-byte `tag` with fields under `data`
+//     (no `args`, no `discriminator`, no `discriminant`). withDerived-
+//     Discriminators filled all 4 with Anchor sighashes that match no wire
+//     (measured: filled {instructions: 4, events: 0}).
+//   - the program declares itself under `program_id` (not `address` /
+//     `metadata.address`), so adopt() and readVerified() — which only check
+//     `idl.address` — adopted the diabloarb file happily under
+//     So11111111111111111111111111111111111111112, a DIFFERENT program
+//     (measured: adopt succeeded; this is the mislabelling face).
+//
+// The rules, applied at every store/codec boundary so the reason is identical
+// everywhere:
+//   - the members the codec ITERATES must be arrays. A mapping dialect
+//     (instructions/types/events/accounts as a dict) is refused by name.
+//   - a name-only legacy IDL (no discriminator, no discriminant, no stored
+//     bytes) stays SUPPORTED: `sememe conform` uses those account lists for
+//     layout checking, and the decode path already refuses such a payload by
+//     name ("unknown instruction discriminator") at the exact 0-decoded
+//     boundary the Kamino measurement pins. Naming that shape "unsupported"
+//     would change attested behavior without a measured wire failure.
+//   - a tag-dispatch instruction (fields under `data`, no `args`) is refused:
+//     the dialect names no wire layout the codec can read, and Anchor sighash
+//     derivation must not be applied to it (a derived table matches no wire).
+//   - oracle fixtures (marinade/meteora/openbook anchor-ts-discriminators.json)
+//     are captured artifacts, never passed to the codec as IDLs — the guard
+//     cannot false-positive on them because nothing feeds them here.
+//
+// Nothing here changes decoding bytes for a supported interface: anchor and
+// shank take the same paths as before, byte for byte.
+
+import { isShankDiscriminant } from './shank.mjs';
+import { rawLeDialectReason } from './rawle.mjs';
+
+const isPlainObject = (value) => !!value && typeof value === 'object' && !Array.isArray(value);
+
+const isByteArray = (value) => Array.isArray(value) && value.length > 0
+  && value.every((byte) => Number.isInteger(byte) && byte >= 0 && byte <= 255);
+
+/** The one machine-readable name of this refusal, used by every boundary. */
+export const UNSUPPORTED_DIALECT_CODE = 'unsupported-idl-dialect';
+
+const MAPPING_HINT = ' (mapping dialects like diabloarb tag-dispatch are not decodable)';
+
+/**
+ * True when `instruction` names a tag-dispatch dialect entry: fields under
+ * `data` and/or an explicit `tag`, with no anchor `args` array. A plain
+ * name-only legacy entry ({ name }) is NOT tagged — it stays a supported
+ * (if selector-less) anchor shape whose account lists drive conform.
+ */
+export function isTagDispatchInstruction(instruction) {
+  return isPlainObject(instruction) && !Array.isArray(instruction.args)
+    && (instruction.data !== undefined || instruction.tag !== undefined);
+}
+
+/**
+ * The named refusal reason for an IDL the codec cannot read, or null when
+ * the shape is fine. `unsupportedIdlReason` is the ONE definition of the
+ * reason text so every entry point (codec context, discriminator fill,
+ * union, decode, adopt, store read) states the same refusal.
+ */
+export function unsupportedIdlReason(idl) {
+  if (!isPlainObject(idl)) return 'unsupported IDL dialect: not an IDL object';
+  // Mapping dialects put the members the codec iterates into a dict
+  // (measured: diabloarb `types` as {Hop, Base, Route}).
+  for (const key of ['instructions', 'types', 'events', 'accounts']) {
+    if (idl[key] !== undefined && !Array.isArray(idl[key])) {
+      return `unsupported IDL dialect: ${key} must be an array, got ${typeof idl[key]}${MAPPING_HINT}`;
+    }
+  }
+  if (!Array.isArray(idl.instructions)) return 'unsupported IDL dialect: no instructions array';
+  for (const instruction of idl.instructions) {
+    if (!isPlainObject(instruction)) {
+      return 'unsupported IDL dialect: instruction entries must be objects';
+    }
+    // A tag-dispatch instruction carries its fields under `data` and has no
+    // `args`: the dialect names no field list the codec could read, and the
+    // Anchor sighash derivation must not be applied to it.
+    if (isTagDispatchInstruction(instruction)) {
+      return `unsupported IDL dialect: instruction ${JSON.stringify(instruction.name ?? null)}`
+        + ` carries no anchor args (tag/data dispatch)${MAPPING_HINT}`;
+    }
+  }
+  for (const event of idl.events ?? []) {
+    if (!isPlainObject(event)) return 'unsupported IDL dialect: event entries must be objects';
+  }
+  return null;
+}
+
+/**
+ * Which dispatch dialect an IDL claims — the pure-shape question the
+ * measurement pins. `name-only` is a supported dialect (a legacy Anchor IDL
+ * that publishes names and layouts but no selectors): the decode path
+ * refuses those payloads by name, and the conform path uses their account
+ * lists.
+ */
+export function idlDialect(idl) {
+  // A raw-LE file is SUPPORTED now (PULS Z wiring) but is not one of the
+  // three Anchor-family dialects this classifier enumerates; it reports
+  // its own name so callers can tell a wired dialect from a refused one.
+  if (unsupportedIdlReason(idl)) {
+    return rawLeDialectReason(idl) === null ? 'raw-le' : 'unsupported';
+  }
+  const instructions = idl.instructions;
+  if (instructions.length === 0) return 'anchor';
+  for (const instruction of instructions) {
+    if (isShankDiscriminant(instruction)) return 'shank';
+    if (isByteArray(instruction?.discriminator)) return 'anchor';
+  }
+  return 'name-only';
+}
+
+/**
+ * The program an IDL declares for itself, under any of the field names
+ * measured in the wild: `address` (Anchor on-chain), `metadata.address`
+ * (shank), `program_id` (diabloarb and other raw dialects).
+ */
+export function declaredProgram(idl) {
+  const candidates = [idl?.address, idl?.metadata?.address, idl?.program_id];
+  for (const candidate of candidates) {
+    if (typeof candidate === 'string' && candidate.trim()) return candidate.trim();
+  }
+  return null;
+}
+
+/**
+ * Throw the caller's error type when the IDL is not structurally decodable.
+ * One line at each of the boundaries, so the guard cannot drift between them.
+ */
+export function assertIdlShape(idl, makeError) {
+  const reason = unsupportedIdlReason(idl);
+  if (!reason) return;
+  const error = makeError(reason);
+  if (error && typeof error === 'object') {
+    error.code = UNSUPPORTED_DIALECT_CODE;
+  }
+  throw error;
+}
+
+/**
+ * The refusal reason ONLY when no engine in the product can read the file.
+ * Since 12.11. PULS Z the raw little-endian engine (src/rawle.mjs) is wired
+ * into the codec: an IDL the Anchor codec refuses by SHAPE but the engine
+ * claims grammar for is decodable, so the store write gate, the store read
+ * gate and the discriminator derivation must not refuse it. Every other
+ * unsupported shape keeps the exact named refusal of `unsupportedIdlReason`.
+ * The codec's own dispatch (src/codec.mjs) asks the same two questions in
+ * the same order: is it outside the Anchor shape, and is it inside the
+ * engine grammar?
+ */
+export function unreadableDialectReason(idl) {
+  const reason = unsupportedIdlReason(idl);
+  if (!reason) return null;
+  return rawLeDialectReason(idl) === null ? null : reason;
+}
+
+/** Like assertIdlShape, but raw-LE-readable files pass — the engine speaks
+ * them now (PULS Z). Same named refusal and same error code otherwise. */
+export function assertReadableDialect(idl, makeError) {
+  const reason = unreadableDialectReason(idl);
+  if (!reason) return;
+  const error = makeError(reason);
+  if (error && typeof error === 'object') {
+    error.code = UNSUPPORTED_DIALECT_CODE;
+  }
+  throw error;
+}

package/src/discriminators.mjs

@@ -0,0 +1,192 @@
+// Derive Anchor discriminators for IDLs that do not carry them.
+//
+// Why this exists: the on-chain IDL of a program is not always the IDL the
+// program was built from. Legacy Anchor IDLs (the `anchor:idl` account form)
+// and several deployed programs publish instruction NAMES and ARGUMENT LAYOUTS
+// but no `discriminator` arrays. Measured on Kamino Lend
+// (KLend2g3cP87fffoy8q1mQqGKjrxjC8boSyAYavgmjD), pulled on-chain 2026-10-29:
+// 66 of 66 instructions and 5 of 5 events carry NO discriminator.
+//
+// Such an IDL is not a decoder input: without a discriminator there is no way
+// to tell which instruction a payload is. It is also what the coverage
+// measurement called "usable" — a schema that names instructions but cannot
+// decode a single byte.
+//
+// The rule is Anchor's own, not a guess:
+//   instruction: sha256("global:" + snake_case(name))[0..8]
+//   event:       sha256("event:" + name)[0..8]
+// (anchor-lang `discriminator` helper; the IDL generator uses the same one).
+//
+// The rule is verified, not assumed. `verifyDerivedDiscriminators` compares
+// derived values against discriminators that ARE present in the IDL, so a
+// program that stores them acts as the oracle. Measured on two independent
+// real programs: Whirlpool 66/66 instructions, Jupiter AMM v6 19/19
+// instructions and 6/6 events agree with the derivation.
+//
+// Nothing here overwrites a stored discriminator. A present value wins; the
+// derivation only fills gaps. A conflict is an error, not a silent override.
+
+import { createHash } from 'node:crypto';
+import { isShankDiscriminant } from './shank.mjs';
+import { unreadableDialectReason, idlDialect } from './dialect.mjs';
+
+const sha256 = (text) => createHash('sha256').update(text).digest();
+
+/** Anchor's snake_case of an instruction name (Rust fn name -> wire name). */
+export function snakeCase(name) {
+  if (typeof name !== 'string' || !name) throw new Error('instruction name must be a non-empty string');
+  return name
+    .replace(/([a-z0-9])([A-Z])/g, '$1_$2')
+    .replace(/([A-Z]+)([A-Z][a-z])/g, '$1_$2')
+    .toLowerCase();
+}
+
+/** Anchor's global instruction discriminator for a name. */
+export function globalDiscriminator(name) {
+  return Array.from(sha256(`global:${snakeCase(name)}`).subarray(0, 8));
+}
+
+/** Anchor's event discriminator for an event name. */
+export function eventDiscriminator(name) {
+  if (typeof name !== 'string' || !name) throw new Error('event name must be a non-empty string');
+  return Array.from(sha256(`event:${name}`).subarray(0, 8));
+}
+
+const isDiscriminator = (value) => Array.isArray(value)
+  && value.length === 8
+  && value.every((byte) => Number.isInteger(byte) && byte >= 0 && byte <= 255);
+
+/**
+ * Any stored discriminator bytes, whatever length the source published. A
+ * non-8-byte array is NOT a gap: it is a stored value under a different
+ * dispatch scheme (measured: HADRo… publishes 38 one-byte instruction
+ * discriminators — a real, chain-accepted wire table that Anchor's sighash
+ * derivation cannot describe). The codec matches and re-encodes on the stored
+ * prefix length, so preservation here is what makes those bytes decodable.
+ */
+const isStoredDiscriminator = (value) => Array.isArray(value)
+  && value.length > 0
+  && value.every((byte) => Number.isInteger(byte) && byte >= 0 && byte <= 255);
+
+/**
+ * Compare derived discriminators against the ones an IDL already stores.
+ *
+ * @returns {{ checked: number, agree: number, conflicts: object[] }}
+ */
+export function verifyDerivedDiscriminators(idl) {
+  const conflicts = [];
+  let checked = 0;
+  let agree = 0;
+  for (const instruction of idl?.instructions ?? []) {
+    if (!isDiscriminator(instruction?.discriminator)) continue;
+    checked++;
+    const derived = globalDiscriminator(instruction.name);
+    const same = derived.every((byte, index) => byte === instruction.discriminator[index]);
+    if (same) agree++;
+    else conflicts.push({
+      kind: 'instruction',
+      name: instruction.name,
+      stored: instruction.discriminator.slice(),
+      derived,
+    });
+  }
+  for (const event of idl?.events ?? []) {
+    if (!isDiscriminator(event?.discriminator)) continue;
+    checked++;
+    const derived = eventDiscriminator(event.name);
+    const same = derived.every((byte, index) => byte === event.discriminator[index]);
+    if (same) agree++;
+    else conflicts.push({
+      kind: 'event',
+      name: event.name,
+      stored: event.discriminator.slice(),
+      derived,
+    });
+  }
+  return { checked, agree, conflicts };
+}
+
+/**
+ * Return a copy of the IDL with discriminators filled in where they are
+ * missing. Stored discriminators are never changed — at ANY length, not just
+ * Anchor's 8 (pre-fix, a stored 1-byte array fell through to the sighash fill
+ * and HADRo's whole wire table was silently replaced by bytes no payload
+ * carries; measured 0/195 decoded pre-fix, 123/195 post-fix). Only an 8-byte
+ * stored value makes a claim under Anchor's rule, so only those are checked
+ * for a conflict; a stored value that disagrees with the derivation is
+ * reported as a conflict.
+ *
+ * @returns {{ idl: object, filled: { instructions: number, events: number }, conflicts: object[] }}
+ */
+export function withDerivedDiscriminators(idl) {
+  // A dialect NO engine in the product can read gets NO derived table at
+  // all. Measured 2026-11-12 on the diabloarb interface: the derivation
+  // filled all four tag-dispatch instructions with Anchor sighashes that
+  // match no wire — a table that looks authoritative and decodes nothing.
+  // The refusal is named (see src/dialect.mjs) and identical to the
+  // codec's own. SINCE THE PULS-Z WIRING the raw little-endian engine is
+  // a product engine: a raw-LE interface carries its own tag dispatch (a
+  // u8 `tag`, not a sighash) and passes this gate to the codec, which
+  // serves it from src/rawle.mjs — no Anchor table is derived for it and
+  // none is needed.
+  const refusal = unreadableDialectReason(idl);
+  if (refusal) throw new Error(refusal);
+  const copy = structuredClone(idl);
+  // A raw-LE file (PULS Z wiring) dispatches on the u8 tag its own file
+  // declares — Anchor sighash derivation for it is the measured PULS X
+  // defect one gate change later: filled {instructions: 4, events: 0}, a
+  // table that looks authoritative and matches no wire byte. The honest
+  // table for this dialect is NO derived table, and the codec serves the
+  // file from src/rawle.mjs. The file still passes the gate (an engine
+  // reads it); only the Anchor filling is withheld.
+  if (idlDialect(idl) === 'raw-le') {
+    return { idl: copy, filled: { instructions: 0, events: 0 }, conflicts: [] };
+  }
+  let instructions = 0;
+  let events = 0;
+  const conflicts = [];
+  for (const instruction of copy.instructions ?? []) {
+    // A shank discriminant is a 1-byte variant selector, not a sighash. The
+    // two schemes are independent: deriving Anchor's sighash for a shank
+    // instruction yields a table that matches no real wire (measured: all 18
+    // lighthouse instructions filled with bogus sighashes before this rule
+    // existed). The stored discriminant is copied verbatim — it is a STORED
+    // value under a different field name, so it is not counted as an Anchor
+    // derivation and never checked against the sighash rule.
+    if (isShankDiscriminant(instruction)) {
+      instruction.discriminator = [instruction.discriminant.value];
+      continue;
+    }
+    if (isStoredDiscriminator(instruction.discriminator)) {
+      // STORED bytes under any scheme: copied verbatim, never filled. Only
+      // Anchor's own 8-byte form is checked against his sighash rule — a
+      // 1-byte stored value is a different dispatch scheme and makes no
+      // sighash claim, so there is nothing to conflict.
+      if (isDiscriminator(instruction.discriminator)) {
+        const derived = globalDiscriminator(instruction.name);
+        if (!derived.every((byte, index) => byte === instruction.discriminator[index])) {
+          conflicts.push({ kind: 'instruction', name: instruction.name, stored: instruction.discriminator.slice(), derived });
+        }
+      }
+      continue;
+    }
+    instruction.discriminator = globalDiscriminator(instruction.name);
+    instructions++;
+  }
+  for (const event of copy.events ?? []) {
+    if (isStoredDiscriminator(event.discriminator)) {
+      // Same rule as instructions: stored bytes at any length are kept
+      // verbatim; only the 8-byte Anchor form is conflict-checked.
+      if (isDiscriminator(event.discriminator)) {
+        const derived = eventDiscriminator(event.name);
+        if (!derived.every((byte, index) => byte === event.discriminator[index])) {
+          conflicts.push({ kind: 'event', name: event.name, stored: event.discriminator.slice(), derived });
+        }
+      }
+      continue;
+    }
+    event.discriminator = eventDiscriminator(event.name);
+    events++;
+  }
+  return { idl: copy, filled: { instructions, events }, conflicts };
+}