cesr-ts 0.3.1 → 0.5.0

package/README.md

@@ -18,7 +18,7 @@ const parser = createParser();
 const out = parser.feed(new TextEncoder().encode("...CESR..."));
 const last = parser.flush();
 
-const text = '{"v":"KERI10JSON00002e_","t":"rpy","d":"Eabc"}';
+const text = "{\"v\":\"KERI10JSON00002e_\",\"t\":\"rpy\",\"d\":\"Eabc\"}";
 const annotated = annotate(text, { domainHint: "txt", pretty: true });
 ```
 
@@ -61,5 +61,5 @@ tufa annotate --in mystream.cesr --pretty
 
 ## License
 
-Licensed under the Apache License, Version 2.0 (`Apache-2.0`). See the
-top-level `LICENSE` file in this repository.
+Licensed under the Apache License, Version 2.0 (`Apache-2.0`). See the top-level
+`LICENSE` file in this repository.

package/esm/src/adapters/async-iterable.js

@@ -1,4 +1,12 @@
 import { createParser } from "../core/parser-engine.js";
+/**
+ * Adapt an async byte stream into parsed CESR frames.
+ *
+ * Boundary contract:
+ * - chunks are fed in arrival order into one parser instance
+ * - emitted parser error events are rethrown as stream errors
+ * - yielded values are the historical `CesrMessage` frame payloads only
+ */
 export async function* toAsyncFrames(source, options = {}) {
     const parser = createParser(options);
     for await (const chunk of source) {

package/esm/src/adapters/effection.js

@@ -1,5 +1,11 @@
 import { action } from "effection";
 import { toAsyncFrames } from "./async-iterable.js";
+/**
+ * Bridge the async-iterable parser adapter into an Effection operation.
+ *
+ * This stays intentionally thin so parser semantics continue to live in
+ * `toAsyncFrames()` rather than forking behavior in an Effection-only path.
+ */
 export function* toEffectionFrames(source, options = {}) {
     const frames = yield* action((resolve) => {
         resolve(toAsyncFrames(source, options));

package/esm/src/annotate/annotator.js

@@ -1,5 +1,6 @@
+import { b } from "../core/bytes.js";
 import { parseBytes } from "../core/parser-engine.js";
-import { renderAnnotatedFrames, renderWrapperAnnotatedStream, } from "./render.js";
+import { renderAnnotatedFrames, renderWrapperAnnotatedStream } from "./render.js";
 const DEFAULT_OPTIONS = Object.freeze({
     commentMode: "inline",
     indent: 2,
@@ -24,19 +25,27 @@ function parsedFramesOrThrow(frames) {
     }
     return parsedFrames;
 }
+/**
+ * Parse input and return one annotation structure per emitted frame.
+ *
+ * Use this when callers want to inspect annotation lines programmatically
+ * instead of flattening the whole stream to one rendered string.
+ */
 export function annotateFrames(input, options) {
     const opts = resolveOptions(options);
-    const bytes = typeof input === "string"
-        ? new TextEncoder().encode(input)
-        : input;
+    const bytes = typeof input === "string" ? b(input) : input;
     const frames = parsedFramesOrThrow(parseBytes(bytes));
     return renderAnnotatedFrames(frames, opts);
 }
+/**
+ * Render one CESR stream into maintainer-oriented annotated text.
+ *
+ * Wrapper-aware rendering is attempted first so opaque wrapper payloads can be
+ * preserved faithfully before falling back to frame-by-frame annotation.
+ */
 export function annotate(input, options) {
     const opts = resolveOptions(options);
-    const bytes = typeof input === "string"
-        ? new TextEncoder().encode(input)
-        : input;
+    const bytes = typeof input === "string" ? b(input) : input;
     const wrapperAnnotated = renderWrapperAnnotatedStream(bytes, opts);
     if (wrapperAnnotated !== null) {
         return wrapperAnnotated;

package/esm/src/annotate/cli.js

@@ -35,6 +35,12 @@ function parseArgs(args) {
     }
     return out;
 }
+/**
+ * Read a full `ReadableStream` into one contiguous byte buffer.
+ *
+ * This is the shared browser/runtime-neutral helper used by annotate CLI
+ * shims that expose stdin as a web stream instead of synchronous file APIs.
+ */
 export async function readAllReadable(stream) {
     const reader = stream.getReader();
     const chunks = [];
@@ -61,6 +67,12 @@ export async function readAllReadable(stream) {
     }
     return out;
 }
+/**
+ * Execute the standalone annotate CLI against the provided IO boundary.
+ *
+ * Error reporting is intentionally normalized here so runtime-specific entry
+ * points can stay as thin bootstraps.
+ */
 export async function annotateCli(args, io) {
     try {
         const options = parseArgs(args);

package/esm/src/annotate/comments.js

@@ -1,6 +1,6 @@
-import { COUNTER_CODE_NAMES_V1, COUNTER_CODE_NAMES_V2, } from "../tables/counter.tables.generated.js";
-import { MATTER_CODE_NAMES } from "../tables/matter.tables.generated.js";
 import { resolveCounterCodeNameTable } from "../tables/counter-version-registry.js";
+import { COUNTER_CODE_NAMES_V1, COUNTER_CODE_NAMES_V2 } from "../tables/counter.tables.generated.js";
+import { MATTER_CODE_NAMES } from "../tables/matter.tables.generated.js";
 const NATIVE_FIELD_LABELS = Object.freeze({
     v: "version string",
     t: "ilk",
@@ -17,6 +17,7 @@ const NATIVE_FIELD_LABELS = Object.freeze({
     c: "traits/config",
     a: "anchors/data",
 });
+/** Resolve a human-readable counter name against either known counter table. */
 export function counterCodeName(code) {
     const v2 = COUNTER_CODE_NAMES_V2[code];
     if (v2)
@@ -26,13 +27,16 @@ export function counterCodeName(code) {
         return v1;
     return "Counter";
 }
+/** Resolve a counter name against the registry selected for one protocol version. */
 export function counterCodeNameForVersion(code, version) {
     const table = resolveCounterCodeNameTable(version);
     return table[code] ?? "Counter";
 }
+/** Resolve a human-readable matter name from the generated matter code table. */
 export function matterCodeName(code) {
     return MATTER_CODE_NAMES[code] ?? "Matter";
 }
+/** Expand well-known native field labels for annotation comments when available. */
 export function nativeLabelName(label) {
     if (!label)
         return null;

package/esm/src/annotate/denot.js

@@ -1,4 +1,10 @@
 const TEXT_ENCODER = new TextEncoder();
+/**
+ * Strip annotation comments/whitespace and rebuild the raw CESR text stream.
+ *
+ * This is the inverse of maintainer-facing annotation output, not a general
+ * parser: comment lines and inline `# ...` commentary are discarded.
+ */
 export function denot(annotated) {
     const tokens = [];
     for (const line of annotated.split(/\r?\n/)) {

package/esm/src/annotate/render.js

@@ -1,14 +1,15 @@
+import { b64ToInt, intToB64 } from "../core/bytes.js";
+import { DeserializeError, GroupSizeError, ShortageError, UnknownCodeError } from "../core/errors.js";
 import { parseBytes } from "../core/parser-engine.js";
-import { DeserializeError, GroupSizeError, ShortageError, UnknownCodeError, } from "../core/errors.js";
 import { sniff } from "../parser/cold-start.js";
-import { parseCounter } from "../primitives/counter.js";
-import { parseMatter } from "../primitives/matter.js";
-import { parseIndexer } from "../primitives/indexer.js";
 import { parseAttachmentDispatchCompat } from "../parser/group-dispatch.js";
-import { counterCodeName, counterCodeNameForVersion, matterCodeName, nativeLabelName, } from "./comments.js";
-import { b64ToInt, intToB64 } from "../core/bytes.js";
+import { Counter, parseCounter } from "../primitives/counter.js";
+import { Indexer } from "../primitives/indexer.js";
+import { Matter, parseMatter } from "../primitives/matter.js";
+import { isCounterGroupLike, isPrimitiveTuple } from "../primitives/primitive.js";
+import { UnknownPrimitive } from "../primitives/unknown.js";
+import { counterCodeName, counterCodeNameForVersion, matterCodeName, nativeLabelName } from "./comments.js";
 const TEXT_DECODER = new TextDecoder();
-const TEXT_ENCODER = new TextEncoder();
 const OPAQUE_TOKEN_COMMENT = "opaque token";
 const OPAQUE_WRAPPER_PAYLOAD_COMMENT = "opaque wrapper payload";
 const WRAPPER_GROUP_NAMES = new Set([
@@ -27,10 +28,10 @@ function toHex(bytes) {
     return Array.from(bytes).map((b) => b.toString(16).padStart(2, "0")).join("");
 }
 function isRecoverableParseError(error) {
-    return error instanceof UnknownCodeError ||
-        error instanceof DeserializeError ||
-        error instanceof ShortageError ||
-        error instanceof GroupSizeError;
+    return error instanceof UnknownCodeError
+        || error instanceof DeserializeError
+        || error instanceof ShortageError
+        || error instanceof GroupSizeError;
 }
 function spaces(count) {
     return " ".repeat(Math.max(0, count));
@@ -58,51 +59,7 @@ function emitLine(lines, value, comment, indent, options) {
     }
     lines.push(`${pad}${value} # ${comment}`);
 }
-function describeToken(token, domain, version) {
-    const input = TEXT_ENCODER.encode(token);
-    try {
-        const counter = parseCounter(input, version, domain);
-        return {
-            comment: `${counterCodeNameForVersion(counter.code, version)} counter`,
-            size: domain === "bny" ? counter.fullSizeB2 : counter.fullSize,
-        };
-    }
-    catch (error) {
-        if (!isRecoverableParseError(error)) {
-            throw error;
-        }
-        // Try indexer/matter below.
-    }
-    try {
-        const indexer = parseIndexer(input, domain);
-        return {
-            comment: `Indexer ${indexer.code}`,
-            size: domain === "bny" ? indexer.fullSizeB2 : indexer.fullSize,
-        };
-    }
-    catch (error) {
-        if (!isRecoverableParseError(error)) {
-            throw error;
-        }
-        // Try matter below.
-    }
-    try {
-        const matter = parseMatter(input, domain);
-        return {
-            comment: matterCodeName(matter.code),
-            size: domain === "bny" ? matter.fullSizeB2 : matter.fullSize,
-        };
-    }
-    catch (error) {
-        if (!isRecoverableParseError(error)) {
-            throw error;
-        }
-        return {
-            comment: OPAQUE_TOKEN_COMMENT,
-            size: token.length,
-        };
-    }
-}
+/** Parse counters with a bounded v1/v2 fallback for annotation-only rendering paths. */
 function parseCounterCompat(input, version, domain) {
     try {
         return parseCounter(input, version, domain);
@@ -117,6 +74,7 @@ function parseCounterCompat(input, version, domain) {
         return parseCounter(input, alternate, domain);
     }
 }
+/** Decode a wrapped genus-version selector into the active protocol version context. */
 function decodeVersionCounter(counter) {
     const triplet = counter.qb64.length >= 3
         ? counter.qb64.slice(-3)
@@ -128,29 +86,41 @@ function decodeVersionCounter(counter) {
         minor: minorRaw,
     };
 }
+/** Render hydrated group entries recursively using semantic primitive comments. */
 function renderGroupItems(lines, items, version, indent, options) {
     for (const item of items) {
-        if (item.kind === "qb64") {
-            const parsed = describeToken(item.qb64, "txt", version);
-            const comment = item.opaque
-                ? OPAQUE_WRAPPER_PAYLOAD_COMMENT
-                : parsed.comment;
-            emitLine(lines, item.qb64, comment, indent, options);
+        if (isPrimitiveTuple(item)) {
+            renderGroupItems(lines, item, version, indent + options.indent, options);
+            continue;
+        }
+        if (isCounterGroupLike(item)) {
+            emitLine(lines, item.qb64, `${item.name} nested group`, indent, options);
+            renderGroupItems(lines, [...item.items], version, indent + options.indent, options);
+            continue;
+        }
+        if (item instanceof UnknownPrimitive) {
+            const value = item.sourceDomain === "bny"
+                ? `0x${toHex(item.qb2)}`
+                : item.qb64;
+            emitLine(lines, value, OPAQUE_WRAPPER_PAYLOAD_COMMENT, indent, options);
             continue;
         }
-        if (item.kind === "qb2") {
-            emitLine(lines, `0x${toHex(item.qb2)}`, item.opaque ? OPAQUE_WRAPPER_PAYLOAD_COMMENT : "raw qb2 triplet token", indent, options);
+        if (item instanceof Counter) {
+            emitLine(lines, item.qb64, `${counterCodeNameForVersion(item.code, version)} counter`, indent, options);
             continue;
         }
-        if (item.kind === "tuple") {
-            renderGroupItems(lines, item.items, version, indent + options.indent, options);
+        if (item instanceof Indexer) {
+            emitLine(lines, item.qb64, `Indexer ${item.code}`, indent, options);
             continue;
         }
-        if (item.kind === "group") {
-            emitLine(lines, `${item.code}`, `${item.name} nested group`, indent, options);
+        if (item instanceof Matter) {
+            emitLine(lines, item.qb64, matterCodeName(item.code), indent, options);
+            continue;
         }
+        emitLine(lines, String(item), OPAQUE_TOKEN_COMMENT, indent, options);
     }
 }
+/** Render one raw attachment-group span, including nested wrapper groups when present. */
 function renderAttachmentGroupRaw(lines, raw, version, indent, options) {
     const domain = asDomain(raw);
     if (domain !== "txt" && domain !== "bny") {
@@ -204,6 +174,7 @@ function renderAttachmentGroupRaw(lines, raw, version, indent, options) {
     renderGroupItems(lines, parsed.group.items, version, indent + options.indent, options);
     return parsed.consumed;
 }
+/** Render a native CESR body-group payload using hydrated native field projections when available. */
 function renderNativeBody(lines, frame, options, version) {
     const raw = frame.body.raw;
     const domain = asDomain(raw);
@@ -212,18 +183,44 @@ function renderNativeBody(lines, frame, options, version) {
     }
     const counter = parseCounterCompat(raw, version, domain);
     emitLine(lines, counter.qb64, `${counterCodeNameForVersion(counter.code, version)} count=${counter.count}`, 0, options);
-    for (const field of frame.body.native?.fields ?? []) {
-        const label = nativeLabelName(field.label);
-        const comment = label
-            ? `${label} (${matterCodeName(field.code)})`
-            : matterCodeName(field.code);
-        emitLine(lines, field.qb64, comment, options.indent, options);
+    const unit = domain === "bny" ? 3 : 4;
+    const headerSize = domain === "bny" ? counter.fullSizeB2 : counter.fullSize;
+    const payloadSize = counter.count * unit;
+    const end = Math.min(raw.length, headerSize + payloadSize);
+    let offset = headerSize;
+    while (offset < end) {
+        const slice = raw.slice(offset, end);
+        try {
+            const nestedCounter = parseCounterCompat(slice, version, domain);
+            const nestedCounterSize = domain === "bny"
+                ? nestedCounter.fullSizeB2
+                : nestedCounter.fullSize;
+            emitLine(lines, nestedCounter.qb64, `${counterCodeNameForVersion(nestedCounter.code, version)} counter`, options.indent, options);
+            offset += nestedCounterSize;
+            continue;
+        }
+        catch (error) {
+            if (!isRecoverableParseError(error)) {
+                throw error;
+            }
+        }
+        const matter = parseMatter(slice, domain);
+        const matterSize = domain === "bny" ? matter.fullSizeB2 : matter.fullSize;
+        const field = frame.body.native?.fields.find((candidate) => candidate.primitive.qb64 === matter.qb64);
+        const label = field ? nativeLabelName(field.label) : null;
+        const primitiveComment = matter instanceof Indexer
+            ? `Indexer ${matter.code}`
+            : matterCodeName(matter.code);
+        const comment = label ? `${label} (${primitiveComment})` : primitiveComment;
+        emitLine(lines, matter.qb64, comment, options.indent, options);
+        offset += matterSize;
     }
 }
+/** Render non-native or opaque message bodies as one annotated body line. */
 function renderMessageBody(lines, frame, options) {
     const rawBody = TEXT_DECODER.decode(frame.body.raw);
-    const isOpaqueCesrBody = frame.body.kind === "CESR" &&
-        frame.body.ked === null;
+    const isOpaqueCesrBody = frame.body.kind === "CESR"
+        && frame.body.ked === null;
     if (isOpaqueCesrBody) {
         emitLine(lines, rawBody, `OPAQUE CESR body (non-serder fallback, hex=${toHex(frame.body.raw)})`, 0, options);
         return;
@@ -249,6 +246,7 @@ function renderMessageBody(lines, frame, options) {
     ].filter(Boolean).join(" ");
     emitLine(lines, body, info, 0, options);
 }
+/** Render one parsed frame and all of its attachment groups into annotation lines. */
 function renderFrame(frame, index, options) {
     const lines = [];
     const version = frame.body.gvrsn ?? frame.body.pvrsn;
@@ -264,6 +262,7 @@ function renderFrame(frame, index, options) {
     }
     return { index, frame, lines };
 }
+/** Parse and render a nested frame chunk inside wrapper-aware annotation flows. */
 function renderFrameChunk(lines, input, indent, options) {
     const parsed = parseBytes(input);
     const frames = [];
@@ -280,6 +279,7 @@ function renderFrameChunk(lines, input, indent, options) {
         }
     }
 }
+/** Walk a stream that may begin with wrapper/version selectors before ordinary frames. */
 function renderWrapperAwareStream(lines, input, inheritedVersion, indent, options) {
     let offset = 0;
     let activeVersion = inheritedVersion;

package/esm/src/core/bytes.js

@@ -1,4 +1,6 @@
+/** Shared UTF-8 encoder used by CESR and DB byte helpers. */
 export const encoder = new TextEncoder();
+/** Shared UTF-8 decoder used by CESR and DB byte helpers. */
 export const decoder = new TextDecoder();
 const B64_ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_";
 /**
@@ -17,6 +19,7 @@ export function concatBytes(...chunks) {
     }
     return out;
 }
+/** Encode a non-negative integer into CESR's URL-safe base64 sextet text. */
 export function intToB64(value, length = 1) {
     if (value < 0) {
         throw new Error(`value must be >= 0, got ${value}`);
@@ -32,6 +35,7 @@ export function intToB64(value, length = 1) {
     }
     return out.padStart(length, "A");
 }
+/** Decode CESR URL-safe base64 sextet text into a non-negative integer. */
 export function b64ToInt(text) {
     let out = 0;
     for (const ch of text) {
@@ -43,10 +47,12 @@ export function b64ToInt(text) {
     }
     return out;
 }
+/** Encode raw bytes to unpadded URL-safe base64 text. */
 export function encodeB64(data) {
     const str = btoa(String.fromCharCode(...data));
     return str.replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/g, "");
 }
+/** Decode unpadded URL-safe base64 text into raw bytes. */
 export function decodeB64(text) {
     const padded = text + "===".slice((text.length + 3) % 4);
     const raw = atob(padded.replace(/-/g, "+").replace(/_/g, "/"));
@@ -56,14 +62,20 @@ export function decodeB64(text) {
     }
     return out;
 }
+/**
+ * Symmetric ceiling function
+ * @param value
+ */
 export function sceil(value) {
     return Math.ceil(value);
 }
+/** Convert a CESR code string to the exact leading qb2 bytes that carry it. */
 export function codeB64ToB2(text) {
     const n = sceil((text.length * 3) / 4);
     const full = text + "A".repeat((4 - (text.length % 4)) % 4);
     return decodeB64(full).slice(0, n);
 }
+/** Convert leading qb2 bytes into the requested number of CESR sextets. */
 export function codeB2ToB64(bytes, sextets) {
     const n = sceil((sextets * 3) / 4);
     if (n > bytes.length) {
@@ -71,6 +83,50 @@ export function codeB2ToB64(bytes, sextets) {
     }
     return encodeB64(bytes.slice(0, n)).slice(0, sextets);
 }
+/** Re-slice the first `sextets` worth of qb2 bytes for parser/code probing. */
 export function nabSextets(bytes, sextets) {
     return codeB64ToB2(codeB2ToB64(bytes, sextets));
 }
+/** UTF-8 string -> bytes helper. */
+export const b = (t) => encoder.encode(t);
+/** UTF-8 bytes -> string helper. */
+export const t = (b) => decoder.decode(b);
+/**
+ * Normalize lmdb-js key/value payloads to `Uint8Array`.
+ * Example: converts Node `Buffer`-like values from `getRange()`.
+ */
+export function toBytes(value) {
+    if (value instanceof Uint8Array) {
+        return value;
+    }
+    return new Uint8Array(value);
+}
+/**
+ * Format number as 32-char hex string, zero padded.
+ * @param num
+ */
+export const to32CharHex = (num) => {
+    return num
+        .toString(16)
+        .padStart(32, "0");
+};
+/** Constant-time-ish byte equality for small DB keys/values. */
+export function bytesEqual(left, right) {
+    if (left.length !== right.length) {
+        return false;
+    }
+    for (let i = 0; i < left.length; i++) {
+        if (left[i] !== right[i]) {
+            return false;
+        }
+    }
+    return true;
+}
+/** Stable hex fingerprint used for set-membership dedupe of binary values. */
+export function bytesHex(value) {
+    // deno-fmt-ignore
+    return Array.from(value)
+        .map((byte) => byte.toString(16)
+        .padStart(2, "0"))
+        .join("");
+}

package/esm/src/core/cbor.js

@@ -0,0 +1,122 @@
+import { Decoder } from "cbor-x/decode";
+import { Encoder } from "cbor-x/encode";
+/**
+ * Normalize encoder output to a plain `Uint8Array`.
+ *
+ * `cbor-x` may return subclasses or reused backing buffers depending on the
+ * runtime and code path. The shared KERI codec deliberately copies the result
+ * so callers see a stable, plain `Uint8Array` contract that is safe to compare,
+ * persist, and hand across package boundaries without inheriting library
+ * implementation details.
+ */
+function normalizeEncodedBytes(bytes) {
+    return new Uint8Array(bytes);
+}
+/**
+ * Reject JavaScript `Map` values anywhere in the payload graph.
+ *
+ * This is not a statement about CBOR in general. CBOR absolutely supports map
+ * values. The narrower rule here is about KERI/ACDC parity: KERIpy serializes
+ * the same semantic payloads through JSON, MGPK, and CBOR, and the CBOR paths
+ * we are mirroring are dict/list shaped rather than "generic CBOR" shaped.
+ *
+ * In TypeScript, allowing `Map` values would silently widen the contract past
+ * what the JSON and MGPK paths can represent and past what KERIpy currently
+ * exercises in the mirrored protocol/storage serializers. This guard fails
+ * early so parity drift becomes an explicit decision instead of an accidental
+ * convenience.
+ *
+ * The walk is cycle-safe because this function is defensive validation, not a
+ * serializer in its own right. Cycles would fail later in the encoder anyway,
+ * but we avoid infinite recursion here while still checking the reachable graph
+ * for `Map` instances.
+ */
+function assertNoMapValues(value, seen = new Set()) {
+    if (value === null || typeof value !== "object") {
+        return;
+    }
+    if (value instanceof Map) {
+        throw new TypeError("KERI/ACDC CBOR payloads must use JSON-compatible plain objects/arrays, not JavaScript Map.");
+    }
+    if (seen.has(value)) {
+        return;
+    }
+    seen.add(value);
+    if (Array.isArray(value)) {
+        for (const item of value) {
+            assertNoMapValues(item, seen);
+        }
+        return;
+    }
+    for (const item of Object.values(value)) {
+        assertNoMapValues(item, seen);
+    }
+}
+/**
+ * Canonical KERI/ACDC CBOR encoder configuration.
+ *
+ * Two choices matter for parity:
+ * - `useRecords: false` disables `cbor-x` record extensions so plain objects
+ *   stay plain maps on the wire, matching KERIpy's `cbor2` behavior.
+ * - `variableMapSize: true` forces preferred-size map headers, avoiding the
+ *   default `map16` preallocation strategy that broke exact byte parity.
+ *
+ * We import `Encoder` from `cbor-x/encode` rather than the package root because
+ * the root Node entrypoint probes `process.env` during module evaluation. That
+ * widened Deno test permissions for no KERI value, so the shared codec avoids
+ * that entrypoint on purpose.
+ */
+const keriCborEncoder = new Encoder({
+    useRecords: false,
+    variableMapSize: true,
+});
+/**
+ * Canonical KERI/ACDC CBOR decoder configuration.
+ *
+ * `mapsAsObjects: true` keeps decoded values aligned with the JSON-compatible
+ * object/list contract enforced by `encodeKeriCbor()`. This prevents the decode
+ * side from reintroducing `Map`-typed semantics that the encode side forbids
+ * and keeps protocol/storage callers working with the same value shapes they
+ * would see from JSON or MGPK decoding.
+ *
+ * Like the encoder, this uses the `cbor-x/decode` subpath to avoid the package
+ * root's Node-oriented environment probe.
+ */
+const keriCborDecoder = new Decoder({
+    useRecords: false,
+    mapsAsObjects: true,
+});
+/**
+ * Encode KERI/ACDC CBOR with the same preferred map-size choices as KERIpy's
+ * `cbor2.dumps`.
+ *
+ * This is a protocol/storage codec for KERI/ACDC payloads, not a generic CBOR
+ * helper. KERIpy's corresponding emitters serialize dict/list-shaped data
+ * through `cbor2.dumps`, for example:
+ * - `keri.core.coring.dumps`
+ * - `keri.core.serdering.Serder.dumps`
+ * - `keri.db.koming.Komer.__serializeCBOR`
+ *
+ * The same semantic payloads also serialize as JSON and MGPK in KERIpy, so the
+ * intended cross-format contract is JSON-compatible plain objects and arrays.
+ * The default `cbor-x` encoder intentionally uses fixed-width `map16` headers
+ * for plain JS objects so it can preallocate and patch in the size later. That
+ * is valid CBOR but not byte-identical to KERIpy. This helper enables
+ * `variableMapSize` so small maps use the same compact headers that `cbor2`
+ * emits and rejects `Map` values so we do not silently drift into a broader
+ * CBOR type contract than KERIpy currently uses.
+ */
+export function encodeKeriCbor(value) {
+    assertNoMapValues(value);
+    return normalizeEncodedBytes(keriCborEncoder.encode(value));
+}
+/**
+ * Decode KERI/ACDC CBOR into plain JS objects/arrays.
+ *
+ * This keeps the decoder aligned with the encoder policy surface and avoids
+ * record-extension or `Map`-typed decode behavior on KERI/ACDC protocol and
+ * storage paths.
+ */
+export function decodeKeriCbor(raw) {
+    return keriCborDecoder.decode(raw);
+}

package/esm/src/core/errors.js

@@ -1,3 +1,10 @@
+/**
+ * Base parser failure carrying optional offset/context for maintainer
+ * diagnostics.
+ *
+ * Subclasses identify which parser phase rejected the input so callers can
+ * decide whether to recover, retry, or fail hard.
+ */
 export class ParserError extends Error {
     constructor(message, offset, context) {
         super(message);
@@ -16,6 +23,7 @@ export class ParserError extends Error {
         this.name = globalThis[Symbol.for("import-meta-ponyfill-esmodule")](import.meta).name;
     }
 }
+/** Input ended before the parser had enough bytes to complete the current unit. */
 export class ShortageError extends ParserError {
     constructor(needed, available, offset) {
         super(`Need ${needed} bytes but only ${available} available`, offset);
@@ -33,16 +41,24 @@ export class ShortageError extends ParserError {
         });
     }
 }
+/** Parser encountered an invalid cold-start selector. */
 export class ColdStartError extends ParserError {
 }
+/** Version framing or version-table selection failed. */
 export class VersionError extends ParserError {
 }
+/** A CESR code selector was not recognized in the active codex. */
 export class UnknownCodeError extends ParserError {
 }
+/** Group/count metadata could not describe a valid parse shape. */
 export class GroupSizeError extends ParserError {
 }
+/** Qualified input could not be deserialized into a valid CESR payload. */
 export class DeserializeError extends ParserError {
 }
+/** A CESR payload could not be serialized into a valid protocol representation. */
+export class SerializeError extends ParserError {
+}
 /** Failure while constructing syntax artifacts from token bytes. */
 export class SyntaxParseError extends ParserError {
     constructor(message, cause, offset, context) {