prefix-safe-json 0.4.4 → 0.5.0

package/dist/ajv.d.ts

@@ -0,0 +1,2 @@
+export { createAjvValidator } from "./validation/ajv-validator.js";
+//# sourceMappingURL=ajv.d.ts.map

package/dist/ajv.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ajv.d.ts","sourceRoot":"","sources":["../src/ajv.ts"],"names":[],"mappings":"AAkBA,OAAO,EAAE,kBAAkB,EAAE,MAAM,+BAA+B,CAAC"}

package/dist/ajv.js

@@ -0,0 +1,19 @@
+// ---------------------------------------------------------------------------
+// prefix-safe-json/ajv — explicit Ajv adapter entry point.
+//
+// `ajv` is a hard runtime dependency of the core execution-authority path
+// (`.`) today, not an optional or lazy one: `coordinator.ts` statically
+// imports `buildValidatorMap` from `./validation/types.js`, which statically
+// imports `createAjvValidator` from `./ajv-validator.js`, which statically
+// imports `ajv` itself - so merely importing the package root loads `ajv`
+// into memory, whether or not a caller ever registers a `schemas` entry.
+// See docs/VALIDATION.md's "Ajv loading" section for why this static-import
+// shape was deliberately kept over a lazy-load alternative.
+//
+// Importing from here instead of the root is only useful if you want an
+// explicit, discoverable Ajv entry point - e.g. to compile one validator up
+// front and reuse it across multiple coordinators/gates. See
+// docs/VALIDATION.md.
+// ---------------------------------------------------------------------------
+export { createAjvValidator } from "./validation/ajv-validator.js";
+//# sourceMappingURL=ajv.js.map

package/dist/ajv.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ajv.js","sourceRoot":"","sources":["../src/ajv.ts"],"names":[],"mappings":"AAAA,8EAA8E;AAC9E,2DAA2D;AAC3D,EAAE;AACF,0EAA0E;AAC1E,wEAAwE;AACxE,6EAA6E;AAC7E,2EAA2E;AAC3E,0EAA0E;AAC1E,yEAAyE;AACzE,4EAA4E;AAC5E,4DAA4D;AAC5D,EAAE;AACF,wEAAwE;AACxE,4EAA4E;AAC5E,6DAA6D;AAC7D,sBAAsB;AACtB,8EAA8E;AAE9E,OAAO,EAAE,kBAAkB,EAAE,MAAM,+BAA+B,CAAC"}

package/dist/conformance/runner.d.ts

@@ -0,0 +1,19 @@
+import type { ConformanceFixture, ConformanceFixtureResult, ConformanceSuiteResult } from "./types.js";
+/**
+ * @public (Experimental)
+ * Runs one conformance fixture against this package's real, unmodified
+ * `createToolCallExecutionGate()` - not a reimplementation - and compares
+ * the resulting decisions against `fixture.expected`. No network, no
+ * provider API key, no model call: `fixture.events` are pushed directly,
+ * exactly as a provider adapter would produce them.
+ */
+export declare function runToolCallIntegrityFixture(fixture: ConformanceFixture): ConformanceFixtureResult;
+/**
+ * @public (Experimental)
+ * Runs every fixture in `fixtures` through {@link runToolCallIntegrityFixture}
+ * and aggregates the results. Deterministic, synchronous, no I/O of its
+ * own - callers own reading fixture files from disk (see
+ * `conformance/fixtures/` and `docs/CONFORMANCE.md`).
+ */
+export declare function runToolCallIntegritySuite(fixtures: readonly ConformanceFixture[]): ConformanceSuiteResult;
+//# sourceMappingURL=runner.d.ts.map

package/dist/conformance/runner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runner.d.ts","sourceRoot":"","sources":["../../src/conformance/runner.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAGV,kBAAkB,EAClB,wBAAwB,EACxB,sBAAsB,EACvB,MAAM,YAAY,CAAC;AAoBpB;;;;;;;GAOG;AACH,wBAAgB,2BAA2B,CAAC,OAAO,EAAE,kBAAkB,GAAG,wBAAwB,CA6CjG;AAED;;;;;;GAMG;AACH,wBAAgB,yBAAyB,CAAC,QAAQ,EAAE,SAAS,kBAAkB,EAAE,GAAG,sBAAsB,CAGzG"}

package/dist/conformance/runner.js

@@ -0,0 +1,78 @@
+import { createToolCallExecutionGate } from "../gate/gate.js";
+function matchDecision(expected, decisions, claimed) {
+    for (const decision of decisions) {
+        if (claimed.has(decision))
+            continue;
+        if (expected.name !== undefined && decision.name !== expected.name)
+            continue;
+        if (expected.toolIndex !== undefined && decision.toolIndex !== expected.toolIndex)
+            continue;
+        if (expected.name === undefined && expected.toolIndex === undefined) {
+            // No correlation key given - fall back to first unclaimed decision,
+            // in the order the gate produced them.
+        }
+        return decision;
+    }
+    return undefined;
+}
+/**
+ * @public (Experimental)
+ * Runs one conformance fixture against this package's real, unmodified
+ * `createToolCallExecutionGate()` - not a reimplementation - and compares
+ * the resulting decisions against `fixture.expected`. No network, no
+ * provider API key, no model call: `fixture.events` are pushed directly,
+ * exactly as a provider adapter would produce them.
+ */
+export function runToolCallIntegrityFixture(fixture) {
+    // `schemaVersion`/`profile` are typed as literal `1`/`"normalized-gate"`,
+    // but that is a compile-time guarantee only - fixtures are ordinary JSON
+    // read off disk (or constructed by a JS caller), so both are checked at
+    // runtime here rather than trusted from the type. v1 only; no migration
+    // machinery for a schemaVersion that doesn't exist yet.
+    if (fixture.schemaVersion !== 1) {
+        throw new Error(`prefix-safe-json: fixture "${fixture.id}" declares schemaVersion ${JSON.stringify(fixture.schemaVersion)}, ` +
+            `which this runner does not support (only schemaVersion 1 exists). See docs/CONFORMANCE.md.`);
+    }
+    if (fixture.profile !== "normalized-gate") {
+        throw new Error(`prefix-safe-json: fixture "${fixture.id}" declares profile ${JSON.stringify(fixture.profile)}, ` +
+            `which this runner does not support (only "normalized-gate" exists in v1). See docs/CONFORMANCE.md.`);
+    }
+    const gate = createToolCallExecutionGate(undefined, undefined, fixture.toolSchemas);
+    for (const event of fixture.events)
+        gate.push(event);
+    const { decisions } = gate.finish();
+    const claimed = new Set();
+    const calls = fixture.expected.map((expected) => {
+        const actual = matchDecision(expected, decisions, claimed);
+        if (!actual) {
+            return { expected, pass: false, failureReason: "no matching decision was produced" };
+        }
+        claimed.add(actual);
+        const pass = actual.action === expected.action && actual.reason === expected.reason;
+        return {
+            expected,
+            pass,
+            actual: { action: actual.action, reason: actual.reason, name: actual.name, toolIndex: actual.toolIndex },
+            ...(pass ? {} : { failureReason: `expected ${expected.action}/${expected.reason}, got ${actual.action}/${actual.reason}` }),
+        };
+    });
+    const unmatchedActualCount = decisions.length - claimed.size;
+    return {
+        id: fixture.id,
+        pass: calls.every((c) => c.pass) && unmatchedActualCount === 0,
+        calls,
+        unmatchedActualCount,
+    };
+}
+/**
+ * @public (Experimental)
+ * Runs every fixture in `fixtures` through {@link runToolCallIntegrityFixture}
+ * and aggregates the results. Deterministic, synchronous, no I/O of its
+ * own - callers own reading fixture files from disk (see
+ * `conformance/fixtures/` and `docs/CONFORMANCE.md`).
+ */
+export function runToolCallIntegritySuite(fixtures) {
+    const results = fixtures.map(runToolCallIntegrityFixture);
+    return { pass: results.every((r) => r.pass), results };
+}
+//# sourceMappingURL=runner.js.map

package/dist/conformance/runner.js.map

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

package/dist/conformance/types.d.ts

@@ -0,0 +1,115 @@
+import type { ExecutionAction, ExecutionReason } from "../gate/types.js";
+import type { NormalizedToolStreamEvent } from "../coordinator/protocol.js";
+/**
+ * @public (Experimental)
+ * How a fixture's event sequence relates to what a real provider can
+ * actually send:
+ *
+ * - `"protocol-realistic"`: this exact sequence has been observed, or is
+ *   directly documented as possible, in a real provider's stream.
+ * - `"sdk-representable"`: the installed provider SDK's own types permit
+ *   constructing and receiving this sequence, but it has not been
+ *   independently confirmed that a real provider sends it.
+ * - `"synthetic-adversarial"`: constructed to stress a specific boundary
+ *   (a resource limit, a pathological ordering) with no claim that any
+ *   provider produces it. Still a legitimate conformance case - not every
+ *   invariant needs a real-world trigger to be worth holding - but never
+ *   to be read as an observed production bug.
+ */
+export type FixtureClassification = "protocol-realistic" | "sdk-representable" | "synthetic-adversarial";
+/**
+ * @public (Experimental)
+ * Where a fixture came from, for provenance. `classification` is required;
+ * everything else is free-form context for a human reader, not consumed by
+ * the runner.
+ */
+export interface FixtureProvenance {
+    readonly classification: FixtureClassification;
+    /** e.g. "vercel/ai", "continuedev/continue" - omitted for fixtures with no external origin. */
+    readonly project?: string;
+    /** An issue/PR/commit URL substantiating this fixture, when one exists. */
+    readonly reference?: string;
+    /** Free-text note, e.g. why a case is classified the way it is. */
+    readonly note?: string;
+}
+/** @public (Experimental) One call's expected execution-authority outcome. */
+export interface ConformanceExpectedCall {
+    /** Correlates against the matching decision's own `name`, when present. */
+    readonly name?: string;
+    /** Correlates against the matching decision's own `toolIndex`, when present. */
+    readonly toolIndex?: number;
+    readonly action: ExecutionAction;
+    readonly reason: ExecutionReason;
+}
+/**
+ * @public (Experimental)
+ * Which conformance claim a fixture makes, made explicit rather than
+ * implied by the corpus's own name. `"normalized-gate"` is the only
+ * profile v1 defines:
+ *
+ * A `"normalized-gate"` fixture tests the coordinator/execution-gate's
+ * response to an already-normalized `NormalizedToolStreamEvent` sequence -
+ * identity correlation, lifecycle/terminal-state handling, and decision
+ * composition, entirely *after* a provider adapter has already produced
+ * that sequence. It does NOT test, and must never be described as
+ * testing, whether an adapter correctly derives that sequence (or a
+ * `provider_diagnostic` within it) from a specific provider's own raw
+ * wire format - that is provider-adapter conformance, a distinct,
+ * currently unwritten profile. See `docs/CONFORMANCE.md`'s "Provider-
+ * adapter conformance — future profile / not covered by normalized-gate
+ * v1" section for exactly what this excludes and why.
+ */
+export type ConformanceProfile = "normalized-gate";
+/**
+ * @public (Experimental)
+ * A single, portable tool-call-integrity conformance fixture: a
+ * provider-neutral normalized event sequence and the execution-authority
+ * decision it must produce. Deliberately expressed in terms of
+ * `NormalizedToolStreamEvent` - the same shape every provider adapter in
+ * this package already emits - rather than any raw provider wire format,
+ * so a fixture never requires understanding a specific SDK's shape to
+ * read or reuse. See `docs/CONFORMANCE.md`.
+ */
+export interface ConformanceFixture {
+    readonly schemaVersion: 1;
+    readonly profile: ConformanceProfile;
+    readonly id: string;
+    readonly description: string;
+    readonly provenance: FixtureProvenance;
+    readonly events: readonly NormalizedToolStreamEvent[];
+    readonly expected: readonly ConformanceExpectedCall[];
+    /**
+     * Optional per-tool JSON Schema (draft-07), keyed by tool name, for
+     * fixtures that specifically exercise schema-validity outcomes (e.g.
+     * `reason: "schema_invalid"`). Deliberately raw JSON Schema only, not a
+     * `ToolInputValidator` - fixtures must stay JSON-serializable. See
+     * `docs/VALIDATION.md` for how validators plug in outside fixtures.
+     */
+    readonly toolSchemas?: Record<string, object>;
+}
+/** @public (Experimental) One expected call matched (or not) against the real decisions produced. */
+export interface ConformanceCallResult {
+    readonly expected: ConformanceExpectedCall;
+    readonly pass: boolean;
+    readonly actual?: {
+        readonly action: ExecutionAction;
+        readonly reason: ExecutionReason;
+        readonly name?: string;
+        readonly toolIndex?: number;
+    };
+    readonly failureReason?: string;
+}
+/** @public (Experimental) The result of running one fixture. */
+export interface ConformanceFixtureResult {
+    readonly id: string;
+    readonly pass: boolean;
+    readonly calls: readonly ConformanceCallResult[];
+    /** Present when the fixture produced more or fewer decisions than `expected` entries. */
+    readonly unmatchedActualCount: number;
+}
+/** @public (Experimental) The result of running a whole fixture suite. */
+export interface ConformanceSuiteResult {
+    readonly pass: boolean;
+    readonly results: readonly ConformanceFixtureResult[];
+}
+//# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/conformance/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AACzE,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,4BAA4B,CAAC;AAE5E;;;;;;;;;;;;;;;GAeG;AACH,MAAM,MAAM,qBAAqB,GAAG,oBAAoB,GAAG,mBAAmB,GAAG,uBAAuB,CAAC;AAEzG;;;;;GAKG;AACH,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,cAAc,EAAE,qBAAqB,CAAC;IAC/C,+FAA+F;IAC/F,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,2EAA2E;IAC3E,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,mEAAmE;IACnE,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,8EAA8E;AAC9E,MAAM,WAAW,uBAAuB;IACtC,2EAA2E;IAC3E,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,gFAAgF;IAChF,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,MAAM,EAAE,eAAe,CAAC;IACjC,QAAQ,CAAC,MAAM,EAAE,eAAe,CAAC;CAClC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,MAAM,kBAAkB,GAAG,iBAAiB,CAAC;AAEnD;;;;;;;;;GASG;AACH,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,aAAa,EAAE,CAAC,CAAC;IAC1B,QAAQ,CAAC,OAAO,EAAE,kBAAkB,CAAC;IACrC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,UAAU,EAAE,iBAAiB,CAAC;IACvC,QAAQ,CAAC,MAAM,EAAE,SAAS,yBAAyB,EAAE,CAAC;IACtD,QAAQ,CAAC,QAAQ,EAAE,SAAS,uBAAuB,EAAE,CAAC;IACtD;;;;;;OAMG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC/C;AAED,qGAAqG;AACrG,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,QAAQ,EAAE,uBAAuB,CAAC;IAC3C,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,MAAM,CAAC,EAAE;QAAE,QAAQ,CAAC,MAAM,EAAE,eAAe,CAAC;QAAC,QAAQ,CAAC,MAAM,EAAE,eAAe,CAAC;QAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAC9I,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;CACjC;AAED,gEAAgE;AAChE,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,KAAK,EAAE,SAAS,qBAAqB,EAAE,CAAC;IACjD,yFAAyF;IACzF,QAAQ,CAAC,oBAAoB,EAAE,MAAM,CAAC;CACvC;AAED,0EAA0E;AAC1E,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,OAAO,EAAE,SAAS,wBAAwB,EAAE,CAAC;CACvD"}

package/dist/conformance/types.js

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

package/dist/conformance/types.js.map

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

package/dist/conformance.d.ts

@@ -0,0 +1,3 @@
+export { runToolCallIntegrityFixture, runToolCallIntegritySuite } from "./conformance/runner.js";
+export type { ConformanceFixture, ConformanceFixtureResult, ConformanceSuiteResult, ConformanceCallResult, ConformanceExpectedCall, FixtureProvenance, FixtureClassification, } from "./conformance/types.js";
+//# sourceMappingURL=conformance.d.ts.map

package/dist/conformance.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"conformance.d.ts","sourceRoot":"","sources":["../src/conformance.ts"],"names":[],"mappings":"AAUA,OAAO,EAAE,2BAA2B,EAAE,yBAAyB,EAAE,MAAM,yBAAyB,CAAC;AACjG,YAAY,EACV,kBAAkB,EAClB,wBAAwB,EACxB,sBAAsB,EACtB,qBAAqB,EACrB,uBAAuB,EACvB,iBAAiB,EACjB,qBAAqB,GACtB,MAAM,wBAAwB,CAAC"}

package/dist/conformance.js

@@ -0,0 +1,11 @@
+// ---------------------------------------------------------------------------
+// prefix-safe-json/conformance — Tool Call Integrity conformance runner.
+//
+// Runs portable, provider-neutral fixtures (see conformance/fixtures/ and
+// docs/CONFORMANCE.md) against this package's own real execution-authority
+// gate. Useful even to projects that do not install this package at
+// runtime: the fixture format and expected outcomes are meaningful on
+// their own, against any implementation of this problem class.
+// ---------------------------------------------------------------------------
+export { runToolCallIntegrityFixture, runToolCallIntegritySuite } from "./conformance/runner.js";
+//# sourceMappingURL=conformance.js.map

package/dist/conformance.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"conformance.js","sourceRoot":"","sources":["../src/conformance.ts"],"names":[],"mappings":"AAAA,8EAA8E;AAC9E,yEAAyE;AACzE,EAAE;AACF,0EAA0E;AAC1E,2EAA2E;AAC3E,oEAAoE;AACpE,sEAAsE;AACtE,+DAA+D;AAC/D,8EAA8E;AAE9E,OAAO,EAAE,2BAA2B,EAAE,yBAAyB,EAAE,MAAM,yBAAyB,CAAC"}

package/dist/coordinator/coordinator.d.ts

@@ -1,6 +1,7 @@
 import { ParserOptions } from "../types.js";
+import { type ToolInputValidator } from "../validation/types.js";
 import { NormalizedToolStreamEvent, StreamEndReason } from "./protocol.js";
-import { ToolCallStreamCoordinator, ToolCallCoordinatorSnapshot, ToolCallCoordinatorEvent, ToolCallCoordinatorFinalResult, CoordinatorPushResult, CoordinatorLimits, JsonSchemaLike } from "./types.js";
+import { ToolCallStreamCoordinator, ToolCallCoordinatorSnapshot, ToolCallCoordinatorEvent, ToolCallCoordinatorFinalResult, CoordinatorPushResult, CoordinatorLimits } from "./types.js";
 export declare class DefaultToolCallStreamCoordinator implements ToolCallStreamCoordinator {
     private readonly limits;
     private readonly parserOptions;
@@ -21,17 +22,30 @@ export declare class DefaultToolCallStreamCoordinator implements ToolCallStreamC
      *   underlying per-call IncrementalJsonParser (limits, repairs). Previously
      *   there was no way to pass the latter through at all; every parser the
      *   coordinator created was hardcoded to library defaults.
-     * @param toolSchemas Optional JSON Schema (draft-07) per tool name. When a
-     *   call for a registered tool reaches outcome "complete", its
-     *   `stableValue` is validated against the schema. Structural
-     *   prefix-safety (no truncated/fabricated values) and schema validity
-     *   are independent concerns — a value can be genuinely complete and
-     *   still not match what the tool declared it needs (wrong type, missing
+     * @param toolSchemas Optional raw JSON Schema (draft-07) per tool name,
+     *   compiled internally through `prefix-safe-json/ajv`'s
+     *   `createAjvValidator()`. This is the pre-0.5 option, unchanged in
+     *   shape - existing callers need no code change.
+     * @param validators Optional {@link ToolInputValidator} per tool name -
+     *   additive, 0.5.0+. Use this to plug in Zod, TypeBox, Valibot, a
+     *   Standard Schema-compliant validator, or a hand-written check, with no
+     *   forced dependency on this package's own validation stack. A tool name
+     *   present in both `toolSchemas` and `validators` is a construction-time
+     *   error - there is no structural discrimination or silent precedence
+     *   between the two; each tool's validation comes from exactly one
+     *   explicit source. See `docs/VALIDATION.md`.
+     *
+     *   When a call for a registered tool reaches outcome "complete", its
+     *   `stableValue` is validated. Structural prefix-safety (no
+     *   truncated/fabricated values) and validator-reported validity are
+     *   independent concerns — a value can be genuinely complete and still
+     *   not match what the tool declared it needs (wrong type, missing
      *   required field the model never provided at all). Both must hold for
-     *   `executable` to be true. Schemas are compiled eagerly here so a
-     *   malformed schema fails fast at construction, not mid-stream.
+     *   `executable` to be true. Entries are resolved eagerly here so a
+     *   malformed schema (or a misconfigured validator's constructor-time
+     *   setup) fails fast at construction, not mid-stream.
      */
-    constructor(limits?: Partial<CoordinatorLimits>, parserOptions?: ParserOptions, toolSchemas?: Record<string, JsonSchemaLike>);
+    constructor(limits?: Partial<CoordinatorLimits>, parserOptions?: ParserOptions, toolSchemas?: Record<string, object>, validators?: Record<string, ToolInputValidator>);
     push(event: NormalizedToolStreamEvent): CoordinatorPushResult;
     private handleStart;
     private handleIdentity;
@@ -51,5 +65,5 @@ export declare class DefaultToolCallStreamCoordinator implements ToolCallStreamC
         providerReason?: string;
     }): ToolCallCoordinatorFinalResult;
 }
-export declare function createToolCallStreamCoordinator(limits?: Partial<CoordinatorLimits>, parserOptions?: ParserOptions, toolSchemas?: Record<string, JsonSchemaLike>): ToolCallStreamCoordinator;
+export declare function createToolCallStreamCoordinator(limits?: Partial<CoordinatorLimits>, parserOptions?: ParserOptions, toolSchemas?: Record<string, object>, validators?: Record<string, ToolInputValidator>): ToolCallStreamCoordinator;
 //# sourceMappingURL=coordinator.d.ts.map

package/dist/coordinator/coordinator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"coordinator.d.ts","sourceRoot":"","sources":["../../src/coordinator/coordinator.ts"],"names":[],"mappings":"AACA,OAAO,EAAyB,aAAa,EAAE,MAAM,aAAa,CAAC;AAEnE,OAAO,EAAE,yBAAyB,EAAgB,eAAe,EAAE,MAAM,eAAe,CAAC;AACzF,OAAO,EACL,yBAAyB,EACzB,2BAA2B,EAC3B,wBAAwB,EACxB,8BAA8B,EAC9B,qBAAqB,EACrB,iBAAiB,EAIjB,cAAc,EACf,MAAM,YAAY,CAAC;AA4CpB,qBAAa,gCAAiC,YAAW,yBAAyB;IAChF,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAoB;IAC3C,OAAO,CAAC,QAAQ,CAAC,aAAa,CAA4B;IAC1D,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAgC;IAC/D,OAAO,CAAC,KAAK,CAAgD;IAC7D,OAAO,CAAC,qBAAqB,CAAkC;IAC/D,OAAO,CAAC,0BAA0B,CAAmD;IACrF,OAAO,CAAC,WAAW,CAAK;IACxB,OAAO,CAAC,UAAU,CAAkC;IACpD,OAAO,CAAC,WAAW,CAA+B;IAClD,OAAO,CAAC,eAAe,CAAK;IAC5B,OAAO,CAAC,cAAc,CAAK;IAC3B,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,cAAc,CAAC,CAAkB;IAEzC;;;;;;;;;;;;;;;OAeG;gBAED,MAAM,CAAC,EAAE,OAAO,CAAC,iBAAiB,CAAC,EACnC,aAAa,CAAC,EAAE,aAAa,EAC7B,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC;IAa9C,IAAI,CAAC,KAAK,EAAE,yBAAyB,GAAG,qBAAqB;IAuE7D,OAAO,CAAC,WAAW;IAiEnB,OAAO,CAAC,cAAc;IAgDtB,OAAO,CAAC,eAAe;IAqCvB,OAAO,CAAC,oBAAoB;IA8B5B,OAAO,CAAC,aAAa;IA6BrB,OAAO,CAAC,UAAU;IAoElB,OAAO,CAAC,eAAe;IAIvB,OAAO,CAAC,wBAAwB;IAwChC,OAAO,CAAC,eAAe;IA0BvB,OAAO,CAAC,OAAO;IAcf,OAAO,CAAC,aAAa;IASrB,QAAQ,IAAI,2BAA2B;IAmBvC,WAAW,IAAI,SAAS,wBAAwB,EAAE;IAMlD,MAAM,CAAC,IAAI,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,eAAe,CAAC;QAAC,cAAc,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,8BAA8B;CAcrG;AAED,wBAAgB,+BAA+B,CAC7C,MAAM,CAAC,EAAE,OAAO,CAAC,iBAAiB,CAAC,EACnC,aAAa,CAAC,EAAE,aAAa,EAC7B,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,GAC3C,yBAAyB,CAE3B"}
+{"version":3,"file":"coordinator.d.ts","sourceRoot":"","sources":["../../src/coordinator/coordinator.ts"],"names":[],"mappings":"AAAA,OAAO,EAAyB,aAAa,EAAE,MAAM,aAAa,CAAC;AAEnE,OAAO,EAAqB,KAAK,kBAAkB,EAA6B,MAAM,wBAAwB,CAAC;AAC/G,OAAO,EAAE,yBAAyB,EAAgB,eAAe,EAAE,MAAM,eAAe,CAAC;AACzF,OAAO,EACL,yBAAyB,EACzB,2BAA2B,EAC3B,wBAAwB,EACxB,8BAA8B,EAC9B,qBAAqB,EACrB,iBAAiB,EAIlB,MAAM,YAAY,CAAC;AAyFpB,qBAAa,gCAAiC,YAAW,yBAAyB;IAChF,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAoB;IAC3C,OAAO,CAAC,QAAQ,CAAC,aAAa,CAA4B;IAC1D,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAkC;IACjE,OAAO,CAAC,KAAK,CAAgD;IAC7D,OAAO,CAAC,qBAAqB,CAAkC;IAC/D,OAAO,CAAC,0BAA0B,CAAmD;IACrF,OAAO,CAAC,WAAW,CAAK;IACxB,OAAO,CAAC,UAAU,CAAkC;IACpD,OAAO,CAAC,WAAW,CAA+B;IAClD,OAAO,CAAC,eAAe,CAAK;IAC5B,OAAO,CAAC,cAAc,CAAK;IAC3B,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,cAAc,CAAC,CAAkB;IAEzC;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA4BG;gBAED,MAAM,CAAC,EAAE,OAAO,CAAC,iBAAiB,CAAC,EACnC,aAAa,CAAC,EAAE,aAAa,EAC7B,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EACpC,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,kBAAkB,CAAC;IAOjD,IAAI,CAAC,KAAK,EAAE,yBAAyB,GAAG,qBAAqB;IAuE7D,OAAO,CAAC,WAAW;IAiEnB,OAAO,CAAC,cAAc;IAgDtB,OAAO,CAAC,eAAe;IAqCvB,OAAO,CAAC,oBAAoB;IA8B5B,OAAO,CAAC,aAAa;IA6BrB,OAAO,CAAC,UAAU;IAgIlB,OAAO,CAAC,eAAe;IAIvB,OAAO,CAAC,wBAAwB;IAwChC,OAAO,CAAC,eAAe;IA0BvB,OAAO,CAAC,OAAO;IAcf,OAAO,CAAC,aAAa;IASrB,QAAQ,IAAI,2BAA2B;IAmBvC,WAAW,IAAI,SAAS,wBAAwB,EAAE;IAMlD,MAAM,CAAC,IAAI,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,eAAe,CAAC;QAAC,cAAc,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,8BAA8B;CAcrG;AAED,wBAAgB,+BAA+B,CAC7C,MAAM,CAAC,EAAE,OAAO,CAAC,iBAAiB,CAAC,EACnC,aAAa,CAAC,EAAE,aAAa,EAC7B,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EACpC,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,kBAAkB,CAAC,GAC9C,yBAAyB,CAE3B"}

package/dist/coordinator/coordinator.js

@@ -1,6 +1,6 @@
-import { Ajv } from "ajv";
 import { createParser } from "../parser.js";
-import { DEFAULT_COORDINATOR_LIMITS } from "./types.js";
+import { buildValidatorMap } from "../validation/types.js";
+import { DEFAULT_COORDINATOR_LIMITS, } from "./types.js";
 import { AUTHORITY_PROTOCOL_VIOLATION_CODES, DUPLICATE_TOOL_CALL_START_DIAGNOSTIC_CODE, SDK_EXECUTION_OBSERVED_DIAGNOSTIC_CODE, SDK_EXECUTION_ERROR_DIAGNOSTIC_CODE, EVENT_AFTER_STREAM_END_DIAGNOSTIC_CODE, TERMINAL_REASON_CONFLICT_DIAGNOSTIC_CODE, } from "./diagnostic-codes.js";
 // A `provider_diagnostic` carrying either code is proof that a provider SDK's
 // own tool loop already invoked this call's `execute` callback (see the two
@@ -12,6 +12,53 @@ const SDK_EXECUTION_OBSERVED_CODES = new Set([
     SDK_EXECUTION_OBSERVED_DIAGNOSTIC_CODE,
     SDK_EXECUTION_ERROR_DIAGNOSTIC_CODE,
 ]);
+/**
+ * @internal
+ * Runtime shape check for what `validator.validate()` actually returned.
+ * `ToolInputValidator` is a TypeScript interface, not a runtime guarantee -
+ * `result && result.valid === true/false` alone is not a safe discriminator:
+ * an array is `typeof "object"` and could carry an incidental `.valid`
+ * property; a function can too (`fn.valid = true` is legal JS), and
+ * `typeof fn !== "object"` is what actually excludes it here. Also rejects
+ * internally contradictory shapes a conforming implementation never
+ * produces: `valid: true` alongside a defined `errors` field, or
+ * `valid: false` with an `errors` field that is anything other than absent
+ * or a `string[]` - a bare string or a non-string array would otherwise
+ * reach `(result.errors ?? []).join("; ")` below, which throws on a string
+ * (no `.join`) and silently stringifies non-string elements on an array.
+ */
+function isWellFormedValidationResult(result) {
+    if (typeof result !== "object" || result === null || Array.isArray(result))
+        return false;
+    const value = result;
+    if (value.valid === true)
+        return value.errors === undefined;
+    if (value.valid === false) {
+        if (value.errors === undefined)
+            return true;
+        return Array.isArray(value.errors) && value.errors.every((e) => typeof e === "string");
+    }
+    return false;
+}
+/**
+ * @internal
+ * Describes an arbitrary, possibly-malformed validator result for a
+ * diagnostic message without ever throwing. A circular object or a value
+ * containing a BigInt both make `JSON.stringify` throw - a diagnostic
+ * describing *why* a result was rejected must never itself crash the
+ * stream it exists to fail closed.
+ */
+function describeMalformedResult(value) {
+    if (typeof value === "object") {
+        try {
+            return JSON.stringify(value);
+        }
+        catch {
+            return Object.prototype.toString.call(value);
+        }
+    }
+    return `${typeof value} ${String(value)}`;
+}
 class CoordinatorCallState {
     internalId;
     provider;
@@ -49,26 +96,33 @@ export class DefaultToolCallStreamCoordinator {
      *   underlying per-call IncrementalJsonParser (limits, repairs). Previously
      *   there was no way to pass the latter through at all; every parser the
      *   coordinator created was hardcoded to library defaults.
-     * @param toolSchemas Optional JSON Schema (draft-07) per tool name. When a
-     *   call for a registered tool reaches outcome "complete", its
-     *   `stableValue` is validated against the schema. Structural
-     *   prefix-safety (no truncated/fabricated values) and schema validity
-     *   are independent concerns — a value can be genuinely complete and
-     *   still not match what the tool declared it needs (wrong type, missing
+     * @param toolSchemas Optional raw JSON Schema (draft-07) per tool name,
+     *   compiled internally through `prefix-safe-json/ajv`'s
+     *   `createAjvValidator()`. This is the pre-0.5 option, unchanged in
+     *   shape - existing callers need no code change.
+     * @param validators Optional {@link ToolInputValidator} per tool name -
+     *   additive, 0.5.0+. Use this to plug in Zod, TypeBox, Valibot, a
+     *   Standard Schema-compliant validator, or a hand-written check, with no
+     *   forced dependency on this package's own validation stack. A tool name
+     *   present in both `toolSchemas` and `validators` is a construction-time
+     *   error - there is no structural discrimination or silent precedence
+     *   between the two; each tool's validation comes from exactly one
+     *   explicit source. See `docs/VALIDATION.md`.
+     *
+     *   When a call for a registered tool reaches outcome "complete", its
+     *   `stableValue` is validated. Structural prefix-safety (no
+     *   truncated/fabricated values) and validator-reported validity are
+     *   independent concerns — a value can be genuinely complete and still
+     *   not match what the tool declared it needs (wrong type, missing
      *   required field the model never provided at all). Both must hold for
-     *   `executable` to be true. Schemas are compiled eagerly here so a
-     *   malformed schema fails fast at construction, not mid-stream.
+     *   `executable` to be true. Entries are resolved eagerly here so a
+     *   malformed schema (or a misconfigured validator's constructor-time
+     *   setup) fails fast at construction, not mid-stream.
      */
-    constructor(limits, parserOptions, toolSchemas) {
+    constructor(limits, parserOptions, toolSchemas, validators) {
         this.limits = { ...DEFAULT_COORDINATOR_LIMITS, ...limits };
         this.parserOptions = parserOptions;
-        this.toolValidators = new Map();
-        if (toolSchemas) {
-            const ajv = new Ajv({ allErrors: true, strict: false });
-            for (const [toolName, schema] of Object.entries(toolSchemas)) {
-                this.toolValidators.set(toolName, ajv.compile(schema));
-            }
-        }
+        this.toolValidators = buildValidatorMap(toolSchemas, validators);
     }
     push(event) {
         if (this.isFinished) {
@@ -365,14 +419,53 @@ export class DefaultToolCallStreamCoordinator {
         // Schema validation is a separate concern from structural
         // prefix-safety: only meaningful once the value is genuinely complete,
         // and only for tools with a registered schema.
+        //
+        // Stryker disable next-line ConditionalExpression: `call.name !==
+        // undefined` cannot observably differ from `true` here - the outcome
+        // assignment above already forces outcome to "invalid" whenever
+        // call.name is undefined, so reaching outcome === "complete" already
+        // guarantees call.name is defined. This conjunct exists for TypeScript's
+        // type narrowing (removing it is a real compile error at
+        // `this.toolValidators.get(call.name)` below, verified directly), not
+        // as an independently reachable runtime branch.
         if (outcome === "complete" && call.name !== undefined) {
             const validator = this.toolValidators.get(call.name);
             if (validator) {
-                call.schemaValid = validator(res.stableValue) === true;
-                if (!call.schemaValid) {
-                    const errors = (validator.errors ?? [])
-                        .map((e) => `${e.instancePath || "<root>"} ${e.message ?? ""}`.trim())
-                        .join("; ");
+                // A validator that throws (e.g. a Standard Schema adapter refusing
+                // an async validator - see docs/VALIDATION.md) fails this one call
+                // closed rather than aborting the whole stream: caught here, not
+                // left to propagate out of push()/finish() and take every other
+                // in-flight call down with it.
+                let didThrow = false;
+                let thrown;
+                // Deliberately `unknown`, not `ToolValidationResult` - the interface
+                // declares validate()'s return type, but a plain-JS implementation
+                // (or an `as`-cast) can hand back anything at runtime, and this
+                // value is trusted no further than any other external input until
+                // isWellFormedValidationResult() below actually proves the shape.
+                let result;
+                try {
+                    result = validator.validate(res.stableValue);
+                }
+                catch (error) {
+                    didThrow = true;
+                    thrown = error;
+                }
+                if (didThrow) {
+                    call.schemaValid = false;
+                    this.addDiagnostic({
+                        code: "E_SCHEMA_VALIDATION_FAILED",
+                        severity: "error",
+                        internalId: call.internalId,
+                        message: `Validator for "${call.name}" threw instead of returning a result: ${thrown instanceof Error ? thrown.message : String(thrown)}`,
+                    });
+                }
+                else if (isWellFormedValidationResult(result) && result.valid === true) {
+                    call.schemaValid = true;
+                }
+                else if (isWellFormedValidationResult(result) && result.valid === false) {
+                    call.schemaValid = false;
+                    const errors = (result.errors ?? []).join("; ");
                     this.addDiagnostic({
                         code: "E_SCHEMA_VALIDATION_FAILED",
                         severity: "error",
@@ -380,6 +473,28 @@ export class DefaultToolCallStreamCoordinator {
                         message: `Tool call arguments for "${call.name}" do not match its schema: ${errors || "unknown validation error"}`,
                     });
                 }
+                else {
+                    // A conforming ToolInputValidator never reaches here - validate()
+                    // is typed to return exactly {valid: true} or {valid: false,
+                    // ...}. This branch exists for every shape the type system cannot
+                    // prevent at runtime: undefined/null, an array, a function
+                    // (including one with an incidental `.valid` property), a
+                    // non-boolean `valid`, `valid: true` alongside a defined `errors`
+                    // field, or `valid: false` with `errors` that isn't absent or a
+                    // plain `string[]` - see isWellFormedValidationResult() above.
+                    // Fails closed the same as a thrown error - the alternative
+                    // (falling through with schemaValid left unset) would let
+                    // executable's `call.schemaValid !== false` check treat an
+                    // unproven, malformed validator result as if no validator had run
+                    // at all.
+                    call.schemaValid = false;
+                    this.addDiagnostic({
+                        code: "E_SCHEMA_VALIDATION_FAILED",
+                        severity: "error",
+                        internalId: call.internalId,
+                        message: `Validator for "${call.name}" returned a malformed result instead of {valid: true} or {valid: false, ...}: ${describeMalformedResult(result)}`,
+                    });
+                }
             }
         }
         // Determine executable according to Executable Policy — structural
@@ -515,7 +630,7 @@ export class DefaultToolCallStreamCoordinator {
         };
     }
 }
-export function createToolCallStreamCoordinator(limits, parserOptions, toolSchemas) {
-    return new DefaultToolCallStreamCoordinator(limits, parserOptions, toolSchemas);
+export function createToolCallStreamCoordinator(limits, parserOptions, toolSchemas, validators) {
+    return new DefaultToolCallStreamCoordinator(limits, parserOptions, toolSchemas, validators);
 }
 //# sourceMappingURL=coordinator.js.map