cesr-ts 0.2.2 → 0.3.0

package/esm/src/parser/group-dispatch.js

@@ -1,41 +1,350 @@
 import { parseCounter } from "../primitives/counter.js";
 import { parseMatter } from "../primitives/matter.js";
 import { parseIndexer } from "../primitives/indexer.js";
-import { DeserializeError, GroupSizeError, ShortageError, UnknownCodeError, } from "../core/errors.js";
+import { GroupSizeError, ShortageError, UnknownCodeError, } from "../core/errors.js";
 import { CtrDexV1, CtrDexV2 } from "../tables/counter-codex.js";
-const SIGER_LIST_CODES_BY_VERSION = {
-    1: new Set([
-        CtrDexV1.ControllerIdxSigs,
-        CtrDexV1.WitnessIdxSigs,
-    ]),
-    2: new Set([
-        CtrDexV2.ControllerIdxSigs,
-        CtrDexV2.BigControllerIdxSigs,
-        CtrDexV2.WitnessIdxSigs,
-        CtrDexV2.BigWitnessIdxSigs,
-    ]),
-};
-const WRAPPER_GROUP_CODES_V1 = new Set([
-    CtrDexV1.AttachmentGroup,
-    CtrDexV1.BigAttachmentGroup,
-    CtrDexV1.BodyWithAttachmentGroup,
-    CtrDexV1.BigBodyWithAttachmentGroup,
-]);
-const WRAPPER_GROUP_CODES_V2 = new Set([
-    CtrDexV2.AttachmentGroup,
-    CtrDexV2.BigAttachmentGroup,
-    CtrDexV2.BodyWithAttachmentGroup,
-    CtrDexV2.BigBodyWithAttachmentGroup,
-]);
+import { resolveVersionedRegistryValue, } from "../tables/counter-version-registry.js";
+import { b64ToInt, intToB64 } from "../core/bytes.js";
+import { composeRecoveryDiagnosticObserver, } from "../core/recovery-diagnostics.js";
+import { createAttachmentVersionFallbackPolicy, } from "./attachment-fallback-policy.js";
+export { createAttachmentVersionFallbackPolicy, } from "./attachment-fallback-policy.js";
+function qb64Item(qb64, opaque = false) {
+    return { kind: "qb64", qb64, opaque };
+}
+function qb2Item(qb2, opaque = false) {
+    return { kind: "qb2", qb2, opaque };
+}
+function tupleItem(items) {
+    return { kind: "tuple", items };
+}
+function nestedGroupItem(code, name, count) {
+    return { kind: "group", code, name, count };
+}
+/** Normalize unknown throwables to an `Error` for diagnostic emission. */
+function asError(error) {
+    return error instanceof Error ? error : new Error(String(error));
+}
+/**
+ * Canonical attachment dispatch specification (authoring form).
+ *
+ * This is the single source of truth for:
+ * - code -> parser routing
+ * - semantic shape classification
+ * - wrapper-group recursion eligibility
+ * - nested siger-list allowance
+ *
+ * Maintainer workflow:
+ * when adding/removing a counter route, edit this constant only, then rely on
+ * descriptor expansion + generated dispatch maps below.
+ */
+export const ATTACHMENT_DISPATCH_SPEC = [
+    {
+        parserKind: "genusVersion",
+        semanticShape: "genusVersionMarker",
+        codesByVersion: {
+            1: [CtrDexV1.KERIACDCGenusVersion],
+            2: [CtrDexV2.KERIACDCGenusVersion],
+        },
+    },
+    {
+        parserKind: "quadlet",
+        semanticShape: "countedGroupPayload",
+        codesByVersion: {
+            1: [
+                CtrDexV1.GenericGroup,
+                CtrDexV1.BigGenericGroup,
+                CtrDexV1.NonNativeBodyGroup,
+                CtrDexV1.BigNonNativeBodyGroup,
+                CtrDexV1.ESSRPayloadGroup,
+                CtrDexV1.BigESSRPayloadGroup,
+                CtrDexV1.PathedMaterialCouples,
+                CtrDexV1.BigPathedMaterialCouples,
+            ],
+            2: [
+                CtrDexV2.GenericGroup,
+                CtrDexV2.BigGenericGroup,
+                CtrDexV2.NonNativeBodyGroup,
+                CtrDexV2.BigNonNativeBodyGroup,
+                CtrDexV2.ESSRPayloadGroup,
+                CtrDexV2.BigESSRPayloadGroup,
+                CtrDexV2.PathedMaterialCouples,
+                CtrDexV2.BigPathedMaterialCouples,
+                CtrDexV2.DatagramSegmentGroup,
+                CtrDexV2.BigDatagramSegmentGroup,
+                CtrDexV2.ESSRWrapperGroup,
+                CtrDexV2.BigESSRWrapperGroup,
+                CtrDexV2.FixBodyGroup,
+                CtrDexV2.BigFixBodyGroup,
+                CtrDexV2.MapBodyGroup,
+                CtrDexV2.BigMapBodyGroup,
+                CtrDexV2.GenericMapGroup,
+                CtrDexV2.BigGenericMapGroup,
+                CtrDexV2.GenericListGroup,
+                CtrDexV2.BigGenericListGroup,
+            ],
+        },
+    },
+    {
+        parserKind: "quadlet",
+        semanticShape: "wrapperGroupPayload",
+        wrapperGroup: true,
+        codesByVersion: {
+            1: [
+                CtrDexV1.AttachmentGroup,
+                CtrDexV1.BigAttachmentGroup,
+                CtrDexV1.BodyWithAttachmentGroup,
+                CtrDexV1.BigBodyWithAttachmentGroup,
+            ],
+            2: [
+                CtrDexV2.AttachmentGroup,
+                CtrDexV2.BigAttachmentGroup,
+                CtrDexV2.BodyWithAttachmentGroup,
+                CtrDexV2.BigBodyWithAttachmentGroup,
+            ],
+        },
+    },
+    {
+        parserKind: "repeatTuple",
+        semanticShape: "primitiveTuples",
+        tupleKinds: ["indexer"],
+        allowsSigerList: true,
+        codesByVersion: {
+            1: [
+                CtrDexV1.ControllerIdxSigs,
+                CtrDexV1.WitnessIdxSigs,
+            ],
+            2: [
+                CtrDexV2.ControllerIdxSigs,
+                CtrDexV2.BigControllerIdxSigs,
+                CtrDexV2.WitnessIdxSigs,
+                CtrDexV2.BigWitnessIdxSigs,
+            ],
+        },
+    },
+    {
+        parserKind: "repeatTuple",
+        semanticShape: "primitiveTuples",
+        tupleKinds: ["matter", "matter"],
+        codesByVersion: {
+            1: [
+                CtrDexV1.NonTransReceiptCouples,
+                CtrDexV1.FirstSeenReplayCouples,
+                CtrDexV1.SealSourceCouples,
+            ],
+            2: [
+                CtrDexV2.NonTransReceiptCouples,
+                CtrDexV2.BigNonTransReceiptCouples,
+                CtrDexV2.FirstSeenReplayCouples,
+                CtrDexV2.BigFirstSeenReplayCouples,
+                CtrDexV2.SealSourceCouples,
+                CtrDexV2.BigSealSourceCouples,
+                CtrDexV2.BackerRegistrarSealCouples,
+                CtrDexV2.BigBackerRegistrarSealCouples,
+                CtrDexV2.TypedDigestSealCouples,
+                CtrDexV2.BigTypedDigestSealCouples,
+            ],
+        },
+    },
+    {
+        parserKind: "repeatTuple",
+        semanticShape: "primitiveTuples",
+        tupleKinds: ["matter", "matter", "matter", "indexer"],
+        codesByVersion: {
+            1: [
+                CtrDexV1.TransReceiptQuadruples,
+            ],
+            2: [
+                CtrDexV2.TransReceiptQuadruples,
+                CtrDexV2.BigTransReceiptQuadruples,
+            ],
+        },
+    },
+    {
+        parserKind: "repeatTuple",
+        semanticShape: "primitiveTuples",
+        tupleKinds: ["matter", "matter", "matter"],
+        codesByVersion: {
+            1: [
+                CtrDexV1.SealSourceTriples,
+            ],
+            2: [
+                CtrDexV2.SealSourceTriples,
+                CtrDexV2.BigSealSourceTriples,
+            ],
+        },
+    },
+    {
+        parserKind: "repeatTuple",
+        semanticShape: "primitiveTuples",
+        tupleKinds: ["matter"],
+        codesByVersion: {
+            2: [
+                CtrDexV2.SealSourceLastSingles,
+                CtrDexV2.BigSealSourceLastSingles,
+                CtrDexV2.DigestSealSingles,
+                CtrDexV2.BigDigestSealSingles,
+                CtrDexV2.MerkleRootSealSingles,
+                CtrDexV2.BigMerkleRootSealSingles,
+            ],
+        },
+    },
+    {
+        parserKind: "transIdxSigGroups",
+        semanticShape: "signatureGroupTuples",
+        codesByVersion: {
+            1: [
+                CtrDexV1.TransIdxSigGroups,
+            ],
+            2: [
+                CtrDexV2.TransIdxSigGroups,
+                CtrDexV2.BigTransIdxSigGroups,
+            ],
+        },
+    },
+    {
+        parserKind: "transLastIdxSigGroups",
+        semanticShape: "lastSignatureGroupTuples",
+        codesByVersion: {
+            1: [
+                CtrDexV1.TransLastIdxSigGroups,
+            ],
+            2: [
+                CtrDexV2.TransLastIdxSigGroups,
+                CtrDexV2.BigTransLastIdxSigGroups,
+            ],
+        },
+    },
+    {
+        parserKind: "sadPathSig",
+        semanticShape: "sadPathSignatures",
+        codesByVersion: {
+            1: [CtrDexV1.SadPathSig],
+        },
+    },
+    {
+        parserKind: "sadPathSigGroup",
+        semanticShape: "sadPathSignatureGroup",
+        codesByVersion: {
+            1: [CtrDexV1.SadPathSigGroup],
+        },
+    },
+    {
+        parserKind: "repeatTuple",
+        semanticShape: "primitiveTuples",
+        tupleKinds: ["matter", "matter", "matter", "matter"],
+        codesByVersion: {
+            2: [
+                CtrDexV2.BlindedStateQuadruples,
+                CtrDexV2.BigBlindedStateQuadruples,
+                CtrDexV2.TypedMediaQuadruples,
+                CtrDexV2.BigTypedMediaQuadruples,
+            ],
+        },
+    },
+    {
+        parserKind: "repeatTuple",
+        semanticShape: "primitiveTuples",
+        tupleKinds: [
+            "matter",
+            "matter",
+            "matter",
+            "matter",
+            "matter",
+            "matter",
+        ],
+        codesByVersion: {
+            2: [
+                CtrDexV2.BoundStateSextuples,
+                CtrDexV2.BigBoundStateSextuples,
+            ],
+        },
+    },
+];
+/**
+ * Expand grouped spec rows into per-version descriptors.
+ *
+ * Why:
+ * downstream builders operate on `(version, code)` units, while spec authoring
+ * stays concise by grouping shared semantics across major versions.
+ */
+function expandDispatchSpec(spec) {
+    const descriptors = [];
+    for (const family of spec) {
+        for (const version of [1, 2]) {
+            for (const code of family.codesByVersion[version] ?? []) {
+                descriptors.push({
+                    version,
+                    code,
+                    parserKind: family.parserKind,
+                    semanticShape: family.semanticShape,
+                    tupleKinds: family.tupleKinds,
+                    wrapperGroup: family.wrapperGroup === true,
+                    allowsSigerList: family.allowsSigerList === true,
+                });
+            }
+        }
+    }
+    return descriptors;
+}
+/**
+ * Build a version-indexed code-set projection from descriptors.
+ *
+ * Used for secondary routing metadata (wrapper recursion/siger-list allowance)
+ * so those sets cannot drift from the canonical dispatch spec.
+ */
+function buildCodeSetByVersion(descriptors, predicate) {
+    const byVersion = {
+        1: new Set(),
+        2: new Set(),
+    };
+    for (const descriptor of descriptors) {
+        if (predicate(descriptor)) {
+            byVersion[descriptor.version].add(descriptor.code);
+        }
+    }
+    return byVersion;
+}
+/**
+ * Normalized per-code dispatch descriptors used by all derived routing tables.
+ *
+ * Invariant:
+ * this array is generated once at module load from `ATTACHMENT_DISPATCH_SPEC`
+ * and should not be hand-edited.
+ */
+const ATTACHMENT_DISPATCH_DESCRIPTORS = expandDispatchSpec(ATTACHMENT_DISPATCH_SPEC);
+/** Siger-list counter codes by major version (for nested trans sig group parsing). */
+const SIGER_LIST_CODES_BY_MAJOR = buildCodeSetByVersion(ATTACHMENT_DISPATCH_DESCRIPTORS, (descriptor) => descriptor.allowsSigerList);
+/** Wrapper counters by major version whose payloads recurse as nested groups. */
+const WRAPPER_GROUP_CODES_BY_MAJOR = buildCodeSetByVersion(ATTACHMENT_DISPATCH_DESCRIPTORS, (descriptor) => descriptor.wrapperGroup);
+const WRAPPER_GROUP_CODES_V1 = WRAPPER_GROUP_CODES_BY_MAJOR[1];
+const WRAPPER_GROUP_CODES_V2 = WRAPPER_GROUP_CODES_BY_MAJOR[2];
+/** Universal genus-version counter code (v1/v2 compatible encoding semantics). */
+const GENUS_VERSION_CODE = CtrDexV2.KERIACDCGenusVersion;
+/** Domain-sensitive primitive size (qb64 vs qb2). */
 function primitiveSize(primitive, domain) {
     return domain === "bny" ? primitive.fullSizeB2 : primitive.fullSize;
 }
+/** Alias for readability at counter header consumption callsites. */
 function counterHeaderSize(counter, domain) {
     return primitiveSize(counter, domain);
 }
+/** Counter count unit size by domain: quadlets in text, triplets in binary. */
 function quadletUnitSize(domain) {
     return domain === "bny" ? 3 : 4;
 }
+/** Decode a genus-version counter payload into major/minor `Versionage`. */
+function decodeVersionCounter(counter) {
+    const triplet = counter.qb64.length >= 3
+        ? counter.qb64.slice(-3)
+        : intToB64(counter.count, 3);
+    const majorRaw = b64ToInt(triplet[0] ?? "A");
+    const minorRaw = b64ToInt(triplet[1] ?? "A");
+    return {
+        major: majorRaw === 1 ? 1 : 2,
+        minor: minorRaw,
+    };
+}
+/** Parse a fixed primitive tuple shape and return qb64 strings in source order. */
 function parseTuple(input, kinds, domain) {
     const items = [];
     let offset = 0;
@@ -43,24 +352,38 @@ function parseTuple(input, kinds, domain) {
         const part = kind === "indexer"
             ? parseIndexer(input.slice(offset), domain)
             : parseMatter(input.slice(offset), domain);
-        items.push(part.qb64);
+        items.push(qb64Item(part.qb64));
         offset += primitiveSize(part, domain);
     }
     return { items, consumed: offset };
 }
+/** Parse `count` tuple repetitions with stable ordering and exact byte accounting. */
 function parseRepeated(input, count, kinds, domain) {
     const items = [];
     let offset = 0;
     for (let i = 0; i < count; i++) {
         const tuple = parseTuple(input.slice(offset), kinds, domain);
-        items.push(tuple.items);
+        items.push(tupleItem(tuple.items));
         offset += tuple.consumed;
     }
     return { items, consumed: offset };
 }
+/** Split opaque counted payload into domain units (quadlets for text, triplets for binary). */
+function splitOpaqueUnits(payload, domain, expectedCount, opaque = false) {
+    if (domain === "bny") {
+        const count = expectedCount ?? Math.floor(payload.length / 3);
+        return Array.from({ length: count }, (_v, i) => qb2Item(payload.slice(i * 3, i * 3 + 3), opaque));
+    }
+    const text = String.fromCharCode(...payload);
+    if (expectedCount !== undefined) {
+        return Array.from({ length: expectedCount }, (_v, i) => qb64Item(text.slice(i * 4, i * 4 + 4), opaque));
+    }
+    return (text.match(/.{1,4}/g) ?? []).map((token) => qb64Item(token, opaque));
+}
+/** Parse nested siger-list group headed by a version-appropriate siger counter. */
 function parseSigerList(input, version, domain) {
     const counter = parseCounter(input, version, domain);
-    const allowed = SIGER_LIST_CODES_BY_VERSION[version.major];
+    const allowed = resolveVersionedRegistryValue(SIGER_LIST_CODES_BY_VERSION, version, "siger-list code set").value;
     if (!allowed.has(counter.code)) {
         throw new UnknownCodeError(`Expected siger-list counter but got ${counter.code}`);
     }
@@ -68,11 +391,20 @@ function parseSigerList(input, version, domain) {
     let offset = counterHeaderSize(counter, domain);
     for (let i = 0; i < counter.count; i++) {
         const part = parseIndexer(input.slice(offset), domain);
-        items.push(part.qb64);
+        items.push(qb64Item(part.qb64));
         offset += primitiveSize(part, domain);
     }
     return { items, consumed: offset };
 }
+/**
+ * Parse quadlet/triplet-counted groups.
+ *
+ * Behavior:
+ * - non-wrapper groups return raw unit chunks (text quadlets or binary triplets).
+ * - wrapper groups recurse into nested attachment-group dispatch.
+ * - compat mode preserves unread wrapper remainder as opaque units on non-boundary
+ *   nested parse errors.
+ */
 function parseQuadletGroup(input, counter, version, wrapperCodes, domain, context) {
     const unitSize = quadletUnitSize(domain);
     const payloadSize = counter.count * unitSize;
@@ -86,32 +418,47 @@ function parseQuadletGroup(input, counter, version, wrapperCodes, domain, contex
         // Wrapper payload is a packed stream of nested groups (best effort).
         const items = [];
         let offset = 0;
+        let nestedVersion = version;
         while (offset < payload.length) {
             try {
+                const nestedCounter = parseCounter(payload.slice(offset), nestedVersion, domain);
+                if (nestedCounter.code === GENUS_VERSION_CODE) {
+                    // Wrapper-scoped version override for subsequent nested groups.
+                    offset += counterHeaderSize(nestedCounter, domain);
+                    nestedVersion = decodeVersionCounter(nestedCounter);
+                    continue;
+                }
                 const nested = parseAttachmentDispatchCompat(
                 // Allow mixed-version nested groups inside wrapper payloads.
                 // Some real-world streams wrap v2 groups inside v1 wrappers.
-                payload.slice(offset), version, domain, context);
-                items.push({
-                    code: nested.group.code,
-                    name: nested.group.name,
-                    count: nested.group.count,
-                });
+                payload.slice(offset), nestedVersion, domain, context);
+                items.push(nestedGroupItem(nested.group.code, nested.group.name, nested.group.count));
                 if (nested.consumed === 0) {
                     throw new GroupSizeError("Nested attachment parser consumed zero bytes");
                 }
                 offset += nested.consumed;
             }
             catch (error) {
-                if (error instanceof ShortageError ||
-                    error instanceof GroupSizeError) {
-                    throw error;
+                const normalized = asError(error);
+                if (normalized instanceof ShortageError ||
+                    normalized instanceof GroupSizeError) {
+                    throw normalized;
+                }
+                if (!context.versionFallbackPolicy.shouldPreserveWrapperRemainder(normalized)) {
+                    throw normalized;
                 }
                 // Intentional recovery point: keep unread wrapper tail as opaque units.
                 const remainder = payload.slice(offset);
-                const opaque = domain === "bny"
-                    ? Array.from({ length: Math.floor(remainder.length / 3) }, (_v, i) => remainder.slice(i * 3, i * 3 + 3))
-                    : (String.fromCharCode(...remainder).match(/.{1,4}/g) ?? []);
+                const opaque = splitOpaqueUnits(remainder, domain, undefined, true);
+                context.recoveryDiagnosticObserver?.({
+                    type: "wrapper-opaque-tail-preserved",
+                    version: nestedVersion,
+                    domain,
+                    wrapperCode: counter.code,
+                    opaqueItemCount: opaque.length,
+                    errorName: normalized.name,
+                    reason: normalized.message,
+                });
                 items.push(...opaque);
                 offset = payload.length;
             }
@@ -121,11 +468,10 @@ function parseQuadletGroup(input, counter, version, wrapperCodes, domain, contex
         }
         return { items, consumed: total };
     }
-    const items = domain === "bny"
-        ? Array.from({ length: counter.count }, (_v, i) => payload.slice(i * 3, i * 3 + 3))
-        : (String.fromCharCode(...payload).match(/.{1,4}/g) ?? []);
+    const items = splitOpaqueUnits(payload, domain, counter.count);
     return { items, consumed: total };
 }
+/** Build parser for repeated tuple-based group families. */
 function repeatTupleParser(kinds) {
     return (input, counter, _version, domain, _context) => {
         const headerSize = counterHeaderSize(counter, domain);
@@ -133,6 +479,7 @@ function repeatTupleParser(kinds) {
         return { items: parsed.items, consumed: parsed.consumed + headerSize };
     };
 }
+/** Parse transferable indexed-signature groups with a 3-field header + siger list. */
 function transIdxSigGroupsParser(input, counter, version, domain, _context) {
     const items = [];
     let offset = counterHeaderSize(counter, domain);
@@ -145,10 +492,11 @@ function transIdxSigGroupsParser(input, counter, version, domain, _context) {
         offset += header.consumed;
         const sigers = parseSigerList(input.slice(offset), version, domain);
         offset += sigers.consumed;
-        items.push([...header.items, sigers.items]);
+        items.push(tupleItem([...header.items, tupleItem(sigers.items)]));
     }
     return { items, consumed: offset };
 }
+/** Parse transferable last-establishment sig groups with header + siger list. */
 function transLastIdxSigGroupsParser(input, counter, version, domain, _context) {
     const items = [];
     let offset = counterHeaderSize(counter, domain);
@@ -157,10 +505,11 @@ function transLastIdxSigGroupsParser(input, counter, version, domain, _context)
         offset += header.consumed;
         const sigers = parseSigerList(input.slice(offset), version, domain);
         offset += sigers.consumed;
-        items.push([...header.items, sigers.items]);
+        items.push(tupleItem([...header.items, tupleItem(sigers.items)]));
     }
     return { items, consumed: offset };
 }
+/** Parse SadPathSig groups: each path is followed by one nested signature group. */
 function sadPathSigParser(input, counter, version, domain, context) {
     const items = [];
     let offset = counterHeaderSize(counter, domain);
@@ -169,187 +518,125 @@ function sadPathSigParser(input, counter, version, domain, context) {
         offset += primitiveSize(path, domain);
         const sigGroup = parseAttachmentDispatchCompat(input.slice(offset), version, domain, context);
         offset += sigGroup.consumed;
-        items.push([path.qb64, {
-                code: sigGroup.group.code,
-                name: sigGroup.group.name,
-                count: sigGroup.group.count,
-            }]);
+        items.push(tupleItem([
+            qb64Item(path.qb64),
+            nestedGroupItem(sigGroup.group.code, sigGroup.group.name, sigGroup.group.count),
+        ]));
     }
     return { items, consumed: offset };
 }
+/** Parse SadPathSigGroup: root path + repeated (path, nested signature group). */
 function sadPathSigGroupParser(input, counter, version, domain, context) {
     const items = [];
     let offset = counterHeaderSize(counter, domain);
     const root = parseMatter(input.slice(offset), domain);
     offset += primitiveSize(root, domain);
-    items.push(root.qb64);
+    items.push(qb64Item(root.qb64));
     for (let i = 0; i < counter.count; i++) {
         const path = parseMatter(input.slice(offset), domain);
         offset += primitiveSize(path, domain);
         const sigGroup = parseAttachmentDispatchCompat(input.slice(offset), version, domain, context);
         offset += sigGroup.consumed;
-        items.push([path.qb64, {
-                code: sigGroup.group.code,
-                name: sigGroup.group.name,
-                count: sigGroup.group.count,
-            }]);
+        items.push(tupleItem([
+            qb64Item(path.qb64),
+            nestedGroupItem(sigGroup.group.code, sigGroup.group.name, sigGroup.group.count),
+        ]));
     }
     return { items, consumed: offset };
 }
+/** Genus-version groups carry only the counter token itself as semantic payload. */
 function genusVersionParser(_input, counter, _version, domain, _context) {
     return {
-        items: [counter.qb64],
+        items: [qb64Item(counter.qb64)],
         consumed: counterHeaderSize(counter, domain),
     };
 }
+/** v1 quadlet/triplet parser variant with v1 wrapper-code semantics. */
 const V1_QUADLET_PARSER = (input, counter, version, domain, context) => parseQuadletGroup(input, counter, version, WRAPPER_GROUP_CODES_V1, domain, context);
+/** v2 quadlet/triplet parser variant with v2 wrapper-code semantics. */
 const V2_QUADLET_PARSER = (input, counter, version, domain, context) => parseQuadletGroup(input, counter, version, WRAPPER_GROUP_CODES_V2, domain, context);
-const V1_DISPATCH = new Map([
-    [CtrDexV1.GenericGroup, V1_QUADLET_PARSER],
-    [CtrDexV1.BigGenericGroup, V1_QUADLET_PARSER],
-    [CtrDexV1.BodyWithAttachmentGroup, V1_QUADLET_PARSER],
-    [CtrDexV1.BigBodyWithAttachmentGroup, V1_QUADLET_PARSER],
-    [CtrDexV1.AttachmentGroup, V1_QUADLET_PARSER],
-    [CtrDexV1.BigAttachmentGroup, V1_QUADLET_PARSER],
-    [CtrDexV1.NonNativeBodyGroup, V1_QUADLET_PARSER],
-    [CtrDexV1.BigNonNativeBodyGroup, V1_QUADLET_PARSER],
-    [CtrDexV1.ESSRPayloadGroup, V1_QUADLET_PARSER],
-    [CtrDexV1.BigESSRPayloadGroup, V1_QUADLET_PARSER],
-    [CtrDexV1.PathedMaterialCouples, V1_QUADLET_PARSER],
-    [CtrDexV1.BigPathedMaterialCouples, V1_QUADLET_PARSER],
-    [CtrDexV1.ControllerIdxSigs, repeatTupleParser(["indexer"])],
-    [CtrDexV1.WitnessIdxSigs, repeatTupleParser(["indexer"])],
-    [CtrDexV1.NonTransReceiptCouples, repeatTupleParser(["matter", "matter"])],
-    [
-        CtrDexV1.TransReceiptQuadruples,
-        repeatTupleParser(["matter", "matter", "matter", "indexer"]),
-    ],
-    [CtrDexV1.FirstSeenReplayCouples, repeatTupleParser(["matter", "matter"])],
-    [CtrDexV1.SealSourceCouples, repeatTupleParser(["matter", "matter"])],
-    [
-        CtrDexV1.SealSourceTriples,
-        repeatTupleParser(["matter", "matter", "matter"]),
-    ],
-    [CtrDexV1.TransIdxSigGroups, transIdxSigGroupsParser],
-    [CtrDexV1.TransLastIdxSigGroups, transLastIdxSigGroupsParser],
-    [CtrDexV1.SadPathSig, sadPathSigParser],
-    [CtrDexV1.SadPathSigGroup, sadPathSigGroupParser],
-    [CtrDexV1.KERIACDCGenusVersion, genusVersionParser],
-]);
-const V2_DISPATCH = new Map([
-    [CtrDexV2.GenericGroup, V2_QUADLET_PARSER],
-    [CtrDexV2.BigGenericGroup, V2_QUADLET_PARSER],
-    [CtrDexV2.BodyWithAttachmentGroup, V2_QUADLET_PARSER],
-    [CtrDexV2.BigBodyWithAttachmentGroup, V2_QUADLET_PARSER],
-    [CtrDexV2.AttachmentGroup, V2_QUADLET_PARSER],
-    [CtrDexV2.BigAttachmentGroup, V2_QUADLET_PARSER],
-    [CtrDexV2.NonNativeBodyGroup, V2_QUADLET_PARSER],
-    [CtrDexV2.BigNonNativeBodyGroup, V2_QUADLET_PARSER],
-    [CtrDexV2.ESSRPayloadGroup, V2_QUADLET_PARSER],
-    [CtrDexV2.BigESSRPayloadGroup, V2_QUADLET_PARSER],
-    [CtrDexV2.PathedMaterialCouples, V2_QUADLET_PARSER],
-    [CtrDexV2.BigPathedMaterialCouples, V2_QUADLET_PARSER],
-    [CtrDexV2.DatagramSegmentGroup, V2_QUADLET_PARSER],
-    [CtrDexV2.BigDatagramSegmentGroup, V2_QUADLET_PARSER],
-    [CtrDexV2.ESSRWrapperGroup, V2_QUADLET_PARSER],
-    [CtrDexV2.BigESSRWrapperGroup, V2_QUADLET_PARSER],
-    [CtrDexV2.FixBodyGroup, V2_QUADLET_PARSER],
-    [CtrDexV2.BigFixBodyGroup, V2_QUADLET_PARSER],
-    [CtrDexV2.MapBodyGroup, V2_QUADLET_PARSER],
-    [CtrDexV2.BigMapBodyGroup, V2_QUADLET_PARSER],
-    [CtrDexV2.GenericMapGroup, V2_QUADLET_PARSER],
-    [CtrDexV2.BigGenericMapGroup, V2_QUADLET_PARSER],
-    [CtrDexV2.GenericListGroup, V2_QUADLET_PARSER],
-    [CtrDexV2.BigGenericListGroup, V2_QUADLET_PARSER],
-    [CtrDexV2.ControllerIdxSigs, repeatTupleParser(["indexer"])],
-    [CtrDexV2.BigControllerIdxSigs, repeatTupleParser(["indexer"])],
-    [CtrDexV2.WitnessIdxSigs, repeatTupleParser(["indexer"])],
-    [CtrDexV2.BigWitnessIdxSigs, repeatTupleParser(["indexer"])],
-    [CtrDexV2.NonTransReceiptCouples, repeatTupleParser(["matter", "matter"])],
-    [CtrDexV2.BigNonTransReceiptCouples, repeatTupleParser(["matter", "matter"])],
-    [
-        CtrDexV2.TransReceiptQuadruples,
-        repeatTupleParser(["matter", "matter", "matter", "indexer"]),
-    ],
-    [
-        CtrDexV2.BigTransReceiptQuadruples,
-        repeatTupleParser(["matter", "matter", "matter", "indexer"]),
-    ],
-    [CtrDexV2.FirstSeenReplayCouples, repeatTupleParser(["matter", "matter"])],
-    [CtrDexV2.BigFirstSeenReplayCouples, repeatTupleParser(["matter", "matter"])],
-    [CtrDexV2.SealSourceCouples, repeatTupleParser(["matter", "matter"])],
-    [CtrDexV2.BigSealSourceCouples, repeatTupleParser(["matter", "matter"])],
-    [
-        CtrDexV2.SealSourceTriples,
-        repeatTupleParser(["matter", "matter", "matter"]),
-    ],
-    [
-        CtrDexV2.BigSealSourceTriples,
-        repeatTupleParser(["matter", "matter", "matter"]),
-    ],
-    [CtrDexV2.SealSourceLastSingles, repeatTupleParser(["matter"])],
-    [CtrDexV2.BigSealSourceLastSingles, repeatTupleParser(["matter"])],
-    [CtrDexV2.DigestSealSingles, repeatTupleParser(["matter"])],
-    [CtrDexV2.BigDigestSealSingles, repeatTupleParser(["matter"])],
-    [CtrDexV2.MerkleRootSealSingles, repeatTupleParser(["matter"])],
-    [CtrDexV2.BigMerkleRootSealSingles, repeatTupleParser(["matter"])],
-    [
-        CtrDexV2.BackerRegistrarSealCouples,
-        repeatTupleParser(["matter", "matter"]),
-    ],
-    [
-        CtrDexV2.BigBackerRegistrarSealCouples,
-        repeatTupleParser(["matter", "matter"]),
-    ],
-    [CtrDexV2.TypedDigestSealCouples, repeatTupleParser(["matter", "matter"])],
-    [CtrDexV2.BigTypedDigestSealCouples, repeatTupleParser(["matter", "matter"])],
-    [CtrDexV2.TransIdxSigGroups, transIdxSigGroupsParser],
-    [CtrDexV2.BigTransIdxSigGroups, transIdxSigGroupsParser],
-    [CtrDexV2.TransLastIdxSigGroups, transLastIdxSigGroupsParser],
-    [CtrDexV2.BigTransLastIdxSigGroups, transLastIdxSigGroupsParser],
-    [
-        CtrDexV2.BlindedStateQuadruples,
-        repeatTupleParser(["matter", "matter", "matter", "matter"]),
-    ],
-    [
-        CtrDexV2.BigBlindedStateQuadruples,
-        repeatTupleParser(["matter", "matter", "matter", "matter"]),
-    ],
-    [
-        CtrDexV2.BoundStateSextuples,
-        repeatTupleParser([
-            "matter",
-            "matter",
-            "matter",
-            "matter",
-            "matter",
-            "matter",
-        ]),
-    ],
-    [
-        CtrDexV2.BigBoundStateSextuples,
-        repeatTupleParser([
-            "matter",
-            "matter",
-            "matter",
-            "matter",
-            "matter",
-            "matter",
-        ]),
-    ],
-    [
-        CtrDexV2.TypedMediaQuadruples,
-        repeatTupleParser(["matter", "matter", "matter", "matter"]),
-    ],
-    [
-        CtrDexV2.BigTypedMediaQuadruples,
-        repeatTupleParser(["matter", "matter", "matter", "matter"]),
-    ],
-    [CtrDexV2.KERIACDCGenusVersion, genusVersionParser],
-]);
+/**
+ * Parser instance cache keyed by tuple shape (`matter|indexer|...`).
+ *
+ * Why:
+ * many codes share identical repeated-tuple semantics; caching preserves one
+ * parser closure per tuple shape and keeps dispatch-map construction stable.
+ */
+const REPEAT_TUPLE_PARSER_CACHE = new Map();
+/**
+ * Resolve one expanded descriptor into its executable parser function.
+ *
+ * Invariant:
+ * this switch must remain exhaustive over `DispatchParserKind`.
+ */
+function parserForDescriptor(descriptor) {
+    switch (descriptor.parserKind) {
+        case "quadlet":
+            return descriptor.version === 2 ? V2_QUADLET_PARSER : V1_QUADLET_PARSER;
+        case "repeatTuple": {
+            if (!descriptor.tupleKinds || descriptor.tupleKinds.length === 0) {
+                throw new Error(`Dispatch descriptor ${descriptor.code} is missing tupleKinds`);
+            }
+            const key = descriptor.tupleKinds.join("|");
+            let parser = REPEAT_TUPLE_PARSER_CACHE.get(key);
+            if (!parser) {
+                parser = repeatTupleParser(descriptor.tupleKinds);
+                REPEAT_TUPLE_PARSER_CACHE.set(key, parser);
+            }
+            return parser;
+        }
+        case "transIdxSigGroups":
+            return transIdxSigGroupsParser;
+        case "transLastIdxSigGroups":
+            return transLastIdxSigGroupsParser;
+        case "sadPathSig":
+            return sadPathSigParser;
+        case "sadPathSigGroup":
+            return sadPathSigGroupParser;
+        case "genusVersion":
+            return genusVersionParser;
+    }
+}
+/**
+ * Build major-version dispatch maps from normalized descriptors.
+ *
+ * Invariant:
+ * each code appears at most once per major version in the final maps; if a code
+ * were duplicated in descriptors, later entries would overwrite earlier ones.
+ */
+function buildDispatchByVersion(descriptors) {
+    const dispatch = {
+        1: new Map(),
+        2: new Map(),
+    };
+    for (const descriptor of descriptors) {
+        dispatch[descriptor.version].set(descriptor.code, parserForDescriptor(descriptor));
+    }
+    return dispatch;
+}
+/** Generated dispatch maps keyed by major version. */
+const DISPATCH_BY_MAJOR = buildDispatchByVersion(ATTACHMENT_DISPATCH_DESCRIPTORS);
+/**
+ * Lift major-indexed artifacts into a major+minor registry.
+ *
+ * Current parser supports one minor (`0`) per major, but this keeps lookup
+ * contracts explicit and ready for minor-version progression.
+ */
+function asMinorZeroRegistry(byMajor) {
+    return Object.freeze({
+        1: Object.freeze({ 0: byMajor[1] }),
+        2: Object.freeze({ 0: byMajor[2] }),
+    });
+}
+/** Siger-list counter code sets resolved by major+minor stream version. */
+const SIGER_LIST_CODES_BY_VERSION = asMinorZeroRegistry(SIGER_LIST_CODES_BY_MAJOR);
+/** Attachment-group dispatch registry resolved by major+minor stream version. */
+const DISPATCH_BY_VERSION = asMinorZeroRegistry(DISPATCH_BY_MAJOR);
+/** Resolve attachment dispatch table for the requested stream version. */
 function getDispatch(version) {
-    return version.major >= 2 ? V2_DISPATCH : V1_DISPATCH;
+    return resolveVersionedRegistryValue(DISPATCH_BY_VERSION, version, "attachment dispatch registry").value;
 }
+/** Parse one attachment group with an explicit version (no version fallback). */
 function parseAttachmentDispatchWithVersion(input, version, domain, context) {
     const counter = parseCounter(input, version, domain);
     const parser = getDispatch(version).get(counter.code);
@@ -371,50 +658,77 @@ function parseAttachmentDispatchWithVersion(input, version, domain, context) {
         consumed: parsed.consumed,
     };
 }
-function parseAttachmentDispatchByMode(input, version, domain, context) {
-    if (context.mode === "strict") {
-        return parseAttachmentDispatchWithVersion(input, version, domain, context);
-    }
+/**
+ * Parse one attachment group using an injected fallback strategy.
+ *
+ * Flow:
+ * 1) attempt parse with provided version
+ * 2) ask policy whether failure is terminal or retryable
+ * 3) on retry, emit fallback observation and parse with policy-selected version
+ */
+function parseAttachmentDispatchWithPolicy(input, version, domain, context) {
     try {
         return parseAttachmentDispatchWithVersion(input, version, domain, context);
     }
     catch (error) {
-        if (!(error instanceof UnknownCodeError) &&
-            !(error instanceof DeserializeError)) {
-            throw error;
+        const normalized = asError(error);
+        const decision = context.versionFallbackPolicy.onVersionDispatchFailure(normalized, version, domain);
+        if (decision.action === "throw") {
+            context.recoveryDiagnosticObserver?.({
+                type: "version-fallback-rejected",
+                version,
+                domain,
+                errorName: normalized.name,
+                reason: normalized.message,
+            });
+            throw normalized;
         }
-        const alternate = version.major >= 2
-            ? { major: 1, minor: 0 }
-            : { major: 2, minor: 0 };
-        const info = {
-            from: version,
-            to: alternate,
-            domain,
-            reason: error.message,
-        };
-        if (context.onVersionFallback) {
-            context.onVersionFallback(info);
-        }
-        else {
-            console.warn(`CESR attachment dispatch fallback ${version.major}.${version.minor} -> ${alternate.major}.${alternate.minor} (${domain}): ${error.message}`);
-        }
-        return parseAttachmentDispatchWithVersion(input, alternate, domain, context);
+        context.recoveryDiagnosticObserver?.({
+            type: "version-fallback-accepted",
+            from: decision.info.from,
+            to: decision.info.to,
+            domain: decision.info.domain,
+            reason: decision.info.reason,
+        });
+        context.versionFallbackPolicy.onVersionFallback(decision.info);
+        return parseAttachmentDispatchWithVersion(input, decision.retryVersion, domain, context);
     }
 }
 /**
- * Parse with primary version, then retry with the alternate major on unknown
- * code/deserialize failures. This mirrors real-world mixed-stream tolerance.
+ * Parse one attachment group with policy-aware fallback behavior.
+ *
+ * By default this uses compat policy semantics to mirror historical
+ * `parseAttachmentDispatchCompat` behavior unless overridden via
+ * `options.versionFallbackPolicy`.
  */
 export function parseAttachmentDispatchCompat(input, version, domain, options = {}) {
+    const versionFallbackPolicy = options.versionFallbackPolicy ??
+        createAttachmentVersionFallbackPolicy({
+            mode: options.mode,
+        });
+    const recoveryDiagnosticObserver = composeRecoveryDiagnosticObserver({
+        onRecoveryDiagnostic: options.onRecoveryDiagnostic,
+        onAttachmentVersionFallback: options.versionFallbackPolicy
+            ? undefined
+            : options.onVersionFallback,
+    });
     const context = {
-        mode: options.mode ?? "compat",
-        onVersionFallback: options.onVersionFallback,
+        versionFallbackPolicy,
+        recoveryDiagnosticObserver,
     };
-    return parseAttachmentDispatchByMode(input, version, domain, context);
+    return parseAttachmentDispatchWithPolicy(input, version, domain, context);
 }
-/** Strict versioned attachment-group dispatch (no major-version fallback). */
+/**
+ * Parse one attachment group with strict fail-fast semantics.
+ *
+ * Why:
+ * this API guarantees no major-version fallback and no wrapper opaque-tail
+ * preservation, matching parity/validation use cases.
+ */
 export function parseAttachmentDispatch(input, version, domain) {
-    return parseAttachmentDispatchByMode(input, version, domain, {
-        mode: "strict",
+    return parseAttachmentDispatchWithPolicy(input, version, domain, {
+        versionFallbackPolicy: createAttachmentVersionFallbackPolicy({
+            mode: "strict",
+        }),
     });
 }