prefix-safe-json 0.1.0 → 0.2.0

package/dist/gate/gate.d.ts

@@ -0,0 +1,25 @@
+import { CoordinatorLimits, JsonSchemaLike } from "../coordinator/types.js";
+import { ParserOptions } from "../types.js";
+import { ToolCallExecutionGate } from "./types.js";
+/**
+ * Creates a fail-closed execution-decision gate for streamed LLM tool calls.
+ * Wraps a `ToolCallStreamCoordinator` (same constructor arguments) and adds
+ * exactly one operation: turn each call's settled state into an
+ * `ExecutionDecision` (`execute` / `retry` / `reject`) via a deterministic,
+ * fully-typed decision table. See `docs/EXECUTION_GATE.md`.
+ *
+ * ```ts
+ * const gate = createToolCallExecutionGate(undefined, undefined, {
+ *   write_file: { type: "object", required: ["path", "content"], properties: {
+ *     path: { type: "string" }, content: { type: "string" } } },
+ * });
+ * for (const raw of providerEvents) {
+ *   for (const normalized of adapter.push(raw)) gate.push(normalized);
+ * }
+ * for (const decision of gate.finish().decisions) {
+ *   if (decision.action === "execute") await tools[decision.name](decision.value);
+ * }
+ * ```
+ */
+export declare function createToolCallExecutionGate(limits?: Partial<CoordinatorLimits>, parserOptions?: ParserOptions, toolSchemas?: Record<string, JsonSchemaLike>): ToolCallExecutionGate;
+//# sourceMappingURL=gate.d.ts.map

package/dist/gate/gate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gate.d.ts","sourceRoot":"","sources":["../../src/gate/gate.ts"],"names":[],"mappings":"AAWA,OAAO,EACL,iBAAiB,EAEjB,cAAc,EAGf,MAAM,yBAAyB,CAAC;AAEjC,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAE5C,OAAO,EAEL,qBAAqB,EAEtB,MAAM,YAAY,CAAC;AA+EpB;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,2BAA2B,CACzC,MAAM,CAAC,EAAE,OAAO,CAAC,iBAAiB,CAAC,EACnC,aAAa,CAAC,EAAE,aAAa,EAC7B,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,GAC3C,qBAAqB,CAEvB"}

package/dist/gate/gate.js

@@ -0,0 +1,96 @@
+// ---------------------------------------------------------------------------
+// ToolCallExecutionGate — high-level execution safety layer.
+//
+// Built by composition over ToolCallStreamCoordinator, not by extending or
+// reimplementing it: the gate holds a coordinator instance and adds exactly
+// one thing coordinator state doesn't already capture - which stream-end
+// reason actually got applied - then maps every ToolCallState through the
+// pure decideExecution() table. No re-parsing, no duplicate event pipeline.
+// ---------------------------------------------------------------------------
+import { createToolCallStreamCoordinator } from "../coordinator/coordinator.js";
+import { decideExecution } from "./decide.js";
+class DefaultToolCallExecutionGate {
+    coordinator;
+    // Mirrors the coordinator's own "first provider_stream_end (from push(),
+    // or from finish()'s meta if none arrived) wins" rule - see push()/finish()
+    // below and DefaultToolCallStreamCoordinator.finish()'s matching
+    // `if (!this.isFinished)` guard. streamEndProviderReason is captured
+    // alongside streamEndReason purely for DecisionEvidence.providerReason -
+    // it is never read by decideExecution()'s own logic.
+    streamEndReason;
+    streamEndProviderReason;
+    streamEndCaptured = false;
+    constructor(limits, parserOptions, toolSchemas) {
+        this.coordinator = createToolCallStreamCoordinator(limits, parserOptions, toolSchemas);
+    }
+    push(event) {
+        if (event.type === "provider_stream_end" && !this.streamEndCaptured) {
+            this.streamEndCaptured = true;
+            this.streamEndReason = event.reason;
+            this.streamEndProviderReason = event.providerReason;
+        }
+        return this.coordinator.push(event);
+    }
+    snapshot() {
+        const snap = this.coordinator.snapshot();
+        const ctx = {
+            // Pre-finish, no stream-end reason has been observed yet ("unknown"
+            // is a neutral placeholder here, not a claim anything went wrong) -
+            // every in-flight call is still "collecting" regardless, so this
+            // never influences whether something looks executable.
+            streamEndReason: this.streamEndReason ?? "unknown",
+            streamEndProviderReason: this.streamEndProviderReason,
+            diagnostics: snap.diagnostics,
+        };
+        return snap.calls.map((call) => decideExecution(call, ctx));
+    }
+    drainEvents() {
+        return this.coordinator.drainEvents();
+    }
+    finish(meta) {
+        if (!this.streamEndCaptured) {
+            this.streamEndCaptured = true;
+            this.streamEndReason = meta?.reason ?? "unknown";
+            this.streamEndProviderReason = meta?.providerReason;
+        }
+        const result = this.coordinator.finish(meta);
+        const diagnostics = this.coordinator.snapshot().diagnostics;
+        // Unlike snapshot() above, this point is only ever reached after
+        // streamEndCaptured is guaranteed true (set on entry to this method, or
+        // already true from an earlier push()/finish() call) - and every path
+        // that sets streamEndCaptured sets streamEndReason to a defined value in
+        // the same branch, so the pre-finish "unknown" placeholder never applies
+        // here.
+        const ctx = {
+            streamEndReason: this.streamEndReason,
+            streamEndProviderReason: this.streamEndProviderReason,
+            diagnostics,
+        };
+        const decisions = result.calls.map((call) => decideExecution(call, ctx));
+        return { decisions, diagnostics };
+    }
+}
+/**
+ * Creates a fail-closed execution-decision gate for streamed LLM tool calls.
+ * Wraps a `ToolCallStreamCoordinator` (same constructor arguments) and adds
+ * exactly one operation: turn each call's settled state into an
+ * `ExecutionDecision` (`execute` / `retry` / `reject`) via a deterministic,
+ * fully-typed decision table. See `docs/EXECUTION_GATE.md`.
+ *
+ * ```ts
+ * const gate = createToolCallExecutionGate(undefined, undefined, {
+ *   write_file: { type: "object", required: ["path", "content"], properties: {
+ *     path: { type: "string" }, content: { type: "string" } } },
+ * });
+ * for (const raw of providerEvents) {
+ *   for (const normalized of adapter.push(raw)) gate.push(normalized);
+ * }
+ * for (const decision of gate.finish().decisions) {
+ *   if (decision.action === "execute") await tools[decision.name](decision.value);
+ * }
+ * ```
+ */
+export function createToolCallExecutionGate(limits, parserOptions, toolSchemas) {
+    return new DefaultToolCallExecutionGate(limits, parserOptions, toolSchemas);
+}
+//# sourceMappingURL=gate.js.map

package/dist/gate/gate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"gate.js","sourceRoot":"","sources":["../../src/gate/gate.ts"],"names":[],"mappings":"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"}

package/dist/gate/types.d.ts

@@ -0,0 +1,184 @@
+import { JsonValue, Diagnostic } from "../types.js";
+import { CoordinatorDiagnostic, CoordinatorPushResult, ToolCallCoordinatorEvent } from "../coordinator/types.js";
+import { NormalizedToolStreamEvent, ProviderName, StreamEndReason } from "../coordinator/protocol.js";
+/**
+ * What to do with a tool call right now.
+ *
+ * - `"execute"`: the arguments are complete, unfabricated, and (if a schema
+ *   was registered for this tool) schema-valid. Safe to run.
+ * - `"retry"`: the provider's output was incomplete or truncated. There is
+ *   nothing wrong with the data received so far - there just isn't a
+ *   trustworthy complete value yet. Re-request/continue generation.
+ * - `"reject"`: the data itself is the problem (malformed JSON, a schema
+ *   mismatch, a resource limit, a provider-side error, or a content-policy
+ *   termination). Re-sending the exact same partial input will not fix it.
+ */
+export type ExecutionAction = "execute" | "retry" | "reject";
+/**
+ * Machine-readable classification of *why* an `ExecutionAction` was chosen.
+ * See `docs/EXECUTION_GATE.md` for the full decision table.
+ */
+export type ExecutionReason = "complete" | "truncated" | "stream_incomplete" | "schema_invalid" | "malformed" | "resource_limit" | "provider_error" | "content_filtered" | "sdk_execution_observed" | "unknown";
+/**
+ * Why a decision came out the way it did - observability, not a second
+ * decision input. Every field here is read-only, derived state already held
+ * elsewhere (`ToolCallState`, the stream-level `DecisionContext`); nothing
+ * on this object ever feeds back into `decideExecution()`'s own logic, and
+ * changing what it reports can never change `action`/`executable`/`reason`.
+ *
+ * Deliberately excludes anything that would require new cross-layer
+ * plumbing to derive reliably (e.g. a received-chunk count - the parser
+ * only tracks cumulative bytes, not `push()` call counts, and adding that
+ * tracking purely to populate a metric here was judged not worth the
+ * coupling for this release).
+ */
+export interface DecisionEvidence {
+    /** Which provider adapter produced this call (`ToolCallState.provider`). */
+    readonly provider: ProviderName;
+    /**
+     * The provider's own, pre-normalization finish/stop reason string, when
+     * the stream-ending event carried one (e.g. `"length"`, `"max_output_tokens"`,
+     * `"content_filter"`). `undefined` when the stream never reported one, or
+     * reported one without a `providerReason` (e.g. a default `finish()` call
+     * with no `meta`).
+     */
+    readonly providerReason?: string;
+    /** The normalized, library-level stream-end reason applied to this call. */
+    readonly streamEndReason: StreamEndReason;
+    /**
+     * Whether a real `provider_stream_end` reason was ever observed, as
+     * opposed to the neutral `"unknown"` default a gate reports before any
+     * stream-end signal has arrived at all. `true` here does NOT mean the
+     * reason was safe - a confirmed `"length"` still has `terminalConfirmed:
+     * true` - only that the stream's end state is genuinely known rather than
+     * merely unclassified or never observed.
+     */
+    readonly terminalConfirmed: boolean;
+    /**
+     * Whether the parser's root JSON container actually closed
+     * (`ToolCallState.parser.rootComplete`) - independent of whether that
+     * closure was genuine or reached via a safe-close repair, and independent
+     * of whether the stream-end reason makes it trustworthy. A syntactically
+     * complete value cut short by `length` has `structurallyComplete: true`
+     * and `parserExecutable: false` at the same time - that combination *is*
+     * the scenario this library exists to catch.
+     */
+    readonly structurallyComplete: boolean;
+    /** `ToolCallState.parser.executable`, verbatim - the parser's own fail-closed verdict. */
+    readonly parserExecutable: boolean;
+    /**
+     * `ToolCallState.schemaValid`, verbatim. `undefined` when no schema was
+     * registered for this tool, or the call never reached a structurally
+     * complete outcome.
+     */
+    readonly schemaValid?: boolean;
+    /** Total bytes received for this call's argument stream (`ToolCallState.parser.receivedBytes`). */
+    readonly receivedBytes: number;
+}
+interface ExecutionDecisionCommon {
+    /** The coordinator's internal call identifier (see `ToolCallState.internalId`). */
+    readonly internalId: string;
+    readonly toolCallId?: string;
+    readonly toolIndex?: number;
+    readonly name?: string;
+    /**
+     * Whatever was safely committed for this call, complete or not - present
+     * for both executable and non-executable decisions so a caller can see
+     * *what part* of a rejected/retried call was genuinely received (e.g. a
+     * `path` field that arrived before a `content` field got cut off).
+     * Never the source of truth for whether it's safe to act on - that's
+     * `action`/`executable`. Absent only when nothing was ever committed.
+     */
+    readonly stableValue?: JsonValue;
+    /** This call's own parser diagnostics, verbatim (`ToolCallState.parser.diagnostics`). */
+    readonly parserDiagnostics: readonly Diagnostic[];
+    /** Coordinator-level diagnostics attributable to this call, verbatim. */
+    readonly coordinatorDiagnostics: readonly CoordinatorDiagnostic[];
+    /**
+     * Why this decision came out the way it did. See `DecisionEvidence` -
+     * always present, purely observational, never a second source of truth
+     * for `action`/`executable`/`reason`.
+     */
+    readonly evidence: DecisionEvidence;
+}
+/**
+ * The one and only shape a decision can have when `action === "execute"`.
+ * `value` is a real, present `JsonValue` here - never `undefined`, never
+ * optional - because this is the single positive case: everything else in
+ * the gate exists to rule this out unless it's genuinely earned.
+ */
+export interface ExecuteDecision extends ExecutionDecisionCommon {
+    readonly action: "execute";
+    readonly executable: true;
+    readonly reason: "complete";
+    readonly value: JsonValue;
+    /**
+     * Narrowed to required here (unlike the inherited `name?: string`):
+     * the coordinator only ever transitions a call to `status: "complete"`
+     * when `name` is defined (see `DefaultToolCallStreamCoordinator.finishCall`
+     * - a call with no name is forced to `"invalid"` instead), so every
+     * `ExecuteDecision` genuinely has one. Encoding that here means
+     * `tools[decision.name](decision.value)` type-checks directly after
+     * narrowing on `action === "execute"`, with no non-null assertion needed.
+     */
+    readonly name: string;
+}
+/**
+ * Every other outcome. `value` does not exist on this type at all (not
+ * `undefined` - absent) - TypeScript itself refuses code that reads a
+ * "final executable value" off a call the gate did not clear for execution.
+ */
+export interface NonExecutableDecision extends ExecutionDecisionCommon {
+    readonly action: "retry" | "reject";
+    readonly executable: false;
+    readonly reason: Exclude<ExecutionReason, "complete">;
+}
+/**
+ * `ExecuteDecision | NonExecutableDecision` - a discriminated union on
+ * `action` (and redundantly on `executable`, for callers who prefer that
+ * check). Narrowing on either field gives you the right shape:
+ *
+ * ```ts
+ * if (decision.action === "execute") {
+ *   await tools[decision.name](decision.value); // JsonValue, not JsonValue|undefined
+ * }
+ * ```
+ */
+export type ExecutionDecision = ExecuteDecision | NonExecutableDecision;
+export interface ToolCallExecutionGateFinalResult {
+    /** One decision per tool call the coordinator ever created. */
+    readonly decisions: readonly ExecutionDecision[];
+    /**
+     * The full, unfiltered coordinator diagnostics list (same as
+     * `coordinator.snapshot().diagnostics`) - includes diagnostics with no
+     * associated call, e.g. `E_COORDINATOR_LIMIT_CALLS` fires for a call that
+     * hit the concurrent-call limit before a `ToolCallState` could even be
+     * created for it, so it can never appear in `decisions`.
+     */
+    readonly diagnostics: readonly CoordinatorDiagnostic[];
+}
+/**
+ * High-level fail-closed execution decision layer built on top of
+ * `ToolCallStreamCoordinator`. Answers one question per tool call: is it
+ * safe to execute right now? Callers never need to touch parser lexical
+ * state, coordinator event mechanics, or JSON Pointer paths - push provider
+ * events in, read `ExecutionDecision`s out.
+ */
+export interface ToolCallExecutionGate {
+    push(event: NormalizedToolStreamEvent): CoordinatorPushResult;
+    /**
+     * In-flight view. Every decision here is `"retry"` or `"reject"` -
+     * `"execute"` is only ever returned once the stream has genuinely
+     * finished (see `finish()`), since schema validity and prefix-safety are
+     * both only meaningful once a call has settled.
+     */
+    snapshot(): readonly ExecutionDecision[];
+    /** Drains the underlying coordinator's raw event queue, for advanced/UI consumers. */
+    drainEvents(): readonly ToolCallCoordinatorEvent[];
+    finish(meta?: {
+        reason?: StreamEndReason;
+        providerReason?: string;
+    }): ToolCallExecutionGateFinalResult;
+}
+export {};
+//# sourceMappingURL=types.d.ts.map

package/dist/gate/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/gate/types.ts"],"names":[],"mappings":"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"}

package/dist/gate/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/gate/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/gate/types.ts"],"names":[],"mappings":""}

package/dist/grammar/frame.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Expectation states for object parsing.
+ */
+export type ObjectExpectation = "first_key_or_end" | "key_after_comma" | "colon" | "value" | "comma_or_end";
+/**
+ * Expectation states for array parsing.
+ */
+export type ArrayExpectation = "first_value_or_end" | "value_after_comma" | "comma_or_end";
+/**
+ * A frame on the grammar stack representing a JSON container.
+ */
+export interface GrammarFrame {
+    /** The type of container. */
+    containerType: "object" | "array";
+    /**
+     * The JSON Pointer path up to this container.
+     * Backed by a lazily-computed, memoized getter (see attachLazyPath) —
+     * reads exactly like a plain string field everywhere else in the codebase.
+     */
+    path: string;
+    /** Current expectation for object parsing. */
+    objectExpectation?: ObjectExpectation;
+    /** Current key being processed. */
+    currentKey?: string;
+    /** Set of keys already seen (for duplicate detection). */
+    seenKeys?: Set<string>;
+    /** Current expectation for array parsing. */
+    arrayExpectation?: ArrayExpectation;
+    /** Index of the next element. */
+    nextArrayIndex: number;
+    /** Byte offset where this container started. */
+    byteStart: number;
+    /**
+     * @internal Lazy-path bookkeeping. Do not read directly — use `.path`.
+     * A frame's own path never changes after creation (only descendants'
+     * currentKey/nextArrayIndex mutate), so it's safe to resolve on demand.
+     */
+    _parent?: GrammarFrame | null;
+    /** @internal The key/index linking `_parent` to this frame, captured at creation time. */
+    _segment?: string | number | null;
+    /** @internal Memoized resolved path, set the first time `.path` is read. */
+    _cachedPath?: string;
+}
+/**
+ * Create a new object frame.
+ * `parent` is the frame this one is nested inside (or null at the root);
+ * `segment` is the key/index leading from parent to this frame (or null at
+ * the root) — the same value `GrammarStack.currentValuePath()` would have
+ * used, captured eagerly since it reflects the parent's mutable state at
+ * this exact moment. Only the (expensive, O(depth)) string flattening is
+ * deferred.
+ */
+export declare function createObjectFrame(parent: GrammarFrame | null, segment: string | number | null, byteStart: number): GrammarFrame;
+/**
+ * Create a new array frame. See createObjectFrame for `parent`/`segment`.
+ */
+export declare function createArrayFrame(parent: GrammarFrame | null, segment: string | number | null, byteStart: number): GrammarFrame;
+//# sourceMappingURL=frame.d.ts.map

package/dist/grammar/frame.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"frame.d.ts","sourceRoot":"","sources":["../../src/grammar/frame.ts"],"names":[],"mappings":"AAMA;;GAEG;AACH,MAAM,MAAM,iBAAiB,GACzB,kBAAkB,GAClB,iBAAiB,GACjB,OAAO,GACP,OAAO,GACP,cAAc,CAAC;AAEnB;;GAEG;AACH,MAAM,MAAM,gBAAgB,GACxB,oBAAoB,GACpB,mBAAmB,GACnB,cAAc,CAAC;AAEnB;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,6BAA6B;IAC7B,aAAa,EAAE,QAAQ,GAAG,OAAO,CAAC;IAElC;;;;OAIG;IACH,IAAI,EAAE,MAAM,CAAC;IAGb,8CAA8C;IAC9C,iBAAiB,CAAC,EAAE,iBAAiB,CAAC;IAEtC,mCAAmC;IACnC,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB,0DAA0D;IAC1D,QAAQ,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IAGvB,6CAA6C;IAC7C,gBAAgB,CAAC,EAAE,gBAAgB,CAAC;IAEpC,iCAAiC;IACjC,cAAc,EAAE,MAAM,CAAC;IAEvB,gDAAgD;IAChD,SAAS,EAAE,MAAM,CAAC;IAElB;;;;OAIG;IACH,OAAO,CAAC,EAAE,YAAY,GAAG,IAAI,CAAC;IAC9B,0FAA0F;IAC1F,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;IAClC,4EAA4E;IAC5E,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AA0DD;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,YAAY,GAAG,IAAI,EAC3B,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,EAC/B,SAAS,EAAE,MAAM,GAChB,YAAY,CAWd;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,YAAY,GAAG,IAAI,EAC3B,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,EAC/B,SAAS,EAAE,MAAM,GAChB,YAAY,CAUd"}

package/dist/grammar/frame.js

@@ -0,0 +1,87 @@
+// ---------------------------------------------------------------------------
+// Grammar stack frame — tracks state of a JSON container
+// ---------------------------------------------------------------------------
+import { appendPointer } from "./pointer.js";
+/**
+ * Resolve (and memoize) a frame's full JSON Pointer path.
+ *
+ * Iterative, not recursive: walks up `_parent` references collecting frames
+ * until it finds one whose path is already cached (or the root), then walks
+ * back down building and caching each frame's path exactly once. This keeps
+ * per-frame cost amortized O(1) regardless of nesting depth, and avoids
+ * both the call-stack growth a recursive walk would have and the O(depth)
+ * eager string concatenation this replaces (which made opening N nested
+ * containers cost O(N^2) total, regardless of whether any value inside them
+ * was ever committed).
+ */
+function resolveFramePath(frame) {
+    if (frame._cachedPath !== undefined)
+        return frame._cachedPath;
+    const chain = [];
+    let cur = frame;
+    while (cur !== null && cur._cachedPath === undefined) {
+        chain.push(cur);
+        cur = cur._parent === undefined ? null : cur._parent;
+    }
+    let basePath = cur !== null ? cur._cachedPath : "";
+    // chain[0] is always `frame` itself (pushed in the first loop iteration),
+    // and this loop runs in reverse, so the last iteration (i === 0) sets
+    // basePath to frame's own resolved path — returning it directly avoids
+    // re-reading frame._cachedPath, which TS can't prove was set here since
+    // the mutation happens through the aliased `f` reference.
+    for (let i = chain.length - 1; i >= 0; i--) {
+        const f = chain[i];
+        const seg = f._segment;
+        basePath =
+            seg === null || seg === undefined ? basePath : appendPointer(basePath, seg);
+        f._cachedPath = basePath;
+    }
+    return basePath;
+}
+function attachLazyPath(frame, parent, segment) {
+    frame._parent = parent;
+    frame._segment = segment;
+    Object.defineProperty(frame, "path", {
+        enumerable: true,
+        configurable: true,
+        get() {
+            return resolveFramePath(frame);
+        },
+    });
+}
+/**
+ * Create a new object frame.
+ * `parent` is the frame this one is nested inside (or null at the root);
+ * `segment` is the key/index leading from parent to this frame (or null at
+ * the root) — the same value `GrammarStack.currentValuePath()` would have
+ * used, captured eagerly since it reflects the parent's mutable state at
+ * this exact moment. Only the (expensive, O(depth)) string flattening is
+ * deferred.
+ */
+export function createObjectFrame(parent, segment, byteStart) {
+    const frame = {
+        containerType: "object",
+        path: "",
+        objectExpectation: "first_key_or_end",
+        seenKeys: new Set(),
+        nextArrayIndex: 0,
+        byteStart,
+    };
+    attachLazyPath(frame, parent, segment);
+    return frame;
+}
+/**
+ * Create a new array frame. See createObjectFrame for `parent`/`segment`.
+ */
+export function createArrayFrame(parent, segment, byteStart) {
+    const frame = {
+        containerType: "array",
+        path: "",
+        arrayExpectation: "first_value_or_end",
+        nextArrayIndex: 0,
+        byteStart,
+    };
+    attachLazyPath(frame, parent, segment);
+    return frame;
+}
+//# sourceMappingURL=frame.js.map

package/dist/grammar/frame.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"frame.js","sourceRoot":"","sources":["../../src/grammar/frame.ts"],"names":[],"mappings":"AAAA,8EAA8E;AAC9E,yDAAyD;AACzD,8EAA8E;AAE9E,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAkE7C;;;;;;;;;;;GAWG;AACH,SAAS,gBAAgB,CAAC,KAAmB;IAC3C,IAAI,KAAK,CAAC,WAAW,KAAK,SAAS;QAAE,OAAO,KAAK,CAAC,WAAW,CAAC;IAE9D,MAAM,KAAK,GAAmB,EAAE,CAAC;IACjC,IAAI,GAAG,GAAwB,KAAK,CAAC;IACrC,OAAO,GAAG,KAAK,IAAI,IAAI,GAAG,CAAC,WAAW,KAAK,SAAS,EAAE,CAAC;QACrD,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QAChB,GAAG,GAAG,GAAG,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC;IACvD,CAAC;IAED,IAAI,QAAQ,GAAG,GAAG,KAAK,IAAI,CAAC,CAAC,CAAE,GAAG,CAAC,WAAsB,CAAC,CAAC,CAAC,EAAE,CAAC;IAE/D,0EAA0E;IAC1E,sEAAsE;IACtE,uEAAuE;IACvE,wEAAwE;IACxE,0DAA0D;IAC1D,KAAK,IAAI,CAAC,GAAG,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;QAC3C,MAAM,CAAC,GAAG,KAAK,CAAC,CAAC,CAAiB,CAAC;QACnC,MAAM,GAAG,GAAG,CAAC,CAAC,QAAQ,CAAC;QACvB,QAAQ;YACN,GAAG,KAAK,IAAI,IAAI,GAAG,KAAK,SAAS,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,aAAa,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC;QAC9E,CAAC,CAAC,WAAW,GAAG,QAAQ,CAAC;IAC3B,CAAC;IAED,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED,SAAS,cAAc,CACrB,KAAmB,EACnB,MAA2B,EAC3B,OAA+B;IAE/B,KAAK,CAAC,OAAO,GAAG,MAAM,CAAC;IACvB,KAAK,CAAC,QAAQ,GAAG,OAAO,CAAC;IACzB,MAAM,CAAC,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE;QACnC,UAAU,EAAE,IAAI;QAChB,YAAY,EAAE,IAAI;QAClB,GAAG;YACD,OAAO,gBAAgB,CAAC,KAAK,CAAC,CAAC;QACjC,CAAC;KACF,CAAC,CAAC;AACL,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,iBAAiB,CAC/B,MAA2B,EAC3B,OAA+B,EAC/B,SAAiB;IAEjB,MAAM,KAAK,GAAiB;QAC1B,aAAa,EAAE,QAAQ;QACvB,IAAI,EAAE,EAAE;QACR,iBAAiB,EAAE,kBAAkB;QACrC,QAAQ,EAAE,IAAI,GAAG,EAAE;QACnB,cAAc,EAAE,CAAC;QACjB,SAAS;KACV,CAAC;IACF,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC;IACvC,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,gBAAgB,CAC9B,MAA2B,EAC3B,OAA+B,EAC/B,SAAiB;IAEjB,MAAM,KAAK,GAAiB;QAC1B,aAAa,EAAE,OAAO;QACtB,IAAI,EAAE,EAAE;QACR,gBAAgB,EAAE,oBAAoB;QACtC,cAAc,EAAE,CAAC;QACjB,SAAS;KACV,CAAC;IACF,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC;IACvC,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/grammar/pointer.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Escape a JSON Pointer reference token per RFC 6901.
+ * ~ → ~0, / → ~1
+ */
+export declare function escapePointerToken(token: string): string;
+/**
+ * Build a JSON Pointer path from parent path and a key or index.
+ */
+export declare function appendPointer(parent: string, token: string | number): string;
+//# sourceMappingURL=pointer.d.ts.map

package/dist/grammar/pointer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pointer.d.ts","sourceRoot":"","sources":["../../src/grammar/pointer.ts"],"names":[],"mappings":"AAIA;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAExD;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,CAK5E"}

package/dist/grammar/pointer.js

@@ -0,0 +1,20 @@
+// ---------------------------------------------------------------------------
+// JSON Pointer utilities (RFC 6901)
+// ---------------------------------------------------------------------------
+/**
+ * Escape a JSON Pointer reference token per RFC 6901.
+ * ~ → ~0, / → ~1
+ */
+export function escapePointerToken(token) {
+    return token.replace(/~/g, "~0").replace(/\//g, "~1");
+}
+/**
+ * Build a JSON Pointer path from parent path and a key or index.
+ */
+export function appendPointer(parent, token) {
+    if (typeof token === "number") {
+        return `${parent}/${token}`;
+    }
+    return `${parent}/${escapePointerToken(token)}`;
+}
+//# sourceMappingURL=pointer.js.map

package/dist/grammar/pointer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pointer.js","sourceRoot":"","sources":["../../src/grammar/pointer.ts"],"names":[],"mappings":"AAAA,8EAA8E;AAC9E,oCAAoC;AACpC,8EAA8E;AAE9E;;;GAGG;AACH,MAAM,UAAU,kBAAkB,CAAC,KAAa;IAC9C,OAAO,KAAK,CAAC,OAAO,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;AACxD,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,aAAa,CAAC,MAAc,EAAE,KAAsB;IAClE,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC9B,OAAO,GAAG,MAAM,IAAI,KAAK,EAAE,CAAC;IAC9B,CAAC;IACD,OAAO,GAAG,MAAM,IAAI,kBAAkB,CAAC,KAAK,CAAC,EAAE,CAAC;AAClD,CAAC"}

package/dist/grammar/stack.d.ts

@@ -0,0 +1,73 @@
+import type { GrammarFrame } from "./frame.js";
+import type { Diagnostic } from "../types.js";
+/**
+ * Manages the stack of open JSON containers.
+ * Handles object/array nesting, expectations, and duplicate key detection.
+ */
+export declare class GrammarStack {
+    private stack;
+    private diagnostics;
+    private hasDuplicateKey;
+    private maxDepth;
+    constructor(maxDepth: number);
+    /** Current depth (number of open containers). */
+    get depth(): number;
+    /** Whether any duplicate key has been seen. */
+    get hasDuplicate(): boolean;
+    /** Get the current (top) frame, or undefined if empty. */
+    get current(): GrammarFrame | undefined;
+    /**
+     * Push a new object container.
+     * Returns the frame, or null if depth limit exceeded.
+     */
+    pushObject(byteStart: number): GrammarFrame | null;
+    /**
+     * Push a new array container.
+     * Returns the frame, or null if depth limit exceeded.
+     */
+    pushArray(byteStart: number): GrammarFrame | null;
+    /**
+     * Pop the current container.
+     * Returns the popped frame.
+     */
+    pop(): GrammarFrame | undefined;
+    /**
+     * Register an object key. Returns true if the key is new.
+     * If duplicate, emits diagnostic and returns false.
+     */
+    registerObjectKey(key: string, byteOffset: number): boolean;
+    /**
+     * Get the JSON Pointer path for where the next value will go.
+     */
+    currentValuePath(): string;
+    /**
+     * The key/index that would lead from the current frame to its next child,
+     * without flattening it into a full path string. Same underlying value
+     * currentValuePath() uses; kept as a raw segment so a newly-pushed child
+     * frame can capture it in O(1) and defer the expensive path-string join
+     * (see grammar/frame.ts) until something actually reads `.path`.
+     */
+    private currentSegment;
+    /**
+     * Advance the array index after an element value is committed.
+     */
+    advanceArrayIndex(): void;
+    /**
+     * Take accumulated diagnostics and clear.
+     */
+    takeDiagnostics(): Diagnostic[];
+    /**
+     * Check if the stack is empty (no open containers).
+     */
+    isEmpty(): boolean;
+    /**
+     * Get all frames (for snapshot/pending info).
+     */
+    getFrames(): readonly GrammarFrame[];
+    /**
+     * Determine if all open containers can be safely closed by just appending '}' or ']'.
+     * This is true if no container is waiting for a colon or a value.
+     */
+    canSafelyCloseAll(): boolean;
+}
+//# sourceMappingURL=stack.d.ts.map

package/dist/grammar/stack.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stack.d.ts","sourceRoot":"","sources":["../../src/grammar/stack.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAG/C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAI9C;;;GAGG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,KAAK,CAAsB;IACnC,OAAO,CAAC,WAAW,CAAoB;IACvC,OAAO,CAAC,eAAe,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAS;gBAEb,QAAQ,EAAE,MAAM;IAI5B,iDAAiD;IACjD,IAAI,KAAK,IAAI,MAAM,CAElB;IAED,+CAA+C;IAC/C,IAAI,YAAY,IAAI,OAAO,CAE1B;IAED,0DAA0D;IAC1D,IAAI,OAAO,IAAI,YAAY,GAAG,SAAS,CAEtC;IAED;;;OAGG;IACH,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,YAAY,GAAG,IAAI;IAmBlD;;;OAGG;IACH,SAAS,CAAC,SAAS,EAAE,MAAM,GAAG,YAAY,GAAG,IAAI;IAmBjD;;;OAGG;IACH,GAAG,IAAI,YAAY,GAAG,SAAS;IAI/B;;;OAGG;IACH,iBAAiB,CAAC,GAAG,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO;IA0B3D;;OAEG;IACH,gBAAgB,IAAI,MAAM;IAc1B;;;;;;OAMG;IACH,OAAO,CAAC,cAAc;IAUtB;;OAEG;IACH,iBAAiB,IAAI,IAAI;IAOzB;;OAEG;IACH,eAAe,IAAI,UAAU,EAAE;IAM/B;;OAEG;IACH,OAAO,IAAI,OAAO;IAIlB;;OAEG;IACH,SAAS,IAAI,SAAS,YAAY,EAAE;IAIpC;;;OAGG;IACH,iBAAiB,IAAI,OAAO;CAkB7B"}