@zocomputer/system-api 0.0.0-stage → 0.1.1

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * `@zocomputer/system-api` — the package root entry: the typed invocation client.
+ *
+ * Re-exports the dependency-free core surface (`createClient`, the catalog
+ * helpers, the client/envelope/transport/error types). This is the import the
+ * plan's examples use — `import { createClient } from "@zocomputer/system-api"`. The
+ * optional structural validator stays behind the separate
+ * `@zocomputer/system-api/validation` specifier, so a typed-only consumer that imports
+ * the root never pulls Ajv, decimal.js, jsonc-parser, or re2js into its bundle.
+ */
+export * from "./core/index.ts";

package/dist/index.js

@@ -0,0 +1,11 @@
+/**
+ * `@zocomputer/system-api` — the package root entry: the typed invocation client.
+ *
+ * Re-exports the dependency-free core surface (`createClient`, the catalog
+ * helpers, the client/envelope/transport/error types). This is the import the
+ * plan's examples use — `import { createClient } from "@zocomputer/system-api"`. The
+ * optional structural validator stays behind the separate
+ * `@zocomputer/system-api/validation` specifier, so a typed-only consumer that imports
+ * the root never pulls Ajv, decimal.js, jsonc-parser, or re2js into its bundle.
+ */
+export * from "./core/index.js";

package/dist/json/index.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Lossless, bounded JSON for the System API SDK — a faithful port of the Python
+ * `hostagent.system_api.json` module, so the client validates exactly what the
+ * server published.
+ *
+ * Every value that crosses the boundary is a {@link JsonValue}: `null`,
+ * `boolean`, `string`, a {@link JsonNumber} (an exact decimal, never a lossy
+ * JS `number`), an array, or a string-keyed object. Numbers are decoded from
+ * their JSON text with no binary-float round trip and canonicalized so equal
+ * numeric values share one representation: integral values (`1`, `1.0`, `1e0`)
+ * become integers; others become a normalized decimal with no trailing zeros.
+ *
+ * Parsing preserves duplicate-key, non-finite, unpaired-surrogate, oversized-
+ * number and bound violations as {@link JsonError} with a bounded `code` and the
+ * instance `path`; messages never echo the offending value.
+ */
+import { Decimal } from "decimal.js";
+export declare const MAX_JSON_BYTES: number;
+export declare const MAX_JSON_NODES = 10000;
+export declare const MAX_JSON_DEPTH = 32;
+export declare const MAX_SERIALIZE_DEPTH = 256;
+export declare const MAX_NUMBER_DIGITS = 100;
+export declare const MAX_NUMBER_EXPONENT = 100;
+/**
+ * A canonical JSON number: an exact decimal plus whether it is integral. Kept
+ * distinct from a JS `number` so no value ever passes through a lossy double.
+ */
+export declare class JsonNumber {
+    readonly decimal: Decimal;
+    readonly isInteger: boolean;
+    /** Canonical JSON text (plain notation, no exponent, no trailing zeros). */
+    readonly text: string;
+    constructor(decimal: Decimal, isInteger: boolean, 
+    /** Canonical JSON text (plain notation, no exponent, no trailing zeros). */
+    text: string);
+}
+export type JsonScalar = null | boolean | string | JsonNumber;
+export type JsonValue = JsonScalar | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+export type JsonObject = {
+    [key: string]: JsonValue;
+};
+export type JsonPath = ReadonlyArray<string | number>;
+/** A value is not bounded, finite, lossless JSON. `code` is a bounded identifier. */
+export declare class JsonError extends Error {
+    readonly code: string;
+    readonly path: JsonPath;
+    constructor(code: string, message: string, path?: JsonPath);
+}
+export declare function formatPointer(path: JsonPath): string;
+export declare function splitPointer(pointer: string): string[];
+/** Canonicalize a numeric token from its exact JSON lexeme. */
+export declare function canonicalNumberFromToken(token: string, path?: JsonPath): JsonNumber;
+/** Render a canonical number as JSON number text (plain notation, no exponent). */
+export declare function formatNumber(value: JsonNumber): string;
+/**
+ * Parse JSON text losslessly, preserving the exact lexeme of every number and
+ * rejecting duplicate keys, `NaN`/`Infinity`, unpaired surrogates, oversized
+ * numbers and anything beyond the byte / node / depth bounds.
+ */
+export declare function loadsJson(data: string | Uint8Array, options?: {
+    maxBytes?: number;
+    maxNodes?: number | null;
+    maxDepth?: number;
+}): JsonValue;
+export declare function canonicalizeJson(value: JsonValue, options?: {
+    maxNodes?: number | null;
+    maxDepth?: number;
+}): JsonValue;
+export declare function checkJsonValue(value: JsonValue, options?: {
+    maxNodes?: number | null;
+    maxDepth?: number;
+}): void;
+/** Return `[nodes, depth]` of a JSON tree without copying it. */
+export declare function measureJson(value: JsonValue, maxDepth?: number): [number, number];
+/** Serialize deterministically: sorted keys (code-unit order), no whitespace. */
+export declare function canonicalJsonString(value: JsonValue): string;
+/** Serialize keeping key order (the wire form the validator returns on success). */
+export declare function dumpsJson(value: JsonValue): string;
+export declare function canonicalJsonBytes(value: JsonValue): Uint8Array;

package/dist/json/index.js

@@ -0,0 +1,404 @@
+/**
+ * Lossless, bounded JSON for the System API SDK — a faithful port of the Python
+ * `hostagent.system_api.json` module, so the client validates exactly what the
+ * server published.
+ *
+ * Every value that crosses the boundary is a {@link JsonValue}: `null`,
+ * `boolean`, `string`, a {@link JsonNumber} (an exact decimal, never a lossy
+ * JS `number`), an array, or a string-keyed object. Numbers are decoded from
+ * their JSON text with no binary-float round trip and canonicalized so equal
+ * numeric values share one representation: integral values (`1`, `1.0`, `1e0`)
+ * become integers; others become a normalized decimal with no trailing zeros.
+ *
+ * Parsing preserves duplicate-key, non-finite, unpaired-surrogate, oversized-
+ * number and bound violations as {@link JsonError} with a bounded `code` and the
+ * instance `path`; messages never echo the offending value.
+ */
+import { Decimal } from "decimal.js";
+import { parseTree } from "jsonc-parser";
+/** Exact decimal arithmetic for bounded numbers; matches the Python precision. */
+const Dec = Decimal.clone({ precision: 400 });
+export const MAX_JSON_BYTES = 16 * 1024 * 1024;
+export const MAX_JSON_NODES = 10_000;
+export const MAX_JSON_DEPTH = 32;
+export const MAX_SERIALIZE_DEPTH = 256;
+export const MAX_NUMBER_DIGITS = 100;
+export const MAX_NUMBER_EXPONENT = 100;
+const NUMBER_TOKEN_MAX_LENGTH = MAX_NUMBER_DIGITS + MAX_NUMBER_EXPONENT + 8;
+const INT_TOKEN = /^-?(?:0|[1-9][0-9]*)$/;
+/**
+ * A canonical JSON number: an exact decimal plus whether it is integral. Kept
+ * distinct from a JS `number` so no value ever passes through a lossy double.
+ */
+export class JsonNumber {
+    decimal;
+    isInteger;
+    text;
+    constructor(decimal, isInteger, 
+    /** Canonical JSON text (plain notation, no exponent, no trailing zeros). */
+    text) {
+        this.decimal = decimal;
+        this.isInteger = isInteger;
+        this.text = text;
+    }
+}
+/** A value is not bounded, finite, lossless JSON. `code` is a bounded identifier. */
+export class JsonError extends Error {
+    code;
+    path;
+    constructor(code, message, path = []) {
+        super(path.length > 0 ? `${message} at ${formatPointer(path)}` : message);
+        this.code = code;
+        this.path = path;
+        this.name = "JsonError";
+    }
+}
+// --- JSON Pointer (RFC 6901) -------------------------------------------------
+function escapeToken(token) {
+    return token.replace(/~/g, "~0").replace(/\//g, "~1");
+}
+export function formatPointer(path) {
+    return path.map((token) => "/" + escapeToken(String(token))).join("");
+}
+function unescapeToken(token) {
+    let out = "";
+    let i = 0;
+    while (i < token.length) {
+        const char = token[i];
+        if (char === "~") {
+            const next = i + 1 < token.length ? token[i + 1] : "";
+            if (next === "0")
+                out += "~";
+            else if (next === "1")
+                out += "/";
+            else
+                throw new JsonError("invalid_pointer", "pointer has an invalid escape sequence");
+            i += 2;
+        }
+        else {
+            out += char;
+            i += 1;
+        }
+    }
+    return out;
+}
+export function splitPointer(pointer) {
+    if (pointer === "")
+        return [];
+    if (!pointer.startsWith("/"))
+        throw new JsonError("invalid_pointer", "pointer must be empty or start with '/'");
+    return pointer
+        .split("/")
+        .slice(1)
+        .map((token) => unescapeToken(token));
+}
+// --- number canonicalization -------------------------------------------------
+/** Count significant digits (trailing zeros excluded), matching Python normalize. */
+function significantDigits(value) {
+    return value.precision(false);
+}
+/**
+ * Canonicalize a decimal value the way Python `canonical_number` does. Integral
+ * values become integers (re-checked against the digit rule); others keep a
+ * normalized decimal. Raises `number_too_large` past the digit/exponent bounds.
+ */
+function canonicalizeDecimal(value, path) {
+    if (!value.isFinite())
+        throw new JsonError("nonfinite_number", "number is not finite", path);
+    const normalized = value; // Decimal already carries no representational noise.
+    const sig = significantDigits(normalized);
+    if (sig > MAX_NUMBER_DIGITS)
+        throw new JsonError("number_too_large", "number exceeds the supported digit count", path);
+    if (normalized.isZero())
+        return new JsonNumber(new Dec(0), true, "0");
+    const adjusted = normalized.e;
+    if (Math.abs(adjusted) > MAX_NUMBER_EXPONENT)
+        throw new JsonError("number_too_large", "number exceeds the supported exponent range", path);
+    const tupleExponent = adjusted - (sig - 1);
+    if (tupleExponent >= 0) {
+        // Integral: re-check through the integer digit rule (1e100 → 101 digits).
+        const intDigits = adjusted + 1;
+        if (intDigits > MAX_NUMBER_DIGITS)
+            throw new JsonError("number_too_large", "integer exceeds the supported digit count", path);
+        return new JsonNumber(normalized, true, normalized.toFixed(0));
+    }
+    return new JsonNumber(normalized, false, normalized.toFixed());
+}
+/** Canonicalize a numeric token from its exact JSON lexeme. */
+export function canonicalNumberFromToken(token, path = []) {
+    if (INT_TOKEN.test(token)) {
+        const digits = token.replace("-", "");
+        if (digits.length > MAX_NUMBER_DIGITS)
+            throw new JsonError("number_too_large", "integer exceeds the supported digit count", path);
+        const value = new Dec(token);
+        return new JsonNumber(value, true, value.toFixed(0));
+    }
+    if (token.length > NUMBER_TOKEN_MAX_LENGTH)
+        throw new JsonError("number_too_large", "number exceeds the supported digit count", path);
+    let value;
+    try {
+        value = new Dec(token);
+    }
+    catch {
+        throw new JsonError("not_json", "document is not valid JSON", path);
+    }
+    return canonicalizeDecimal(value, path);
+}
+/** Render a canonical number as JSON number text (plain notation, no exponent). */
+export function formatNumber(value) {
+    return value.text;
+}
+// --- string checks -----------------------------------------------------------
+/** True when the string contains an unpaired UTF-16 surrogate. */
+function hasLoneSurrogate(value) {
+    for (let i = 0; i < value.length; i++) {
+        const code = value.charCodeAt(i);
+        if (code >= 0xd800 && code <= 0xdbff) {
+            const next = i + 1 < value.length ? value.charCodeAt(i + 1) : 0;
+            if (next < 0xdc00 || next > 0xdfff)
+                return true;
+            i++;
+        }
+        else if (code >= 0xdc00 && code <= 0xdfff) {
+            return true;
+        }
+    }
+    return false;
+}
+function checkString(value, path) {
+    if (hasLoneSurrogate(value))
+        throw new JsonError("invalid_string", "string contains an unpaired surrogate", path);
+    return value;
+}
+// --- bounded walk (node + depth budget) --------------------------------------
+class Walk {
+    maxNodes;
+    nodes = 0;
+    maxDepth;
+    constructor(maxNodes, maxDepth) {
+        this.maxNodes = maxNodes;
+        this.maxDepth = Math.min(maxDepth, MAX_SERIALIZE_DEPTH);
+    }
+    visit(path, depth) {
+        if (depth > this.maxDepth)
+            throw new JsonError("too_deep", "value nesting exceeds the supported depth", path);
+        this.nodes += 1;
+        if (this.maxNodes !== null && this.nodes > this.maxNodes)
+            throw new JsonError("too_many_nodes", "value exceeds the supported node count", path);
+    }
+}
+// --- parse (jsonc-parser tree → canonical JsonValue) -------------------------
+function buildValue(node, path, depth, walk) {
+    walk.visit(path, depth);
+    switch (node.type) {
+        case "null":
+            return null;
+        case "boolean":
+            return node.value;
+        case "string":
+            return checkString(node.value, path);
+        case "number":
+            return canonicalNumberFromToken(node.offsetText ?? String(node.value), path);
+        case "array": {
+            const out = [];
+            const children = node.children ?? [];
+            for (let i = 0; i < children.length; i++) {
+                out.push(buildValue(children[i], [...path, i], depth + 1, walk));
+            }
+            return out;
+        }
+        case "object": {
+            // Null-prototype record: assigning a `__proto__` key must create an own
+            // data property (not invoke the inherited setter), so the literal is
+            // preserved and a duplicate `__proto__` is caught by the hasOwn check.
+            const out = Object.create(null);
+            const children = node.children ?? [];
+            for (const prop of children) {
+                const keyNode = prop.children?.[0];
+                const valNode = prop.children?.[1];
+                if (keyNode === undefined || valNode === undefined)
+                    throw new JsonError("not_json", "document is not valid JSON", path);
+                const key = keyNode.value;
+                if (Object.prototype.hasOwnProperty.call(out, key))
+                    throw new JsonError("duplicate_key", "object has a duplicate key", path);
+                out[checkString(key, path)] = buildValue(valNode, [...path, key], depth + 1, walk);
+            }
+            return out;
+        }
+        default:
+            throw new JsonError("not_json", "document is not valid JSON", path);
+    }
+}
+/**
+ * Parse JSON text losslessly, preserving the exact lexeme of every number and
+ * rejecting duplicate keys, `NaN`/`Infinity`, unpaired surrogates, oversized
+ * numbers and anything beyond the byte / node / depth bounds.
+ */
+export function loadsJson(data, options = {}) {
+    const maxBytes = options.maxBytes ?? MAX_JSON_BYTES;
+    const maxNodes = options.maxNodes === undefined ? MAX_JSON_NODES : options.maxNodes;
+    const maxDepth = options.maxDepth ?? MAX_JSON_DEPTH;
+    let text;
+    if (typeof data === "string") {
+        if (new TextEncoder().encode(data).length > maxBytes)
+            throw new JsonError("too_large", "document exceeds the supported size");
+        text = data;
+    }
+    else {
+        if (data.length > maxBytes)
+            throw new JsonError("too_large", "document exceeds the supported size");
+        try {
+            text = new TextDecoder("utf-8", { fatal: true }).decode(data);
+        }
+        catch {
+            throw new JsonError("invalid_string", "document is not valid UTF-8");
+        }
+    }
+    const errors = [];
+    const root = parseTree(text, errors, {
+        disallowComments: true,
+        allowTrailingComma: false,
+        allowEmptyContent: false,
+    });
+    if (errors.length > 0 || root === undefined) {
+        for (const error of errors) {
+            const fragment = text.slice(error.offset, error.offset + 12).trimStart();
+            if (/^-?(NaN|Infinity)/.test(fragment))
+                throw new JsonError("nonfinite_number", "NaN and Infinity are not JSON numbers");
+        }
+        throw new JsonError("not_json", "document is not valid JSON");
+    }
+    return buildValue(attachLexemes(root, text), [], 1, new Walk(maxNodes, maxDepth));
+}
+/** Attach each number node's exact source lexeme (jsonc-parser drops precision). */
+function attachLexemes(node, text) {
+    if (node.type === "number") {
+        node.offsetText = text.slice(node.offset, node.offset + node.length);
+    }
+    for (const child of node.children ?? [])
+        attachLexemes(child, text);
+    return node;
+}
+// --- canonicalization / measurement of an existing JsonValue tree ------------
+function canonicalizeValue(value, path, depth, walk) {
+    walk.visit(path, depth);
+    if (value === null || typeof value === "boolean")
+        return value;
+    if (typeof value === "string")
+        return checkString(value, path);
+    if (value instanceof JsonNumber)
+        return canonicalizeDecimal(value.decimal, path);
+    if (Array.isArray(value))
+        return value.map((item, index) => canonicalizeValue(item, [...path, index], depth + 1, walk));
+    // Null-prototype record so a `__proto__` key survives canonicalization as an
+    // own data property rather than mutating the prototype chain.
+    const out = Object.create(null);
+    for (const key of Object.keys(value))
+        out[checkString(key, path)] = canonicalizeValue(value[key], [...path, key], depth + 1, walk);
+    return out;
+}
+export function canonicalizeJson(value, options = {}) {
+    const maxNodes = options.maxNodes === undefined ? MAX_JSON_NODES : options.maxNodes;
+    const maxDepth = options.maxDepth ?? MAX_JSON_DEPTH;
+    return canonicalizeValue(value, [], 1, new Walk(maxNodes, maxDepth));
+}
+export function checkJsonValue(value, options = {}) {
+    const maxNodes = options.maxNodes === undefined ? MAX_JSON_NODES : options.maxNodes;
+    const maxDepth = options.maxDepth ?? MAX_JSON_DEPTH;
+    canonicalizeValue(value, [], 1, new Walk(maxNodes, maxDepth));
+}
+/** Return `[nodes, depth]` of a JSON tree without copying it. */
+export function measureJson(value, maxDepth = MAX_SERIALIZE_DEPTH) {
+    const walk = new Walk(null, maxDepth);
+    const depth = measure(value, [], 1, walk);
+    return [walk.nodes, depth];
+}
+function measure(value, path, depth, walk) {
+    walk.visit(path, depth);
+    if (Array.isArray(value)) {
+        let deepest = depth;
+        value.forEach((item, index) => {
+            deepest = Math.max(deepest, measure(item, [...path, index], depth + 1, walk));
+        });
+        return deepest;
+    }
+    if (value !== null &&
+        !(value instanceof JsonNumber) &&
+        typeof value === "object") {
+        let deepest = depth;
+        for (const key of Object.keys(value))
+            deepest = Math.max(deepest, measure(value[key], [...path, key], depth + 1, walk));
+        return deepest;
+    }
+    return depth;
+}
+// --- canonical serialization -------------------------------------------------
+function encodeString(value) {
+    return JSON.stringify(value);
+}
+function writeValue(value, parts, sortKeys) {
+    if (value === null)
+        parts.push("null");
+    else if (value === true)
+        parts.push("true");
+    else if (value === false)
+        parts.push("false");
+    else if (typeof value === "string")
+        parts.push(encodeString(value));
+    else if (value instanceof JsonNumber)
+        parts.push(value.text);
+    else if (Array.isArray(value)) {
+        if (value.length === 0) {
+            parts.push("[]");
+            return;
+        }
+        parts.push("[");
+        value.forEach((item, index) => {
+            if (index)
+                parts.push(",");
+            writeValue(item, parts, sortKeys);
+        });
+        parts.push("]");
+    }
+    else {
+        const keys = Object.keys(value);
+        if (keys.length === 0) {
+            parts.push("{}");
+            return;
+        }
+        if (sortKeys)
+            keys.sort();
+        parts.push("{");
+        keys.forEach((key, index) => {
+            if (index)
+                parts.push(",");
+            parts.push(encodeString(key));
+            parts.push(":");
+            writeValue(value[key], parts, sortKeys);
+        });
+        parts.push("}");
+    }
+}
+/** Serialize deterministically: sorted keys (code-unit order), no whitespace. */
+export function canonicalJsonString(value) {
+    const canonical = canonicalizeJson(value, {
+        maxNodes: null,
+        maxDepth: MAX_SERIALIZE_DEPTH,
+    });
+    const parts = [];
+    writeValue(canonical, parts, true);
+    return parts.join("");
+}
+/** Serialize keeping key order (the wire form the validator returns on success). */
+export function dumpsJson(value) {
+    const canonical = canonicalizeJson(value, {
+        maxNodes: null,
+        maxDepth: MAX_SERIALIZE_DEPTH,
+    });
+    const parts = [];
+    writeValue(canonical, parts, false);
+    return parts.join("");
+}
+export function canonicalJsonBytes(value) {
+    return new TextEncoder().encode(canonicalJsonString(value));
+}

package/dist/validation/index.d.ts

@@ -0,0 +1,19 @@
+import type { InvocationValidator } from "../core/validator.ts";
+export { CompiledSchema, SchemaDefinitionError, SchemaError, SchemaValidationError, compileSchema, } from "./schema.ts";
+/** Thrown when the schema bundle handed to the factory is malformed. */
+export declare class SchemaBundleError extends Error {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+/** Thrown when a call resolves to no manifest entry or a disagreeing digest. */
+export declare class ValidatorTargetError extends Error {
+    constructor(message: string);
+}
+/**
+ * Build a structural {@link InvocationValidator} from the offline schema bundle
+ * bytes. The bundle is decoded and every action schema compiled up front, so
+ * both hooks are synchronous and allocation-light. A malformed bundle throws
+ * {@link SchemaBundleError} at construction; it never fails silently.
+ */
+export declare function createSchemaValidator(schemaBundleBytes: Uint8Array): InvocationValidator;

package/dist/validation/index.js

@@ -0,0 +1,149 @@
+import { JsonNumber, MAX_JSON_DEPTH, loadsJson, } from "./json.js";
+import { MAX_SCHEMA_DEPTH, compileSchema, } from "./schema.js";
+export { CompiledSchema, SchemaDefinitionError, SchemaError, SchemaValidationError, compileSchema, } from "./schema.js";
+/** The manifest wraps each bounded schema, so it nests a few levels deeper. */
+const MAX_MANIFEST_DEPTH = MAX_SCHEMA_DEPTH + 8;
+/** The only offline-manifest format this factory accepts (codegen emits `1`). */
+const SUPPORTED_MANIFEST_FORMAT_VERSION = 1;
+/** Action/contract versions are positive 32-bit integers, matching the contract. */
+const MAX_CONTRACT_VERSION = 2_147_483_647;
+/**
+ * The invocation envelope nests the validated `input`/`result` one level down,
+ * so it is parsed with the node bound disabled and only wrapper depth headroom;
+ * the selected value carries its own node/depth budget inside `CompiledSchema`.
+ * Mirrors the server's `MAX_JSON_DEPTH + ENVELOPE_DEPTH_HEADROOM`.
+ */
+const ENVELOPE_DEPTH_HEADROOM = 2;
+const MAX_ENVELOPE_DEPTH = MAX_JSON_DEPTH + ENVELOPE_DEPTH_HEADROOM;
+/** Thrown when the schema bundle handed to the factory is malformed. */
+export class SchemaBundleError extends Error {
+    constructor(message, options) {
+        super(message, options);
+        this.name = "SchemaBundleError";
+    }
+}
+/** Thrown when a call resolves to no manifest entry or a disagreeing digest. */
+export class ValidatorTargetError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "ValidatorTargetError";
+    }
+}
+function isObject(value) {
+    return (value !== null &&
+        typeof value === "object" &&
+        !Array.isArray(value) &&
+        !(value instanceof JsonNumber));
+}
+function targetKey(action, version) {
+    return `${action}\u0000${version}`;
+}
+/**
+ * Build a structural {@link InvocationValidator} from the offline schema bundle
+ * bytes. The bundle is decoded and every action schema compiled up front, so
+ * both hooks are synchronous and allocation-light. A malformed bundle throws
+ * {@link SchemaBundleError} at construction; it never fails silently.
+ */
+export function createSchemaValidator(schemaBundleBytes) {
+    let manifest;
+    try {
+        manifest = loadsJson(schemaBundleBytes, {
+            maxNodes: null,
+            maxDepth: MAX_MANIFEST_DEPTH,
+        });
+    }
+    catch (error) {
+        throw new SchemaBundleError("schema bundle is not valid JSON", {
+            cause: error,
+        });
+    }
+    if (!isObject(manifest))
+        throw new SchemaBundleError("schema bundle must be a JSON object");
+    // Refuse any bundle that does not declare the supported format, so an unknown
+    // future or foreign shape can never silently claim validation. Extra
+    // top-level metadata fields (an authenticated catalog export's
+    // `protocol_version`, `view_revision`, `selection`, `default_versions`,
+    // `availability`, `catalog_digest`, …) are ignored, not rejected.
+    const formatVersion = manifest["format_version"];
+    if (!(formatVersion instanceof JsonNumber) ||
+        !formatVersion.isInteger ||
+        Number(formatVersion.text) !== SUPPORTED_MANIFEST_FORMAT_VERSION)
+        throw new SchemaBundleError(`schema bundle format is unsupported (expected format_version ${SUPPORTED_MANIFEST_FORMAT_VERSION})`);
+    const rawActions = manifest["actions"];
+    if (!Array.isArray(rawActions))
+        throw new SchemaBundleError("schema bundle is missing an 'actions' array");
+    const index = new Map();
+    for (const raw of rawActions) {
+        if (!isObject(raw))
+            throw new SchemaBundleError("each manifest action must be an object");
+        const name = raw["name"];
+        const version = raw["version"];
+        const digest = raw["digest"];
+        const inputSchema = raw["input_schema"];
+        const outputSchema = raw["output_schema"];
+        if (typeof name !== "string" || name.length === 0)
+            throw new SchemaBundleError("a manifest action is missing its name");
+        if (!(version instanceof JsonNumber && version.isInteger))
+            throw new SchemaBundleError(`manifest action '${name}' has a non-integer version`);
+        const versionValue = Number(version.text);
+        if (versionValue < 1 || versionValue > MAX_CONTRACT_VERSION)
+            throw new SchemaBundleError(`manifest action '${name}' has an out-of-range version`);
+        if (typeof digest !== "string" || digest.length === 0)
+            throw new SchemaBundleError(`manifest action '${name}' is missing its digest`);
+        if (!isObject(inputSchema) || !isObject(outputSchema))
+            throw new SchemaBundleError(`manifest action '${name}' is missing an input or output schema`);
+        let input;
+        let output;
+        try {
+            input = compileSchema(inputSchema);
+            output = compileSchema(outputSchema);
+        }
+        catch (error) {
+            throw new SchemaBundleError(`manifest action '${name}' has an uncompilable schema`, { cause: error });
+        }
+        const key = targetKey(name, versionValue);
+        // A duplicate (action, version) makes the schema source ambiguous — refuse
+        // rather than let a later entry silently overwrite an earlier one.
+        if (index.has(key))
+            throw new SchemaBundleError(`manifest has a duplicate entry for action '${name}' version ${versionValue}`);
+        index.set(key, { digest, input, output });
+    }
+    const resolve = (target) => {
+        const entry = index.get(targetKey(target.action, target.version));
+        if (entry === undefined)
+            throw new ValidatorTargetError(`no schema for action '${target.action}' version ${target.version}`);
+        if (entry.digest !== target.digest)
+            throw new ValidatorTargetError(`schema digest disagrees with the pinned catalog for action '${target.action}' version ${target.version}`);
+        return entry;
+    };
+    const field = (body, key) => {
+        if (!isObject(body) || !Object.hasOwn(body, key))
+            throw new SchemaBundleError(`invocation body is missing '${key}'`);
+        return body[key];
+    };
+    // Parse the wrapping envelope with the node bound disabled and only wrapper
+    // depth headroom; the selected `input`/`result` is budgeted inside
+    // `CompiledSchema.validate`, so a server-legal payload is never rejected as an
+    // envelope for the wrapper's own nodes.
+    const parseEnvelope = (text) => loadsJson(text, { maxNodes: null, maxDepth: MAX_ENVELOPE_DEPTH });
+    return {
+        validateRequestBody(target, exactBody) {
+            const entry = resolve(target);
+            // Validate the exact bytes the way the server canonicalizes input:
+            // defaults are filled before conformance is judged, so the hook accepts
+            // exactly the inputs the server accepts.
+            entry.input.validate(field(parseEnvelope(exactBody), "input"), {
+                applyDefaults: true,
+            });
+        },
+        validateSuccessBody(target, rawText, _success) {
+            const entry = resolve(target);
+            // Re-parse the raw bytes losslessly (the correlated `success` carries a
+            // precision-lossy `result`) and validate the result against the output
+            // schema without filling defaults, matching `validate_output`.
+            entry.output.validate(field(parseEnvelope(rawText), "result"), {
+                applyDefaults: false,
+            });
+        },
+    };
+}

package/dist/validation/json.d.ts

@@ -0,0 +1 @@
+export * from "../json/index.ts";

package/dist/validation/json.js

@@ -0,0 +1 @@
+export * from "../json/index.js";