sememe 0.0.0-stage → 0.4.22

package/bin/sememe.mjs

@@ -0,0 +1,556 @@
+#!/usr/bin/env node
+import os from 'node:os';
+import path from 'node:path';
+import { readFileSync } from 'node:fs';
+// `pull` is imported LAZILY (inside the branch): it is the only path that
+// needs @solana/web3.js. A consumer who installed the package for DECODING
+// only — the common case — must be able to run `sememe decode` without any
+// package installed at all, so the acquisition dependency is never loaded
+// unless a pull is actually requested.
+import { decodePayload, decodeStoredAccount, decodeUnionPayload, decodeUnionStoredAccount, adopt, parsePayload } from '../src/decode.mjs';
+import {
+  decodeNativeInstruction, nativeProvenance, nativePrograms, isNativeProgram,
+} from '../src/native.mjs';
+import {
+  decodeTokenInstruction, tokenProvenance, tokenPrograms, isTokenProgram,
+} from '../src/token.mjs';
+import {
+  decodeRaydiumInstruction, raydiumProvenance, raydiumPrograms, isRaydiumProgram,
+} from '../src/raydium.mjs';
+import {
+  decodeAtaInstruction, ataProvenance, ataPrograms, isAtaProgram,
+} from '../src/ata.mjs';
+import { toJsonSafe } from '../src/codec.mjs';
+import { VERIFIED_SHORT_FORMS, SHORT_FORM_SOURCE } from '../src/short-forms.mjs';
+// The DECLARED surface of every command (which flags it takes, how many
+// positionals it consumes). Imported statically: it has no imports of its
+// own, so it stays inside the decode core's zero-dependency guarantee.
+import { parseCommandArgs, UsageError } from '../src/cli-surface.mjs';
+
+const usage = `usage:
+  sememe absent-help
+      print the chain-verified short wire forms that --absent verified licenses.
+  sememe pull <program-id> [--store <directory>] [--rpc <https-url>]
+  sememe gap <program-id> [--rpc <https-url>]
+      answer the question "why is there no interface here?" BEFORE you pull.
+      Probes both on-chain IDL addresses and returns one of:
+        pullable              an interface exists on chain that this program's
+                              store simply does not have yet -> run sememe pull
+        no-interface-published  neither address answers -> pulling it can never
+                              help: adopt a published copy or derive upstream
+        present-undecodable   an account exists but its schema is unusable
+        vendored              answered by sememe's pinned wire table, no IDL
+        unknown               the RPC failed — deliberately NOT an absence
+      Never reports an RPC failure as an absence, and never tells you to pull
+      a program that publishes nothing (the fix would never arrive).
+  sememe adopt <program-id> <file> [--store <directory>] [--source <label>]
+      store a first-party PUBLISHED interface copy next to the on-chain pull, so
+      union decode has a second verified source. The receipt says "published":
+      it is provenance of bytes, not proof the bytes describe the deployed program.
+  sememe adopt-lighthouse [--store <directory>]
+      the measured #1-remaining-gap case, wired end to end: adopt Lighthouse
+      (L2TExMFK…, 1,214 payloads in the committed 6-block window) from the
+      vendored first-party copy (Jac0xb/lighthouse, MIT), hash-checked against
+      its pin BEFORE any write; the receipt's origin stays declared.
+  sememe lock [--store <directory>] [--out <file>]
+      snapshot the WHOLE store into a sememe.lock document: for every program,
+      the exact fingerprint its newest verified receipt answered with, plus
+      source/slot/receipt provenance. Every receipt is re-checked through the
+      store reader first — a store the reader refuses produces NO lock, never
+      a lock over damage. Commit the file; CI then runs "sememe verify".
+  sememe verify [--store <directory>] [--lock <file>] [--mode error|warn]
+      re-check the store against the lock and refuse drift BY NAME:
+        drifted     the store answers a pinned program with a DIFFERENT
+                    fingerprint (a newer pull replaced it) — reported with
+                    both fingerprints
+        missing     the store has no receipt for a pinned program
+        unverified  a pinned object fails the store reader's re-hash check
+      Extra store programs are reported, never a violation: the lock pins
+      minimums, not store equality. --mode error (default) exits 1 when any
+      violation exists (the CI gate); --mode warn reports and exits 0.
+  sememe decode <program-id> <payload> [--store <directory>] [--trailing report|error] [--absent error|report|verified]
+      payload: base58 or hex instruction data (discriminator + args)
+      --trailing report (default): decode the IDL-described prefix and report
+          the bytes the IDL does not explain under "trailing"; --trailing error
+          refuses the payload instead.
+      --absent error (default): a payload that ENDS where a declared field
+          would start is refused as truncated. --absent report: decode it and
+          name the absent fields. --absent verified: decode it only when a
+          chain witness covers that exact wire form (see --absent-help).
+  sememe decode --union <program-id> <payload> [--store <directory>]
+      decode against BOTH stored sources (on-chain + adopted). The result names
+      the source that answered, the other source's verdict, and any layout
+      drift between them. Byte evidence arbitrates; a name conflict is refused.
+  sememe account <program-id> <account-data> [--store <directory>] [--name <account-type>]
+      account-data: base64 account bytes (as getMultipleAccounts returns them)
+          or hex. Without --name the account's 8-byte discriminator picks the
+          account type from the stored IDL.
+  sememe account --union <program-id> <account-data> [--store <directory>]
+      decode against BOTH stored sources (on-chain + adopted), like
+      "sememe decode --union". The result names the source that answered, the
+      other source's verdict, and any layout drift between them. Byte evidence
+      arbitrates; a name conflict is refused.
+  sememe conform <transaction.json> [--store <directory>] [--only <program-id>]
+      transaction.json: an RPC getTransaction/getBlock response entry
+          (encoding "json") with its meta — as saved by any RPC client.
+      Checks EVERY instruction of the transaction against the interface the
+      verified store declares for its program: account count, signer flags,
+      pinned addresses, and extra accounts. A disagreement is named; an
+      unreadable transaction shape is REFUSED, never reported as conforming.
+  sememe decode-native <program-id> <payload> [--trailing report|error]
+      payload: base58 or hex instruction data. For the NATIVE programs (System,
+      ComputeBudget) there is no IDL to pull: their interface is pinned from
+      the upstream runtime, and this decodes against that pin. The result names
+      the instruction, its arguments, and whether the bytes re-encode exactly.
+  sememe native-provenance [program-id]
+      print the pinned source, encoding rule and measured traffic for a native
+      program (or for all of them).
+  sememe decode-token <program-id> <payload> [--trailing report|error]
+      payload: base58 or hex instruction data. For SPL TOKEN and TOKEN-2022
+      there is no IDL account to pull at either address: their interface is
+      pinned from the upstream Rust crates (pack/unpack wire rule), and this
+      decodes against that pin. Extension sub-instructions report as trailing.
+      Token-2022 payloads whose first byte is no token tag fall through to the
+      token-METADATA table (spl-token-metadata-interface, 8-byte
+      discriminators) — the same fallback Token-2022's own processor takes.
+  sememe token-provenance [program-id]
+      print the pinned crate, encoding rule and variant count for a token
+      program (or for both).
+  sememe decode-raydium <program-id> <payload> [--trailing report|error]
+      payload: base58 or hex instruction data. For RAYDIUM AMM V4 there is no
+      IDL account to pull at either address: its interface is pinned from the
+      upstream program source (sparse u8 tag, pack/unpack wire rule), and this
+      decodes against that pin. Variants upstream itself refuses stay refused.
+  sememe raydium-provenance [program-id]
+      print the pinned upstream commit, encoding rule and variant counts for a
+      Raydium program (or for all of them).
+  sememe decode-ata <program-id> [<payload>] [--empty] [--trailing report|error]
+      payload: base58 or hex instruction data, or --empty for the processor's
+      own empty-input Create fallback. For the SPL ASSOCIATED TOKEN ACCOUNT
+      program there is no IDL account to pull at either address: its interface
+      is pinned from the upstream program source (borsh unit enum, empty-input
+      processor fallback), and this decodes against that pin.
+  sememe ata-provenance [program-id]
+      print the pinned upstream commit, encoding rule and variant counts for
+      the SPL Associated Token Account program.
+
+Every command declares the flags it accepts and how many positional arguments
+it consumes. A flag the command does not know, a flag given twice, a flag
+without a value, or a surplus positional argument is REFUSED BY NAME before
+any work happens -- no store is read, no file is written, no RPC is
+contacted. The refusal names the closest supported flag:
+
+  sememe lock --store ./store --o out.lock
+      sememe lock: unknown flag "--o" — did you mean "--out"?
+      supported flags: --store, --out`;
+
+const [command, ...tokens] = process.argv.slice(2);
+
+try {
+  // Parse the whole command line AGAINST THE SPEC, up front, before any
+  // branch runs: an unknown flag, a repeated flag, a missing flag value or a
+  // surplus positional argument is refused here, before a store is read, a
+  // file is written or an RPC is contacted. Previously the flags were
+  // searched for by name, so a typo was silently dropped and the command ran
+  // against whatever it would have done without that flag — a lock written to
+  // a different path than the one the caller named, a pull that touched the
+  // default store after a --stor typo.
+  const { flags, positionals } = parseCommandArgs(command, tokens);
+  const program = positionals[0];
+  // The positionals the branches consume with args.shift(): everything after
+  // the first one. Flags are already separated, so no order matters.
+  const args = positionals.slice(1);
+  const unionRequested = flags['--union'] === true;
+  const option = (name, fallback) => (Object.prototype.hasOwnProperty.call(flags, name) ? flags[name] : fallback);
+
+  if (command === 'absent-help') {
+    // The evidence behind --absent verified, printed so a user can see WHICH
+    // wire forms are licensed before relying on the flag.
+    console.log(JSON.stringify({
+      source: SHORT_FORM_SOURCE,
+      forms: VERIFIED_SHORT_FORMS,
+    }, null, 2));
+  } else if (command === 'pull') {
+    if (!program) throw Error('pull needs a program id');
+    const store = option('--store', path.join(os.homedir(), '.sememe'));
+    const rpc = option('--rpc', 'https://api.mainnet-beta.solana.com');
+    let pull;
+    try {
+      ({ pull } = await import('../src/pull.mjs'));
+    } catch (error) {
+      // The library already refuses with a complete sentence naming the fix
+      // (src/peer.mjs); wrapping it again produced a doubled message that
+      // said "install it next to sememe" twice. Anything else still gets the
+      // contextual wrap with the cause appended.
+      if (error?.code === 'peer_dependency_missing') throw error;
+      throw Error(`pull needs @solana/web3.js: install it next to sememe (npm i @solana/web3.js@1.98.4) — ${String(error?.message ?? error).slice(0, 120)}`);
+    }
+    console.log(JSON.stringify(await pull(program, store, rpc), null, 2));
+  } else if (command === 'gap') {
+    if (!program) throw Error('gap needs a program id');
+    const rpc = option('--rpc', 'https://api.mainnet-beta.solana.com');
+    let probe, where, nextStep;
+    try {
+      // Lazily imported like `pull`: the only path that needs web3.js.
+      ({ probeGap: probe, nextStep } = await import('../src/gap.mjs'));
+      ({ addresses: where } = await import('../src/acquire.mjs'));
+    } catch (error) {
+      if (error?.code === 'peer_dependency_missing') throw error;
+      throw Error(`gap needs @solana/web3.js: install it next to sememe (npm i @solana/web3.js@1.98.4) — ${String(error?.message ?? error).slice(0, 120)}`);
+    }
+    // The same classifier the qualification report uses, so what a user is
+    // told and what the research artifact records are one code path.
+    const { rows } = await probe([{ program, payloads: 0 }], { url: rpc });
+    const row = rows[0];
+    console.log(JSON.stringify({ ...row, addresses: await where(program), next: nextStep(row, program) }, null, 2));
+    if (row.verdict === 'unknown') process.exitCode = 3;
+  } else if (command === 'lock') {
+    if (!program) {
+      // No program argument: lock the WHOLE store (the common case). A program
+      // id here would otherwise be swallowed silently, so an explicit store
+      // wide lock must be chosen by omitting the argument entirely.
+      const store = option('--store', path.join(os.homedir(), '.sememe'));
+      const out = option('--out', 'sememe.lock');
+      const { writeLock } = await import('../src/lock.mjs');
+      const doc = await writeLock(store, out);
+      console.log(JSON.stringify(doc, null, 2));
+    } else {
+      throw Error(`lock takes no program id — it snapshots the whole store; got "${program}"`);
+    }
+  } else if (command === 'verify') {
+    const store = option('--store', path.join(os.homedir(), '.sememe'));
+    const lockFile = option('--lock', 'sememe.lock');
+    const mode = option('--mode', 'error');
+    if (mode !== 'error' && mode !== 'warn') throw Error('--mode must be "error" or "warn"');
+    if (program) throw Error(`verify takes no program id — it checks the whole lock; got "${program}"`);
+    const { checkLock } = await import('../src/lock.mjs');
+    const report = await checkLock(store, lockFile, { mode });
+    console.log(JSON.stringify(report, null, 2));
+    if (report.violations > 0) {
+      console.error(JSON.stringify({
+        note: `store does not match ${lockFile}: ${report.drifted.length} drifted, ${report.missing.length} missing, ${report.unverified.length} unverified, ${report.relabelled.length} relabelled, ${report.unbound.length} unbound`,
+        drifted: report.drifted.map((d) => d.program),
+        missing: report.missing,
+        unverified: report.unverified.map((u) => (u.scope === 'extra'
+          ? `${u.program} (extra: the lock does not pin it — re-pull that program's receipt)`
+          : u.program)),
+        relabelled: report.relabelled.map((r) => r.program),
+        unbound: report.unbound.map((r) => r.program),
+      }));
+      // The note goes to stderr as a WARNING. The exit stays 0: in error mode
+      // checkLock already threw above (that is the gate), so reaching here
+      // with violations can only be warn mode — a warning that fails the
+      // build is not a warning.
+    }
+  } else if (command === 'adopt') {
+    if (!program) throw Error('adopt needs a program id');
+    const file = args.shift();
+    if (!file) throw Error('adopt needs the interface file to store');
+    const store = option('--store', path.join(os.homedir(), '.sememe'));
+    const source = option('--source', 'published');
+    const origin = option('--origin', undefined);
+    const adopted = await adopt(program, file, store, {
+      source,
+      ...(origin === undefined ? {} : { origin }),
+    });
+    // The origin's STATUS travels with the result: a declared label is a
+    // claim the caller typed, not a provenance sememe checked. The CLI says
+    // so out loud, so an adopter cannot mistake a stored string for a
+    // verified one.
+    console.log(JSON.stringify({
+      ...adopted,
+      originStatus: adopted.originStatus ?? 'declared',
+      originNote: adopted.originNote
+        ?? 'declared origin, not verified: sememe did not check that this repository, commit or file exists — provenance of bytes, not proof they describe the deployed program',
+    }, null, 2));
+  } else if (command === 'adopt-lighthouse') {
+    const store = option('--store', path.join(os.homedir(), '.sememe'));
+    const { adoptLighthouse } = await import('../src/lighthouse.mjs');
+    const { adopt: adoptFn } = await import('../src/adopt.mjs');
+    const result = await adoptLighthouse(store, { adopt: adoptFn });
+    console.log(JSON.stringify({
+      program: result.receipt.program,
+      source: result.receipt.source,
+      origin: result.receipt.origin,
+      originStatus: result.receipt.originStatus,
+      originNote: result.receipt.originNote,
+      fingerprint: result.receipt.fingerprint,
+      instructionCount: result.receipt.instructionCount,
+      path: result.receipt.path,
+      receiptPath: result.receipt.receiptPath,
+    }, null, 2));
+  } else if (command === 'decode') {
+    if (!program) throw Error('decode needs a program id');
+    const payload = args.shift();
+    if (!payload) throw Error('decode needs an instruction payload');
+    const store = option('--store', path.join(os.homedir(), '.sememe'));
+    const trailing = option('--trailing', undefined);
+    if (trailing !== undefined && trailing !== 'report' && trailing !== 'error') {
+      throw Error('--trailing must be "report" or "error"');
+    }
+    const absent = option('--absent', undefined);
+    if (absent !== undefined && !['error', 'report', 'verified'].includes(absent)) {
+      throw Error('--absent must be "error", "report" or "verified"');
+    }
+    const union = unionRequested;
+    const extra = { ...(trailing === undefined ? {} : { trailing }), ...(absent === undefined ? {} : { absent }) };
+    // A program that publishes NO interface — the two token programs, the two
+    // native programs, Raydium AMM v4 — has no stored receipt, so the store
+    // path cannot answer for it. That is not a missing-pull problem and the
+    // error must not say it is: name the vendored path that CAN answer, or a
+    // first-time user reads "run sememe pull" as the fix and pulls forever.
+    const vendored = (programId) => (isTokenProgram(programId) ? 'decode-token'
+      : isNativeProgram(programId) ? 'decode-native'
+        : isRaydiumProgram(programId) ? 'decode-raydium'
+          : isAtaProgram(programId) ? 'decode-ata' : null);
+    let decoded;
+    try {
+      decoded = union
+        ? await decodeUnionPayload(store, program, payload, extra)
+        : await decodePayload(store, program, payload, extra);
+    } catch (error) {
+      const message = String(error?.message ?? error);
+      const command = vendored(program);
+      if (command && (message.startsWith('no stored IDL for program') || message.startsWith('no sememe store at'))) {
+        // The vendored answer is the whole answer: no pull will ever create a
+        // receipt for this program, so the "run sememe pull" part of the
+        // store's message is dropped rather than left to contradict the hint.
+        throw Error(`${program} publishes no interface to pull, so there is nothing to store — ` +
+          `its wire table is pinned from upstream instead.\n` +
+          `  use: sememe ${command} ${program} <payload>`);
+      }
+      throw error;
+    }
+    console.log(JSON.stringify(decoded, null, 2));
+    // A short-form decode is a measurement-backed claim, so the evidence is
+    // surfaced on stderr as well: a scripted caller should not have to know
+    // to look inside the JSON to learn the field was absent and why.
+    if (decoded.shortForm) {
+      console.error(JSON.stringify({
+        note: `${decoded.name} decoded as a chain-verified short form: the wire carries no `
+          + `${JSON.stringify(decoded.shortForm.absent)}`,
+        verified: decoded.shortForm.verified,
+        absent: decoded.shortForm.absent,
+        witnesses: decoded.shortForm.witnesses,
+        source: decoded.shortForm.source,
+      }));
+    }
+    // Unexplained bytes are a completeness finding, not a crash: report them
+    // on stderr so scripted callers notice without losing the decode result.
+    if (decoded.trailing.count > 0 && trailing !== 'error') {
+      console.error(JSON.stringify({
+        note: `${decoded.trailing.count} byte(s) after ${decoded.name} are not described by the stored IDL`,
+        consumed: decoded.consumed,
+        bytes: decoded.bytes,
+        trailing: decoded.trailing,
+      }));
+    }
+  } else if (command === 'conform') {
+    // The first positional after `conform` is the file (it lands in `program`
+    // like every other command's first argument).
+    const file = program ?? args.shift();
+    if (!file) throw Error('conform needs a transaction JSON file');
+    const store = option('--store', path.join(os.homedir(), '.sememe'));
+    const only = option('--only', undefined);
+    const envelope = JSON.parse(readFileSync(file, 'utf8'));
+    // Accept either a bare transaction entry or the full RPC envelope.
+    const transaction = envelope?.result ?? envelope;
+    const { checkTransaction } = await import('../src/conformance.mjs');
+    const report = await checkTransaction(transaction, store, only ? { only: [only] } : {});
+    console.log(JSON.stringify(report, null, 2));
+    const disagreement = report.summary.byVerdict;
+    const violations = Object.entries(disagreement)
+      .filter(([kind]) => ['missing-declared-accounts', 'declared-signer-not-signing', 'fixed-address-mismatch', 'undeclared-signing-account'].includes(kind));
+    if (violations.length) {
+      console.error(JSON.stringify({ note: 'account-list disagreement(s) found', kinds: violations.map(([kind, count]) => `${kind}:${count}`) }));
+      process.exitCode = 1;
+    }
+  } else if (command === 'decode-native') {
+    if (!program) throw Error('decode-native needs a program id');
+    const payload = args.shift();
+    if (!payload) throw Error('decode-native needs an instruction payload');
+    const trailing = option('--trailing', 'report');
+    if (trailing !== 'report' && trailing !== 'error') {
+      throw Error('--trailing must be "report" or "error"');
+    }
+    const decoded = decodeNativeInstruction(program, parsePayload(payload), { trailing });
+    console.log(JSON.stringify({
+      program,
+      kind: 'native-instruction',
+      name: decoded.name,
+      selector: decoded.selector,
+      selectorWidth: decoded.selectorWidth,
+      args: toJsonSafe(decoded.args),
+      bytes: decoded.bytes,
+      consumed: decoded.consumed,
+      trailing: decoded.trailing,
+      roundTripByteExact: decoded.roundTripByteExact,
+      interface: nativeProvenance(program),
+    }, null, 2));
+  } else if (command === 'native-provenance') {
+    const wanted = program;
+    if (wanted) {
+      const provenance = nativeProvenance(wanted);
+      if (!provenance) throw Error(`${wanted} is not a native program sememe pins`);
+      console.log(JSON.stringify(provenance, null, 2));
+    } else {
+      console.log(JSON.stringify(nativePrograms().map((id) => nativeProvenance(id)), null, 2));
+    }
+  } else if (command === 'decode-token') {
+    if (!program) throw Error('decode-token needs a program id');
+    const payload = args.shift();
+    if (!payload) throw Error('decode-token needs an instruction payload');
+    const trailing = option('--trailing', 'report');
+    if (trailing !== 'report' && trailing !== 'error') {
+      throw Error('--trailing must be "report" or "error"');
+    }
+    const decoded = decodeTokenInstruction(program, parsePayload(payload), { trailing });
+    if (decoded.refused === 'not-token') {
+      throw Error(`${program} is not a token program sememe pins — try decode-native or decode`);
+    }
+    console.log(JSON.stringify({
+      program,
+      kind: 'token-instruction',
+      name: decoded.name,
+      tag: decoded.tag,
+      selectorWidth: decoded.selectorWidth,
+      args: toJsonSafe(decoded.args),
+      authorityType: decoded.authorityType,
+      bytes: decoded.bytes,
+      consumed: decoded.consumed,
+      trailing: decoded.trailing,
+      roundTripByteExact: decoded.roundTripByteExact,
+      interface: tokenProvenance(program),
+    }, null, 2));
+  } else if (command === 'token-provenance') {
+    const wanted = program;
+    if (wanted) {
+      const provenance = tokenProvenance(wanted);
+      if (!provenance) throw Error(`${wanted} is not a token program sememe pins`);
+      console.log(JSON.stringify(provenance, null, 2));
+    } else {
+      console.log(JSON.stringify(tokenPrograms().map((id) => tokenProvenance(id)), null, 2));
+    }
+  } else if (command === 'raydium-provenance') {
+    const wanted = program;
+    if (wanted) {
+      const provenance = raydiumProvenance(wanted);
+      if (!provenance) throw Error(`${wanted} is not a Raydium program sememe pins`);
+      console.log(JSON.stringify(provenance, null, 2));
+    } else {
+      console.log(JSON.stringify(raydiumPrograms().map((id) => raydiumProvenance(id)), null, 2));
+    }
+  } else if (command === 'decode-raydium') {
+    if (!program) throw Error('decode-raydium needs a program id');
+    const payload = args.shift();
+    if (!payload) throw Error('decode-raydium needs an instruction payload');
+    const trailing = option('--trailing', 'report');
+    if (trailing !== 'report' && trailing !== 'error') {
+      throw Error('--trailing must be "report" or "error"');
+    }
+    const decoded = decodeRaydiumInstruction(program, parsePayload(payload), { trailing });
+    if (decoded.refused === 'not-raydium') {
+      throw Error(`${program} is not a Raydium program sememe pins — try decode-native, decode-token or decode`);
+    }
+    console.log(JSON.stringify({
+      program,
+      kind: 'raydium-instruction',
+      name: decoded.name,
+      tag: decoded.tag,
+      selectorWidth: decoded.selectorWidth,
+      args: toJsonSafe(decoded.args),
+      absent: decoded.absent,
+      bytes: decoded.bytes,
+      consumed: decoded.consumed,
+      trailing: decoded.trailing,
+      roundTripByteExact: decoded.roundTripByteExact,
+      interface: raydiumProvenance(program),
+    }, null, 2));
+  } else if (command === 'decode-ata') {
+    if (!program) throw Error('decode-ata needs a program id');
+    const trailing = option('--trailing', 'report');
+    if (trailing !== 'report' && trailing !== 'error') {
+      throw Error('--trailing must be "report" or "error"');
+    }
+    // The empty payload is a REAL instruction for this program: the pin's
+    // processor executes empty input as Create. It therefore needs a way to
+    // be said out loud, and `--empty` is that way — the base58/hex parsers
+    // have no empty string, by design.
+    const empty = flags['--empty'] === true;
+    const payloadArg = args.shift();
+    if (!payloadArg && !empty) {
+      throw Error('decode-ata needs an instruction payload (use --empty for the empty-input Create fallback)');
+    }
+    if (payloadArg && empty) {
+      throw Error('decode-ata: give a payload or --empty, not both');
+    }
+    const decoded = decodeAtaInstruction(program, empty ? Buffer.alloc(0) : parsePayload(payloadArg), { trailing });
+    if (decoded.refused === 'not-ata') {
+      throw Error(`${program} is not a program sememe pins with the ATA table — try decode-native, decode-token, decode-raydium or decode`);
+    }
+    console.log(JSON.stringify({
+      program,
+      kind: 'ata-instruction',
+      name: decoded.name,
+      tag: decoded.tag,
+      selectorWidth: decoded.selectorWidth,
+      args: {},
+      bytes: decoded.bytes,
+      consumed: decoded.consumed,
+      trailing: decoded.trailing,
+      roundTripByteExact: decoded.roundTripByteExact,
+      note: decoded.note,
+      interface: ataProvenance(program),
+    }, null, 2));
+  } else if (command === 'ata-provenance') {
+    const provenance = program ? ataProvenance(program) : null;
+    if (program && !provenance) {
+      throw Error(`${program} is not a program sememe pins with the ATA table — try decode-native, decode-token, decode-raydium or decode`);
+    }
+    console.log(JSON.stringify(provenance ?? ataPrograms().map((id) => ataProvenance(id)), null, 2));
+  } else if (command === 'account') {
+    if (!program) throw Error('account needs a program id');
+    const data = args.shift();
+    if (!data) throw Error('account needs the account data (base64 or hex)');
+    const store = option('--store', path.join(os.homedir(), '.sememe'));
+    const name = option('--name', undefined);
+    const trailing = option('--trailing', undefined);
+    if (trailing !== undefined && trailing !== 'report' && trailing !== 'error') {
+      throw Error('--trailing must be "report" or "error"');
+    }
+    // The union path reads BOTH verified store sources for the program (the
+    // on-chain pull and the adopted published copy) and arbitrates by byte
+    // evidence, exactly like `sememe decode --union`. Without it the account
+    // path read ONE receipt, so a store holding two copies of a program had
+    // two opinions about an account's layout and only one was consulted.
+    const decoded = unionRequested
+      ? await decodeUnionStoredAccount(store, program, data,
+        name === undefined ? { trailing } : { name, trailing })
+      : await decodeStoredAccount(store, program, data,
+        name === undefined ? { trailing } : { name, trailing });
+    console.log(JSON.stringify(decoded, null, 2));
+    if (decoded.trailing.count > 0 && trailing !== 'error') {
+      console.error(JSON.stringify({
+        note: `${decoded.trailing.count} byte(s) after the described struct are not described by the stored IDL`,
+        consumed: decoded.consumed,
+        bytes: decoded.bytes,
+        trailing: decoded.trailing,
+      }));
+    }
+  } else {
+    console.error(usage);
+    process.exitCode = 2;
+  }
+} catch (error) {
+  if (error instanceof UsageError) {
+    // A malformed command line is refused BEFORE any work, and it is a usage
+    // problem, not a failure of the work: plain text on stderr — the same
+    // channel the unknown-command usage dump uses — and exit 2. The machine
+    // readable JSON error channel stays for errors the work itself produced.
+    console.error(error.message);
+    process.exitCode = 2;
+  } else {
+    console.error(JSON.stringify({ error: String(error?.message ?? error) }));
+    process.exitCode = 1;
+  }
+}

package/index.mjs

@@ -0,0 +1,48 @@
+// sememe's package entry: the offline decode surface, and nothing else.
+//
+// The split is deliberate and enforced (test/package.test.mjs,
+// test/deps.test.mjs):
+//
+//   the entry ("sememe")
+//     - decodes instructions, accounts and event self-CPIs from a local,
+//       fingerprint-verified store; re-checks the receipt on every read;
+//     - imports only node: builtins and files inside this package, so a
+//       consumer installs ZERO runtime dependencies;
+//     - never touches the network, the CLI, or the qualification harness.
+//
+//   the acquisition subpath ("sememe/pull")
+//     - acquisition: finds a program's IDL account on chain and writes the
+//       store. Needs @solana/web3.js (declared as an optional peer) and a
+//       network. A decoder-only consumer never loads it.
+//
+// A package that exports its harness is a harness. This file exists so the
+// consumer's surface is a list you can read in one screen.
+
+export {
+  decodePayload,
+  decodeUnionPayload,
+  decodeStoredAccount,
+  decodeUnionStoredAccount,
+  findStoredIdl,
+  findStoredIdls,
+  adopt,
+  parsePayload,
+  decodeHex,
+  decodeBase58,
+  unionDecode,
+  unionAccountDecode,
+  UnionRefusal,
+  verifiedShortForm,
+  VERIFIED_SHORT_FORMS,
+} from './src/decode.mjs';
+
+export { encodeBase58 } from './src/base58.mjs';
+export { canonicalJson } from './src/canonical.mjs';
+// The native programs (System, ComputeBudget) are NOT re-exported here on
+// purpose: src/native.mjs derives its wire table from the pinned upstream
+// sources AT IMPORT TIME and refuses to load when the committed artifact
+// disagrees. That loud failure is right for the native decoder, but it must
+// not take the whole entry down for a consumer who only decodes an Anchor
+// instruction. Use `sememe/native` for those two programs. The same applies
+// to the two token programs (SPL Token, Token-2022) — `sememe/token` derives
+// their wire tables from the pinned upstream Rust crates the same way.

package/interface/ata-ATokenGPvbdGVxr1b2hvZbsiqW5xWH25efTNsLJA8knL.json

@@ -0,0 +1,62 @@
+{
+  "program": "ATokenGPvbdGVxr1b2hvZbsiqW5xWH25efTNsLJA8knL",
+  "label": "SPL Associated Token Account",
+  "scheme": "native-ata",
+  "source": {
+    "repo": "solana-program/associated-token-account",
+    "pin": "fbf5379e7398ac8b231c73ee8a9ff677b43dd0ec",
+    "license": "Apache-2.0 (LICENSE vendored beside the sources)",
+    "enum": "AssociatedTokenAccountInstruction (borsh unit enum: the variant index is the one-byte payload)",
+    "programSource": "vendored interface/src/lib.rs declare_id",
+    "files": [
+      {
+        "file": "interface/src/instruction.rs",
+        "role": "AssociatedTokenAccountInstruction: borsh unit enum, serialise arms carry the wire byte",
+        "sha256": "sha256:033191cb1316fe2370fb9f694b0a0f9f140f647ca44661f07cb661ed4aa8c56d"
+      },
+      {
+        "file": "program/src/processor.rs",
+        "role": "runtime verdict: empty input falls back to Create, borsh try_from_slice judges the rest, InvalidInstructionData refuses",
+        "sha256": "sha256:e8bf0dd2d9ac87ebc488faf73dee2530df6d6dc83bc19907def973c5209953ca"
+      },
+      {
+        "file": "interface/src/lib.rs",
+        "role": "the program id (declare_id), read from upstream, not re-typed",
+        "sha256": "sha256:a1bf5de71e01902c9a5b42604ba4eb696c7ef4c100bc6c72a0b59a926f4efad0"
+      }
+    ],
+    "vendoredAt": "vendor/spl-associated-token-account/fbf5379e7398ac8b231c73ee8a9ff677b43dd0ec",
+    "derivation": "src/ata-interface.mjs: tag = the declaration index upstream's borsh serialise arm pushes; args = none (unit enum); runtime verdicts read from the processor (empty input falls back to Create, borsh try_from_slice judges, InvalidInstructionData refuses)"
+  },
+  "runtime": {
+    "judge": "borsh AssociatedTokenAccountInstruction::try_from_slice(input)",
+    "emptyInputFallback": "Create",
+    "unknownInputRefusal": "ProgramError::InvalidInstructionData",
+    "source": "program/src/processor.rs at the pin"
+  },
+  "selector": {
+    "width": 1,
+    "encoding": "borsh enum index, u8; empty input is the processor's own Create fallback, not an unknown selector"
+  },
+  "argEncoding": "unit enum: payload is exactly the one index byte; no argument bytes",
+  "instructions": [
+    {
+      "tag": 0,
+      "name": "Create",
+      "wire": "borsh-unit-enum",
+      "args": []
+    },
+    {
+      "tag": 1,
+      "name": "CreateIdempotent",
+      "wire": "borsh-unit-enum",
+      "args": []
+    },
+    {
+      "tag": 2,
+      "name": "RecoverNested",
+      "wire": "borsh-unit-enum",
+      "args": []
+    }
+  ]
+}