cesr-ts 0.2.3 → 0.3.1

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

@@ -0,0 +1,137 @@
+/**
+ * Greedy frame-boundary policy for `framed=false` mode.
+ *
+ * What:
+ * - continue draining as long as parse boundaries permit
+ * - continue collecting contiguous attachment groups in the same cycle
+ * - defer body-only end-of-buffer frames to preserve attachment lookahead
+ *
+ * Why:
+ * unframed mode prioritizes maximal parse progress and compatibility with
+ * legacy greedy continuation semantics.
+ */
+class GreedyFrameBoundaryPolicy {
+    /**
+     * Keep draining after one queued frame emission.
+     *
+     * Why `false`:
+     * greedy mode should emit all immediately available deferred siblings before
+     * returning control to the caller.
+     */
+    shouldStopAfterQueuedFrameEmission() {
+        return false;
+    }
+    /**
+     * Keep draining after one completed frame emission.
+     *
+     * Why `false`:
+     * unframed callers expect `feed()` to make as much deterministic progress as
+     * possible with currently buffered input.
+     */
+    shouldStopAfterCompletedFrameEmission() {
+        return false;
+    }
+    /**
+     * Keep collecting attachment groups until boundary/shortage.
+     *
+     * Why `false`:
+     * greedy mode intentionally aggregates all contiguous trailing attachment
+     * groups into one frame in the same drain cycle.
+     */
+    shouldStopAfterAttachmentGroupCollection() {
+        return false;
+    }
+    /**
+     * Do not emit pending frame immediately after one resumed attachment append.
+     *
+     * Why `false`:
+     * greedy continuation should keep waiting until a clear frame boundary is
+     * observed, so additional attachments can still be absorbed.
+     */
+    shouldEmitPendingAfterAttachmentResume() {
+        return false;
+    }
+    /**
+     * Defer body-only frame when no bytes remain.
+     *
+     * Why conditional `true`:
+     * when attachment count is zero and the buffer is exhausted, hold as pending
+     * to allow a following chunk to provide trailing attachments.
+     */
+    shouldDeferBodyOnlyFrame(attachmentCount, remainingBufferLength) {
+        return attachmentCount === 0 && remainingBufferLength === 0;
+    }
+}
+/**
+ * Bounded frame-boundary policy for `framed=true` mode.
+ *
+ * What:
+ * - enforce one bounded parser work unit per drain cycle
+ * - emit promptly instead of greedy continuation
+ *
+ * Why:
+ * framed mode exists for deterministic stepwise consumption by callers that
+ * interleave parsing with downstream processing.
+ */
+class BoundedFrameBoundaryPolicy {
+    /**
+     * Stop after one queued frame emission.
+     *
+     * Why `true`:
+     * framed mode caps per-cycle output to a single unit of deferred progress.
+     */
+    shouldStopAfterQueuedFrameEmission() {
+        return true;
+    }
+    /**
+     * Stop after one completed frame emission.
+     *
+     * Why `true`:
+     * preserves bounded cadence guarantees for framed consumers.
+     */
+    shouldStopAfterCompletedFrameEmission() {
+        return true;
+    }
+    /**
+     * Stop after one attachment-group collection step.
+     *
+     * Why `true`:
+     * bounded mode avoids greedy attachment accumulation and returns control after
+     * the first attachment parsing unit.
+     */
+    shouldStopAfterAttachmentGroupCollection() {
+        return true;
+    }
+    /**
+     * Emit pending frame immediately after one resumed attachment append.
+     *
+     * Why `true`:
+     * framed continuation is intentionally stepwise and should not retain pending
+     * once one bounded continuation step has succeeded.
+     */
+    shouldEmitPendingAfterAttachmentResume() {
+        return true;
+    }
+    /**
+     * Never defer body-only frame waiting for possible future attachments.
+     *
+     * Why `false`:
+     * framed mode emits completed units as soon as possible instead of applying
+     * greedy end-of-buffer hold behavior.
+     */
+    shouldDeferBodyOnlyFrame(_attachmentCount, _remainingBufferLength) {
+        return false;
+    }
+}
+/**
+ * Build default frame-boundary strategy from legacy parser options.
+ *
+ * Why:
+ * maintains backward compatibility for `framed` while allowing call sites to
+ * inject explicit `FrameBoundaryPolicy` implementations.
+ */
+export function createFrameBoundaryPolicy(framed = false) {
+    return framed
+        ? new BoundedFrameBoundaryPolicy()
+        : new GreedyFrameBoundaryPolicy();
+}

package/esm/src/core/parser-stream-state.js

@@ -0,0 +1,62 @@
+import { sniff } from "../parser/cold-start.js";
+import { concatBytes } from "./bytes.js";
+/**
+ * Owns mutable stream-level parser state (buffer, absolute offset, stream version).
+ *
+ * This class intentionally has no parse policy; it only provides deterministic
+ * state transitions used by parser orchestration.
+ */
+export class ParserStreamState {
+    /** Initialize stream state with the parser's default top-level version. */
+    constructor(initialVersion) {
+        Object.defineProperty(this, "state", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: { buffer: new Uint8Array(0), offset: 0 }
+        });
+        Object.defineProperty(this, "activeVersion", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        this.activeVersion = initialVersion;
+    }
+    /** Current unconsumed bytes. */
+    get buffer() {
+        return this.state.buffer;
+    }
+    /** Absolute consumed-byte offset (monotonic). */
+    get offset() {
+        return this.state.offset;
+    }
+    /** Active top-level stream version context. */
+    get streamVersion() {
+        return this.activeVersion;
+    }
+    /** Update active top-level stream version context. */
+    set streamVersion(version) {
+        this.activeVersion = version;
+    }
+    /** Append bytes to the buffered stream tail. */
+    append(chunk) {
+        this.state.buffer = concatBytes(this.state.buffer, chunk);
+    }
+    /** Consume a prefix from the buffer and advance absolute offset. */
+    consume(length) {
+        this.state.buffer = this.state.buffer.slice(length);
+        this.state.offset += length;
+    }
+    /** Consume all leading annotation-domain separator bytes (`ano`). */
+    consumeLeadingAno() {
+        while (this.state.buffer.length > 0 && sniff(this.state.buffer) === "ano") {
+            this.consume(1);
+        }
+    }
+    /** Reset buffer/offset/version to initial parser state. */
+    reset(initialVersion) {
+        this.state = { buffer: new Uint8Array(0), offset: 0 };
+        this.activeVersion = initialVersion;
+    }
+}

package/esm/src/core/recovery-diagnostics.js

@@ -0,0 +1,25 @@
+/**
+ * Compose diagnostics and legacy fallback callback observers.
+ *
+ * Why:
+ * keeps compatibility with legacy fallback callbacks while normalizing
+ * observability through one structured diagnostics stream.
+ */
+export function composeRecoveryDiagnosticObserver(options = {}) {
+    const { onRecoveryDiagnostic, onAttachmentVersionFallback, } = options;
+    if (!onRecoveryDiagnostic && !onAttachmentVersionFallback) {
+        return undefined;
+    }
+    return (diagnostic) => {
+        onRecoveryDiagnostic?.(diagnostic);
+        if (diagnostic.type !== "version-fallback-accepted") {
+            return;
+        }
+        onAttachmentVersionFallback?.({
+            from: diagnostic.from,
+            to: diagnostic.to,
+            domain: diagnostic.domain,
+            reason: diagnostic.reason,
+        });
+    };
+}

package/esm/src/index.js

@@ -1,6 +1,8 @@
 export * from "./core/types.js";
 export * from "./core/errors.js";
 export * from "./core/parser-engine.js";
+export * from "./core/parser-policy.js";
+export * from "./core/recovery-diagnostics.js";
 export * from "./parser/cold-start.js";
 export * from "./parser/group-dispatch.js";
 export * from "./serder/smell.js";
@@ -39,8 +41,10 @@ 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 "./tables/counter-version-registry.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";
+export * from "./bench/parser-benchmark.js";

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

@@ -0,0 +1,142 @@
+import { DeserializeError, UnknownCodeError } from "../core/errors.js";
+/**
+ * Classify parse failures that are safe for alternate-major retry.
+ *
+ * Why:
+ * only unknown-code and deserialize failures are treated as compatibility
+ * boundaries; structural/boundary errors should remain fail-fast.
+ */
+function isVersionFallbackError(error) {
+    return error instanceof UnknownCodeError || error instanceof DeserializeError;
+}
+/**
+ * Compute one-step alternate-major retry target.
+ *
+ * Why:
+ * compat behavior intentionally toggles between v1 and v2 majors and does not
+ * perform multi-step or minor-version search.
+ */
+function alternateMajorVersion(version) {
+    return version.major >= 2 ? { major: 1, minor: 0 } : { major: 2, minor: 0 };
+}
+/**
+ * Strict fallback policy.
+ *
+ * What:
+ * - no version retry
+ * - no wrapper opaque-tail recovery
+ *
+ * Why:
+ * strict mode is intended for parity/fail-fast validation where ambiguous
+ * compatibility recovery must not hide malformed or mixed-major input.
+ */
+class StrictAttachmentVersionFallbackPolicy {
+    /**
+     * Always reject retry and preserve original error.
+     *
+     * Why `throw`:
+     * strict policy must not reinterpret unknown/deserialize failures as
+     * compatibility drift.
+     */
+    onVersionDispatchFailure(_error, _version, _domain) {
+        return { action: "throw" };
+    }
+    /**
+     * No-op fallback observer.
+     *
+     * Why:
+     * strict policy never accepts fallback; observer is intentionally inert.
+     */
+    onVersionFallback(_info) {
+        // Strict policy never falls back; this is intentionally a no-op.
+    }
+    /**
+     * Disable wrapper opaque remainder preservation.
+     *
+     * Why `false`:
+     * strict mode must expose nested wrapper parse failures directly.
+     */
+    shouldPreserveWrapperRemainder(_error) {
+        return false;
+    }
+}
+/**
+ * Compatibility fallback policy.
+ *
+ * What:
+ * - retry unknown/deserialize failures on alternate major version
+ * - preserve unread wrapper remainder as opaque payload on recoverable errors
+ *
+ * Why:
+ * interop streams in the ecosystem can mix major-version counters/payloads, and
+ * compat mode intentionally favors successful parse continuity.
+ */
+class CompatAttachmentVersionFallbackPolicy {
+    /**
+     * @param fallbackObserver Optional callback for accepted fallback events.
+     */
+    constructor(fallbackObserver) {
+        Object.defineProperty(this, "fallbackObserver", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        this.fallbackObserver = fallbackObserver;
+    }
+    /**
+     * Retry only for compatibility-classified failures.
+     *
+     * Why conditional:
+     * unknown/deserialize errors often indicate major-table mismatch; other error
+     * classes generally represent structural issues that should not be retried.
+     */
+    onVersionDispatchFailure(error, version, domain) {
+        if (!isVersionFallbackError(error)) {
+            return { action: "throw" };
+        }
+        const retryVersion = alternateMajorVersion(version);
+        return {
+            action: "retry",
+            retryVersion,
+            info: {
+                from: version,
+                to: retryVersion,
+                domain,
+                reason: error.message,
+            },
+        };
+    }
+    /**
+     * Emit fallback event through optional callback.
+     *
+     * Why:
+     * keeps observability side effects caller-controlled.
+     */
+    onVersionFallback(info) {
+        this.fallbackObserver?.(info);
+    }
+    /**
+     * Preserve unread wrapper payload as opaque units.
+     *
+     * Why `true`:
+     * compat mode intentionally tolerates nested wrapper irregularities and
+     * retains undecoded remainder for downstream visibility.
+     */
+    shouldPreserveWrapperRemainder(_error) {
+        return true;
+    }
+}
+/**
+ * Build default fallback strategy from legacy options.
+ *
+ * Why:
+ * preserves backward-compatible `mode` API while allowing explicit policy
+ * injection for new call sites.
+ */
+export function createAttachmentVersionFallbackPolicy(options = {}) {
+    const mode = options.mode ?? "compat";
+    return mode === "strict"
+        ? new StrictAttachmentVersionFallbackPolicy()
+        : new CompatAttachmentVersionFallbackPolicy(options.onVersionFallback);
+}