sememe 0.4.22 → 0.4.24

package/README.md

@@ -69,7 +69,7 @@ What this changes about the thesis, stated plainly: sememe's decode path is stro
 
 **HADRo's 195 refusals were NOT source lag — stored discriminators are stored at ANY length (fixed and measured 2026-11-12, `tools/measure-hadro-short-discriminator.mjs` -> `research/hadro-short-discriminator-2026-11-12.json`, pinned by `test/hadro-short-discriminator.test.mjs` 7 tests + `test/hadro-short-discriminator-measurement.test.mjs` 5 tests).** The ecosystem measurement had labelled HADRo (`HADRo…VDQ8`) a "total source-lag face" at 0/195. It was wrong, and the PULS V two-tree measurement (`git archive c304e80` for the pre-fix tree, a byte-identical probe in both) proved why: the program's published IDL stores **38 one-byte instruction discriminators** — a real, chain-accepted wire table (unique values 0x00..0x26) — and `withDerivedDiscriminators` treated only 8-byte arrays as "stored", so every stored byte was OVERWRITTEN with Anchor's 8-byte sighash, against that module's own header rule ("stored discriminators are never changed"). The replaced table matches no payload: pre-fix 0/195 decoded; post-fix **123/195 decode through the product path** (51 full byte-exact, 72 `setCurve` described-exact with reported trailing bytes), and the remaining 72 (`setRiskCurve`) stay **honestly refused and NAMED** — that IDL declares a vector length the wire bytes do not carry. The same `length === 8` assumption in `src/union.mjs`'s rename-evidence map was fixed the same way (stored means any non-empty byte array). The fix is surgical and the measurement pins that: pump.fun (400/842, 249 byte-exact), pfeeU (5/464) and Eternal (227/242 byte-exact) verdicts are BYTE-IDENTICAL between the trees; Eternal's 76 stored 1-byte EVENT discriminators are now preserved too (the event dispatch path reads 8-byte heads, so that preservation changes no decode in this window — stated, not smoothed). Honest limits ride in the artifact; the unit face flips `false -> true` on both instruction and event preservation, and the store face `0/38 -> 38/38`.
 
-The stranger-facing truth this pins down: **the 1,000-transaction decode is one command, offline, and fails loudly.** What it does not prove is that an outside person has run it — and that is now **measured, not asserted** (`tools/measure-foreign-run.mjs` -> `research/foreign-run-2026-11-05.json`): verdict `not-distributed-not-consumed`, i.e. zero non-owner signals on every channel that was read — 0 non-owner stars/forks/issues/PRs on this repo, 0 non-owner comments on the two outbound threads (`step-finance-oss/step-ingestooor#1` and `jup-ag/rfq-webhook-toolkit#96`, both open), 0 foreign-authored threads containing this project's slug. The first external run therefore remains the open gate. The measurement has limits and names them: the broad mention sweep covers 92 of 93 results (GitHub's search index hides one result in every ordering — measured, not assumed), a registry `404` for the bare name `sememe` on npm/crates.io/PyPI means **no install channel is published yet**, never "nobody used it", and the code-index absence is only claimed for the indexed part of GitHub (the sweep's self-reference control passes). Reproduce with `npm test` (includes `test/stranger-decode.test.mjs`, which runs this tool against both fixtures and falsifies it three ways: tampered payload, missing store, and a mutation of the pass/fail logic). The funnel a stranger walks before that first run is measured separately (2026-11-05, `tools/measure-stranger-funnel.mjs` -> `research/stranger-funnel-2026-11-05.json`): a fresh GitHub clone ran both quickstart commands verbatim (1,089 and 6,337 payloads, all decoded byte-exactly, exit 0), the published tag `v0.3.0` installed into an empty app with no npm account, and its entry decoded 1,119/1,119 real payloads byte-exactly from `node_modules/sememe` — the harness (tools/test/research) does not travel into the install. The quickstart block itself is pinned by `test/quickstart-funnel.test.mjs`, which caught and fixed one defect on 2026-11-05: the documented output line was the pre-2026-11-04 schema (missing `rpcEncoding`, `chainParsedInstructions`, `missingBytes`) — a stranger comparing her terminal to the README saw two different products. The README now documents the line the tool actually prints, and a hand-edited documented line goes red.
+The stranger-facing truth this pins down: **the 1,000-transaction decode is one command, offline, and fails loudly.** What it does not prove is that an outside person has run it — and that is now **measured, not asserted** (`tools/measure-foreign-run.mjs` -> `research/foreign-run-2026-11-05.json`): verdict `not-distributed-not-consumed`, i.e. zero non-owner signals on every channel that was read — 0 non-owner stars/forks/issues/PRs on this repo, 0 non-owner comments on the two outbound threads (`step-finance-oss/step-ingestooor#1` and `jup-ag/rfq-webhook-toolkit#96`, both open), 0 foreign-authored threads containing this project's slug. The first external run therefore remains the open gate. The measurement has limits and names them: the broad mention sweep covers 92 of 93 results (GitHub's search index hides one result in every ordering — measured, not assumed), a registry `404` for the bare name `sememe` on npm/crates.io/PyPI meant **no install channel was published yet** at that time, never "nobody used it" — npm published the name on 2026-11-12 (crates.io/PyPI still have no `sememe`; both are aliasing checks, not consumption evidence), and the code-index absence is only claimed for the indexed part of GitHub (the sweep's self-reference control passes). Reproduce with `npm test` (includes `test/stranger-decode.test.mjs`, which runs this tool against both fixtures and falsifies it three ways: tampered payload, missing store, and a mutation of the pass/fail logic). The funnel a stranger walks before that first run is measured separately (2026-11-05, `tools/measure-stranger-funnel.mjs` -> `research/stranger-funnel-2026-11-05.json`): a fresh GitHub clone ran both quickstart commands verbatim (1,089 and 6,337 payloads, all decoded byte-exactly, exit 0), the published tag `v0.3.0` installed into an empty app with no npm account, and its entry decoded 1,119/1,119 real payloads byte-exactly from `node_modules/sememe` — the harness (tools/test/research) does not travel into the install. The quickstart block itself is pinned by `test/quickstart-funnel.test.mjs`, which caught and fixed one defect on 2026-11-05: the documented output line was the pre-2026-11-04 schema (missing `rpcEncoding`, `chainParsedInstructions`, `missingBytes`) — a stranger comparing her terminal to the README saw two different products. The README now documents the line the tool actually prints, and a hand-edited documented line goes red. Re-measured 2026-11-13 after the registry channel opened (`research/foreign-run-2026-11-12.json`): the registry check reads `npm: found` for the bare name while the verdict stays `not-distributed-not-consumed` — publish is not consumption, and the first external run remains the open gate.
 
 ## Your own transactions: raw RPC responses (the shape you already hold)
 
@@ -132,7 +132,7 @@ sememe is a local, content-addressed schema store with a verification contract:
 ## Install (as a consumer, not a contributor)
 
 ```bash
-npm install github:auroraxo/sememe#v0.4.22   # tagged release; no npm account needed
+npm install github:auroraxo/sememe#v0.4.24   # tagged release; no npm account needed
 ```
 
 ```js
@@ -151,14 +151,14 @@ The **library** refuses the same way: importing `sememe/pull` or `sememe/gap` wi
 **From an install (not a clone), the CLI is `npx sememe …`** — npm exec resolves the package's own `bin` from `node_modules`; the bare command `sememe` is not on your `PATH` after a plain `npm install`, and `node bin/sememe.mjs` works only inside a clone of the repository (both measured 2026-11-05 from a real tarball install). The consumer journey from the install, verbatim:
 
 ```bash
-npm install github:auroraxo/sememe#v0.4.22 @solana/web3.js   # acquisition needs the peer
+npm install github:auroraxo/sememe#v0.4.24 @solana/web3.js   # acquisition needs the peer
 npx sememe pull whirLbMiicVdio4qvUfM5KAg6Ct8VwpYzGff3uctyCc --store ./store
 npx sememe decode whirLbMiicVdio4qvUfM5KAg6Ct8VwpYzGff3uctyCc 2b04ed0b1ac91e62a40d0100000000000100000000000000af331ba8327fbb35b1c4feff00000000010001010000000601 --store ./store
 ```
 
 `./store` is the local content-addressed store the error `no sememe store at ./store: run "sememe pull" first` tells you to create — the `pull` above is that creation step; the vendored programs (System, ComputeBudget, SPL Token, Token-2022, Raydium AMM v4, SPL Associated Token Account) need no store at all: `npx sememe decode-native 11111111111111111111111111111111 <payload>` answers offline from the pinned upstream tables. If you ever point the decoder at a store directory that does not exist yet, the refusal names the fix; `npx sememe` is the form of that fix that runs where you are. Measured 2026-11-05 from the packed tarball of this tree: install (zero deps) → `npx sememe pull` (live mainnet) → `npx sememe decode` (byte-exact, live-pulled object byte-identical to the fixture store object `0b886e37…660f`).
 
-Publishing to the npm registry itself is deliberately not done: the files allowlist already ships none of this repository's tests, fixtures or qualification harness (pinned by `test/package.test.mjs`), and no registry name squatting is part of the plan. The git tag is the release artifact; `test/package.test.mjs` (the contract above), `tools/e2e-package-consumer.mjs` (a real install into an empty directory) and `test/install-surface.test.mjs` (the shipped README's install commands run verbatim from the packed tarball) keep it honest.
+Publishing to the npm registry changed on 2026-11-12: the `sememe` name is now live on registry.npmjs.org (first shipped as 0.4.21; the measured registry install of `sememe@0.4.22` into an empty app decoded the Whirlpool fixture payload `swap_v2`, `roundTripByteExact: true`). `npm install sememe` and `npm install github:auroraxo/sememe#v0.4.24` deliver the same product files from the same code: the files allowlist already ships none of this repository's tests, fixtures or qualification harness (pinned by `test/package.test.mjs`), so the git tag remains the release artifact — `test/package.test.mjs` (the contract above), `tools/e2e-package-consumer.mjs` (a real install into an empty directory) and `test/install-surface.test.mjs` (the shipped README's install commands run verbatim from the packed tarball) keep both channels honest.
 
 ## Working now: pin the answers (`sememe lock` + `sememe verify`, 2026-11-05)
 
@@ -271,7 +271,8 @@ freshness against the chain; `scope: "extra"` tells you *where* the damage
 is, not *who* wrote it; and the reported extra is an unpinned program, so a
 store can still gain a program the lock has never seen (by design — that is
 the minimums rule). No third party has run this; there are 0 external users,
-0 stars, and `npm publish` remains credentials-blocked. The published
+0 stars (`npm publish` was credentials-blocked until 2026-11-12, when the
+registry name shipped — see the Install section). The published
 `v0.4.10` tag keeps this defect (a tag is immutable); `v0.4.11` carries
 the fix.
 
@@ -2636,7 +2637,7 @@ the next release.
 
 This release carries the raw-LE wiring above to the install channel: the
 pinned tag now contains `src/rawle.mjs` and every wired boundary, so
-`npm install github:auroraxo/sememe#v0.4.22` degrades nobody (Whirlpool,
+the v0.4.22 install degrades nobody (Whirlpool,
 shank, name-only anchor controls pin unchanged) and answers the diabloarb
 dialect where v0.4.21 refused it by name.
 
@@ -2680,6 +2681,68 @@ Suite after this release: **954 tests / 950 pass / 4 named network skips /
 surface re-measured against that tag is clean (newest = latest = pinned,
 0 defects — `research/release-surface-2026-11-12b.json`).
 
+## v0.4.23 / v0.4.24: struct-internal absent fields decode under the evidence gate — and the registry stays truthful (2026-11-13)
+
+The absent-field policy (`absent: "report"`) only fired at TOP-LEVEL argument
+boundaries, so a payload that ends on the boundary of the LAST FIELD INSIDE a
+struct argument was refused under every policy. Measured on mainnet: Archer's
+legacy Swap form (tag `0f`, 19 bytes) omits `SwapParams.builderFeePpm`
+INSIDE `swapParams` and is chain-executed — witness `5Kpdai4oRG…`, slot
+468261978, `err: null`, instruction bytes byte-identical to the payload
+(`research/archer-legacy-swap-witness-2026-11-12.json`; the pinned IDL's own
+`SwapParams` docs describe the shorter form as supported and read as a 0 fee,
+with the program's own `success` log line). One of the 83 payloads in
+`research/archer-second-source-2026-11-12.json` hit exactly this and v0.4.22
+refused it with `truncated input: need 4 byte(s) at offset 19`.
+
+This release decodes it and re-encodes it byte-exactly: inside a named struct,
+under the same decode-only evidence gate (`ctx.__absentPolicy`), a boundary
+ending mid-struct makes the remaining fields ABSENT, named by their dotted path
+(`swapParams.builderFeePpm`), never invented; cuts INSIDE a field and boundary
+cuts inside vec/array elements still refuse; the strict default policy is
+untouched; `encodeInstructionData` accepts the dotted absent names (trailing
+run per struct). `verifiedShortForm` now matches short (sub-8-byte) shank
+discriminators by prefix — the rule the codec's instruction index already used
+— so the 1-byte Archer tag reaches the chain-verified short-form table. Pinned
+by `test/struct-absent-short-form.test.mjs` (10 tests: the falsification
+ladder is 6 red on the v0.4.22 tree, green here).
+
+The registry channel is live and carries this release with the tag: the
+foreign-run sweep measured `npm: found` for the bare name with the verdict
+still `not-distributed-not-consumed`
+(`research/foreign-run-2026-11-12.json`) — publish is not consumption, and
+the first external run stays the open gate.
+
+Install — the registry and the tag ship the same product files (`npm install
+sememe` resolves to 0.4.23, the one tag this README pins above):
+
+```bash
+npm install sememe   # registry: 0.4.23, zero runtime dependencies
+```
+
+Limits, stated plainly: the Archer interface still does not ship inside the
+store (no on-chain IDL; the Apache-2.0 first-party copy stays adopt-only and
+hash-gated — unchanged); enum- and vec-body boundary cuts still refuse until a
+chain witness names them (the rule stays evidence-gated; no speculative wire
+form is accepted); tags <= v0.4.22 keep the truncation refusal (a tag is
+immutable); one owner account, zero external users, no audit.
+
+Suite for this release: **964 tests / 960 pass / 4 named network skips /
+0 fail** (954 → 964: the 10 new pin tests). CI green on `main`
+(43332583023); the release surface re-measured after publishing is CLEAN —
+newest = latest = pinned, 0 defects (`research/release-surface-2026-11-13.json`),
+and the registry carries the release as `latest` (measured after propagation).
+
+v0.4.23 (published 2026-11-13 00:49 UTC) carried this release to both channels
+but its README held TWO install pins — the front page plus the historical
+v0.4.22 section line — and the journey contract
+(`test/base58-journey.test.mjs` and five siblings) requires exactly one:
+tag CI 43340061132 RED with `README must pin exactly one tag, found v0.4.23,
+v0.4.22` (394b37b is the fix). The v0.4.23 tag and its npm tarball are
+published and immutable, so they keep the two-pin README; **v0.4.24 is the
+corrected release** — same product bytes as v0.4.23 (no src/ change since
+3fa9627), one pin, journey suite green (27/27), registry `latest` = 0.4.24.
+
 ## The remaining 35 publish-nothing programs, classified against foreign sources (2026-11-04)
 
 With Lighthouse decoded under shank, exactly **35 programs (87 payloads)** remained

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sememe",
-  "version": "0.4.22",
+  "version": "0.4.24",
   "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

@@ -365,8 +365,14 @@ function decodeAt(type, cur, ctx, path, depth) {
       throw new CodecError(`vector length ${length} needs ${length * minimum} byte(s) but ${cur.remaining} remain`, path);
     }
     const out = [];
-    for (let index = 0; index < length; index++) {
-      out.push(decodeAt(type.vec, cur, ctx, `${path}[${index}]`, depth + 1));
+    const insideCollection = ctx.__insideCollection;
+    ctx.__insideCollection = true;
+    try {
+      for (let index = 0; index < length; index++) {
+        out.push(decodeAt(type.vec, cur, ctx, `${path}[${index}]`, depth + 1));
+      }
+    } finally {
+      ctx.__insideCollection = insideCollection;
     }
     return out;
   }
@@ -428,8 +434,40 @@ function decodeAt(type, cur, ctx, path, depth) {
       throw new CodecError('malformed struct field', path);
     }
     const out = {};
-    for (const field of fields) {
-      assign(out, field.name, decodeAt(field.type, cur, ctx, `${path}.${field.name}`, depth + 1), path);
+    for (const [index, field] of fields.entries()) {
+      // The payload ends exactly where this struct's next field would begin.
+      // Under the caller-risk 'report' policy (reached only through
+      // ctx.__absentPolicy — decodeInstructionData sets it, and nothing else
+      // in the codec opts in), the rest of THIS struct is ABSENT, not
+      // truncated: a field boundary is the only place a payload can end and
+      // still carry a complete value for what came before. The marker names
+      // the missing fields by their path RELATIVE TO THE ARGUMENT (e.g.
+      // builderFeePpm inside swapParams), so decodeInstructionData can report
+      // `swapParams.builderFeePpm` and tell a struct-internal absence from a
+      // missing top-level argument. Under the strict default this branch
+      // never engages and the field decode refuses as truncated.
+      if (ctx.__absentPolicy === 'report' && cur.remaining === 0) {
+        if (ctx.__insideCollection) {
+          // A struct inside a vec/array: the wire stopped inside a repeated
+          // element, and the element INDEX is not recoverable from the
+          // bytes. Naming an absence there would be a guess, so it refuses
+          // like a mid-field cut until a witness says what to call it.
+          throw new CodecError(
+            `truncated input: the payload ends inside a repeated struct field (${path})`,
+            path);
+        }
+        const missing = fields.slice(index).map((rest) => rest.name);
+        ctx.__absentCollected?.push(...missing.map((name) => [...(ctx.__absentTrail ?? []), name].join('.')));
+        out.__absentFields = missing;
+        return out;
+      }
+      const trail = ctx.__absentTrail;
+      trail?.push(field.name);
+      try {
+        assign(out, field.name, decodeAt(field.type, cur, ctx, `${path}.${field.name}`, depth + 1), path);
+      } finally {
+        trail?.pop();
+      }
     }
     return out;
   }
@@ -445,6 +483,10 @@ function decodeAt(type, cur, ctx, path, depth) {
     if (!shape) throw new CodecError(`malformed variant ${JSON.stringify(variant.name)}`, path);
     const out = { __kind: variant.name };
     if (shape.kind === 'unit') return out;
+    // Note: a payload cut inside an enum variant's fields refuses even under
+    // the absent:'report' policy — the struct-boundary absence rule covers
+    // struct arguments (the shape every measured witness used), not variant
+    // bodies. Widening it needs its own chain witness first.
     if (shape.kind === 'tuple') {
       out.fields = shape.fields.map((fieldType, position) =>
         decodeAt(fieldType, cur, ctx, `${path}.fields[${position}]`, depth + 1));
@@ -461,14 +503,46 @@ function decodeAt(type, cur, ctx, path, depth) {
 
 function decodeArray(inner, length, cur, ctx, path, depth) {
   const out = [];
-  for (let index = 0; index < length; index++) {
-    out.push(decodeAt(inner, cur, ctx, `${path}[${index}]`, depth + 1));
+  const insideCollection = ctx.__insideCollection;
+  ctx.__insideCollection = true;
+  try {
+    for (let index = 0; index < length; index++) {
+      out.push(decodeAt(inner, cur, ctx, `${path}[${index}]`, depth + 1));
+    }
+  } finally {
+    ctx.__insideCollection = insideCollection;
   }
   return out;
 }
 
 // --- encoder ----------------------------------------------------------------
 
+/**
+ * Struct fields of a type that an absent PATH may descend through. Only
+ * named structs qualify: a dotted absent name like swapParams.builderFeePpm
+ * describes where the wire stopped, and only a named struct's fields can
+ * name that place. Anything else (tuple struct, enum, array, primitive) is a
+ * refusal — inventing an absence inside a shape that cannot name its fields
+ * would be exactly the guesswork the policy exists to avoid.
+ */
+function structFieldsForAbsentPath(type, ctx, path) {
+  let current = type;
+  if (current && typeof current === 'object' && 'defined' in current) {
+    const name = typeof current.defined === 'string' ? current.defined : current.defined?.name;
+    const typedef = ctx.types.get(name);
+    if (!typedef) throw new CodecError(`absent path crosses unknown type ${JSON.stringify(name)}`, path);
+    current = typedef.type;
+  }
+  if (current && typeof current === 'object' && current.kind === 'type' && 'type' in current) {
+    current = current.type;
+  }
+  const fields = structShape(current);
+  if (!fields || !isNamedStructFields(fields)) {
+    throw new CodecError(`absent path crosses a type that is not a named struct`, path);
+  }
+  return fields;
+}
+
 function encodeAt(type, value, ctx, path, depth) {
   if (depth > MAX_DEPTH) throw new CodecError('type nesting too deep (recursive type?)', path);
 
@@ -562,8 +636,31 @@ function encodeAt(type, value, ctx, path, depth) {
     const expected = new Set(fields.map((field) => field.name));
     const unknown = Object.keys(value).filter((key) => !expected.has(key));
     if (unknown.length) throw new CodecError(`unexpected field(s): ${unknown.join(', ')}`, path);
+    // Struct-internal absent fields: encodeInstructionData resolves dotted
+    // absent names (swapParams.builderFeePpm) to the VALUE object that owns
+    // the field and records the omission on ctx. Same rule as the top level:
+    // within this struct only a trailing run may be omitted, every omitted
+    // name must be declared, and what remains must still carry a value —
+    // byte-exactness is the only evidence this encoder offers.
+    const skip = ctx.__absentFields?.get(value);
+    if (skip) {
+      const unknownSkip = [...skip].filter((name) => !expected.has(name));
+      if (unknownSkip.length) {
+        throw new CodecError(`unexpected absent field(s): ${unknownSkip.join(', ')}`, path);
+      }
+      let seenSkip = false;
+      for (const field of fields) {
+        if (skip.has(field.name)) { seenSkip = true; continue; }
+        if (seenSkip) {
+          throw new CodecError(
+            `field ${JSON.stringify(field.name)} follows an absent field — only a trailing run may be omitted`,
+            path);
+        }
+      }
+    }
     const parts = [];
     for (const field of fields) {
+      if (skip?.has(field.name)) continue;
       if (!(field.name in value)) throw new CodecError(`missing field ${JSON.stringify(field.name)}`, path);
       parts.push(encodeAt(field.type, value[field.name], ctx, `${path}.${field.name}`, depth + 1));
     }
@@ -986,6 +1083,14 @@ export function decodeInstructionData(idl, data, { allowTrailing, trailing, abse
   const args = {};
   const absentArgs = [];
   const declaredArgs = instruction.args ?? [];
+  // 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
+  // produces that marker under ctx.__absentPolicy === 'report' — every other
+  // entry into the codec leaves these inert.
+  ctx.__absentPolicy = absentPolicy;
+  ctx.__absentCollected = absentArgs;
+  ctx.__absentTrail = [];
   for (const [position, argument] of declaredArgs.entries()) {
     if (!argument || typeof argument.name !== 'string' || !('type' in argument)) {
       throw new CodecError(`instruction ${instruction.name} has a malformed argument`, null);
@@ -1000,8 +1105,23 @@ 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.
-    assign(args, argument.name, decodeAt(argument.type, cursor, ctx, `${instruction.name}.${argument.name}`, 0), instruction.name);
+    ctx.__absentTrail.push(argument.name);
+    let value;
+    try {
+      value = decodeAt(argument.type, cursor, ctx, `${instruction.name}.${argument.name}`, 0);
+    } finally {
+      ctx.__absentTrail.pop();
+    }
+    // A struct the wire stopped inside carries the `__absentFields` marker;
+    // peel it off so the decoded args never show codec-internal keys. The
+    // dotted names were already collected into absentArgs. The strip is
+    // recursive: a struct nested in a struct carries its own marker.
+    stripAbsentMarkers(value);
+    assign(args, argument.name, value, instruction.name);
   }
+  delete ctx.__absentPolicy;
+  delete ctx.__absentCollected;
+  delete ctx.__absentTrail;
   const trailingCount = cursor.remaining;
   const trailingHex = trailingCount > 0
     ? Buffer.from(data.subarray(cursor.offset)).toString('hex')
@@ -1027,6 +1147,26 @@ export function decodeInstructionData(idl, data, { allowTrailing, trailing, abse
   };
 }
 
+/**
+ * Remove the codec-internal `__absentFields` markers from a decoded value.
+ *
+ * The marker is how a struct tells the instruction level "the wire ended on
+ * my field boundary, and THESE fields are the ones it did not carry". It is
+ * bookkeeping, not data: a consumer must never see it inside the decoded
+ * args. Recursive, because a struct nested in a struct carries its own
+ * marker.
+ */
+function stripAbsentMarkers(value) {
+  if (!value || typeof value !== 'object') return value;
+  if (Array.isArray(value)) {
+    for (const item of value) stripAbsentMarkers(item);
+    return value;
+  }
+  delete value.__absentFields;
+  for (const key of Object.keys(value)) stripAbsentMarkers(value[key]);
+  return value;
+}
+
 /**
  * Encode one instruction payload (discriminator + args) using the IDL.
  *
@@ -1058,6 +1198,10 @@ export function encodeInstructionData(idl, name, args, { absent } = {}) {
   const known = new Set(declared.map((argument) => argument.name));
   const absentSet = new Set(Array.isArray(absent) ? absent : []);
   for (const fieldName of absentSet) {
+    // A dotted name names a field INSIDE a declared struct argument; it is
+    // validated against that struct further down, where the struct's own
+    // field list is known.
+    if (fieldName.includes('.')) continue;
     if (!known.has(fieldName)) {
       throw new CodecError(`unexpected argument(s) for ${instruction.name}: ${fieldName}`, instruction.name);
     }
@@ -1079,13 +1223,68 @@ export function encodeInstructionData(idl, name, args, { absent } = {}) {
   if (unknown.length) {
     throw new CodecError(`unexpected argument(s) for ${instruction.name}: ${unknown.join(', ')}`, null);
   }
-  const parts = [bytes];
-  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));
+  // Struct-internal absent fields: an absent name with a dot names a field
+  // INSIDE a declared struct argument (swapParams.builderFeePpm). Resolve
+  // each dotted path to the value object that owns the field, and record the
+  // omission on the encode context so encodeAt's struct branch skips it —
+  // with the same rules the top level enforces: only a trailing run of that
+  // struct's fields may be omitted, and the value must not carry the field.
+  // The encoder is the inverse of the decoder's struct-boundary marker: the
+  // dotted absent list is exactly what the decode reported.
+  const nestedAbsent = new Map(); // value object -> Set(struct-relative field names)
+  for (const fieldName of absentSet) {
+    if (!fieldName.includes('.')) continue;
+    const parts = fieldName.split('.');
+    if (!known.has(parts[0])) {
+      throw new CodecError(`unexpected argument(s) for ${instruction.name}: ${parts[0]}`, instruction.name);
+    }
+    const ownerName = parts[0];
+    const ownerType = declared.find((argument) => argument.name === ownerName)?.type;
+    // Walk the INTERMEDIATE segments through named structs; the LAST segment
+    // is the omitted field itself, validated against the struct it lives in.
+    let containerType = ownerType;
+    let containerValue = args[ownerName];
+    for (const part of parts.slice(1, -1)) {
+      const fields = structFieldsForAbsentPath(containerType, ctx, fieldName);
+      const nextField = fields.find((field) => field.name === part);
+      if (!nextField) {
+        throw new CodecError(`unexpected absent field(s) for ${instruction.name}: ${fieldName}`, instruction.name);
+      }
+      containerType = nextField.type;
+      if (!containerValue || typeof containerValue !== 'object' || !(part in containerValue)) {
+        throw new CodecError(
+          `absent path ${JSON.stringify(fieldName)} crosses a field the value does not carry`, instruction.name);
+      }
+      containerValue = containerValue[part];
+    }
+    const fields = structFieldsForAbsentPath(containerType, ctx, fieldName);
+    const leaf = parts[parts.length - 1];
+    if (!fields.some((field) => field.name === leaf)) {
+      throw new CodecError(`unexpected absent field(s) for ${instruction.name}: ${fieldName}`, instruction.name);
+    }
+    if (!containerValue || typeof containerValue !== 'object' || Array.isArray(containerValue)) {
+      throw new CodecError(`expected a struct object for ${JSON.stringify(fieldName)}, got ${describe(containerValue)}`, instruction.name);
+    }
+    if (leaf in containerValue) {
+      throw new CodecError(`argument ${JSON.stringify(fieldName)} is both absent and present`, instruction.name);
+    }
+    if (!nestedAbsent.has(containerValue)) nestedAbsent.set(containerValue, new Set());
+    nestedAbsent.get(containerValue).add(leaf);
+  }
+  if (nestedAbsent.size) {
+    ctx.__absentFields = nestedAbsent;
+  }
+  try {
+    const parts = [bytes];
+    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));
+    }
+    return Buffer.concat(parts);
+  } finally {
+    delete ctx.__absentFields;
   }
-  return Buffer.concat(parts);
 }
 
 /**

package/src/short-forms.mjs

@@ -114,23 +114,51 @@ const VERIFIED_SHORT_FORMS = [
     absent: ['is_cashback_enabled', 'creator_fee_bps', 'is_holder_reward'],
     witnesses: 1,
   },
+  // --- 2026-11-12: the first short form whose missing field sits INSIDE a
+  // struct argument (research/archer-legacy-swap-witness-2026-11-12.json).
+  // Every form above ends at a TOP-LEVEL argument boundary; this one ends on
+  // the boundary of the LAST field inside `swapParams`, so the absent name
+  // is dotted (`swapParams.builderFeePpm`) and the codec's struct-boundary
+  // rule is what makes it decodable. Evidence: a Swap executed at slot
+  // 468261978 with err:null whose instruction bytes are byte-identical to
+  // the 19-byte payload (checked against the RPC witness twice: `json`
+  // encoding base58 -> 0f430000000000000000000000000000000100), the Archer
+  // CPI's own `success` line, and the pinned IDL's SwapParams docs which
+  // describe the shorter legacy payload as a supported form read as a 0 fee.
+  {
+    program: 'Archer8kgiavM61GyusMzaaS2ft5sALtNsD1HxkUPMhy',
+    discriminator: '0f',
+    bytes: 19,
+    instruction: 'Swap',
+    absent: ['swapParams.builderFeePpm'],
+    witnesses: 1,
+    missingFieldInsideStruct: true,
+  },
 ];
 
 export const SHORT_FORM_SOURCE =
   'research/short-form-wire-forms-2026-11-03.json + research/short-form-wire-forms-2026-11-04.json '
-  + '(chain witnesses: err:null, byte-identical payload, matching program log line)';
+  + '(chain witnesses: err:null, byte-identical payload, matching program log line) '
+  + 'research/archer-legacy-swap-witness-2026-11-12.json (chain witness: err:null, byte-identical payload)';
 
 export const VERIFIED = VERIFIED_SHORT_FORMS;
 export { VERIFIED_SHORT_FORMS };
 
 /** Look up a payload in the chain-verified short-form table; null when absent. */
 export function verifiedShortForm(program, data) {
+  // Struct-internal short forms may carry a discriminator SHORTER than 8
+  // bytes (measured: Archer's shank tag, 1 byte). The old `data.length < 8`
+  // guard refused any lookup that could not yield such a match: a 19-byte
+  // payload with a 1-byte tag reaches the table fine once the prefix is
+  // clipped to min(8, len) — exactly the rule the codec's instruction index
+  // already uses for short stored discriminators.
   if (!program || !(data instanceof Uint8Array)) return null;
-  if (data.length < 8) return null;
-  const discriminator = Buffer.from(data.subarray(0, 8)).toString('hex');
+  if (data.length === 0) return null;
+  const prefixLength = Math.min(8, data.length);
+  const discriminator = Buffer.from(data.subarray(0, prefixLength)).toString('hex');
   return VERIFIED_SHORT_FORMS.find((entry) =>
     entry.program === program
-    && entry.discriminator === discriminator
+    && discriminator.startsWith(entry.discriminator)
     && entry.bytes === data.length) ?? null;
 }