cesr-ts 0.1.0

package/esm/src/core/parser-engine.js

@@ -0,0 +1,589 @@
+import { concatBytes } from "./bytes.js";
+import { sniff } from "../parser/cold-start.js";
+import { reapSerder } from "../serder/serdery.js";
+import { parseAttachmentGroup } from "../parser/attachment-parser.js";
+import { ColdStartError, DeserializeError, ParserError, ShortageError, UnknownCodeError, } from "./errors.js";
+import { parseCounter } from "../primitives/counter.js";
+import { parseMatter } from "../primitives/matter.js";
+import { parseVerser } from "../primitives/verser.js";
+import { parseIlker } from "../primitives/ilker.js";
+import { isLabelerCode, parseLabeler } from "../primitives/labeler.js";
+import { parseMapperBody } from "../primitives/mapper.js";
+import { CtrDexV1, CtrDexV2 } from "../tables/counter-codex.js";
+import { b64ToInt, intToB64 } from "./bytes.js";
+import { Kinds, Protocols } from "../tables/versions.js";
+const DEFAULT_VERSION = { major: 2, minor: 0 };
+const BODY_WITH_ATTACH_CODES = new Set([
+    CtrDexV1.BodyWithAttachmentGroup,
+    CtrDexV1.BigBodyWithAttachmentGroup,
+    CtrDexV2.BodyWithAttachmentGroup,
+    CtrDexV2.BigBodyWithAttachmentGroup,
+]);
+const NON_NATIVE_BODY_CODES = new Set([
+    CtrDexV1.NonNativeBodyGroup,
+    CtrDexV1.BigNonNativeBodyGroup,
+    CtrDexV2.NonNativeBodyGroup,
+    CtrDexV2.BigNonNativeBodyGroup,
+]);
+const FIX_BODY_CODES = new Set([
+    CtrDexV2.FixBodyGroup,
+    CtrDexV2.BigFixBodyGroup,
+]);
+const MAP_BODY_CODES = new Set([
+    CtrDexV2.MapBodyGroup,
+    CtrDexV2.BigMapBodyGroup,
+]);
+const GENUS_VERSION_CODE = CtrDexV2.KERIACDCGenusVersion;
+function tokenSize(token, cold) {
+    return cold === "bny" ? token.fullSizeB2 : token.fullSize;
+}
+function quadletUnit(cold) {
+    return cold === "bny" ? 3 : 4;
+}
+function isAttachmentDomain(cold) {
+    return cold === "txt" || cold === "bny";
+}
+export class CesrParserCore {
+    constructor(options = {}) {
+        Object.defineProperty(this, "state", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: { buffer: new Uint8Array(0), offset: 0 }
+        });
+        Object.defineProperty(this, "framed", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "attachmentDispatchMode", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "onAttachmentVersionFallback", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "pendingFrame", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: null
+        });
+        this.framed = options.framed ?? false;
+        this.attachmentDispatchMode = options.attachmentDispatchMode ?? "compat";
+        this.onAttachmentVersionFallback = options.onAttachmentVersionFallback;
+    }
+    /** Append bytes and emit any complete parse events. */
+    feed(chunk) {
+        this.state.buffer = concatBytes(this.state.buffer, chunk);
+        return this.drain();
+    }
+    /** Flush pending state at end-of-stream, emitting frame/error if needed. */
+    flush() {
+        const out = [];
+        if (this.pendingFrame) {
+            out.push({ type: "frame", frame: this.pendingFrame.frame });
+            this.pendingFrame = null;
+        }
+        if (this.state.buffer.length === 0)
+            return out;
+        out.push({
+            type: "error",
+            error: new ShortageError(this.state.buffer.length + 1, this.state.buffer.length, this.state.offset),
+        });
+        return out;
+    }
+    reset() {
+        this.state = { buffer: new Uint8Array(0), offset: 0 };
+        this.pendingFrame = null;
+    }
+    /**
+     * Core streaming loop.
+     * Keeps state machine behavior explicit: consume separators, parse a base
+     * frame, then greedily collect trailing attachment groups.
+     */
+    drain() {
+        const out = [];
+        while (this.state.buffer.length > 0) {
+            try {
+                this.consumeLeadingAno();
+                if (this.state.buffer.length === 0) {
+                    break;
+                }
+                if (this.pendingFrame) {
+                    if (!this.resumePendingFrame(out)) {
+                        break;
+                    }
+                    continue;
+                }
+                const base = this.parseFrame(this.state.buffer);
+                this.consume(base.consumed);
+                const attachments = [...base.frame.attachments];
+                const version = base.version;
+                let pausedForAttachmentShortage = false;
+                try {
+                    while (this.state.buffer.length > 0) {
+                        const nextCold = sniff(this.state.buffer);
+                        if (nextCold === "msg")
+                            break;
+                        if (nextCold === "ano") {
+                            this.consumeLeadingAno();
+                            continue;
+                        }
+                        if (!isAttachmentDomain(nextCold)) {
+                            throw new ColdStartError(`Unsupported attachment cold code ${nextCold}`);
+                        }
+                        const { group, consumed } = parseAttachmentGroup(this.state.buffer, version, nextCold, {
+                            mode: this.attachmentDispatchMode,
+                            onVersionFallback: this.onAttachmentVersionFallback,
+                        });
+                        attachments.push(group);
+                        this.consume(consumed);
+                        if (this.framed)
+                            break;
+                    }
+                }
+                catch (error) {
+                    if (error instanceof ShortageError) {
+                        this.pendingFrame = {
+                            frame: { serder: base.frame.serder, attachments },
+                            version,
+                        };
+                        pausedForAttachmentShortage = true;
+                    }
+                    else {
+                        throw error;
+                    }
+                }
+                if (pausedForAttachmentShortage) {
+                    break;
+                }
+                const completed = {
+                    serder: base.frame.serder,
+                    attachments,
+                };
+                if (!this.framed && attachments.length === 0 &&
+                    this.state.buffer.length === 0) {
+                    this.pendingFrame = { frame: completed, version };
+                    break;
+                }
+                out.push({ type: "frame", frame: completed });
+                if (this.framed)
+                    break;
+            }
+            catch (error) {
+                if (error instanceof ShortageError) {
+                    break;
+                }
+                const normalized = error instanceof ParserError
+                    ? error
+                    : new ParserError(String(error), this.state.offset);
+                out.push({ type: "error", error: normalized });
+                this.reset();
+                break;
+            }
+        }
+        return out;
+    }
+    resumePendingFrame(out) {
+        if (!this.pendingFrame)
+            return false;
+        if (this.state.buffer.length === 0)
+            return false;
+        const nextCold = sniff(this.state.buffer);
+        if (nextCold === "ano") {
+            this.consumeLeadingAno();
+            return this.state.buffer.length > 0;
+        }
+        if (nextCold === "msg") {
+            out.push({ type: "frame", frame: this.pendingFrame.frame });
+            this.pendingFrame = null;
+            return true;
+        }
+        if (!isAttachmentDomain(nextCold)) {
+            throw new ColdStartError(`Unsupported pending-frame continuation cold code ${nextCold}`);
+        }
+        if (this.pendingFrame.frame.serder.kind === Kinds.cesr) {
+            const peek = parseCounter(this.state.buffer, this.pendingFrame.version, nextCold);
+            if (BODY_WITH_ATTACH_CODES.has(peek.code) ||
+                NON_NATIVE_BODY_CODES.has(peek.code) ||
+                FIX_BODY_CODES.has(peek.code) ||
+                MAP_BODY_CODES.has(peek.code) ||
+                peek.code === GENUS_VERSION_CODE) {
+                out.push({ type: "frame", frame: this.pendingFrame.frame });
+                this.pendingFrame = null;
+                return true;
+            }
+        }
+        const { group, consumed } = parseAttachmentGroup(this.state.buffer, this.pendingFrame.version, nextCold, {
+            mode: this.attachmentDispatchMode,
+            onVersionFallback: this.onAttachmentVersionFallback,
+        });
+        this.pendingFrame.frame.attachments.push(group);
+        this.consume(consumed);
+        if (this.framed) {
+            out.push({ type: "frame", frame: this.pendingFrame.frame });
+            this.pendingFrame = null;
+            return false;
+        }
+        if (this.state.buffer.length === 0) {
+            return false;
+        }
+        const afterCold = sniff(this.state.buffer);
+        if (afterCold === "ano") {
+            this.consumeLeadingAno();
+            return this.state.buffer.length > 0;
+        }
+        if (afterCold === "msg") {
+            out.push({ type: "frame", frame: this.pendingFrame.frame });
+            this.pendingFrame = null;
+            return true;
+        }
+        return true;
+    }
+    consume(length) {
+        this.state.buffer = this.state.buffer.slice(length);
+        this.state.offset += length;
+    }
+    consumeLeadingAno() {
+        while (this.state.buffer.length > 0 && sniff(this.state.buffer) === "ano") {
+            this.consume(1);
+        }
+    }
+    /**
+     * Parse a single top-level frame start from current buffer head.
+     * Supports message-domain serders and CESR-native body groups.
+     */
+    parseFrame(input, inheritedVersion = DEFAULT_VERSION) {
+        let offset = 0;
+        let activeVersion = inheritedVersion;
+        let cold = sniff(input.slice(offset));
+        while (cold === "ano") {
+            offset += 1;
+            if (input.length <= offset) {
+                throw new ShortageError(offset + 1, input.length);
+            }
+            cold = sniff(input.slice(offset));
+        }
+        if (cold === "txt" || cold === "bny") {
+            const peek = parseCounter(input.slice(offset), activeVersion, cold);
+            if (peek.code === GENUS_VERSION_CODE) {
+                offset += tokenSize(peek, cold);
+                activeVersion = this.decodeVersionCounter(peek);
+                if (input.length <= offset) {
+                    throw new ShortageError(offset + 1, input.length);
+                }
+                cold = sniff(input.slice(offset));
+            }
+        }
+        if (cold === "msg") {
+            const { serder, consumed } = reapSerder(input.slice(offset));
+            return {
+                frame: { serder, attachments: [] },
+                consumed: offset + consumed,
+                version: serder.gvrsn ?? serder.pvrsn,
+            };
+        }
+        if (!isAttachmentDomain(cold)) {
+            throw new ColdStartError(`Expected message or CESR body group at frame start but got ${cold}`);
+        }
+        const counter = parseCounter(input.slice(offset), activeVersion, cold);
+        const headerSize = tokenSize(counter, cold);
+        const unit = quadletUnit(cold);
+        if (BODY_WITH_ATTACH_CODES.has(counter.code)) {
+            return this.parseBodyWithAttachmentGroup(input, offset, headerSize, counter.count, unit, activeVersion);
+        }
+        if (NON_NATIVE_BODY_CODES.has(counter.code)) {
+            return this.parseNonNativeBodyGroup(input, offset, headerSize, counter.count, unit, cold, activeVersion);
+        }
+        if (FIX_BODY_CODES.has(counter.code) || MAP_BODY_CODES.has(counter.code)) {
+            return this.parseNativeBodyGroup(input, offset, headerSize, counter.count, unit, cold, activeVersion, counter.code);
+        }
+        throw new ColdStartError(`Unsupported body-group counter at frame start: ${counter.code}`);
+    }
+    /** Parse wrapped body+attachments payloads as a complete nested frame. */
+    parseBodyWithAttachmentGroup(input, offset, headerSize, count, unit, version) {
+        const payloadSize = count * unit;
+        const total = headerSize + payloadSize;
+        if (input.length < offset + total) {
+            throw new ShortageError(offset + total, input.length);
+        }
+        const payload = input.slice(offset + headerSize, offset + total);
+        const nested = this.parseCompleteFrame(payload, version, false);
+        if (nested.consumed !== payload.length) {
+            throw new ColdStartError("BodyWithAttachmentGroup payload did not parse to a complete frame");
+        }
+        return {
+            frame: nested.frame,
+            consumed: offset + total,
+            version: nested.frame.serder.gvrsn ?? nested.frame.serder.pvrsn,
+        };
+    }
+    /** Parse a non-native body group; keep opaque fallback when serder reap fails. */
+    parseNonNativeBodyGroup(input, offset, headerSize, count, unit, cold, version) {
+        const matter = parseMatter(input.slice(offset + headerSize), cold);
+        const bodySize = tokenSize(matter, cold);
+        const payloadSize = count * unit;
+        if (payloadSize !== bodySize) {
+            throw new ColdStartError(`NonNativeBodyGroup payload size mismatch: expected=${payloadSize} actual=${bodySize}`);
+        }
+        try {
+            const { serder } = reapSerder(matter.raw);
+            return {
+                frame: { serder, attachments: [] },
+                consumed: offset + headerSize + bodySize,
+                version: serder.gvrsn ?? serder.pvrsn,
+            };
+        }
+        catch (_error) {
+            // Intentional recovery: NonNativeBodyGroup payload is opaque CESR body data.
+            // If it cannot be interpreted as a KERI/ACDC Serder, preserve bytes and
+            // continue with conservative metadata instead of failing the frame parse.
+            return {
+                frame: {
+                    serder: {
+                        raw: matter.raw,
+                        ked: null,
+                        proto: Protocols.keri,
+                        kind: Kinds.cesr,
+                        size: matter.raw.length,
+                        pvrsn: version,
+                        gvrsn: version,
+                        ilk: null,
+                        said: null,
+                    },
+                    attachments: [],
+                },
+                consumed: offset + headerSize + bodySize,
+                version,
+            };
+        }
+    }
+    /** Parse fixed/map native body groups and extract semantic native fields. */
+    parseNativeBodyGroup(input, offset, headerSize, count, unit, cold, version, bodyCode) {
+        const payloadSize = count * unit;
+        const total = headerSize + payloadSize;
+        if (input.length < offset + total) {
+            throw new ShortageError(offset + total, input.length);
+        }
+        const raw = input.slice(offset, offset + total);
+        const metadata = this.extractNativeMetadata(raw, cold, version);
+        const fields = this.extractNativeFields(raw, cold, version);
+        return {
+            frame: {
+                serder: {
+                    raw,
+                    ked: null,
+                    proto: metadata.proto,
+                    kind: Kinds.cesr,
+                    size: raw.length,
+                    pvrsn: metadata.pvrsn,
+                    gvrsn: metadata.gvrsn,
+                    ilk: metadata.ilk,
+                    said: metadata.said,
+                    native: {
+                        bodyCode,
+                        fields,
+                    },
+                },
+                attachments: [],
+            },
+            consumed: offset + total,
+            version,
+        };
+    }
+    /** Decode genus-version counter suffix to active CESR version. */
+    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");
+        const major = majorRaw === 1 ? 1 : 2;
+        return {
+            major,
+            minor: minorRaw,
+        };
+    }
+    /**
+     * Best-effort native metadata extraction.
+     * This is intentionally advisory and may recover instead of failing hard.
+     */
+    extractNativeMetadata(raw, cold, fallbackVersion) {
+        let offset = 0;
+        let proto = Protocols.keri;
+        let pvrsn = fallbackVersion;
+        let gvrsn = fallbackVersion;
+        let ilk = null;
+        let said = null;
+        try {
+            const bodyCounter = parseCounter(raw, fallbackVersion, cold);
+            offset += cold === "bny" ? bodyCounter.fullSizeB2 : bodyCounter.fullSize;
+            // In map-body mode, labels may appear between semantic fields.
+            // Metadata extraction skips those labels before reading core fields.
+            if (MAP_BODY_CODES.has(bodyCounter.code)) {
+                offset = this.skipNativeLabelers(raw, offset, cold);
+            }
+            const verser = parseVerser(raw.slice(offset), cold);
+            offset += tokenSize(verser, cold);
+            proto = verser.proto;
+            pvrsn = verser.pvrsn;
+            gvrsn = verser.gvrsn;
+            if (MAP_BODY_CODES.has(bodyCounter.code)) {
+                offset = this.skipNativeLabelers(raw, offset, cold);
+            }
+            const ilker = parseIlker(raw.slice(offset), cold);
+            offset += tokenSize(ilker, cold);
+            ilk = ilker.ilk;
+            if (MAP_BODY_CODES.has(bodyCounter.code)) {
+                offset = this.skipNativeLabelers(raw, offset, cold);
+            }
+            const saider = parseMatter(raw.slice(offset), cold);
+            if (saider.code.startsWith("E")) {
+                said = saider.qb64;
+            }
+        }
+        catch (_error) {
+            // Intentional recovery: native metadata extraction is advisory only.
+            // Strict token validation happens in extractNativeFields/mapper parsing.
+        }
+        return { proto, pvrsn, gvrsn, ilk, said };
+    }
+    /** Skip consecutive native label tokens (V/W) from an offset. */
+    skipNativeLabelers(raw, offset, cold) {
+        let out = offset;
+        while (out < raw.length) {
+            const item = parseMatter(raw.slice(out), cold);
+            if (!isLabelerCode(item.code)) {
+                break;
+            }
+            out += tokenSize(item, cold);
+        }
+        return out;
+    }
+    /** Strict native field extraction for annotation and higher-level processing. */
+    extractNativeFields(raw, cold, fallbackVersion) {
+        const bodyCounter = parseCounter(raw, fallbackVersion, cold);
+        if (MAP_BODY_CODES.has(bodyCounter.code)) {
+            const mapper = parseMapperBody(raw, fallbackVersion, cold);
+            return mapper.fields.map((field) => ({
+                label: field.label,
+                code: field.code,
+                qb64: field.qb64,
+            }));
+        }
+        const fields = [];
+        const total = tokenSize(bodyCounter, cold);
+        const payloadBytes = bodyCounter.count * quadletUnit(cold);
+        const start = total;
+        const end = start + payloadBytes;
+        let offset = start;
+        let pendingLabel = null;
+        while (offset < end) {
+            const at = raw.slice(offset, end);
+            const ctr = this.tryParseCounter(at, fallbackVersion, cold);
+            if (ctr) {
+                const size = tokenSize(ctr, cold);
+                offset += size;
+                fields.push({
+                    label: pendingLabel,
+                    code: ctr.code,
+                    qb64: ctr.qb64,
+                });
+                pendingLabel = null;
+                continue;
+            }
+            const token = parseMatter(at, cold);
+            const size = tokenSize(token, cold);
+            offset += size;
+            if (isLabelerCode(token.code)) {
+                pendingLabel = parseLabeler(at, cold).label;
+                continue;
+            }
+            fields.push({
+                label: pendingLabel,
+                code: token.code,
+                qb64: token.qb64,
+            });
+            pendingLabel = null;
+        }
+        if (offset !== end) {
+            throw new ShortageError(end, offset);
+        }
+        if (pendingLabel !== null) {
+            throw new ColdStartError("Dangling native map label without value");
+        }
+        return fields;
+    }
+    /** Counter probe with ordered version fallback; throws on shortage. */
+    tryParseCounter(input, version, cold) {
+        const attempts = [
+            version,
+            { major: 2, minor: 0 },
+            { major: 1, minor: 0 },
+        ];
+        for (const attempt of attempts) {
+            try {
+                return parseCounter(input, attempt, cold);
+            }
+            catch (error) {
+                if (error instanceof ShortageError) {
+                    throw error;
+                }
+                if (error instanceof UnknownCodeError ||
+                    error instanceof DeserializeError) {
+                    continue;
+                }
+                throw error;
+            }
+        }
+        return null;
+    }
+    /** Parse one complete frame plus optional attachments from a standalone slice. */
+    parseCompleteFrame(input, inheritedVersion = DEFAULT_VERSION, stopAtNextMessage = true) {
+        const base = this.parseFrame(input, inheritedVersion);
+        const version = base.version;
+        const attachments = [];
+        let offset = base.consumed;
+        while (offset < input.length) {
+            const nextCold = sniff(input.slice(offset));
+            if (nextCold === "ano") {
+                offset += 1;
+                continue;
+            }
+            if (nextCold === "msg") {
+                if (stopAtNextMessage)
+                    break;
+                throw new ColdStartError("Enclosed frame payload encountered unexpected nested message start");
+            }
+            if (!isAttachmentDomain(nextCold)) {
+                throw new ColdStartError(`Unsupported attachment cold code ${nextCold}`);
+            }
+            const { group, consumed } = parseAttachmentGroup(input.slice(offset), version, nextCold, {
+                mode: this.attachmentDispatchMode,
+                onVersionFallback: this.onAttachmentVersionFallback,
+            });
+            attachments.push(group);
+            offset += consumed;
+            if (this.framed)
+                break;
+        }
+        return {
+            frame: { serder: base.frame.serder, attachments },
+            consumed: offset,
+        };
+    }
+}
+export function createParser(options = {}) {
+    return new CesrParserCore(options);
+}
+export function parseBytes(bytes, options = {}) {
+    const parser = createParser(options);
+    return [...parser.feed(bytes), ...parser.flush()];
+}

package/esm/src/core/types.js

@@ -0,0 +1 @@
+export {};

package/esm/src/index.js

@@ -0,0 +1,46 @@
+export * from "./core/types.js";
+export * from "./core/errors.js";
+export * from "./core/parser-engine.js";
+export * from "./parser/cold-start.js";
+export * from "./parser/group-dispatch.js";
+export * from "./serder/smell.js";
+export * from "./serder/serder.js";
+export * from "./serder/serdery.js";
+export * from "./primitives/matter.js";
+export * from "./primitives/counter.js";
+export * from "./primitives/indexer.js";
+export * from "./primitives/verser.js";
+export * from "./primitives/ilker.js";
+export * from "./primitives/labeler.js";
+export * from "./primitives/texter.js";
+export * from "./primitives/bexter.js";
+export * from "./primitives/pather.js";
+export * from "./primitives/mapper.js";
+export * from "./primitives/number.js";
+export * from "./primitives/seqner.js";
+export * from "./primitives/dater.js";
+export * from "./primitives/diger.js";
+export * from "./primitives/prefixer.js";
+export * from "./primitives/noncer.js";
+export * from "./primitives/saider.js";
+export * from "./primitives/cigar.js";
+export * from "./primitives/verfer.js";
+export * from "./primitives/traitor.js";
+export * from "./primitives/tholder.js";
+export * from "./primitives/sealer.js";
+export * from "./primitives/blinder.js";
+export * from "./primitives/mediar.js";
+export * from "./primitives/compactor.js";
+export * from "./primitives/aggor.js";
+export * from "./primitives/registry.js";
+export * from "./adapters/async-iterable.js";
+export * from "./adapters/effection.js";
+export * from "./router/router-stub.js";
+export * from "./tables/versions.js";
+export * from "./tables/table-types.js";
+export * from "./tables/counter-codex.js";
+export * from "./annotate/types.js";
+export * from "./annotate/comments.js";
+export * from "./annotate/render.js";
+export * from "./annotate/annotator.js";
+export * from "./annotate/denot.js";

package/esm/src/parser/attachment-parser.js

@@ -0,0 +1,4 @@
+import { parseAttachmentDispatchCompat, } from "./group-dispatch.js";
+export function parseAttachmentGroup(input, version, domain, options = {}) {
+    return parseAttachmentDispatchCompat(input, version, domain, options);
+}

package/esm/src/parser/cold-start.js

@@ -0,0 +1,17 @@
+import { ColdStartError, ShortageError } from "../core/errors.js";
+export function sniff(ims) {
+    if (ims.length === 0) {
+        throw new ShortageError(1, 0);
+    }
+    const tritet = ims[0] >> 5;
+    if (tritet === 0o3 || tritet === 0o4 || tritet === 0o5 || tritet === 0o6) {
+        return "msg";
+    }
+    if (tritet === 0o1 || tritet === 0o2)
+        return "txt";
+    if (tritet === 0o7)
+        return "bny";
+    if (tritet === 0o0)
+        return "ano";
+    throw new ColdStartError(`Unexpected tritet=${tritet} at stream start`);
+}