[lorisleiva]

This PR adds getNodeCodec, which decodes bytes into a tree of decoded nodes rather than plain values. Each decoded node keeps the path of the node that decoded it, so consumers such as explorers and the upcoming display code can read values from their types rather than guess them from JavaScript shapes.

const decoded = getNodeCodec([root, program, counterAccount]).decode(bytes);
decoded.value; // { authority: '9BbW…ftkT', count: 42n }
assertIsDecodedNode(decoded.data, 'structTypeNode');
decoded.data.fields[1].type; // { path: [root, program, counterAccount, struct, countField, u64], value: 42n, preOffset: 32, postOffset: 40 }

• Decoded nodes: each one has a path, a value in the format of getNodeValueCodec, and the absolute cursor positions before and after reading it (preOffset and postOffset, transforms included, as in Kit's offset codecs). Children are named after their node's attributes: data, type, fields, variant, item, items and entries. Map keys keep their decoded values, for example 7n.
• Links are transparent: a linked type decodes as its definition, and that definition's path is the one reported. This works across programs and for recursive types. A link's own transforms are included in the cursor positions of the type it decodes as.
• Types: there is one explicit Decoded…Node type per node kind, plus DecodedNode<TNode>, GetDecodedNodeFromKind, DecodedNodeCodec, and the isDecodedNode / assertIsDecodedNode guards.
• One source of truth: getNodeValueCodec and its visitor are now derived from getNodeCodecVisitor, and their behaviour is unchanged. On mpl-token-metadata's create data, value decoding goes from 12 to 22 µs and value encoding from 16 to 20 µs. That cost was accepted to avoid maintaining two codec paths.

[lorisleiva]

• [2.x] Format decoded nodes into formatted node trees #1218
• [2.x] Add formatters for booleans, bytes, enums and public keys #1217
• [2.x] Return decoded nodes from dynamic parsers #1216
• [2.x] Add formatters for decoded nodes #1215
• [2.x] Decode Codama nodes into decoded node trees #1214 👈 (View in Graphite)
• [2.x] Report defined types without a finite value in validators #1213
• [2.x] Support recursive defined types in dynamic codecs #1212
• [2.x] Detect cyclic defined types #1211
• [2.x] Port the dynamic client to Codama v2 #1209
• [2.x] Reject duplicate set items in dynamic codecs #1208
• [2.x] Upgrade v1 instructions, programs and roots to v2 #1207
• [2.x] Keep the cause of validation items and drop their node #1206
• [2.x] Make NodePath non-distributive over node unions #1205
• [2.x] Use the published v1 node types in @codama/upgrade #1201
• [2.x] Add v1 to v2 upgrade converters for types and values #1200
• [2.x] Adapt to spec 2.0.0-rc.1 #1196
• main

This stack of pull requests is managed by Graphite. Learn more about stacking.

[lorisleiva]

@trevor-cortex

[trevor-cortex]

Summary

Adds getNodeCodec, a codec that decodes bytes into a DecodedNode tree (path + value + absolute byte range + named children) and re-derives getNodeValueCodec / getNodeValueCodecVisitor from it via mapVisitor(..., getValueCodec). The visitor now builds every node as an "unranged" decoded node through getLeafCodec / getCompositeCodec, and the intercept layer stamps offset/size on top with withRange. Byte-slicing transforms (fixedSize, sizePrefix, sentinel) go through withSlicedBytes, which maintains a baseOffsets stack so inner ranges stay absolute even when Kit hands the inner codec a copy of the bytes. Links are transparent (decode as the linked definition's type, reported at the definition's path), recursive types work via the existing lazy codec, and decoded.ts adds one Decoded…Node type per kind plus isDecodedNode / assertIsDecodedNode.

The design is sound and the implementation is careful. I verified the withSlicedBytes slice-start logic against Kit's fixDecoderSize / addDecoderSizePrefix / addDecoderSentinel (including the fixBytes pad/truncate path and the "no slice when offset is 0 and length matches" shortcut, both handled by the bytes !== outer.bytes check), and the value-codec behaviour matches the previous implementation line by line (tuple missing items, option undefined → None, struct undefined → {}, map keys as strings, enum string shorthand). Nested size prefixes, recursive types, cross-program links and link transforms are all covered by tests.

Things to watch

• Changeset. @codama/dynamic-codecs is public and this adds new API, but I don't see a .changeset/*.md in the changed files. CONTRIBUTING asks for one per user-facing change (npx changeset add --empty). If it lives elsewhere in the stack, ignore this.
• Byte ranges under non-padded offset transforms (inline on withRange). offset/size are the cursor span, which diverges from the "first byte read / bytes read" wording in DecodedNodeBase for absolute/relative/preOffset strategies and can produce size: 0 or a negative size. Only the padded strategy is tested.
• inProgress.codec is the unranged composite (inline in visitDefinedType). Harmless today because the recursive link path only ever reads .type, but it's a latent trap.
• NodeCodec isn't exported although it's the return type of the public getNodeCodecVisitor (inline).
• Link transforms are attributed to the linked type's node. it includes the transforms of links in the byte range of their type makes this deliberate, and it's consistent with "transforms included", but note the consumer-facing asymmetry: the reported path ends at the definition's type, which doesn't carry the link's transforms, so an explorer can't explain the extra bytes from the path alone. Might be worth a sentence in the README's "Links are transparent" paragraph.

Notes for subsequent reviewers

• baseOffsets is shared by every codec produced by one visitor instance. That's fine because reads are synchronous and nested (push/pop in try/finally), but a codec from visitor A nested inside a codec from visitor B wouldn't see B's base offset. Not a realistic path through the public API.
• Kit's sentinel-count array strategy compares at item boundaries without slicing, so sentinel-counted collections don't need withSlicedBytes. The existing test only exercises one at offset 0; a quick case inside a struct would make that explicit.
• The TupleTypeNode test change isn't a behaviour change: a 2-item tuple encoded from [42] already failed in the string codec with actualType: 'undefined'; the test just pins it now that getCompositeCodec passes input?.value through.

[changeset-bot]

⚠️ No Changeset found

Latest commit: 123c3f8

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[trevor-cortex]

Re-review

Re-fetched everything. All the points from my first pass are addressed:

• Cursor positions. offset/size became preOffset/postOffset, documented as cursor positions in Kit's vocabulary rather than "bytes read", which removes the ambiguity under non-padded offset transforms. The three new tests (relative pre-offset moving back, absolute post-offset rewinding, absolute pre-offset on a composite whose children land elsewhere) pin the semantics, and postOffset < preOffset is now a documented possibility rather than a surprise.
• inProgress.codec is now withRange(codec) with a comment explaining why, so the lazy recursive codec hands back ranged DecodedDefinedTypeNodes. The outer intercept withRange still wraps the returned unranged codec, so there's no double application on the direct path and the recursive path gets exactly one. I checked the linked-list test's expected offsets against this and they're consistent.
• DecodedNodeCodec is exported from decoded.ts and used as the visitor's return type.
• README now states that a link's transforms are included in the cursor positions of the type it decodes as, even though that type's node doesn't carry them.
• Sentinel-counted array inside a struct is covered by it keeps cursor positions absolute within arrays ending with a sentinel.

Nothing new to flag in the updated codecs.ts; the Unranged<T> distributive Omit and the satisfies checks per visitor are a nice way to keep each decoded node shape honest without widening the public types.

The only item still outstanding is the changeset: the file list is unchanged (9 files, no .changeset/*.md). Since @codama/dynamic-codecs is public and this adds getNodeCodec, getNodeCodecVisitor and the Decoded… types, it'll need one before release unless it's being handled elsewhere in the stack. Not blocking the approval.