@jangts/agent-core 0.1.0 → 0.2.0

package/dist/esm/utils/break-observer.js

@@ -1,10 +1,28 @@
 let onBreak;
+// Re-entrancy guard: an observer that itself calls breakWhile would otherwise recurse
+// until the stack overflows.
 let notifying = false;
-/** Hosts may install a diagnostic observer; no logging or persistence is enabled by default. */
+/**
+ * Install the host-owned break observer.
+ *
+ * No logging or persistence is enabled by default; passing no argument (or an empty
+ * config) removes any previously installed observer.
+ *
+ * @param config - Observation configuration; `onBreak` receives one frozen event per rejection.
+ */
 export function configureBreakWhile(config = {}) {
     onBreak = config.onBreak;
 }
-/** Diagnostic failures must never replace the original interruption. */
+/**
+ * Notify the installed observer about a rejection.
+ *
+ * The original interruption is authoritative: observer failures, and rejections of the
+ * promise an observer returns, are swallowed.
+ *
+ * @param error - The value that is about to be thrown by `breakWhile`.
+ * @param tags - Call-site tags supplied by the caller of `breakWhile`.
+ * @param rule - The failing check, whose own tags are merged into the reported set.
+ */
 export function observeBreak(error, tags, rule) {
     if (!onBreak || notifying)
         return;

package/dist/esm/utils/cancellation.d.ts

@@ -1,12 +1,63 @@
-/** Cancellation reasons are arbitrary thrown values, including hostile objects. */
+/**
+ * Detect a deadline expiry as opposed to any other cancellation.
+ *
+ * The reason of an aborted signal is an arbitrary thrown value, including hostile
+ * objects whose `name` getter throws, so the lookup is guarded.
+ *
+ * @param reason - Value delivered as `signal.reason`.
+ * @returns True when the reason is named `TimeoutError`.
+ */
 export declare function isTimeoutReason(reason: unknown): boolean;
-/** Optional request signals only shorten the lifetime; deduplicate without replacing a parent. */
+/**
+ * Merge optional signals into one lifetime bound.
+ *
+ * Duplicates are removed first so a signal appearing both as an execution parent and
+ * as a request signal does not allocate a redundant composite. When nothing is
+ * supplied a fresh, never-aborting signal is returned, which keeps callers free of
+ * undefined checks.
+ *
+ * @param sources - Candidate signals in precedence-free order; `undefined` entries are ignored.
+ * @returns A signal that aborts as soon as any supplied signal aborts.
+ */
 export declare function combineSignals(...sources: readonly (AbortSignal | undefined)[]): AbortSignal;
-/** Abandon waiting, but keep observing late rejection and remove the abort listener. */
+/**
+ * Race a pending value against an abort signal.
+ *
+ * Abandoning the wait does not cancel the underlying work: a late rejection is still
+ * consumed to avoid an unhandled rejection, and the abort listener is always removed.
+ *
+ * @param value - Value or promise to await; `undefined` keeps the same await semantics.
+ * @param signal - Optional lifetime bound; without it the value is awaited unchanged.
+ * @returns The resolved value.
+ * @throws The signal reason when aborted, or the rejection of `value`.
+ */
 export declare function awaitWithSignal<Value>(value: Value | PromiseLike<Value>, signal?: AbortSignal): Promise<Value>;
-/** Authorization and validation hooks may await, but only void means success. */
+/**
+ * Run an assertion that may be asynchronous, bounded by a signal.
+ *
+ * Only a `void` result counts as success, so a hook that discards its decision as a
+ * boolean is rejected rather than silently treated as passing. The signal is checked
+ * before and after the hook so a decision produced after cancellation is discarded.
+ *
+ * @param check - Hook invoked once; may return a promise.
+ * @param signal - Lifetime bound for the hook and its result.
+ * @param message - Message for the TypeError raised when the hook does not return void.
+ * @returns A promise resolved once the assertion passed.
+ * @throws The signal reason when aborted, the hook's rejection, or the assertion TypeError.
+ */
 export declare function awaitAssertion(check: () => unknown, signal: AbortSignal, message: string): Promise<void>;
-/** Chunk timers exceeding the platform limit without shortening the persisted deadline. */
+/**
+ * Abort at an absolute wall-clock deadline, combined with a parent signal.
+ *
+ * Timers above the platform maximum are chunked instead of being clamped, so the
+ * persisted deadline is never shortened. The deadline is recomputed from the clock on
+ * each chunk, which keeps the effective expiry correct across timer drift.
+ *
+ * @param deadline - Absolute deadline in epoch milliseconds.
+ * @param parent - Additional lifetime bound, typically the execution signal.
+ * @param now - Clock source; injectable for tests.
+ * @returns The combined `signal` and a `dispose` function that cancels the pending timer.
+ */
 export declare function createDeadlineSignal(deadline: number, parent: AbortSignal, now?: () => number): {
     signal: AbortSignal;
     dispose(): void;

package/dist/esm/utils/cancellation.js

@@ -1,5 +1,21 @@
+/**
+ * Cancellation and deadline plumbing shared by the model runner and the engine.
+ *
+ * Every helper here treats an abort signal as a pure lifetime bound: it may only
+ * shorten waiting, never extend it, and it never replaces a caller-supplied parent
+ * signal. Exports: `isTimeoutReason`, `combineSignals`, `awaitWithSignal`,
+ * `awaitAssertion` and `createDeadlineSignal`.
+ */
 import { assertion } from './synchronous.js';
-/** Cancellation reasons are arbitrary thrown values, including hostile objects. */
+/**
+ * Detect a deadline expiry as opposed to any other cancellation.
+ *
+ * The reason of an aborted signal is an arbitrary thrown value, including hostile
+ * objects whose `name` getter throws, so the lookup is guarded.
+ *
+ * @param reason - Value delivered as `signal.reason`.
+ * @returns True when the reason is named `TimeoutError`.
+ */
 export function isTimeoutReason(reason) {
     try {
         return reason?.name === 'TimeoutError';
@@ -8,12 +24,36 @@ export function isTimeoutReason(reason) {
         return false;
     }
 }
-/** Optional request signals only shorten the lifetime; deduplicate without replacing a parent. */
+/**
+ * Merge optional signals into one lifetime bound.
+ *
+ * Duplicates are removed first so a signal appearing both as an execution parent and
+ * as a request signal does not allocate a redundant composite. When nothing is
+ * supplied a fresh, never-aborting signal is returned, which keeps callers free of
+ * undefined checks.
+ *
+ * @param sources - Candidate signals in precedence-free order; `undefined` entries are ignored.
+ * @returns A signal that aborts as soon as any supplied signal aborts.
+ */
 export function combineSignals(...sources) {
-    const signals = [...new Set(sources.filter((signal) => signal !== undefined))];
-    return signals.length > 1 ? AbortSignal.any(signals) : signals[0] ?? new AbortController().signal;
+    const signals = [
+        ...new Set(sources.filter((signal) => signal !== undefined)),
+    ];
+    return signals.length > 1
+        ? AbortSignal.any(signals)
+        : (signals[0] ?? new AbortController().signal);
 }
-/** Abandon waiting, but keep observing late rejection and remove the abort listener. */
+/**
+ * Race a pending value against an abort signal.
+ *
+ * Abandoning the wait does not cancel the underlying work: a late rejection is still
+ * consumed to avoid an unhandled rejection, and the abort listener is always removed.
+ *
+ * @param value - Value or promise to await; `undefined` keeps the same await semantics.
+ * @param signal - Optional lifetime bound; without it the value is awaited unchanged.
+ * @returns The resolved value.
+ * @throws The signal reason when aborted, or the rejection of `value`.
+ */
 export async function awaitWithSignal(value, signal) {
     if (!signal)
         return value;
@@ -31,14 +71,37 @@ export async function awaitWithSignal(value, signal) {
         signal.removeEventListener('abort', abort);
     }
 }
-/** Authorization and validation hooks may await, but only void means success. */
+/**
+ * Run an assertion that may be asynchronous, bounded by a signal.
+ *
+ * Only a `void` result counts as success, so a hook that discards its decision as a
+ * boolean is rejected rather than silently treated as passing. The signal is checked
+ * before and after the hook so a decision produced after cancellation is discarded.
+ *
+ * @param check - Hook invoked once; may return a promise.
+ * @param signal - Lifetime bound for the hook and its result.
+ * @param message - Message for the TypeError raised when the hook does not return void.
+ * @returns A promise resolved once the assertion passed.
+ * @throws The signal reason when aborted, the hook's rejection, or the assertion TypeError.
+ */
 export async function awaitAssertion(check, signal, message) {
     signal.throwIfAborted();
     const result = await awaitWithSignal(check(), signal);
     signal.throwIfAborted();
     assertion(result, message);
 }
-/** Chunk timers exceeding the platform limit without shortening the persisted deadline. */
+/**
+ * Abort at an absolute wall-clock deadline, combined with a parent signal.
+ *
+ * Timers above the platform maximum are chunked instead of being clamped, so the
+ * persisted deadline is never shortened. The deadline is recomputed from the clock on
+ * each chunk, which keeps the effective expiry correct across timer drift.
+ *
+ * @param deadline - Absolute deadline in epoch milliseconds.
+ * @param parent - Additional lifetime bound, typically the execution signal.
+ * @param now - Clock source; injectable for tests.
+ * @returns The combined `signal` and a `dispose` function that cancels the pending timer.
+ */
 export function createDeadlineSignal(deadline, parent, now = Date.now) {
     const controller = new AbortController();
     let timer;
@@ -50,6 +113,11 @@ export function createDeadlineSignal(deadline, parent, now = Date.now) {
             timer = setTimeout(schedule, Math.min(remaining, 2147483647));
     };
     schedule();
-    return { signal: combineSignals(parent, controller.signal), dispose() { if (timer !== undefined)
-            clearTimeout(timer); } };
+    return {
+        signal: combineSignals(parent, controller.signal),
+        dispose() {
+            if (timer !== undefined)
+                clearTimeout(timer);
+        },
+    };
 }

package/dist/esm/utils/catalog.d.ts

@@ -1,5 +1,24 @@
+/**
+ * Immutable id-keyed catalog snapshot.
+ *
+ * Modules that own registrable definitions (tools, capabilities, prompts) publish the
+ * snapshot produced here instead of exposing their mutable `Map`, so later mutations
+ * by the owner cannot be observed and no consumer can mutate the registry.
+ *
+ * Exports: `readonlyCatalog`.
+ */
 import type { ReadonlyCatalog } from '../structs/common.js';
-/** Entries are compiled/snapshotted by the owning module; this exposes no mutable Map. */
+/**
+ * Build a frozen catalog from an iterable of definitions.
+ *
+ * Ids must be non-empty after trimming and unique; both violations surface as a
+ * TypeError during construction rather than on first lookup.
+ *
+ * @param definitions - Definitions to snapshot; iteration order is preserved in `definitions`.
+ * @param missing - Factory for the error thrown by `require` when an id is absent.
+ * @returns A frozen catalog; `get` is unguarded while `require` throws via `missing`.
+ * @throws TypeError When an id is blank or duplicated.
+ */
 export declare function readonlyCatalog<Definition extends {
     readonly id: string;
 }>(definitions: Iterable<Readonly<Definition>>, missing: (id: string) => Error): ReadonlyCatalog<Definition>;

package/dist/esm/utils/catalog.js

@@ -1,4 +1,14 @@
-/** Entries are compiled/snapshotted by the owning module; this exposes no mutable Map. */
+/**
+ * Build a frozen catalog from an iterable of definitions.
+ *
+ * Ids must be non-empty after trimming and unique; both violations surface as a
+ * TypeError during construction rather than on first lookup.
+ *
+ * @param definitions - Definitions to snapshot; iteration order is preserved in `definitions`.
+ * @param missing - Factory for the error thrown by `require` when an id is absent.
+ * @returns A frozen catalog; `get` is unguarded while `require` throws via `missing`.
+ * @throws TypeError When an id is blank or duplicated.
+ */
 export function readonlyCatalog(definitions, missing) {
     const byId = new Map();
     for (const definition of definitions) {
@@ -7,9 +17,14 @@ export function readonlyCatalog(definitions, missing) {
         byId.set(definition.id, definition);
     }
     const snapshot = Object.freeze([...byId.values()]);
-    return Object.freeze({ definitions: snapshot, ids: () => Object.freeze([...byId.keys()]),
-        values: () => byId.values(), entries: () => byId.entries(), has: (id) => byId.has(id),
-        get: (id) => byId.get(id), require(id) {
+    return Object.freeze({
+        definitions: snapshot,
+        ids: () => Object.freeze([...byId.keys()]),
+        values: () => byId.values(),
+        entries: () => byId.entries(),
+        has: (id) => byId.has(id),
+        get: (id) => byId.get(id),
+        require(id) {
             const value = byId.get(id);
             if (value === undefined)
                 throw missing(id);

package/dist/esm/utils/debug.d.ts

@@ -1,6 +1,25 @@
+/**
+ * Adapter between App-supplied debug loggers and the diagnostics pipeline.
+ *
+ * Sub-flow loggers are mutable, execution-owned objects. This module reads one at the
+ * moment a diagnostic fact is built and converts it into a frozen array of steps, so
+ * persisted observations never retain a live logger.
+ *
+ * Exports: `captureSubSteps`.
+ */
 import type { SubFlowLogger } from '../structs/debug.js';
 import type { DiagnosticIdentity } from '../structs/diagnostics.js';
-/** Only execution-owned logger instances can produce new child log arrays. */
+/**
+ * Read the current sub-step log of one execution visit.
+ *
+ * A missing reader or a logger that yields nothing produces the empty shape, which
+ * lets callers spread the result unconditionally. Failures are reported as one
+ * dropped step instead of propagating, because diagnostics must not break execution.
+ *
+ * @param read - Getter for the current logger; omitted when the caller has no logger.
+ * @param identity - Diagnostic identity copied onto each captured step.
+ * @returns Frozen `subSteps`, the number of dropped steps and whether the log was truncated.
+ */
 export declare function captureSubSteps(read: (() => SubFlowLogger | undefined) | undefined, identity?: Readonly<DiagnosticIdentity>): {
     subSteps: readonly Readonly<import("../index.js").RecordedSubStep>[];
     subStepsDropped: number;

package/dist/esm/utils/debug.js

@@ -1,13 +1,25 @@
 import { readSubFlowLogger } from '../diagnostics/sub-flow.js';
 import { synchronous } from './synchronous.js';
-/** Only execution-owned logger instances can produce new child log arrays. */
+/**
+ * Read the current sub-step log of one execution visit.
+ *
+ * A missing reader or a logger that yields nothing produces the empty shape, which
+ * lets callers spread the result unconditionally. Failures are reported as one
+ * dropped step instead of propagating, because diagnostics must not break execution.
+ *
+ * @param read - Getter for the current logger; omitted when the caller has no logger.
+ * @param identity - Diagnostic identity copied onto each captured step.
+ * @returns Frozen `subSteps`, the number of dropped steps and whether the log was truncated.
+ */
 export function captureSubSteps(read, identity) {
     const empty = { subSteps: Object.freeze([]), subStepsDropped: 0, subStepsTruncated: false };
     if (!read)
         return empty;
     try {
         const logger = synchronous(read(), 'Debug steps must be synchronous');
-        return logger === undefined ? empty : { ...empty, subSteps: readSubFlowLogger(logger, undefined, identity) };
+        return logger === undefined
+            ? empty
+            : { ...empty, subSteps: readSubFlowLogger(logger, undefined, identity) };
     }
     catch {
         return { ...empty, subStepsDropped: 1 };

package/dist/esm/utils/index.d.ts

@@ -1,3 +1,11 @@
+/**
+ * Generic helpers shared by every other module of `@jangts/agent-core`.
+ *
+ * Nothing here knows about business prompts, stages or transports: this barrel only
+ * re-exports rule traversal, text comparison, model protocol errors and retrieval
+ * query keys. Consumers inside the package import the concrete module directly;
+ * this entry exists so cross-module reuse has one stable surface.
+ */
 export * from './rules.js';
 export { commonPrefixLength } from './text.js';
 export { modelProtocolError } from './model-protocol.js';

package/dist/esm/utils/index.js

@@ -1,3 +1,11 @@
+/**
+ * Generic helpers shared by every other module of `@jangts/agent-core`.
+ *
+ * Nothing here knows about business prompts, stages or transports: this barrel only
+ * re-exports rule traversal, text comparison, model protocol errors and retrieval
+ * query keys. Consumers inside the package import the concrete module directly;
+ * this entry exists so cross-module reuse has one stable surface.
+ */
 export * from './rules.js';
 export { commonPrefixLength } from './text.js';
 export { modelProtocolError } from './model-protocol.js';

package/dist/esm/utils/interaction-definition.d.ts

@@ -1,3 +1,20 @@
+/**
+ * Snapshot one interaction command definition before it is registered.
+ *
+ * Definitions are often plain objects composed with prototype methods or getters.
+ * Copying the known contract fields explicitly keeps those inherited members while
+ * dropping any other implementation helper, which is not part of the runtime contract.
+ *
+ * Exports: `pinCommandDefinition`.
+ */
 import type { CommandDefinition } from '../structs/kits/interaction.js';
-/** Read contract properties explicitly so prototype methods/getters survive composition. */
+/**
+ * Produce a detached copy of the contract fields of a command definition.
+ *
+ * Callbacks are rebound to the original definition so `this` keeps pointing at the
+ * source object; `undefined` entries are dropped so optional fields stay absent.
+ *
+ * @param definition - Source definition, possibly carrying inherited members.
+ * @returns A new partial definition containing only the declared contract fields.
+ */
 export declare function pinCommandDefinition<Value extends object, Result, Args extends unknown[]>(definition: Partial<CommandDefinition<Value, Result, Args>>): Partial<CommandDefinition<Value, Result, Args>>;

package/dist/esm/utils/interaction-definition.js

@@ -1,10 +1,30 @@
-/** Read contract properties explicitly so prototype methods/getters survive composition. */
+/**
+ * Produce a detached copy of the contract fields of a command definition.
+ *
+ * Callbacks are rebound to the original definition so `this` keeps pointing at the
+ * source object; `undefined` entries are dropped so optional fields stay absent.
+ *
+ * @param definition - Source definition, possibly carrying inherited members.
+ * @returns A new partial definition containing only the declared contract fields.
+ */
 export function pinCommandDefinition(definition) {
-    const snapshot = { ...definition, fields: definition.fields, category: definition.category, version: definition.version,
-        description: definition.description, terminal: definition.terminal, discriminator: definition.discriminator,
-        ownedFields: definition.ownedFields, additionalProperties: definition.additionalProperties, optionalPresence: definition.optionalPresence,
-        modes: definition.modes, tags: definition.tags, checks: definition.checks,
+    const snapshot = {
+        ...definition,
+        fields: definition.fields,
+        category: definition.category,
+        version: definition.version,
+        description: definition.description,
+        terminal: definition.terminal,
+        discriminator: definition.discriminator,
+        ownedFields: definition.ownedFields,
+        additionalProperties: definition.additionalProperties,
+        optionalPresence: definition.optionalPresence,
+        modes: definition.modes,
+        tags: definition.tags,
+        checks: definition.checks,
         error: typeof definition.error === 'function' ? definition.error.bind(definition) : definition.error,
-        refine: definition.refine?.bind(definition), format: definition.format?.bind(definition) };
+        refine: definition.refine?.bind(definition),
+        format: definition.format?.bind(definition),
+    };
     return Object.fromEntries(Object.entries(snapshot).filter(([, value]) => value !== undefined));
 }

package/dist/esm/utils/invocation.d.ts

@@ -1,7 +1,42 @@
+/**
+ * Invocation identity and result envelopes.
+ *
+ * Invocation ids are platform-neutral: they identify one call inside a run and are
+ * deliberately independent of App or request identities, so callers can correlate
+ * diagnostics without importing a domain concept.
+ *
+ * Exports: `invocationId`, `invocationResult` and `toolInvocation`.
+ */
 import type { InvocationMetadata, InvocationResult } from '../structs/invocation.js';
-/** Call IDs are platform-neutral and independent of App/request identities. */
+/**
+ * Generate an invocation id.
+ *
+ * @returns A random UUID from the platform crypto implementation.
+ */
 export declare function invocationId(): string;
+/**
+ * Wrap a value and its metadata in a frozen result envelope.
+ *
+ * Both layers are frozen so downstream consumers cannot mutate an already reported
+ * invocation.
+ *
+ * @param value - The produced value.
+ * @param metadata - Invocation metadata describing the call.
+ * @returns A frozen `InvocationResult`.
+ */
 export declare function invocationResult<Value, Metadata extends InvocationMetadata>(value: Value, metadata: Metadata): InvocationResult<Value, Metadata>;
+/**
+ * Normalize the positional tool-invocation shorthand used by App handlers.
+ *
+ * The shorthand only accepts exactly one request so a handler cannot silently drop
+ * additional tools; the request must carry a non-blank `toolId` and an explicit
+ * `input` property, which distinguishes "no input" from "input omitted".
+ *
+ * @param request - Candidate request supplied as a single argument.
+ * @param arity - Number of arguments the caller actually passed; must be 1.
+ * @returns A plain object with the four supported request fields.
+ * @throws TypeError When the arity or the request shape is invalid.
+ */
 export declare function toolInvocation(request: import('../structs/capabilities/tools.js').ToolInvocationRequest, arity: number): {
     toolId: string;
     input: unknown;

package/dist/esm/utils/invocation.js

@@ -1,11 +1,49 @@
-/** Call IDs are platform-neutral and independent of App/request identities. */
-export function invocationId() { return globalThis.crypto.randomUUID(); }
+/**
+ * Generate an invocation id.
+ *
+ * @returns A random UUID from the platform crypto implementation.
+ */
+export function invocationId() {
+    return globalThis.crypto.randomUUID();
+}
+/**
+ * Wrap a value and its metadata in a frozen result envelope.
+ *
+ * Both layers are frozen so downstream consumers cannot mutate an already reported
+ * invocation.
+ *
+ * @param value - The produced value.
+ * @param metadata - Invocation metadata describing the call.
+ * @returns A frozen `InvocationResult`.
+ */
 export function invocationResult(value, metadata) {
     return Object.freeze({ value, invocation: Object.freeze(metadata) });
 }
+/**
+ * Normalize the positional tool-invocation shorthand used by App handlers.
+ *
+ * The shorthand only accepts exactly one request so a handler cannot silently drop
+ * additional tools; the request must carry a non-blank `toolId` and an explicit
+ * `input` property, which distinguishes "no input" from "input omitted".
+ *
+ * @param request - Candidate request supplied as a single argument.
+ * @param arity - Number of arguments the caller actually passed; must be 1.
+ * @returns A plain object with the four supported request fields.
+ * @throws TypeError When the arity or the request shape is invalid.
+ */
 export function toolInvocation(request, arity) {
-    if (arity !== 1 || !request || typeof request !== 'object' || typeof request.toolId !== 'string' || !request.toolId.trim() || !('input' in request)) {
+    if (arity !== 1 ||
+        !request ||
+        typeof request !== 'object' ||
+        typeof request.toolId !== 'string' ||
+        !request.toolId.trim() ||
+        !('input' in request)) {
         throw new TypeError('Use one tool request with toolId and input');
     }
-    return { toolId: request.toolId, input: request.input, diagnostics: request.diagnostics, signal: request.signal };
+    return {
+        toolId: request.toolId,
+        input: request.input,
+        diagnostics: request.diagnostics,
+        signal: request.signal,
+    };
 }

package/dist/esm/utils/model-protocol.d.ts

@@ -1 +1,9 @@
+/**
+ * Throw a model protocol validation error.
+ *
+ * @param message - Primary issue message, always reported with code `MODEL_PROTOCOL`.
+ * @param reason - Optional secondary code for the same message, used to distinguish variants.
+ * @returns Never returns; the declared `never` return lets callers use it in expressions.
+ * @throws ValidationError carrying one or two issues.
+ */
 export declare function modelProtocolError(message: string, reason?: string): never;

package/dist/esm/utils/model-protocol.js

@@ -1,4 +1,23 @@
+/**
+ * Fail a model-facing protocol contract.
+ *
+ * Model output is untrusted input: violations are reported as `ValidationError`
+ * issues so callers can inspect every problem instead of catching a bare Error.
+ *
+ * Exports: `modelProtocolError`.
+ */
 import { ValidationError } from '../structs/errors.js';
+/**
+ * Throw a model protocol validation error.
+ *
+ * @param message - Primary issue message, always reported with code `MODEL_PROTOCOL`.
+ * @param reason - Optional secondary code for the same message, used to distinguish variants.
+ * @returns Never returns; the declared `never` return lets callers use it in expressions.
+ * @throws ValidationError carrying one or two issues.
+ */
 export function modelProtocolError(message, reason) {
-    throw new ValidationError([{ code: 'MODEL_PROTOCOL', message }, ...(reason ? [{ code: reason, message }] : [])]);
+    throw new ValidationError([
+        { code: 'MODEL_PROTOCOL', message },
+        ...(reason ? [{ code: reason, message }] : []),
+    ]);
 }

package/dist/esm/utils/object.d.ts

@@ -1 +1,17 @@
+/**
+ * Structural object freezing for schema snapshots.
+ *
+ * JSON schemas are shared by definition, so a consumer that mutates a nested keyword
+ * would corrupt every other consumer. This deep freeze makes that attempt fail loudly.
+ *
+ * Exports: `freezeSchema`.
+ */
+/**
+ * Recursively freeze an object graph.
+ *
+ * Arrays are objects, so they are covered as well. Already frozen nodes are skipped,
+ * which makes the walk safe on cyclic or shared sub-graphs and idempotent.
+ *
+ * @param value - Candidate node; primitives and non-objects are ignored.
+ */
 export declare function freezeSchema(value: unknown): void;

package/dist/esm/utils/object.js

@@ -1,3 +1,19 @@
+/**
+ * Structural object freezing for schema snapshots.
+ *
+ * JSON schemas are shared by definition, so a consumer that mutates a nested keyword
+ * would corrupt every other consumer. This deep freeze makes that attempt fail loudly.
+ *
+ * Exports: `freezeSchema`.
+ */
+/**
+ * Recursively freeze an object graph.
+ *
+ * Arrays are objects, so they are covered as well. Already frozen nodes are skipped,
+ * which makes the walk safe on cyclic or shared sub-graphs and idempotent.
+ *
+ * @param value - Candidate node; primitives and non-objects are ignored.
+ */
 export function freezeSchema(value) {
     if (!value || typeof value !== 'object' || Object.isFrozen(value))
         return;

package/dist/esm/utils/observer.d.ts

@@ -1,2 +1,20 @@
-/** Observers receive detached data; uncloneable observations are skipped, never exposed by reference. */
+/**
+ * Defensive delivery of observed values to App-supplied observers.
+ *
+ * Observation is optional and must never influence the observed operation, so the
+ * value is cloned, failures are swallowed and returned promises are consumed.
+ *
+ * Exports: `observeSafely`.
+ */
+/**
+ * Deliver a detached copy of a value to an observer.
+ *
+ * The clone prevents an observer from mutating execution state through a shared
+ * reference. A value that cannot be structured-cloned is skipped entirely rather
+ * than handed over by reference.
+ *
+ * @param observe - Observer callback, if one is installed.
+ * @param value - Value to clone and deliver.
+ * @returns Nothing; the observer may run asynchronously after this returns.
+ */
 export declare function observeSafely<Value>(observe: ((value: Value) => void | Promise<void>) | undefined, value: Value): void;

package/dist/esm/utils/observer.js

@@ -1,4 +1,22 @@
-/** Observers receive detached data; uncloneable observations are skipped, never exposed by reference. */
+/**
+ * Defensive delivery of observed values to App-supplied observers.
+ *
+ * Observation is optional and must never influence the observed operation, so the
+ * value is cloned, failures are swallowed and returned promises are consumed.
+ *
+ * Exports: `observeSafely`.
+ */
+/**
+ * Deliver a detached copy of a value to an observer.
+ *
+ * The clone prevents an observer from mutating execution state through a shared
+ * reference. A value that cannot be structured-cloned is skipped entirely rather
+ * than handed over by reference.
+ *
+ * @param observe - Observer callback, if one is installed.
+ * @param value - Value to clone and deliver.
+ * @returns Nothing; the observer may run asynchronously after this returns.
+ */
 export function observeSafely(observe, value) {
     if (!observe)
         return;
@@ -7,5 +25,7 @@ export function observeSafely(observe, value) {
         if (pending)
             void Promise.resolve(pending).catch(() => { });
     }
-    catch { /* Observation is independent of the operation. */ }
+    catch {
+        /* Observation is independent of the operation. */
+    }
 }