keri-ts 0.10.0 → 0.10.2

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

@@ -1,644 +0,0 @@
-import { parseAttachmentGroup } from "../parser/attachment-parser.ts";
-import { sniff } from "../parser/cold-start.ts";
-import { parseCounter } from "../primitives/counter.ts";
-import { parseIlker } from "../primitives/ilker.ts";
-import { isLabelerCode, parseLabeler } from "../primitives/labeler.ts";
-import { interpretMapperBodySyntax, parseMapperBodySyntax } from "../primitives/mapper.ts";
-import { parseMatter } from "../primitives/matter.ts";
-import { parseVerser } from "../primitives/verser.ts";
-import { reapSerder } from "../serder/serdery.ts";
-import { Kinds, Protocols } from "../tables/versions.ts";
-import { b64ToInt, intToB64 } from "./bytes.ts";
-import { ColdStartError, DeserializeError, SemanticInterpretationError, ShortageError, SyntaxParseError, UnknownCodeError, } from "./errors.ts";
-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.ts";
-/**
- * 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) {
-            // Non-native body groups wrap one Matter primitive. If Serder hydration
-            // fails, expose the primitive body bytes only; callers that inspect the
-            // fallback should not see the surrounding group counter envelope.
-            const raw = matter.raw;
-            return {
-                frame: {
-                    body: {
-                        raw,
-                        ked: null,
-                        proto: Protocols.keri,
-                        kind: Kinds.cesr,
-                        size: 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);
-        // KERIpy parity rule: once the frame parser has classified a top-level
-        // FixBodyGroup/MapBodyGroup as a native message body, the result must be a
-        // real Serder or a parse error. Arbitrary native map/list corpora still
-        // belong to lower-level CESR-native surfaces such as Mapper/Aggor.
-        const { serder } = reapSerder(raw);
-        if (serder.proto !== metadata.proto
-            || serder.pvrsn.major !== metadata.pvrsn.major
-            || serder.pvrsn.minor !== metadata.pvrsn.minor
-            || (metadata.ilk !== null && serder.ilk !== metadata.ilk)
-            || (metadata.said !== null && serder.said !== metadata.said)) {
-            throw new SemanticInterpretationError("Native body syntax pre-read disagreed with Serder hydration");
-        }
-        serder.native = {
-            bodyCode,
-            fields,
-        };
-        const body = serder;
-        return {
-            frame: {
-                body,
-                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",
-                    primitive: ctr,
-                });
-                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,
-                    primitive: token,
-                });
-                continue;
-            }
-            entries.push({
-                kind: "value",
-                primitive: token,
-            });
-        }
-        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,
-                    primitive: field.primitive,
-                }));
-            }
-            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,
-                primitive: entry.primitive,
-            });
-            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");
-    }
-}