@jangts/agent-core 0.1.0 → 0.2.0

package/dist/cjs/support/model/reply-preview.js

@@ -1,6 +1,15 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.createReplyPreview = createReplyPreview;
+/**
+ * Incremental reply preview: project partial model output into presentable bubbles.
+ *
+ * The projection is a lexical scan, deliberately separate from authoritative JSON or schema
+ * validation, and it only reads explicitly registered prose fields. It is presentation only: it
+ * must never authorize, persist or execute a proposal.
+ *
+ * Main export: `createReplyPreview` and its rule/settings types.
+ */
 const synchronous_js_1 = require("../../utils/synchronous.js");
 /** Incremental lexical projection, deliberately separate from authoritative JSON/schema validation. */
 class StringProjection {
@@ -44,7 +53,16 @@ class StringProjection {
                     if (ch === 'u')
                         token.unicode = '';
                     else {
-                        const escapes = { '"': '"', '\\': '\\', '/': '/', b: '\b', f: '\f', n: '\n', r: '\r', t: '\t' };
+                        const escapes = {
+                            '"': '"',
+                            '\\': '\\',
+                            '/': '/',
+                            b: '\b',
+                            f: '\f',
+                            n: '\n',
+                            r: '\r',
+                            t: '\t',
+                        };
                         if (!(ch in escapes))
                             throw new Error('Invalid escape');
                         token.text += escapes[ch];
@@ -89,7 +107,9 @@ class StringProjection {
             }
             const frame = this.stack.at(-1);
             if (ch === '}' || ch === ']') {
-                if (!frame || (ch === '}' ? frame.kind !== '{' : frame.kind !== '[') || !['key', 'value', 'comma'].includes(frame.state))
+                if (!frame ||
+                    (ch === '}' ? frame.kind !== '{' : frame.kind !== '[') ||
+                    !['key', 'value', 'comma'].includes(frame.state))
                     throw new Error('Invalid close');
                 this.stack.pop();
                 this.complete();
@@ -111,8 +131,16 @@ class StringProjection {
                 if (!frame || !['key', 'value'].includes(frame.state))
                     throw new Error('Invalid string position');
                 const key = frame.state === 'key', path = this.path();
-                const projected = !key && this.paths.some(pattern => path.length === pattern.length && pattern.every((key, i) => key === '*' ? /^\d+$/.test(path[i]) : key === path[i]));
-                this.token = { key, path, text: '', projectionKey: projected ? JSON.stringify(path) : undefined, escape: false };
+                const projected = !key &&
+                    this.paths.some((pattern) => path.length === pattern.length &&
+                        pattern.every((key, i) => (key === '*' ? /^\d+$/.test(path[i]) : key === path[i])));
+                this.token = {
+                    key,
+                    path,
+                    text: '',
+                    projectionKey: projected ? JSON.stringify(path) : undefined,
+                    escape: false,
+                };
                 continue;
             }
             if (frame && frame.state !== 'value')
@@ -123,23 +151,46 @@ class StringProjection {
             if (ch === '{' || ch === '[') {
                 if (this.stack.length >= 32)
                     throw new Error('Too deep');
-                this.stack.push({ path: this.path(), kind: ch, state: ch === '{' ? 'key' : 'value', index: 0, keys: new Set() });
+                this.stack.push({
+                    path: this.path(),
+                    kind: ch,
+                    state: ch === '{' ? 'key' : 'value',
+                    index: 0,
+                    keys: new Set(),
+                });
             }
             else
                 this.primitive = true;
         }
     }
-    string(path) { const key = JSON.stringify(path); return this.completedStrings.has(key) ? this.values.get(key)?.text : undefined; }
+    string(path) {
+        const key = JSON.stringify(path);
+        return this.completedStrings.has(key) ? this.values.get(key)?.text : undefined;
+    }
     texts(paths = this.paths) {
         // Later bubbles can arrive first in JSON; keep their indices stable until the leading prose exists.
         const first = paths[0];
         if (first && !first.includes('*') && !this.values.has(JSON.stringify(first)))
             return [];
-        return paths.flatMap(pattern => [...this.values.values()].filter(({ path }) => path.length === pattern.length && pattern.every((key, i) => key === '*' ? /^\d+$/.test(path[i]) : key === path[i]))
-            .sort((a, b) => Number(a.path.at(-1)) - Number(b.path.at(-1)))).map(value => value.text);
+        return paths
+            .flatMap((pattern) => [...this.values.values()]
+            .filter(({ path }) => path.length === pattern.length &&
+            pattern.every((key, i) => (key === '*' ? /^\d+$/.test(path[i]) : key === path[i])))
+            .sort((a, b) => Number(a.path.at(-1)) - Number(b.path.at(-1))))
+            .map((value) => value.text);
     }
 }
-/** Only explicitly registered prose fields are projected. Tools/reviews are never selected implicitly. */
+/**
+ * Create a model-output event handler that publishes preview bubbles.
+ *
+ * The handler resets on `model.start`, ignores other invocations, disables itself on unexpected
+ * output, and clears the preview when a call ends unsuccessfully. Rules are snapshotted at
+ * creation, and only explicitly registered prose fields are projected.
+ *
+ * @param options Rules, optional renderer, character budget and the bubble sink.
+ * @returns An async handler for `ModelOutputEvent`.
+ * @throws {TypeError} When the sink is missing or `maxChars` is not a positive integer.
+ */
 function createReplyPreview(options) {
     if (typeof options.sink !== 'function')
         throw new TypeError('A reply preview sink is required');
@@ -147,7 +198,7 @@ function createReplyPreview(options) {
     const maxChars = options.maxChars ?? 16000;
     if (!Number.isSafeInteger(maxChars) || maxChars < 1)
         throw new TypeError('Invalid reply preview budget');
-    const rules = options.rules.map(rule => Object.freeze({
+    const rules = options.rules.map((rule) => Object.freeze({
         capabilityId: rule.capabilityId,
         stageId: rule.stageId,
         paths: rule.paths === undefined ? undefined : structuredClone(rule.paths),
@@ -158,10 +209,13 @@ function createReplyPreview(options) {
     let selected;
     let activeCall;
     const publish = async (texts) => {
-        // Hold incomplete surrogate pairs and never show internal control characters.
+        // Hold incomplete surrogate pairs and never show internal control characters. The bubble cap
+        // is independent of `maxChars`: at most five bubbles and 16000 characters reach the sink.
         let remaining = 16000;
-        const bubbles = texts.slice(0, 5).map(text => {
-            const value = (render ? (0, synchronous_js_1.synchronous)(render(text), 'Reply preview renderers must be synchronous') : text).slice(0, remaining).replace(/[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f]|[\ud800-\udbff]$/gu, '');
+        const bubbles = texts.slice(0, 5).map((text) => {
+            const value = (render ? (0, synchronous_js_1.synchronous)(render(text), 'Reply preview renderers must be synchronous') : text)
+                .slice(0, remaining)
+                .replace(/[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f]|[\ud800-\udbff]$/gu, '');
             remaining -= value.length;
             return value;
         });
@@ -197,14 +251,17 @@ function createReplyPreview(options) {
         if (disabled)
             return;
         const part = event.payload.part;
-        chars += typeof part === 'string' ? part.length : (part.name?.length ?? 0) + (part.arguments?.length ?? 0);
+        chars +=
+            typeof part === 'string'
+                ? part.length
+                : (part.name?.length ?? 0) + (part.arguments?.length ?? 0);
         if (chars > maxChars) {
             disabled = true;
             await publish([]);
             return;
         }
         if (typeof part === 'string') {
-            const rule = rules.find(rule => !rule.capabilityId && rule.stageId === event.payload.stageId);
+            const rule = rules.find((rule) => !rule.capabilityId && rule.stageId === event.payload.stageId);
             if (!rule) {
                 if (part.trim()) {
                     disabled = true;
@@ -222,7 +279,7 @@ function createReplyPreview(options) {
             return;
         }
         name += part.name ?? '';
-        const rule = rules.find(rule => rule.capabilityId === name && (!rule.stageId || rule.stageId === event.payload.stageId));
+        const rule = rules.find((rule) => rule.capabilityId === name && (!rule.stageId || rule.stageId === event.payload.stageId));
         if (!rule) {
             if (selected) {
                 disabled = true;
@@ -235,7 +292,10 @@ function createReplyPreview(options) {
         try {
             if (!selected) {
                 selected = rule;
-                parser = new StringProjection([...(rule.paths ?? [['text'], ['bubbles', '*']]), ...(rule.when ? [rule.when.path] : [])]);
+                parser = new StringProjection([
+                    ...(rule.paths ?? [['text'], ['bubbles', '*']]),
+                    ...(rule.when ? [rule.when.path] : []),
+                ]);
                 parser.push(argumentsText);
                 argumentsText = '';
             }

package/dist/cjs/support/model/stage-transport.js

@@ -1,17 +1,37 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.createStageModelTransport = createStageModelTransport;
+/**
+ * Stage-scoped model transport: expose only the capabilities declared for each stage.
+ *
+ * Static capability sources are projected once at construction; dynamic sources are re-projected
+ * at the model boundary. Either way, an undeclared stage or capability is rejected rather than
+ * silently omitted.
+ *
+ * Main export: `createStageModelTransport`.
+ */
 const synchronous_js_1 = require("../../utils/synchronous.js");
 const model_js_1 = require("../../capabilities/model.js");
 const rules_js_1 = require("../../utils/rules.js");
 const transports_js_1 = require("./transports.js");
-/** Compile static references now; dynamic sources are checked afresh at the model boundary. */
+/**
+ * Build a transport that projects a capability source through declared stage references.
+ *
+ * @param registration Transport declaration: unique ID, stage-to-capability references, interaction
+ *   adapter, options and a static or per-stage capability source.
+ * @returns A Core model transport with `capabilities(stage)`.
+ * @throws {Error} When a stage ID repeats, has no capability IDs, the declaration has no stages, a
+ *   stage or capability is not registered, or a dynamic capability source is asynchronous.
+ */
 function createStageModelTransport(registration) {
     const stages = new Map();
     for (const stage of registration.stages) {
         const ids = stage.capabilityIds;
-        (0, rules_js_1.breakWhile)(!stage.id?.trim() || stages.has(stage.id) || !Array.isArray(ids) || !ids.length
-            || new Set(ids).size !== ids.length, `Invalid model stage: ${stage.id}`);
+        (0, rules_js_1.breakWhile)(!stage.id?.trim() ||
+            stages.has(stage.id) ||
+            !Array.isArray(ids) ||
+            !ids.length ||
+            new Set(ids).size !== ids.length, `Invalid model stage: ${stage.id}`);
         stages.set(stage.id, Object.freeze([...ids]));
     }
     (0, rules_js_1.breakWhile)(!stages.size, 'Model transport requires declared stages');
@@ -33,13 +53,19 @@ function createStageModelTransport(registration) {
             },
         });
     };
-    const fixed = typeof source === 'function' ? undefined
-        : new Map([...stages.keys()].map(stage => [stage, project(stage, source)]));
+    const fixed = typeof source === 'function'
+        ? undefined
+        : new Map([...stages.keys()].map((stage) => [stage, project(stage, source)]));
     return (0, transports_js_1.createModelTransport)({
-        id, adapter, options, requireStrictArguments,
+        id,
+        adapter,
+        options,
+        requireStrictArguments,
         capabilities(stage) {
             (0, rules_js_1.breakWhile)(!stages.has(stage), `Unregistered model stage: ${id} -> ${stage}`);
-            return fixed ? fixed.get(stage) : project(stage, (0, synchronous_js_1.synchronous)(source.call(registration, stage), 'Model capability sources must be synchronous'));
+            return fixed
+                ? fixed.get(stage)
+                : project(stage, (0, synchronous_js_1.synchronous)(source.call(registration, stage), 'Model capability sources must be synchronous'));
         },
     });
 }

package/dist/cjs/support/model/strategies.js

@@ -2,21 +2,70 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.modelBudgetStrategies = void 0;
 exports.createModelStrategy = createModelStrategy;
+/**
+ * Model strategy presets: compose a Core `ModelRunnerOptions` from named sources.
+ *
+ * A strategy selects a model definition (inline or by catalog ID), optional reasoning variant and
+ * a budget preset, then layers any explicit Core fields last. Values are local admission
+ * allowances, not claims about provider capacity or performance.
+ *
+ * Main exports: `modelBudgetStrategies`, `createModelStrategy` and the strategy option types.
+ */
 const binding_js_1 = require("../../model/binding.js");
-/** Local admission and output allowances, never a claim about provider capacity or performance. */
+/**
+ * Budget presets by expected workload size.
+ *
+ * `maxCalls` counts model calls per run; `maxInputChars`/`maxOutputChars` are character budgets;
+ * `maxOutputTokens` is the per-call output reservation; `callTimeoutMs` bounds one call in
+ * milliseconds. These are local admission and output allowances, never a claim about provider
+ * capacity or performance.
+ */
 exports.modelBudgetStrategies = Object.freeze({
-    small: Object.freeze({ maxCalls: 2, maxInputChars: 8000, maxOutputChars: 4000, maxOutputTokens: 512, callTimeoutMs: 15000 }),
-    medium: Object.freeze({ maxCalls: 8, maxInputChars: 32000, maxOutputChars: 16000, maxOutputTokens: 1024, callTimeoutMs: 30000 }),
-    large: Object.freeze({ maxCalls: 16, maxInputChars: 64000, maxOutputChars: 32000, maxOutputTokens: 4096, callTimeoutMs: 60000 }),
+    small: Object.freeze({
+        maxCalls: 2,
+        maxInputChars: 8000,
+        maxOutputChars: 4000,
+        maxOutputTokens: 512,
+        callTimeoutMs: 15000,
+    }),
+    medium: Object.freeze({
+        maxCalls: 8,
+        maxInputChars: 32000,
+        maxOutputChars: 16000,
+        maxOutputTokens: 1024,
+        callTimeoutMs: 30000,
+    }),
+    large: Object.freeze({
+        maxCalls: 16,
+        maxInputChars: 64000,
+        maxOutputChars: 32000,
+        maxOutputTokens: 4096,
+        callTimeoutMs: 60000,
+    }),
 });
-// Exhaustiveness ensures new Core settings cannot silently disappear at this boundary.
+// Exhaustiveness ensures new Core settings cannot silently disappear at this boundary: adding a
+// setting to `ModelRunnerSettings` without listing it here fails type checking.
 const budgetSettingKeys = {
-    maxCalls: true, callTimeoutMs: true, maxOutputChars: true, usage: true,
-    children: true, maxInputChars: true, maxSchemaChars: true, tokenBudget: true, maxOutputTokens: true,
+    maxCalls: true,
+    callTimeoutMs: true,
+    maxOutputChars: true,
+    usage: true,
+    children: true,
+    maxInputChars: true,
+    maxSchemaChars: true,
+    tokenBudget: true,
+    maxOutputTokens: true,
 };
 const settingKeys = {
-    ...budgetSettingKeys, provider: true, execution: true, transports: true, sink: true, errors: true,
+    ...budgetSettingKeys,
+    provider: true,
+    execution: true,
+    transports: true,
+    sink: true,
+    errors: true,
 };
+// Copy only known Core keys, so helper fields such as `model`, `models` or `budget` in a selected
+// definition are not forwarded as runner options.
 function settings(source) {
     const result = {};
     for (const key of Object.keys(settingKeys))
@@ -42,20 +91,32 @@ function createModelStrategy(options) {
     if (typeof model !== 'string' && models !== undefined)
         throw new TypeError('Use a model ID with configured models');
     const selected = typeof model === 'string'
-        ? models && Object.hasOwn(models, model) ? models[model] : undefined : model;
+        ? models && Object.hasOwn(models, model)
+            ? models[model]
+            : undefined
+        : model;
     if (!selected || typeof selected !== 'object')
         throw new TypeError(`Unknown model strategy: ${String(model)}`);
-    const reasoningSettings = reasoning === undefined ? undefined
-        : reasoningOptions && Object.hasOwn(reasoningOptions, reasoning) ? reasoningOptions[reasoning] : undefined;
+    const reasoningSettings = reasoning === undefined
+        ? undefined
+        : reasoningOptions && Object.hasOwn(reasoningOptions, reasoning)
+            ? reasoningOptions[reasoning]
+            : undefined;
     if (reasoning !== undefined && !reasoningSettings)
         throw new TypeError(`Unknown reasoning strategy: ${reasoning}`);
     if (typeof budget === 'string' && !Object.hasOwn(exports.modelBudgetStrategies, budget))
         throw new TypeError(`Unknown model budget: ${budget}`);
-    if (!budget || (typeof budget !== 'string' && (typeof budget !== 'object' || Array.isArray(budget))))
+    if (!budget ||
+        (typeof budget !== 'string' && (typeof budget !== 'object' || Array.isArray(budget))))
         throw new TypeError('Invalid model budget strategy');
     const preset = typeof budget === 'string' ? exports.modelBudgetStrategies[budget] : exports.modelBudgetStrategies.medium;
-    const result = { ...preset, ...settings(selected), ...(reasoningSettings && settings(reasoningSettings)),
-        ...(typeof budget === 'object' && budgetSettings(budget)), ...settings(options) };
+    const result = {
+        ...preset,
+        ...settings(selected),
+        ...(reasoningSettings && settings(reasoningSettings)),
+        ...(typeof budget === 'object' && budgetSettings(budget)),
+        ...settings(options),
+    };
     // Validate through the same Core rules without creating a request runner or spending calls.
     (0, binding_js_1.snapshotModelBinding)(result);
     return Object.freeze(result);

package/dist/cjs/support/model/transports.js

@@ -3,32 +3,71 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.createModelTransport = void 0;
 exports.createTextTransport = createTextTransport;
 exports.createJsonTransport = createJsonTransport;
+/**
+ * Model transport creators for plain text and typed JSON values.
+ *
+ * Both produce Core `ModelTransportDefinition` objects with an ID, so a runner can select them by
+ * name. Neither invokes a model: preparation, response assembly and parsing stay in Core.
+ *
+ * Main exports: `createTextTransport`, `createJsonTransport`, `createModelTransport` and the
+ * transport registration type.
+ */
 const schema_adapter_js_1 = require("../../utils/schema-adapter.js");
 const options_js_1 = require("../../model/options.js");
 const model_protocol_js_1 = require("../../utils/model-protocol.js");
 const transports_js_1 = require("../../model/transports.js");
 var selection_transport_js_1 = require("../../model/selection-transport.js");
 Object.defineProperty(exports, "createModelTransport", { enumerable: true, get: function () { return selection_transport_js_1.createModelTransport; } });
+/**
+ * Create a plain-text transport that trims the assembled response.
+ *
+ * @param definition Transport ID and optional temperature.
+ * @returns A frozen Core transport definition typed as string output.
+ */
 function createTextTransport(definition) {
     return (0, transports_js_1.createPlainTextTransport)(definition.id, definition.options);
 }
-/** Typed JSON values without a capability-selection envelope. */
+/**
+ * Create a typed JSON transport without a capability-selection envelope.
+ *
+ * The transport embeds the JSON Schema in the instruction and requires the response to be one
+ * complete JSON value. The returned response parser rejects native call events and invalid JSON,
+ * then validates the value through the supplied schema.
+ *
+ * @param definition Transport ID, output schema and optional temperature/json settings.
+ * @returns A frozen Core transport definition typed as `Output`.
+ * @throws {TypeError} When the ID is blank or the schema adapter cannot be snapshotted.
+ */
 function createJsonTransport(definition) {
     const { id, outputSchema, options } = definition;
     if (typeof id !== 'string' || !id.trim())
         throw new TypeError('JSON transport requires an ID');
     const schema = (0, schema_adapter_js_1.snapshotSchemaAdapter)(outputSchema);
-    const settings = Object.freeze({ ...(0, options_js_1.snapshotModelOptions)({ temperature: options?.temperature, json: options?.json ?? true }) });
-    const instruction = 'Return exactly one complete JSON value matching this JSON Schema: '
-        + JSON.stringify(schema.jsonSchema) + '\nReturn the value itself, without prose, fences, a schema document or a capability-selection envelope.';
-    return Object.freeze({ id, prepare() {
-            return { options: settings, instruction, schemaChars: instruction.length, createResponse() {
+    const settings = Object.freeze({
+        ...(0, options_js_1.snapshotModelOptions)({ temperature: options?.temperature, json: options?.json ?? true }),
+    });
+    const instruction = 'Return exactly one complete JSON value matching this JSON Schema: ' +
+        JSON.stringify(schema.jsonSchema) +
+        '\nReturn the value itself, without prose, fences, a schema document or a capability-selection envelope.';
+    return Object.freeze({
+        id,
+        prepare() {
+            return {
+                options: settings,
+                instruction,
+                schemaChars: instruction.length,
+                createResponse() {
                     let raw = '';
-                    return { get outputChars() { return raw.length; }, push(part) {
+                    return {
+                        get outputChars() {
+                            return raw.length;
+                        },
+                        push(part) {
                             if (typeof part !== 'string')
                                 (0, model_protocol_js_1.modelProtocolError)('JSON value transport does not accept native call events');
                             raw += part;
-                        }, finish() {
+                        },
+                        finish() {
                             let value;
                             try {
                                 value = JSON.parse(raw);
@@ -37,7 +76,10 @@ function createJsonTransport(definition) {
                                 (0, model_protocol_js_1.modelProtocolError)('JSON value transport requires complete JSON');
                             }
                             return schema.parse(value);
-                        } };
-                } };
-        } });
+                        },
+                    };
+                },
+            };
+        },
+    });
 }

package/dist/cjs/support/registration.js

@@ -1,24 +1,66 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.defineRegistrationCatalog = defineRegistrationCatalog;
+/**
+ * Conditional registration support: compile an ordered list of install steps for an application.
+ *
+ * Steps are validated and bound once, then installed per invocation. Predicates run at install
+ * time and only see what previous steps already installed, so ordering is part of the contract.
+ * This is app-side composition for Core-facing handlers; it defines no new scheduling protocol.
+ *
+ * Main export: `defineRegistrationCatalog`.
+ */
 const catalog_js_1 = require("../utils/catalog.js");
 const synchronous_js_1 = require("../utils/synchronous.js");
 const rules_js_1 = require("../utils/rules.js");
-/** Compile an installation plan once; predicates observe preceding installations at request time. */
+/**
+ * Compile an ordered installation plan.
+ *
+ * Predicates observe the effects of preceding installations at request time; a predicate that
+ * throws rejects the install instead of being treated as `false`. Callbacks are bound to their
+ * declaring definition so implementations may rely on `this`.
+ *
+ * @param definitions Registration steps in execution order.
+ * @returns A frozen catalog plus `install(context)`, which runs enabled steps sequentially.
+ * @throws {Error} When a `register` handler is missing or a `when` predicate is not a function.
+ */
 function defineRegistrationCatalog(definitions) {
-    const catalog = (0, catalog_js_1.readonlyCatalog)(definitions.map(definition => {
+    const catalog = (0, catalog_js_1.readonlyCatalog)(definitions.map((definition) => {
         const { id, when, register } = definition;
         (0, rules_js_1.breakWhile)([
-            { occur: typeof register !== 'function', error: 'Missing registration handler', tags: ['handler'] },
-            { occur: when !== undefined && typeof when !== 'function', error: 'Invalid registration predicate', tags: ['predicate'] },
+            {
+                occur: typeof register !== 'function',
+                error: 'Missing registration handler',
+                tags: ['handler'],
+            },
+            {
+                occur: when !== undefined && typeof when !== 'function',
+                error: 'Invalid registration predicate',
+                tags: ['predicate'],
+            },
         ], ['agent-core', 'registration']);
-        return Object.freeze({ id, when: when?.bind(definition), register: register.bind(definition) });
-    }), id => new TypeError(`Unknown registration: ${id}`));
+        return Object.freeze({
+            id,
+            when: when?.bind(definition),
+            register: register.bind(definition),
+        });
+    }), (id) => new TypeError(`Unknown registration: ${id}`));
     return Object.freeze({
         ...catalog,
+        /**
+         * Run every enabled step in declaration order against `context`.
+         *
+         * Stops at the first failing predicate or handler; earlier installations are not rolled back.
+         *
+         * @param context Value passed to each predicate and registration handler.
+         * @throws {TypeError} When a predicate is asynchronous or does not return a boolean, or when
+         *   a handler is asynchronous.
+         */
         install(context) {
             for (const entry of catalog.definitions) {
-                const enabled = entry.when ? (0, synchronous_js_1.booleanResult)(entry.when(context), 'Registration predicates must be synchronous', 'Registration predicates must return boolean') : true;
+                const enabled = entry.when
+                    ? (0, synchronous_js_1.booleanResult)(entry.when(context), 'Registration predicates must be synchronous', 'Registration predicates must return boolean')
+                    : true;
                 if (enabled) {
                     (0, synchronous_js_1.synchronous)(entry.register(context), 'Registration handlers must be synchronous');
                 }

package/dist/cjs/support/schema.js

@@ -3,10 +3,30 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.fromJsonSchema = fromJsonSchema;
 exports.fromParserSchema = fromParserSchema;
 exports.defineSchema = defineSchema;
+/**
+ * Schema adapter helpers: turn JSON Schema compilers and library parsers into Core adapters.
+ *
+ * Support supplies the adapter shape and snapshotting; the compiler, validator package and error
+ * messages remain application choices. A plain JSON Schema without a typed compiler stays unknown
+ * instead of being silently treated as permissive.
+ *
+ * Main exports: `fromJsonSchema`, `fromParserSchema` and `defineSchema`.
+ */
 const schema_adapter_js_1 = require("../utils/schema-adapter.js");
 const object_js_1 = require("../utils/object.js");
 const synchronous_js_1 = require("../utils/synchronous.js");
-/** Uses a caller-owned typed compiler. A plain schema without a typed compiler remains unknown. */
+/**
+ * Build an adapter from a caller-owned typed JSON Schema compiler.
+ *
+ * The schema is cloned and frozen before it reaches the compiler, so later mutation of the input
+ * cannot change validation. Compilation and validation must both be synchronous.
+ *
+ * @param schema JSON Schema describing the accepted value.
+ * @param options Compiler plus an optional error factory for rejected values.
+ * @returns A frozen adapter exposing `jsonSchema` and a `parse` that returns the input as `Value`.
+ * @throws {TypeError} When the compiler is asynchronous or does not return a validator, or when no
+ *   custom error applies; also when the validator is asynchronous or does not return a boolean.
+ */
 function fromJsonSchema(schema, options) {
     const jsonSchema = structuredClone(schema);
     (0, object_js_1.freezeSchema)(jsonSchema);
@@ -14,19 +34,41 @@ function fromJsonSchema(schema, options) {
     if (typeof validate !== 'function')
         throw new TypeError('Schema compilers must return a validator');
     const error = options.error?.bind(options);
-    return (0, schema_adapter_js_1.snapshotSchemaAdapter)({ jsonSchema, parse(value) {
+    return (0, schema_adapter_js_1.snapshotSchemaAdapter)({
+        jsonSchema,
+        parse(value) {
             const valid = (0, synchronous_js_1.booleanResult)(validate(value), 'Schema validators must be synchronous', 'Schema validators must return boolean');
             if (!valid)
-                throw (0, synchronous_js_1.synchronous)(error?.(value, validate.errors), 'Schema error factories must be synchronous') ?? new TypeError('Input does not match JSON Schema');
+                throw ((0, synchronous_js_1.synchronous)(error?.(value, validate.errors), 'Schema error factories must be synchronous') ?? new TypeError('Input does not match JSON Schema'));
             return value;
-        } });
+        },
+    });
 }
+/**
+ * Wrap a library schema that already parses values (for example Zod or Valibot style).
+ *
+ * `parse` is delegated unchanged, so the library keeps ownership of coercion and error reporting;
+ * only the JSON Schema projection is produced here.
+ *
+ * @param schema Object exposing a `parse` method.
+ * @param options Converter that projects the schema into JSON Schema.
+ * @returns A frozen adapter whose `parse` returns the wrapped parser's result type.
+ * @throws {TypeError} When the JSON Schema conversion is asynchronous.
+ */
 function fromParserSchema(schema, options) {
     return (0, schema_adapter_js_1.snapshotSchemaAdapter)({
         jsonSchema: (0, synchronous_js_1.synchronous)(options.toJsonSchema(schema), 'Schema conversion must be synchronous'),
         parse: schema.parse.bind(schema),
     });
 }
+/**
+ * Re-snapshot an existing adapter without changing its behavior.
+ *
+ * Used to detach a caller-owned adapter from later mutation before it is exposed or reused.
+ *
+ * @param definition Adapter to copy.
+ * @returns A frozen adapter with the same validation and parsing behavior.
+ */
 function defineSchema(definition) {
     return (0, schema_adapter_js_1.snapshotSchemaAdapter)(definition);
 }