prefix-safe-json 0.4.5 → 0.5.0

package/dist/validation/types.d.ts

@@ -0,0 +1,60 @@
+/**
+ * @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`.
+ *
+ * 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. 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;AA+BD;;;;;;;;;;;;;;;GAeG;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,CAmCjC"}

package/dist/validation/types.js

@@ -0,0 +1,77 @@
+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)}`;
+}
+/**
+ * @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`.
+ *
+ * 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. 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) {
+        // 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(schemas)) {
+            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":"AAAA,OAAO,EAAE,wBAAwB,EAAE,MAAM,oBAAoB,CAAC;AA2C9D;;;;;;;;;;;;;GAaG;AACH,SAAS,0BAA0B,CAAC,KAAc;IAChD,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,OAAQ,KAAgC,CAAC,QAAQ,KAAK,UAAU,CAAC;AACzH,CAAC;AAED,SAAS,wBAAwB,CAAC,KAAc;IAC9C,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC9B,IAAI,CAAC;YACH,OAAO,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;QAC/B,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,MAAM,CAAC,SAAS,CAAC,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QAC/C,CAAC;IACH,CAAC;IACD,OAAO,GAAG,OAAO,KAAK,IAAI,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC;AAC5C,CAAC;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,iBAAiB,CAC/B,OAA2C,EAC3C,UAA0D;IAE1D,IAAI,OAAO,IAAI,UAAU,EAAE,CAAC;QAC1B,KAAK,MAAM,QAAQ,IAAI,MAAM,CAAC,IAAI,CAAC,UAAU,CAAC,EAAE,CAAC;YAC/C,IAAI,MAAM,CAAC,SAAS,CAAC,cAAc,CAAC,IAAI,CAAC,OAAO,EAAE,QAAQ,CAAC,EAAE,CAAC;gBAC5D,MAAM,IAAI,KAAK,CACb,0BAA0B,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,uCAAuC;oBACvF,gGAAgG,CACnG,CAAC;YACJ,CAAC;QACH,CAAC;IACH,CAAC;IAED,MAAM,GAAG,GAAG,IAAI,GAAG,EAA8B,CAAC;IAClD,IAAI,OAAO,EAAE,CAAC;QACZ,sEAAsE;QACtE,yDAAyD;QACzD,oEAAoE;QACpE,gEAAgE;QAChE,oEAAoE;QACpE,KAAK,MAAM,CAAC,QAAQ,EAAE,SAAS,CAAC,IAAI,wBAAwB,CAAC,OAAO,CAAC,EAAE,CAAC;YACtE,GAAG,CAAC,GAAG,CAAC,QAAQ,EAAE,SAAS,CAAC,CAAC;QAC/B,CAAC;IACH,CAAC;IACD,IAAI,UAAU,EAAE,CAAC;QACf,KAAK,MAAM,CAAC,QAAQ,EAAE,SAAS,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,UAAU,CAAC,EAAE,CAAC;YAC/D,IAAI,CAAC,0BAA0B,CAAC,SAAS,CAAC,EAAE,CAAC;gBAC3C,MAAM,IAAI,KAAK,CACb,gCAAgC,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,wCAAwC;oBAC9F,4DAA4D,wBAAwB,CAAC,SAAS,CAAC,EAAE,CACpG,CAAC;YACJ,CAAC;YACD,GAAG,CAAC,GAAG,CAAC,QAAQ,EAAE,SAAS,CAAC,CAAC;QAC/B,CAAC;IACH,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "prefix-safe-json",
-  "version": "0.4.5",
+  "version": "0.5.0",
   "description": "Fail-closed execution integrity for streamed LLM tool calls — reject truncated or unconfirmed arguments before side effects",
   "keywords": [
     "json",
@@ -31,6 +31,18 @@
     ".": {
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
+    },
+    "./ajv": {
+      "types": "./dist/ajv.d.ts",
+      "import": "./dist/ajv.js"
+    },
+    "./standard-schema": {
+      "types": "./dist/standard-schema.d.ts",
+      "import": "./dist/standard-schema.js"
+    },
+    "./conformance": {
+      "types": "./dist/conformance.d.ts",
+      "import": "./dist/conformance.js"
     }
   },
   "files": [