prefix-safe-json 0.4.5 → 0.5.1

package/dist/validation/types.d.ts

@@ -0,0 +1,63 @@
+/**
+ * @public (Experimental)
+ * The result of validating one tool call's arguments. Structurally minimal
+ * on purpose: `errors`, when present, are already-formatted human-readable
+ * strings, not ecosystem-specific issue objects (Zod issues, Ajv errors,
+ * TypeBox errors, ...) - each adapter is responsible for turning its own
+ * validator's native error shape into readable text, so nothing downstream
+ * needs to know which validation ecosystem produced a given verdict.
+ */
+export type ToolValidationResult = {
+    readonly valid: true;
+} | {
+    readonly valid: false;
+    readonly errors?: readonly string[];
+};
+/**
+ * @public (Experimental)
+ * The validation boundary this package's execution-authority core depends
+ * on. It is deliberately not `ajv`, `zod`, `typebox`, `valibot`, or any
+ * other specific ecosystem's own type - implement this against whichever
+ * validator your project already uses and pass it in; nothing in this
+ * package's core needs to know it exists.
+ *
+ * A validator verdict is one more piece of evidence, never authority on its
+ * own: `valid: false` can make a decision `reject`; `valid: true` never by
+ * itself makes a decision `execute` - completeness and lifecycle evidence
+ * still have to hold too. See `docs/EXECUTION_GATE.md`.
+ *
+ * Contract:
+ * - `validate` runs synchronously and returns a result. It may throw to
+ *   signal validator misconfiguration (mirroring how a malformed JSON
+ *   Schema already fails fast at construction rather than mid-stream); the
+ *   coordinator treats a thrown `validate()` as `valid: false` for that one
+ *   call rather than letting the exception abort the whole stream - see
+ *   `docs/VALIDATION.md#a-validator-that-throws`.
+ * - `validate` must be deterministic and free of side effects - it is called
+ *   with the call's already-parsed, already-complete `stableValue`, and its
+ *   return value must depend only on that input.
+ */
+export interface ToolInputValidator {
+    validate(value: unknown): ToolValidationResult;
+}
+/**
+ * @internal
+ * Builds the coordinator's internal per-tool validator map from the two
+ * explicit, separate registration options. There is no structural/duck-type
+ * discrimination anywhere in this path - `schemas` entries are always
+ * compiled as JSON Schema, `validators` entries are always used as-is, and
+ * a tool name present in both is a construction-time error rather than a
+ * silently-resolved precedence rule. See `docs/VALIDATION.md`. The one
+ * exception is refusal, never re-routing: `assertJsonSchemaDocument` rejects
+ * objects that are recognizably not JSON Schema before Ajv sees them.
+ *
+ * Collision detection runs *before* any schema is compiled, so a colliding
+ * tool name is always reported as a collision - deterministically, even
+ * when that same tool's `schemas` entry also happens to be malformed JSON
+ * Schema (or one of the objects `assertJsonSchemaDocument` refuses).
+ * Without this ordering, whichever check happened to run first would decide
+ * which error the caller sees, for reasons unrelated to which problem is
+ * actually more fundamental.
+ */
+export declare function buildValidatorMap(schemas: Record<string, object> | undefined, validators: Record<string, ToolInputValidator> | undefined): Map<string, ToolInputValidator>;
+//# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/validation/types.ts"],"names":[],"mappings":"AAEA;;;;;;;;GAQG;AACH,MAAM,MAAM,oBAAoB,GAC5B;IAAE,QAAQ,CAAC,KAAK,EAAE,IAAI,CAAA;CAAE,GACxB;IAAE,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;CAAE,CAAC;AAEnE;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG,oBAAoB,CAAC;CAChD;AA2ED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,SAAS,EAC3C,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,kBAAkB,CAAC,GAAG,SAAS,GACzD,GAAG,CAAC,MAAM,EAAE,kBAAkB,CAAC,CA+CjC"}

package/dist/validation/types.js

@@ -0,0 +1,131 @@
+import { buildSharedAjvValidators } from "./ajv-validator.js";
+/**
+ * @internal
+ * Runtime shape check for a `validators[toolName]` entry. `ToolInputValidator`
+ * is a TypeScript interface, not a runtime guarantee - a plain-JavaScript
+ * caller (or a `as never`/`as ToolInputValidator` cast) can hand this
+ * anything. An explicitly *registered* malformed validator must never be
+ * silently equivalent to "no validator registered": `coordinator.ts`'s
+ * `if (validator) { ... }` truthiness check would otherwise skip a `null`/
+ * `undefined`/`false`/`0`/`""` entry entirely, letting the call execute
+ * with zero diagnostic - the same class of fail-open gap already closed for
+ * a validator that returns a malformed *result* (see
+ * `docs/VALIDATION.md#a-validator-that-returns-a-malformed-result`). This
+ * check exists so that gap cannot reopen one level up, at registration time.
+ */
+function isToolInputValidatorShaped(value) {
+    return typeof value === "object" && value !== null && typeof value.validate === "function";
+}
+function describeInvalidValidator(value) {
+    if (typeof value === "object") {
+        try {
+            return JSON.stringify(value);
+        }
+        catch {
+            return Object.prototype.toString.call(value);
+        }
+    }
+    return `${typeof value} ${String(value)}`;
+}
+// Registry key the Vercel AI SDK stamps on the objects `jsonSchema()` and
+// `zodSchema()` return (the same global symbol across ai@5, @6 and @7).
+const AI_SDK_SCHEMA_MARKER = Symbol.for("vercel.ai.schema");
+/**
+ * @internal
+ * Rejects two schema-library objects that are routinely mistaken for JSON
+ * Schema documents. This is not structural discrimination - nothing is
+ * converted or re-routed; a recognized non-JSON-Schema object is refused, and
+ * everything else is still compiled as JSON Schema exactly as before.
+ *
+ * - An AI SDK `jsonSchema()`/`zodSchema()` wrapper keeps its schema behind a
+ *   `jsonSchema` getter, and Ajv (`strict: false`) ignores every field it
+ *   does not recognize, so the wrapper compiles to an accept-everything
+ *   validator: every call would pass validation. That is the fail-open case
+ *   this check exists for.
+ * - A Standard Schema object (Zod, Valibot, ArkType, ...) either crashes Ajv
+ *   with an unrelated-looking meta-schema error or, depending on its own
+ *   fields, compiles to something that validates the wrong thing.
+ *
+ * Plain JSON Schema documents, including TypeBox schemas (plain objects that
+ * only add symbol keys), carry neither marker and are unaffected.
+ */
+function assertJsonSchemaDocument(toolName, schema) {
+    // Functions too: an ArkType schema is a callable Standard Schema.
+    if ((typeof schema !== "object" && typeof schema !== "function") || schema === null)
+        return;
+    const name = JSON.stringify(toolName);
+    if (schema[AI_SDK_SCHEMA_MARKER]) {
+        throw new Error(`prefix-safe-json: schemas[${name}] is an AI SDK jsonSchema()/zodSchema() wrapper, not a JSON Schema ` +
+            `document - compiled as-is it would validate nothing. Register the raw schema it wraps instead, ` +
+            `e.g. schemas: { ${name}: wrapper.jsonSchema }.`);
+    }
+    const standard = schema["~standard"];
+    if (typeof standard === "object" && standard !== null && typeof standard.validate === "function") {
+        throw new Error(`prefix-safe-json: schemas[${name}] is a Standard Schema (Zod, Valibot, ArkType, ...), not a JSON Schema ` +
+            `document. Register it through "validators" instead: validators: { ${name}: fromStandardSchema(schema) }, ` +
+            `with fromStandardSchema imported from "prefix-safe-json/standard-schema".`);
+    }
+}
+/**
+ * @internal
+ * Builds the coordinator's internal per-tool validator map from the two
+ * explicit, separate registration options. There is no structural/duck-type
+ * discrimination anywhere in this path - `schemas` entries are always
+ * compiled as JSON Schema, `validators` entries are always used as-is, and
+ * a tool name present in both is a construction-time error rather than a
+ * silently-resolved precedence rule. See `docs/VALIDATION.md`. The one
+ * exception is refusal, never re-routing: `assertJsonSchemaDocument` rejects
+ * objects that are recognizably not JSON Schema before Ajv sees them.
+ *
+ * Collision detection runs *before* any schema is compiled, so a colliding
+ * tool name is always reported as a collision - deterministically, even
+ * when that same tool's `schemas` entry also happens to be malformed JSON
+ * Schema (or one of the objects `assertJsonSchemaDocument` refuses).
+ * Without this ordering, whichever check happened to run first would decide
+ * which error the caller sees, for reasons unrelated to which problem is
+ * actually more fundamental.
+ */
+export function buildValidatorMap(schemas, validators) {
+    if (schemas && validators) {
+        for (const toolName of Object.keys(validators)) {
+            if (Object.prototype.hasOwnProperty.call(schemas, toolName)) {
+                throw new Error(`prefix-safe-json: tool ${JSON.stringify(toolName)} is registered in both "schemas" and ` +
+                    `"validators" - a tool's validation must come from exactly one source. Remove one registration.`);
+            }
+        }
+    }
+    const map = new Map();
+    if (schemas) {
+        // Read every entry exactly once, then use that one snapshot for both the
+        // refusal check and compilation. If a `schemas` value were an accessor,
+        // iterating `schemas` twice (once here, once inside
+        // buildSharedAjvValidators) could let a getter return a plain schema on
+        // the checked pass and an AI SDK wrapper on the compiled pass, so the
+        // wrapper reaches Ajv unchecked and compiles to accept-everything -
+        // exactly what assertJsonSchemaDocument exists to stop.
+        const schemaEntries = Object.entries(schemas);
+        for (const [toolName, schema] of schemaEntries) {
+            assertJsonSchemaDocument(toolName, schema);
+        }
+        const materializedSchemas = Object.fromEntries(schemaEntries);
+        // One shared Ajv instance for every schema in THIS `schemas` object -
+        // pre-0.5 behavior, restored here after 0.5's per-schema
+        // createAjvValidator() calls regressed it (a schema could no longer
+        // $ref another schema registered in the same construction - see
+        // buildSharedAjvValidators's own doc comment for the direct proof).
+        for (const [toolName, validator] of buildSharedAjvValidators(materializedSchemas)) {
+            map.set(toolName, validator);
+        }
+    }
+    if (validators) {
+        for (const [toolName, validator] of Object.entries(validators)) {
+            if (!isToolInputValidatorShaped(validator)) {
+                throw new Error(`prefix-safe-json: validators[${JSON.stringify(toolName)}] is not a valid ToolInputValidator - ` +
+                    `expected an object with a "validate" function, received: ${describeInvalidValidator(validator)}`);
+            }
+            map.set(toolName, validator);
+        }
+    }
+    return map;
+}
+//# sourceMappingURL=types.js.map

package/dist/validation/types.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "prefix-safe-json",
-  "version": "0.4.5",
+  "version": "0.5.1",
   "description": "Fail-closed execution integrity for streamed LLM tool calls — reject truncated or unconfirmed arguments before side effects",
   "keywords": [
     "json",
@@ -12,7 +12,7 @@
     "tool-execution",
     "execution-safety",
     "function-calling",
-    "json-repair",
+    "vercel-ai-sdk",
     "json-parser"
   ],
   "license": "MIT OR Apache-2.0",
@@ -30,7 +30,23 @@
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
-      "import": "./dist/index.js"
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./ajv": {
+      "types": "./dist/ajv.d.ts",
+      "import": "./dist/ajv.js",
+      "default": "./dist/ajv.js"
+    },
+    "./standard-schema": {
+      "types": "./dist/standard-schema.d.ts",
+      "import": "./dist/standard-schema.js",
+      "default": "./dist/standard-schema.js"
+    },
+    "./conformance": {
+      "types": "./dist/conformance.d.ts",
+      "import": "./dist/conformance.js",
+      "default": "./dist/conformance.js"
     }
   },
   "files": [
@@ -98,7 +114,8 @@
     "tsx": "^4.16.0",
     "typescript": "^5.5.0",
     "typescript-eslint": "^8.0.0",
-    "vitest": "^3.2.6"
+    "vitest": "^3.2.6",
+    "zod": "4.4.3"
   },
   "pnpm": {
     "overrides": {