sememe 0.4.24 → 0.4.25

package/index.mjs

@@ -38,6 +38,12 @@ export {
 
 export { encodeBase58 } from './src/base58.mjs';
 export { canonicalJson } from './src/canonical.mjs';
+// The count-from-header table: a vector whose element count the wire states
+// in a DECLARED header argument carries NO Borsh length prefix. The table is
+// the evidence — it names the measured program address, the measured
+// instruction names and where the measurement lives. Exported so a consumer
+// can ask WHICH layouts are evidence-backed instead of guessing.
+export { COUNT_FROM_HEADER, countFromHeader } from './src/wire-layout.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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sememe",
-  "version": "0.4.24",
+  "version": "0.4.25",
   "description": "Local, fingerprint-verified Solana program interfaces: pull an IDL once, then decode instructions, accounts and events offline. Zero dependencies on the decode path. Ships derived wire tables for System, ComputeBudget, SPL Token, Token-2022 (incl. its token-metadata fallback), Raydium AMM v4 and the SPL Associated Token Account, pinned to upstream Rust.",
   "license": "MIT",
   "type": "module",

package/src/codec.mjs

@@ -22,6 +22,7 @@ import { encodeBase58, decodeBase58 } from './base58.mjs';
 import { isShankIdl, isShankDiscriminant, shankDiscriminatorBytes, SHANK_LEB128_TYPES } from './shank.mjs';
 import { assertIdlShape, unsupportedIdlReason } from './dialect.mjs';
 import { rawLeDialectReason, decodeRawLe, encodeRawLe, RawLeError } from './rawle.mjs';
+import { countFromHeader } from './wire-layout.mjs';
 
 const MAX_DEPTH = 32;
 // Instruction data is bounded by transaction size; a hostile length prefix
@@ -356,6 +357,31 @@ function decodeAt(type, cur, ctx, path, depth) {
     return { __option: 'Some', value: decodeAt(type.option, cur, ctx, `${path}.value`, depth + 1) };
   }
   if ('vec' in type) {
+    // Count-from-header (src/wire-layout.mjs): a measured program+instruction
+    // whose wire carries the element count in a declared header argument and
+    // NO u32 Borsh prefix. The hook fires ONLY when ctx.__countFromHeader
+    // names THIS path — set by the instruction loop after the count argument
+    // decoded, cleared before every other argument — so every other interface
+    // keeps the strict prefix codec byte for byte.
+    if (ctx.__countFromHeader && ctx.__countFromHeader.vectorPath === path) {
+      const length = ctx.__countFromHeader.count;
+      const elementSize = ctx.__countFromHeader.pointBytes;
+      const needed = length * elementSize;
+      if (needed > cur.remaining) {
+        // The measured count does not fit the remaining bytes: this is NOT a
+        // Borsh prefix, so the refusal names the layout rule — never the
+        // garbage number a prefix read would produce.
+        throw new CodecError(
+          `${length} ${elementSize}-byte element(s) need ${needed} byte(s) but ${cur.remaining} remain — ` +
+          `${ctx.__countFromHeader.instruction}.${ctx.__countFromHeader.vectorArg} has no length prefix on the wire; ` +
+          `the count comes from ${ctx.__countFromHeader.countArg}`, path);
+      }
+      const out = [];
+      for (let index = 0; index < length; index++) {
+        out.push(decodeAt(type.vec, cur, ctx, `${path}[${index}]`, depth + 1));
+      }
+      return out;
+    }
     const length = readLittle(cur, 4, false, path);
     const minimum = minSize(type.vec, ctx);
     if (minimum === 0 && length > HARD_VEC_CAP) {
@@ -571,6 +597,23 @@ function encodeAt(type, value, ctx, path, depth) {
     return Buffer.concat([Buffer.from([1]), encodeAt(type.option, value.value, ctx, `${path}.value`, depth + 1)]);
   }
   if ('vec' in type) {
+    // Encoder half of count-from-header (src/wire-layout.mjs): the measured
+    // program+instruction writes the elements with NO u32 prefix. When the
+    // elements disagree with the declared count, the encode is refused by
+    // name — the count IS the layout, so silently fixing it would invent a
+    // wire the program never speaks.
+    if (ctx.__countFromHeader && ctx.__countFromHeader.vectorPath === path) {
+      const { count, countArg, instruction, vectorArg } = ctx.__countFromHeader;
+      if (value.length !== count) {
+        throw new CodecError(
+          `${instruction}.${vectorArg} carries ${value.length} element(s) but ${countArg} says ${count} — ` +
+          `this vector has no length prefix on the wire, the count is the header`, path);
+      }
+      const parts = [];
+      value.forEach((item, index) =>
+        parts.push(encodeAt(type.vec, item, ctx, `${path}[${index}]`, depth + 1)));
+      return Buffer.concat(parts);
+    }
     if (!Array.isArray(value)) throw new CodecError(`expected an array, got ${describe(value)}`, path);
     if (value.length > 0xffffffff) throw new CodecError(`vector length ${value.length} exceeds u32`, path);
     const parts = [writeLittle(4, false, value.length, path)];
@@ -1083,6 +1126,12 @@ export function decodeInstructionData(idl, data, { allowTrailing, trailing, abse
   const args = {};
   const absentArgs = [];
   const declaredArgs = instruction.args ?? [];
+  // Count-from-header (src/wire-layout.mjs): the measured program+instruction
+  // pair whose vector argument carries NO u32 prefix because the wire states
+  // the element count in a declared header argument. The rule is looked up by
+  // THIS idl's address and THIS instruction name, so an identical shape under
+  // another address or name keeps the strict codec byte for byte.
+  const headerRule = countFromHeader(idl, instruction.name);
   // Struct-internal absences (the payload ends INSIDE a declared struct
   // argument, on that struct's own field boundary) surface as a marker the
   // struct decoder leaves on the decoded value. The struct decoder only
@@ -1106,11 +1155,28 @@ export function decodeInstructionData(idl, data, { allowTrailing, trailing, abse
     // With absent:'error' (default) this falls through to decodeAt, which
     // reports `truncated input` — the behaviour every existing caller pins.
     ctx.__absentTrail.push(argument.name);
+    // Arm the vec hook ONLY for the argument the table names, and ONLY when
+    // the count it depends on was actually declared and decoded BEFORE this
+    // argument (G3: an interface without a declared count stays strict).
+    const headerCount = headerRule && argument.name === headerRule.vectorArg && 'vec' in (argument.type ?? {})
+      && typeof args[headerRule.countArg] === 'number' && Number.isSafeInteger(args[headerRule.countArg])
+      ? args[headerRule.countArg] : null;
+    if (headerCount !== null) {
+      ctx.__countFromHeader = {
+        count: headerCount,
+        countArg: headerRule.countArg,
+        vectorArg: headerRule.vectorArg,
+        vectorPath: `${instruction.name}.${headerRule.vectorArg}`,
+        pointBytes: headerRule.pointBytes,
+        instruction: instruction.name,
+      };
+    }
     let value;
     try {
       value = decodeAt(argument.type, cursor, ctx, `${instruction.name}.${argument.name}`, 0);
     } finally {
       ctx.__absentTrail.pop();
+      if (headerCount !== null) delete ctx.__countFromHeader;
     }
     // A struct the wire stopped inside carries the `__absentFields` marker;
     // peel it off so the decoded args never show codec-internal keys. The
@@ -1276,10 +1342,38 @@ export function encodeInstructionData(idl, name, args, { absent } = {}) {
   }
   try {
     const parts = [bytes];
+    // Encoder half of count-from-header (src/wire-layout.mjs): same gates as
+    // the decode — the table must name THIS program+instruction, and the
+    // args must carry an integer count for the vector being encoded. A
+    // count that disagrees with the elements is refused by name, never
+    // silently corrected: the count IS the wire layout.
+    const headerRule = countFromHeader(idl, instruction.name);
+    const countIndex = headerRule ? declared.findIndex((argument) => argument.name === headerRule.countArg) : -1;
+    const vectorIndex = headerRule ? declared.findIndex((argument) => argument.name === headerRule.vectorArg) : -1;
     for (const argument of declared) {
       if (absentSet.has(argument.name)) continue;
       if (!(argument.name in args)) throw new CodecError(`missing argument ${JSON.stringify(argument.name)}`, instruction.name);
-      parts.push(encodeAt(argument.type, args[argument.name], ctx, `${instruction.name}.${argument.name}`, 0));
+      const headerCount = headerRule
+        && argument.name === headerRule.vectorArg
+        && 'vec' in (argument.type ?? {})
+        && countIndex !== -1 && vectorIndex !== -1 && countIndex < vectorIndex
+        && typeof args[headerRule.countArg] === 'number' && Number.isSafeInteger(args[headerRule.countArg])
+        ? args[headerRule.countArg] : null;
+      if (headerCount !== null) {
+        ctx.__countFromHeader = {
+          count: headerCount,
+          countArg: headerRule.countArg,
+          vectorArg: headerRule.vectorArg,
+          vectorPath: `${instruction.name}.${headerRule.vectorArg}`,
+          pointBytes: headerRule.pointBytes,
+          instruction: instruction.name,
+        };
+      }
+      try {
+        parts.push(encodeAt(argument.type, args[argument.name], ctx, `${instruction.name}.${argument.name}`, 0));
+      } finally {
+        if (headerCount !== null) delete ctx.__countFromHeader;
+      }
     }
     return Buffer.concat(parts);
   } finally {

package/src/wire-layout.mjs

@@ -0,0 +1,88 @@
+// Count-from-header: an evidence-gated rule for a vector whose element count
+// the wire carries in an instruction HEADER field, not as a Borsh length
+// prefix.
+//
+// WHY THIS RULE EXISTS (measured 2026-11-13, 13.11. PULS AD -> AE)
+//
+// HADRoNbLovyqhCsocfYQYB7QdfCAAinN9HTePvBCVDQ8 publishes an on-chain IDL
+// that declares `points` as `vec<CurvePointInput>`, which means "a u32 Borsh
+// length prefix, then the elements". The deployed program writes NO prefix:
+// the element count is the `numPoints` u8 the instruction already declares
+// in its own header, and the points follow the header directly. Measured on
+// 144 chain-accepted payloads (research/hadro-vec-wire-2026-11-13.json):
+//
+//   wire = 1-byte discriminator + u8 header + numPoints x 21-byte
+//          CurvePointInput + an 8-byte tail
+//
+// What the strict u32-prefix codec did with that, measured on the same
+// payloads:
+//
+//   * 72 setRiskCurve payloads REFUSED with a garbage number — the u32 the
+//     codec read as the vector length was the first four bytes of the first
+//     curve point;
+//   * 72 setCurve payloads "decoded" with points: [] and 46 trailing bytes —
+//     an EMPTY curve, described, not decoded. 0 byte-exact.
+//
+// THE RULE: when a listed program+instruction declares an integer count
+// argument BEFORE the vector argument, the vector carries no length prefix on
+// the wire; its element count is the count argument's decoded value. The
+// encoder half writes the elements without a prefix, and a count that does
+// not fit the remaining bytes is refused BY NAME ("no length prefix on the
+// wire"), never by a garbage number.
+//
+// GATES — every one is load-bearing, and each has a guard in
+// test/hadro-count-from-header.test.mjs:
+//
+//   G1  the program address must be the measured program
+//       (G4: the same interface under another address keeps the strict codec)
+//   G2  the instruction name must be one of the measured names
+//       (G4: a shape the table does not name keeps the strict codec)
+//   G3  the instruction must DECLARE an integer count argument before the
+//       vector argument (G3: removing `numPoints` keeps the strict codec)
+//
+// A rule that fired on evidence the table was not measured on would decode
+// bytes by an argument that happens to be named "numPoints"; the gates are
+// what make this a measurement instead of a name match.
+//
+// Measured on the committed 144 payloads: setCurve (discriminator 0x04) is
+// always numPoints=2; setRiskCurve (0x08) carries numPoints in 2..19. The
+// tail after the points is 8 bytes for all 144 (an undeclared field the IDL
+// does not name — reported as trailing, never invented).
+
+const POINT_BYTES = 21;
+
+/**
+ * The measured count-from-header table, keyed by program address.
+ *
+ * Every entry is a program+instruction pair whose wire layout was measured
+ * against chain-accepted payloads with a committed artifact; nothing here is
+ * inferred from an IDL claim or from a shape match.
+ */
+export const COUNT_FROM_HEADER = {
+  HADRoNbLovyqhCsocfYQYB7QdfCAAinN9HTePvBCVDQ8: {
+    source: 'research/hadro-vec-wire-2026-11-13.json',
+    instructions: {
+      setCurve: { countArg: 'numPoints', vectorArg: 'points' },
+      setRiskCurve: { countArg: 'numPoints', vectorArg: 'points' },
+    },
+  },
+};
+
+/**
+ * Resolve the count-from-header rule for an IDL+instruction, or null.
+ *
+ * The returned rule is a promise about EVIDENCE, not a hint: it carries the
+ * count argument's name, the vector argument's name, and the measured point
+ * size. The caller must re-check that the count argument was actually
+ * declared (and decoded) before the vector, or the rule has no evidence to
+ * speak and must stay silent.
+ *
+ * @param {object} idl  the IDL being decoded (must carry `address`)
+ * @param {string} name  the instruction name being decoded/encoded
+ * @returns {{countArg: string, vectorArg: string, pointBytes: number}|null}
+ */
+export function countFromHeader(idl, name) {
+  const entry = COUNT_FROM_HEADER[idl?.address]?.instructions?.[name];
+  if (!entry) return null;
+  return { ...entry, pointBytes: POINT_BYTES };
+}