cesr-ts 0.2.3 → 0.3.1

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

@@ -0,0 +1,643 @@
+import { parseAttachmentGroup } from "../parser/attachment-parser.js";
+import { sniff } from "../parser/cold-start.js";
+import { parseCounter } from "../primitives/counter.js";
+import { parseIlker } from "../primitives/ilker.js";
+import { isLabelerCode, parseLabeler } from "../primitives/labeler.js";
+import { parseMatter } from "../primitives/matter.js";
+import { interpretMapperBodySyntax, parseMapperBodySyntax, } from "../primitives/mapper.js";
+import { parseVerser } from "../primitives/verser.js";
+import { reapSerder } from "../serder/serdery.js";
+import { Kinds, Protocols } from "../tables/versions.js";
+import { b64ToInt, intToB64 } from "./bytes.js";
+import { ColdStartError, DeserializeError, SemanticInterpretationError, ShortageError, SyntaxParseError, UnknownCodeError, } from "./errors.js";
+import { BODY_WITH_ATTACHMENT_GROUP_NAMES, DEFAULT_VERSION, FRAME_START_GROUP_NAMES, GENERIC_GROUP_NAMES, GENUS_VERSION_CODE, isAttachmentDomain, isFrameBoundaryCounter, MAP_BODY_CODES, NATIVE_BODY_GROUP_NAMES, NON_NATIVE_BODY_GROUP_NAMES, quadletUnit, tokenSize, } from "./parser-constants.js";
+/**
+ * Parses frame starts and bounded frame payload structures.
+ *
+ * Responsibilities:
+ * - resolve frame-start forms (`msg`, native/body groups, wrappers)
+ * - preserve version-scope semantics for stream and nested payloads
+ * - emit enclosed GenericGroup siblings through callback for deferred handling
+ */
+export class FrameParser {
+    constructor(options) {
+        Object.defineProperty(this, "frameBoundaryPolicy", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "attachmentVersionFallbackPolicy", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "onEnclosedFrames", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "recoveryDiagnosticObserver", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        this.frameBoundaryPolicy = options.frameBoundaryPolicy;
+        this.attachmentVersionFallbackPolicy =
+            options.attachmentVersionFallbackPolicy;
+        this.onEnclosedFrames = options.onEnclosedFrames;
+        this.recoveryDiagnosticObserver = options.recoveryDiagnosticObserver;
+    }
+    /** Probe whether the next token is a top-level frame boundary counter. */
+    isFrameBoundaryAhead(input, version, cold) {
+        const peek = this.tryParseCounter(input, version, cold);
+        return peek !== null && isFrameBoundaryCounter(peek);
+    }
+    /**
+     * Parse one frame start from the current head.
+     * Does not parse trailing top-level attachments.
+     */
+    parseFrame(input, inheritedVersion = DEFAULT_VERSION) {
+        const syntax = this.parseFrameStartSyntax(input, inheritedVersion);
+        return this.interpretFrameStartSyntax(input, syntax);
+    }
+    /**
+     * Parse frame-start tokens into a syntax artifact.
+     *
+     * Non-goal: this is not a global two-pass parser rewrite. It only separates
+     * the highest-coupling frame-start syntax extraction from semantic dispatch.
+     */
+    parseFrameStartSyntax(input, inheritedVersion) {
+        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") {
+            return {
+                kind: "message",
+                offset,
+                cold,
+                streamVersion: activeVersion,
+            };
+        }
+        if (!isAttachmentDomain(cold)) {
+            throw new ColdStartError(`Expected message or CESR body group at frame start but got ${cold}`);
+        }
+        const { counter, version: frameVersion, } = this.resolveFrameStartCounter(input.slice(offset), activeVersion, cold);
+        const headerSize = tokenSize(counter, cold);
+        const unit = quadletUnit(cold);
+        if (BODY_WITH_ATTACHMENT_GROUP_NAMES.has(counter.name)) {
+            return {
+                kind: "bodyWithAttachmentGroup",
+                offset,
+                cold,
+                streamVersion: frameVersion,
+                counter,
+                frameVersion,
+                headerSize,
+                unit,
+            };
+        }
+        if (NON_NATIVE_BODY_GROUP_NAMES.has(counter.name)) {
+            return {
+                kind: "nonNativeBodyGroup",
+                offset,
+                cold,
+                streamVersion: frameVersion,
+                counter,
+                frameVersion,
+                headerSize,
+                unit,
+            };
+        }
+        if (NATIVE_BODY_GROUP_NAMES.has(counter.name)) {
+            return {
+                kind: "nativeBodyGroup",
+                offset,
+                cold,
+                streamVersion: frameVersion,
+                counter,
+                frameVersion,
+                headerSize,
+                unit,
+            };
+        }
+        if (GENERIC_GROUP_NAMES.has(counter.name)) {
+            return {
+                kind: "genericGroup",
+                offset,
+                cold,
+                streamVersion: frameVersion,
+                counter,
+                frameVersion,
+                headerSize,
+                unit,
+            };
+        }
+        throw new ColdStartError(`Unsupported body-group counter at frame start: ${counter.code}`);
+    }
+    /** Interpret frame-start syntax artifacts into semantic parse behavior. */
+    interpretFrameStartSyntax(input, syntax) {
+        const requireGroupMetadata = () => {
+            const counter = syntax.counter;
+            const frameVersion = syntax.frameVersion;
+            const headerSize = syntax.headerSize;
+            const unit = syntax.unit;
+            if (!counter || !frameVersion || !headerSize || !unit) {
+                throw new SemanticInterpretationError("Frame-start syntax artifact missing required group metadata");
+            }
+            return { counter, frameVersion, headerSize, unit };
+        };
+        switch (syntax.kind) {
+            case "message": {
+                const { serder, consumed } = reapSerder(input.slice(syntax.offset));
+                return {
+                    frame: { body: serder, attachments: [] },
+                    consumed: syntax.offset + consumed,
+                    version: serder.gvrsn ?? serder.pvrsn,
+                    streamVersion: serder.gvrsn ?? serder.pvrsn,
+                };
+            }
+            case "bodyWithAttachmentGroup": {
+                const { counter, frameVersion, headerSize, unit } = requireGroupMetadata();
+                return this.parseBodyWithAttachmentGroup(input, syntax.offset, headerSize, counter.count, unit, frameVersion, syntax.streamVersion);
+            }
+            case "nonNativeBodyGroup": {
+                if (syntax.cold !== "txt" && syntax.cold !== "bny") {
+                    throw new SemanticInterpretationError(`Expected attachment domain for non-native body but got ${syntax.cold}`);
+                }
+                const { counter, frameVersion, headerSize, unit } = requireGroupMetadata();
+                return this.parseNonNativeBodyGroup(input, syntax.offset, headerSize, counter.count, unit, syntax.cold, frameVersion, syntax.streamVersion);
+            }
+            case "nativeBodyGroup": {
+                if (syntax.cold !== "txt" && syntax.cold !== "bny") {
+                    throw new SemanticInterpretationError(`Expected attachment domain for native body but got ${syntax.cold}`);
+                }
+                const { counter, frameVersion, headerSize, unit } = requireGroupMetadata();
+                return this.parseNativeBodyGroup(input, syntax.offset, headerSize, counter.count, unit, syntax.cold, frameVersion, counter.code, syntax.streamVersion);
+            }
+            case "genericGroup": {
+                const { counter, frameVersion, headerSize, unit } = requireGroupMetadata();
+                return this.parseGenericGroup(input, syntax.offset, headerSize, counter.count, unit, frameVersion, syntax.streamVersion);
+            }
+        }
+    }
+    /** Parse nested `BodyWithAttachmentGroup` payload as one complete enclosed frame. */
+    parseBodyWithAttachmentGroup(input, offset, headerSize, count, unit, version, streamVersion) {
+        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.body.gvrsn ?? nested.frame.body.pvrsn, // fallback to pvrsn is a v1 fallback compatibility heuristic
+            streamVersion,
+        };
+    }
+    /**
+     * Parse `NonNativeBodyGroup` payload, preserving opaque-body fallback behavior
+     * when Serder decode is not possible.
+     * Returns only a body object (Serder) with no attachments.
+     */
+    parseNonNativeBodyGroup(input, offset, headerSize, count, unit, cold, version, streamVersion) {
+        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: { body: serder, attachments: [] },
+                consumed: offset + headerSize + bodySize,
+                version: serder.gvrsn ?? serder.pvrsn,
+                streamVersion,
+            };
+        }
+        catch (_error) {
+            return {
+                frame: {
+                    body: {
+                        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,
+                streamVersion,
+            };
+        }
+    }
+    /** Parse native fixed/map body group and extract metadata/native fields. */
+    parseNativeBodyGroup(input, offset, headerSize, count, unit, cold, version, bodyCode, streamVersion) {
+        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 syntax = this.parseNativeBodySyntax(raw, cold, version);
+        const metadata = this.interpretNativeMetadataSyntax(syntax.metadata, version);
+        const fields = this.interpretNativeFieldSyntax(syntax.fields);
+        return {
+            frame: {
+                body: {
+                    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,
+            streamVersion,
+        };
+    }
+    /**
+     * Parse bounded `GenericGroup` payload into enclosed frames.
+     * Returns first frame and reports remaining siblings via callback.
+     */
+    parseGenericGroup(input, offset, headerSize, count, unit, version, streamVersion) {
+        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 frames = this.parseFrameSequence(payload, version);
+        if (frames.length === 0) {
+            throw new ColdStartError("GenericGroup payload contained no enclosed frames");
+        }
+        const [first, ...rest] = frames;
+        if (rest.length > 0) {
+            this.onEnclosedFrames(rest);
+        }
+        return {
+            frame: first,
+            consumed: offset + total,
+            version: first.body.gvrsn ?? first.body.pvrsn,
+            streamVersion,
+        };
+    }
+    /** Parse all enclosed frames inside a bounded payload slice, in order. */
+    parseFrameSequence(input, inheritedVersion) {
+        const out = [];
+        let offset = 0;
+        let activeVersion = inheritedVersion;
+        while (offset < input.length) {
+            while (offset < input.length && sniff(input.slice(offset)) === "ano") {
+                offset += 1;
+            }
+            if (offset >= input.length) {
+                break;
+            }
+            const base = this.parseFrame(input.slice(offset), activeVersion);
+            offset += base.consumed;
+            const frameVersion = base.version;
+            const streamVersion = base.streamVersion;
+            const attachments = [...base.frame.attachments];
+            // greedily parse attachment groups until offset == input.length
+            while (offset < input.length) {
+                const nextCold = sniff(input.slice(offset));
+                if (nextCold === "ano") {
+                    offset += 1;
+                    continue;
+                }
+                if (nextCold === "msg") {
+                    break;
+                }
+                if (!isAttachmentDomain(nextCold)) {
+                    throw new ColdStartError(`Unsupported attachment cold code ${nextCold}`);
+                }
+                if (this.isFrameBoundaryAhead(input.slice(offset), streamVersion, nextCold)) {
+                    break;
+                }
+                const { group, consumed } = parseAttachmentGroup(input.slice(offset), frameVersion, nextCold, {
+                    versionFallbackPolicy: this.attachmentVersionFallbackPolicy,
+                    onRecoveryDiagnostic: this.recoveryDiagnosticObserver,
+                });
+                attachments.push(group);
+                offset += consumed;
+            }
+            out.push({
+                body: base.frame.body,
+                attachments,
+            });
+            activeVersion = base.streamVersion;
+        }
+        return out;
+    }
+    /** Parse one complete frame from a bounded slice, including trailing attachments. */
+    parseCompleteFrame(input, inheritedVersion = DEFAULT_VERSION, stopAtNextMessage = true) {
+        const base = this.parseFrame(input, inheritedVersion);
+        const version = base.version;
+        const attachments = [...base.frame.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, {
+                versionFallbackPolicy: this.attachmentVersionFallbackPolicy,
+                onRecoveryDiagnostic: this.recoveryDiagnosticObserver,
+            });
+            attachments.push(group);
+            offset += consumed;
+            if (this.frameBoundaryPolicy.shouldStopAfterAttachmentGroupCollection()) {
+                break;
+            }
+        }
+        return {
+            frame: { body: base.frame.body, attachments },
+            consumed: offset,
+        };
+    }
+    /** Decode a genus-version counter token into major/minor Versionage values. */
+    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,
+        };
+    }
+    /** Build native-body syntax artifacts used by semantic interpretation phase. */
+    parseNativeBodySyntax(raw, cold, fallbackVersion) {
+        try {
+            const bodyCounter = parseCounter(raw, fallbackVersion, cold);
+            return {
+                metadata: this.parseNativeMetadataSyntax(raw, cold, fallbackVersion, bodyCounter.code),
+                fields: this.parseNativeFieldSyntax(raw, cold, fallbackVersion, bodyCounter.code),
+            };
+        }
+        catch (error) {
+            if (error instanceof ShortageError ||
+                error instanceof UnknownCodeError ||
+                error instanceof DeserializeError) {
+                throw new SyntaxParseError(`Native body syntax parse failed: ${error.message}`, error);
+            }
+            throw error;
+        }
+    }
+    /** Parse advisory native metadata tokens without semantic projection. */
+    parseNativeMetadataSyntax(raw, cold, fallbackVersion, bodyCode) {
+        const out = {};
+        let offset = 0;
+        try {
+            const bodyCounter = parseCounter(raw, fallbackVersion, cold);
+            offset += tokenSize(bodyCounter, cold);
+            if (MAP_BODY_CODES.has(bodyCode)) {
+                offset = this.skipNativeLabelers(raw, offset, cold);
+            }
+            out.verser = parseVerser(raw.slice(offset), cold);
+            offset += tokenSize(out.verser, cold);
+            if (MAP_BODY_CODES.has(bodyCode)) {
+                offset = this.skipNativeLabelers(raw, offset, cold);
+            }
+            out.ilker = parseIlker(raw.slice(offset), cold);
+            offset += tokenSize(out.ilker, cold);
+            if (MAP_BODY_CODES.has(bodyCode)) {
+                offset = this.skipNativeLabelers(raw, offset, cold);
+            }
+            out.saider = parseMatter(raw.slice(offset), cold);
+        }
+        catch (_error) {
+            // metadata parse remains advisory; do not fail native-body parse when absent.
+        }
+        return out;
+    }
+    /** Interpret advisory metadata syntax into projected body metadata fields. */
+    interpretNativeMetadataSyntax(syntax, fallbackVersion) {
+        return {
+            proto: syntax.verser?.proto ?? Protocols.keri,
+            pvrsn: syntax.verser?.pvrsn ?? fallbackVersion,
+            gvrsn: syntax.verser?.gvrsn ?? fallbackVersion,
+            ilk: syntax.ilker?.ilk ?? null,
+            said: syntax.saider?.code.startsWith("E") ? syntax.saider.qb64 : null,
+        };
+    }
+    /** Parse native field tokens without resolving label/value pairing semantics. */
+    parseNativeFieldSyntax(raw, cold, fallbackVersion, bodyCode) {
+        if (MAP_BODY_CODES.has(bodyCode)) {
+            return {
+                kind: "map",
+                mapper: parseMapperBodySyntax(raw, fallbackVersion, cold),
+            };
+        }
+        const bodyCounter = parseCounter(raw, fallbackVersion, cold);
+        const total = tokenSize(bodyCounter, cold);
+        const payloadBytes = bodyCounter.count * quadletUnit(cold);
+        const start = total;
+        const end = start + payloadBytes;
+        const entries = [];
+        let offset = start;
+        while (offset < end) {
+            const at = raw.slice(offset, end);
+            const ctr = this.tryParseCounter(at, fallbackVersion, cold);
+            if (ctr) {
+                const size = tokenSize(ctr, cold);
+                entries.push({
+                    kind: "value",
+                    code: ctr.code,
+                    qb64: ctr.qb64,
+                });
+                offset += size;
+                continue;
+            }
+            const token = parseMatter(at, cold);
+            const size = tokenSize(token, cold);
+            offset += size;
+            if (isLabelerCode(token.code)) {
+                entries.push({
+                    kind: "label",
+                    label: parseLabeler(at, cold).label,
+                    code: token.code,
+                    qb64: token.qb64,
+                });
+                continue;
+            }
+            entries.push({
+                kind: "value",
+                code: token.code,
+                qb64: token.qb64,
+            });
+        }
+        if (offset !== end) {
+            throw new ShortageError(end, offset);
+        }
+        return { kind: "fixed", entries };
+    }
+    /** Interpret native field syntax into semantic fields with label/value pairing. */
+    interpretNativeFieldSyntax(syntax) {
+        if (syntax.kind === "map") {
+            try {
+                return interpretMapperBodySyntax(syntax.mapper).map((field) => ({
+                    label: field.label,
+                    code: field.code,
+                    qb64: field.qb64,
+                }));
+            }
+            catch (error) {
+                if (error instanceof SemanticInterpretationError) {
+                    throw new SemanticInterpretationError(`Native body semantic interpretation failed: ${error.message}`, error);
+                }
+                throw error;
+            }
+        }
+        const out = [];
+        let pendingLabel = null;
+        for (const entry of syntax.entries) {
+            if (entry.kind === "label") {
+                pendingLabel = entry.label;
+                continue;
+            }
+            out.push({
+                label: pendingLabel,
+                code: entry.code,
+                qb64: entry.qb64,
+            });
+            pendingLabel = null;
+        }
+        if (pendingLabel !== null) {
+            throw new SemanticInterpretationError("Dangling native map label without value");
+        }
+        return out;
+    }
+    /** Skip consecutive labeler tokens in native map-body parsing context. */
+    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;
+    }
+    /** Probe parseCounter with ordered major-version fallback. */
+    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;
+    }
+    /** Resolve a valid frame-start counter, preferring current stream major version. */
+    resolveFrameStartCounter(input, preferredVersion, cold) {
+        const alternate = preferredVersion.major >= 2
+            ? { major: 1, minor: 0 }
+            : { major: 2, minor: 0 };
+        const attempts = [preferredVersion, alternate];
+        let firstParsed = null;
+        let firstError = null;
+        for (const attempt of attempts) {
+            try {
+                const counter = parseCounter(input, attempt, cold);
+                if (!firstParsed) {
+                    firstParsed = { counter, version: attempt };
+                }
+                if (FRAME_START_GROUP_NAMES.has(counter.name)) {
+                    return { counter, version: attempt };
+                }
+            }
+            catch (error) {
+                if (error instanceof ShortageError) {
+                    throw error;
+                }
+                if (error instanceof UnknownCodeError ||
+                    error instanceof DeserializeError) {
+                    if (!firstError) {
+                        firstError = error;
+                    }
+                    continue;
+                }
+                throw error;
+            }
+        }
+        if (firstParsed) {
+            return firstParsed;
+        }
+        if (firstError) {
+            throw firstError;
+        }
+        throw new ColdStartError("Unable to resolve frame-start counter");
+    }
+}