@jangts/agent-core 0.1.0 → 0.2.0

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

@@ -1,7 +1,44 @@
-/** Schema and terminal semantics come entirely from registration, with no built-in step names. */
+/**
+ * Strict id-keyed registry for model output protocols.
+ *
+ * Registration is the only source of schema and terminal semantics: the core never
+ * knows protocol names. Writes are checked eagerly so a duplicate or blank id fails at
+ * wiring time instead of at dispatch time.
+ *
+ * Exports: `ProtocolRegistry`.
+ */
+/**
+ * Append-only protocol registry.
+ *
+ * Extending `Map` keeps lookup semantics familiar while `set` rejects every invalid
+ * registration, which makes the instance effectively immutable after wiring.
+ */
 export declare class ProtocolRegistry<Protocol> extends Map<string, Protocol> {
+    /**
+     * @param definitions - Initial id/protocol pairs, applied through the validating `set`.
+     * @throws TypeError When any initial entry is invalid or duplicated.
+     */
     constructor(definitions?: Iterable<readonly [string, Protocol]>);
+    /**
+     * @returns A frozen array of registered ids in insertion order.
+     */
     ids(): readonly string[];
+    /**
+     * Look up a protocol that must exist.
+     *
+     * @param id - Protocol id.
+     * @returns The registered protocol.
+     * @throws TypeError When the id is unknown.
+     */
     require(id: string): Protocol;
+    /**
+     * Register a protocol.
+     *
+     * @param id - Non-blank protocol id.
+     * @param protocol - Protocol implementation.
+     * @returns This registry, for chaining.
+     * @throws TypeError When the id is blank or the protocol is nullish.
+     * @throws Error When the id is already registered.
+     */
     set(id: string, protocol: Protocol): this;
 }

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

@@ -1,13 +1,56 @@
-/** Schema and terminal semantics come entirely from registration, with no built-in step names. */
+/**
+ * Strict id-keyed registry for model output protocols.
+ *
+ * Registration is the only source of schema and terminal semantics: the core never
+ * knows protocol names. Writes are checked eagerly so a duplicate or blank id fails at
+ * wiring time instead of at dispatch time.
+ *
+ * Exports: `ProtocolRegistry`.
+ */
+/**
+ * Append-only protocol registry.
+ *
+ * Extending `Map` keeps lookup semantics familiar while `set` rejects every invalid
+ * registration, which makes the instance effectively immutable after wiring.
+ */
 export class ProtocolRegistry extends Map {
+    /**
+     * @param definitions - Initial id/protocol pairs, applied through the validating `set`.
+     * @throws TypeError When any initial entry is invalid or duplicated.
+     */
     constructor(definitions = []) {
         super();
         for (const [id, protocol] of definitions)
             this.set(id, protocol);
     }
-    ids() { return Object.freeze([...this.keys()]); }
-    require(id) { const value = this.get(id); if (value === undefined)
-        throw new TypeError(`Unknown protocol: ${id}`); return value; }
+    /**
+     * @returns A frozen array of registered ids in insertion order.
+     */
+    ids() {
+        return Object.freeze([...this.keys()]);
+    }
+    /**
+     * Look up a protocol that must exist.
+     *
+     * @param id - Protocol id.
+     * @returns The registered protocol.
+     * @throws TypeError When the id is unknown.
+     */
+    require(id) {
+        const value = this.get(id);
+        if (value === undefined)
+            throw new TypeError(`Unknown protocol: ${id}`);
+        return value;
+    }
+    /**
+     * Register a protocol.
+     *
+     * @param id - Non-blank protocol id.
+     * @param protocol - Protocol implementation.
+     * @returns This registry, for chaining.
+     * @throws TypeError When the id is blank or the protocol is nullish.
+     * @throws Error When the id is already registered.
+     */
     set(id, protocol) {
         if (!id.trim() || protocol === null || protocol === undefined)
             throw new TypeError('Invalid protocol registration');

package/dist/esm/utils/query-key.d.ts

@@ -1,2 +1,12 @@
-/** Stable structural equality for queries; array order remains meaningful. */
+/**
+ * Serialize a query into a stable structural key.
+ *
+ * Object keys are sorted recursively while array positions are preserved. Values that
+ * JSON cannot represent, such as functions or `undefined`, make `JSON.stringify`
+ * return undefined and therefore produce an error instead of a colliding key.
+ *
+ * @param value - Query value to canonicalize.
+ * @returns A JSON string usable as a map key.
+ * @throws TypeError When the value cannot be serialized.
+ */
 export declare function retrievalQueryKey(value: unknown): string;

package/dist/esm/utils/query-key.js

@@ -1,5 +1,23 @@
+/**
+ * Stable identity for retrieval queries.
+ *
+ * Retrieval caches need a key that is insensitive to property order but sensitive to
+ * array order, because a query's result list is order-dependent.
+ *
+ * Exports: `retrievalQueryKey`.
+ */
 import { breakWhile } from './rules.js';
-/** Stable structural equality for queries; array order remains meaningful. */
+/**
+ * Serialize a query into a stable structural key.
+ *
+ * Object keys are sorted recursively while array positions are preserved. Values that
+ * JSON cannot represent, such as functions or `undefined`, make `JSON.stringify`
+ * return undefined and therefore produce an error instead of a colliding key.
+ *
+ * @param value - Query value to canonicalize.
+ * @returns A JSON string usable as a map key.
+ * @throws TypeError When the value cannot be serialized.
+ */
 export function retrievalQueryKey(value) {
     const serialized = JSON.stringify(canonical(value));
     breakWhile(serialized === undefined, () => new TypeError('Query cannot be serialized'));
@@ -9,7 +27,8 @@ function canonical(value) {
     if (Array.isArray(value))
         return value.map(canonical);
     if (value && typeof value === 'object') {
-        return Object.fromEntries(Object.entries(value).sort(([left], [right]) => left.localeCompare(right))
+        return Object.fromEntries(Object.entries(value)
+            .sort(([left], [right]) => left.localeCompare(right))
             .map(([key, item]) => [key, canonical(item)]));
     }
     return value;

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

@@ -1,9 +1,41 @@
+/**
+ * Registration projections for App-provided definitions.
+ *
+ * A registered definition may carry executable helpers alongside its data contract.
+ * Only public data survives registration, so the runtime contract cannot silently grow
+ * when an implementation adds a helper.
+ *
+ * Exports: the `RegistrationData` and `RegistrationProjection` types plus
+ * `registrationData`.
+ */
 type Handler = (...args: any[]) => unknown;
-/** Public data survives registration; extra implementation helpers are not a runtime contract. */
+/**
+ * Keys of `Value` whose type contains no callable member.
+ *
+ * Functions are excluded so a definition's implementation helpers never become part of
+ * the public registration contract.
+ */
 export type RegistrationData<Value> = Pick<Value, {
     [Key in keyof Value]-?: [Extract<Value[Key], Handler>] extends [never] ? Key : never;
 }[keyof Value]>;
+/**
+ * Data-only view of a registered value, intersected with the declared contract.
+ *
+ * The contract keys are kept even when the implementation narrows them, so consumers
+ * type against the published interface rather than one implementation.
+ */
 export type RegistrationProjection<Value, Contract> = Readonly<Contract & RegistrationData<Value> & Pick<Value, Extract<keyof Value, keyof Contract>>>;
-/** Snapshot inherited metadata with its real receiver, without retaining a mutable prototype. */
+/**
+ * Copy the inherited, non-function data of a definition.
+ *
+ * The walk starts at the source and moves up the prototype chain while reading every
+ * accessor with the source as receiver, so getters keep observing their own instance
+ * without the snapshot retaining the mutable prototype. `constructor` is skipped for
+ * inherited levels because it describes the class rather than the definition.
+ *
+ * @param source - Definition to snapshot.
+ * @param excluded - Keys that must not appear in the result.
+ * @returns A plain object containing enumerable, writable non-function data.
+ */
 export declare function registrationData<Value extends object, Key extends PropertyKey = never>(source: Value, excluded?: readonly Key[]): Omit<RegistrationData<Value>, Key>;
 export {};

package/dist/esm/utils/registration.js

@@ -1,4 +1,15 @@
-/** Snapshot inherited metadata with its real receiver, without retaining a mutable prototype. */
+/**
+ * Copy the inherited, non-function data of a definition.
+ *
+ * The walk starts at the source and moves up the prototype chain while reading every
+ * accessor with the source as receiver, so getters keep observing their own instance
+ * without the snapshot retaining the mutable prototype. `constructor` is skipped for
+ * inherited levels because it describes the class rather than the definition.
+ *
+ * @param source - Definition to snapshot.
+ * @param excluded - Keys that must not appear in the result.
+ * @returns A plain object containing enumerable, writable non-function data.
+ */
 export function registrationData(source, excluded = []) {
     const result = {};
     const seen = new Set(excluded);
@@ -10,7 +21,12 @@ export function registrationData(source, excluded = []) {
             const descriptor = Object.getOwnPropertyDescriptor(owner, key);
             const value = descriptor.get ? descriptor.get.call(source) : descriptor.value;
             if (typeof value !== 'function')
-                Object.defineProperty(result, key, { value, enumerable: true, configurable: true, writable: true });
+                Object.defineProperty(result, key, {
+                    value,
+                    enumerable: true,
+                    configurable: true,
+                    writable: true,
+                });
         }
     }
     return result;

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

@@ -1,14 +1,91 @@
+/**
+ * Declarative rule primitives.
+ *
+ * Three shapes cover the enumerable decisions in this package: first-match dispatch
+ * (`matchRule`), ordered mutation of shared input (`walkRules`) and reject-on-failure
+ * validation (`breakWhile`). Ordinary single-condition code stays an `if`; these helpers
+ * exist so multi-branch tables stay readable and their ordering is explicit.
+ *
+ * Exports: `matchRule`, `walkRules`, `breakWhile`, the re-exported
+ * `configureBreakWhile`, and the rule types from `structs/utils/rules`.
+ */
 import type { MatchRule, WalkRule, BreakReason, BreakCheck, BreakPredicate } from '../structs/utils/rules.js';
 export { configureBreakWhile } from './break-observer.js';
-/** First match owns the result, even when its handler returns undefined. */
+/**
+ * Dispatch to the first matching rule.
+ *
+ * A rule without a pattern matches unconditionally, so the table's order decides
+ * precedence. The first match owns the result even when its handler returns undefined,
+ * and later rules are not consulted.
+ *
+ * @param rules - Ordered rules; only the first match is executed.
+ * @param input - Value passed to the pattern and handler.
+ * @returns The handler result, or undefined when nothing matched.
+ * @throws TypeError When a pattern returns a thenable or a non-boolean.
+ */
 export declare function matchRule<Input, Result>(rules: readonly MatchRule<Input, Result>[], input: Input): Result | undefined;
-/** Walk in order; later predicates observe earlier updates. Exceptions stop traversal. */
+/**
+ * Walk every rule in order, mutating the shared input.
+ *
+ * Later rules observe the mutations of earlier ones, which is why traversal is strictly
+ * sequential and every participant must be synchronous. Throwing stops the walk
+ * immediately; remaining rules are skipped.
+ *
+ * @param rules - Ordered rules.
+ */
 export declare function walkRules(rules: readonly WalkRule[]): void;
+/**
+ * Walk every rule in order, mutating the shared input.
+ *
+ * @param rules - Ordered rules.
+ * @param input - Mutable input shared by all hooks and handlers.
+ */
 export declare function walkRules<Input>(rules: readonly WalkRule<Input>[], input: Input): void;
-/** Reject when a failure occurs; ordinary processing remains ordinary if statements. */
+/**
+ * Reject as soon as one of several conditions holds.
+ *
+ * Ordinary processing stays an ordinary `if`; this helper is for validation tables
+ * whose entries are evaluated in order and stop at the first failure. Behaviour that
+ * depends on earlier entries is expressed with a callback form.
+ *
+ * @param occur - Predicates, or a single predicate/array of predicates.
+ * @param error - Reason thrown on the first match; defaults to an empty Error.
+ * @param tags - Tags reported to the installed break observer.
+ * @throws The configured reason of the first matching check.
+ */
 export declare function breakWhile(occur: readonly BreakPredicate[], error?: BreakReason, tags?: readonly string[]): void;
+/**
+ * Reject when any predicate holds, reporting the given observer tags.
+ *
+ * @param occur - Predicates evaluated in order.
+ * @param tags - Tags reported to the installed break observer.
+ */
 export declare function breakWhile(occur: readonly BreakPredicate[], tags: readonly string[]): void;
+/**
+ * Reject when any structured check holds.
+ *
+ * Each check may carry its own reason and tags; the first match stops the evaluation.
+ *
+ * @param checks - Checks evaluated in order.
+ * @param tags - Call-site tags merged with each check's own tags.
+ */
 export declare function breakWhile(checks: readonly BreakCheck[], tags?: readonly string[]): void;
+/**
+ * Reject when a single value is truthy.
+ *
+ * Ordinary truthiness applies, so a function passed as a value counts as a failure;
+ * use the predicate form to evaluate it instead.
+ *
+ * @param occur - Value tested with JavaScript truthiness.
+ * @param error - Reason thrown when the value is truthy.
+ * @param tags - Tags reported to the installed break observer.
+ */
 export declare function breakWhile(occur: unknown, error?: BreakReason, tags?: readonly string[]): void;
+/**
+ * Reject when a single value is truthy, reporting the given observer tags.
+ *
+ * @param occur - Value tested with JavaScript truthiness.
+ * @param tags - Tags reported to the installed break observer.
+ */
 export declare function breakWhile(occur: unknown, tags: readonly string[]): void;
-export type { MatchRule, WalkRule, BreakReason, BreakCheck, BreakPredicate, BreakEvent, BreakWhileConfig } from '../structs/utils/rules.js';
+export type { MatchRule, WalkRule, BreakReason, BreakCheck, BreakPredicate, BreakEvent, BreakWhileConfig, } from '../structs/utils/rules.js';

package/dist/esm/utils/rules.js

@@ -1,14 +1,29 @@
 import { synchronous, booleanResult } from './synchronous.js';
 import { observeBreak } from './break-observer.js';
 export { configureBreakWhile } from './break-observer.js';
-/** First match owns the result, even when its handler returns undefined. */
+/**
+ * Dispatch to the first matching rule.
+ *
+ * A rule without a pattern matches unconditionally, so the table's order decides
+ * precedence. The first match owns the result even when its handler returns undefined,
+ * and later rules are not consulted.
+ *
+ * @param rules - Ordered rules; only the first match is executed.
+ * @param input - Value passed to the pattern and handler.
+ * @returns The handler result, or undefined when nothing matched.
+ * @throws TypeError When a pattern returns a thenable or a non-boolean.
+ */
 export function matchRule(rules, input) {
-    return rules.find(rule => rule.pattern === undefined || booleanResult(rule.pattern(input), 'Rule patterns must return boolean synchronously'))?.handle(input);
+    return rules
+        .find((rule) => rule.pattern === undefined ||
+        booleanResult(rule.pattern(input), 'Rule patterns must return boolean synchronously'))
+        ?.handle(input);
 }
 export function walkRules(rules, input = undefined) {
     for (const rule of rules) {
         synchronous(rule.before?.(input), 'Rule traversal hooks must be synchronous');
-        if (rule.pattern === undefined || booleanResult(rule.pattern(input), 'Rule patterns must return boolean synchronously'))
+        if (rule.pattern === undefined ||
+            booleanResult(rule.pattern(input), 'Rule patterns must return boolean synchronously'))
             synchronous(rule.handle(input), 'Rule traversal handlers must be synchronous');
     }
 }
@@ -17,24 +32,37 @@ export function breakWhile(occur, errorOrTags, tags = []) {
     const callTags = Array.isArray(errorOrTags) ? errorOrTags : tags;
     // A single value keeps ordinary JS truthiness, including a function used as a value.
     const checks = Array.isArray(occur)
-        ? typeof occur[0] === 'function' && occur.every(item => typeof item === 'function')
+        ? typeof occur[0] === 'function' && occur.every((item) => typeof item === 'function')
             ? [{ occur, error }]
             : occur
         : [{ occur: () => occur, error }];
     for (const check of checks) {
         try {
-            if (!check || typeof check !== 'object' || Array.isArray(check) || !Object.hasOwn(check, 'occur')
-                || 'condition' in check || 'conditions' in check)
+            if (!check ||
+                typeof check !== 'object' ||
+                Array.isArray(check) ||
+                !Object.hasOwn(check, 'occur') ||
+                'condition' in check ||
+                'conditions' in check)
                 throw new TypeError('A break check requires occur; condition and conditions were renamed to occur');
             const occur = check.occur;
-            if (Array.isArray(occur) && occur.some(predicate => typeof predicate !== 'function'))
+            if (Array.isArray(occur) && occur.some((predicate) => typeof predicate !== 'function'))
                 throw new TypeError('An occur array requires predicates');
-            const matched = Array.isArray(occur) ? occur.some(predicate => synchronous(predicate(), 'Occur predicates must be synchronous'))
-                : typeof occur === 'function' ? synchronous(occur(), 'Occur predicates must be synchronous') : occur;
+            const matched = Array.isArray(occur)
+                ? occur.some((predicate) => synchronous(predicate(), 'Occur predicates must be synchronous'))
+                : typeof occur === 'function'
+                    ? synchronous(occur(), 'Occur predicates must be synchronous')
+                    : occur;
             if (!matched)
                 continue;
-            const reason = typeof check.error === 'function' ? synchronous(check.error(), 'Break reasons must be synchronous') : check.error;
-            throw reason === undefined ? new Error() : typeof reason === 'string' ? new Error(reason) : reason;
+            const reason = typeof check.error === 'function'
+                ? synchronous(check.error(), 'Break reasons must be synchronous')
+                : check.error;
+            throw reason === undefined
+                ? new Error()
+                : typeof reason === 'string'
+                    ? new Error(reason)
+                    : reason;
         }
         catch (failure) {
             observeBreak(failure, callTags, check);

package/dist/esm/utils/schema-adapter.d.ts

@@ -1,3 +1,14 @@
 import type { SchemaAdapter } from '../structs/common.js';
-/** Pin the parser and its receiver independently of the schema snapshot. */
+/**
+ * Detach a schema adapter into a frozen, synchronous definition.
+ *
+ * The JSON schema is cloned and deep-frozen; the parser is bound to the original
+ * definition so a method keeps its receiver, then wrapped so a thenable result is
+ * rejected rather than awaited.
+ *
+ * @param definition - Adapter to snapshot.
+ * @param asyncError - Message used when the parser returns a thenable.
+ * @returns A frozen adapter with a cloned schema and a synchronous parser.
+ * @throws TypeError When `jsonSchema` is missing or not a plain object.
+ */
 export declare function snapshotSchemaAdapter<Value>(definition: SchemaAdapter<Value>, asyncError?: string): SchemaAdapter<Value>;

package/dist/esm/utils/schema-adapter.js

@@ -1,6 +1,26 @@
+/**
+ * Snapshot helper for registered schema adapters.
+ *
+ * An adapter owns a JSON schema and a parser. Both must be detached from the App object
+ * that supplied them, both must be immutable afterwards, and the parser must stay
+ * synchronous, because schema snapshots are reused across requests and diagnostics.
+ *
+ * Exports: `snapshotSchemaAdapter`.
+ */
 import { freezeSchema } from './object.js';
 import { synchronous } from './synchronous.js';
-/** Pin the parser and its receiver independently of the schema snapshot. */
+/**
+ * Detach a schema adapter into a frozen, synchronous definition.
+ *
+ * The JSON schema is cloned and deep-frozen; the parser is bound to the original
+ * definition so a method keeps its receiver, then wrapped so a thenable result is
+ * rejected rather than awaited.
+ *
+ * @param definition - Adapter to snapshot.
+ * @param asyncError - Message used when the parser returns a thenable.
+ * @returns A frozen adapter with a cloned schema and a synchronous parser.
+ * @throws TypeError When `jsonSchema` is missing or not a plain object.
+ */
 export function snapshotSchemaAdapter(definition, asyncError = 'Schema parsers must be synchronous') {
     const { jsonSchema } = definition;
     if (!jsonSchema || typeof jsonSchema !== 'object' || Array.isArray(jsonSchema)) {
@@ -9,5 +29,8 @@ export function snapshotSchemaAdapter(definition, asyncError = 'Schema parsers m
     const snapshot = structuredClone(jsonSchema);
     freezeSchema(snapshot);
     const parse = definition.parse.bind(definition);
-    return Object.freeze({ jsonSchema: snapshot, parse: (input) => synchronous(parse(input), asyncError) });
+    return Object.freeze({
+        jsonSchema: snapshot,
+        parse: (input) => synchronous(parse(input), asyncError),
+    });
 }

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

@@ -1,9 +1,65 @@
-/** Shared thenable test for contracts that either reject or explicitly await one. */
+/**
+ * Guards for contracts that require synchronous participants.
+ *
+ * Handlers, predicates and parsers are declared synchronous by contract. Detecting an
+ * accidental async implementation early is cheaper than debugging an interleaved
+ * execution, so every such call site passes its result through these helpers.
+ *
+ * Exports: `isPromiseLike`, `synchronous`, `assertion`, `maybeAssertion` and
+ * `booleanResult`.
+ */
+/**
+ * Test for a thenable without invoking it.
+ *
+ * @param value - Candidate value.
+ * @returns True when the value carries a callable `then`.
+ */
 export declare function isPromiseLike(value: unknown): value is PromiseLike<unknown>;
-/** Reject an accidental async callback and consume its eventual rejection. This cannot undo its side effects. */
+/**
+ * Reject an accidentally asynchronous callback.
+ *
+ * A thenable is consumed before throwing so its eventual rejection cannot surface as an
+ * unhandled rejection. Any side effects the callback already started cannot be undone.
+ *
+ * @param value - Result of the callback.
+ * @param message - Message for the TypeError raised when the result is thenable.
+ * @returns The same value, narrowed to a non-thenable.
+ * @throws TypeError When the value is a thenable.
+ */
 export declare function synchronous<Value>(value: Value, message: string): Value;
-/** Assertions and authorization must finish with undefined, never a discarded boolean. */
+/**
+ * Require an assertion hook to finish with `undefined`.
+ *
+ * Returning a boolean is a common mistake that would silently pass; requiring `void`
+ * makes a discarded decision fail loudly.
+ *
+ * @param value - Result of the assertion hook.
+ * @param message - Message for the TypeError.
+ * @throws TypeError When the result is thenable or not `undefined`.
+ */
 export declare function assertion(value: unknown, message: string): void;
-/** Retain a synchronous assertion when allowed; await only actual thenables. */
+/**
+ * Accept a synchronous assertion or await an actually asynchronous one.
+ *
+ * Only a thenable is awaited; synchronous results are validated immediately so callers
+ * that rely on ordering do not yield to the event loop unnecessarily.
+ *
+ * @param value - Result of the assertion hook.
+ * @param message - Message for the TypeError.
+ * @returns Nothing, or a promise resolved once the awaited assertion passed.
+ * @throws TypeError When the hook does not finish with `undefined`.
+ */
 export declare function maybeAssertion(value: unknown, message: string): void | Promise<void>;
+/**
+ * Require a synchronous boolean decision.
+ *
+ * Truthiness is not accepted: routing must receive an explicit `true` or `false` so a
+ * predicate that forgets to return a value is reported instead of silently skipping.
+ *
+ * @param value - Result of the predicate.
+ * @param message - Message for the thenable TypeError.
+ * @param invalidMessage - Message for the non-boolean TypeError; defaults to `message`.
+ * @returns The validated boolean.
+ * @throws TypeError When the result is thenable or not boolean.
+ */
 export declare function booleanResult(value: unknown, message: string, invalidMessage?: string): boolean;

package/dist/esm/utils/synchronous.js

@@ -1,9 +1,35 @@
-/** Shared thenable test for contracts that either reject or explicitly await one. */
+/**
+ * Guards for contracts that require synchronous participants.
+ *
+ * Handlers, predicates and parsers are declared synchronous by contract. Detecting an
+ * accidental async implementation early is cheaper than debugging an interleaved
+ * execution, so every such call site passes its result through these helpers.
+ *
+ * Exports: `isPromiseLike`, `synchronous`, `assertion`, `maybeAssertion` and
+ * `booleanResult`.
+ */
+/**
+ * Test for a thenable without invoking it.
+ *
+ * @param value - Candidate value.
+ * @returns True when the value carries a callable `then`.
+ */
 export function isPromiseLike(value) {
-    return value !== null && (typeof value === 'object' || typeof value === 'function')
-        && typeof value.then === 'function';
+    return (value !== null &&
+        (typeof value === 'object' || typeof value === 'function') &&
+        typeof value.then === 'function');
 }
-/** Reject an accidental async callback and consume its eventual rejection. This cannot undo its side effects. */
+/**
+ * Reject an accidentally asynchronous callback.
+ *
+ * A thenable is consumed before throwing so its eventual rejection cannot surface as an
+ * unhandled rejection. Any side effects the callback already started cannot be undone.
+ *
+ * @param value - Result of the callback.
+ * @param message - Message for the TypeError raised when the result is thenable.
+ * @returns The same value, narrowed to a non-thenable.
+ * @throws TypeError When the value is a thenable.
+ */
 export function synchronous(value, message) {
     if (isPromiseLike(value)) {
         void Promise.resolve(value).catch(() => { });
@@ -11,17 +37,48 @@ export function synchronous(value, message) {
     }
     return value;
 }
-/** Assertions and authorization must finish with undefined, never a discarded boolean. */
+/**
+ * Require an assertion hook to finish with `undefined`.
+ *
+ * Returning a boolean is a common mistake that would silently pass; requiring `void`
+ * makes a discarded decision fail loudly.
+ *
+ * @param value - Result of the assertion hook.
+ * @param message - Message for the TypeError.
+ * @throws TypeError When the result is thenable or not `undefined`.
+ */
 export function assertion(value, message) {
     if (synchronous(value, message) !== undefined)
         throw new TypeError(message);
 }
-/** Retain a synchronous assertion when allowed; await only actual thenables. */
+/**
+ * Accept a synchronous assertion or await an actually asynchronous one.
+ *
+ * Only a thenable is awaited; synchronous results are validated immediately so callers
+ * that rely on ordering do not yield to the event loop unnecessarily.
+ *
+ * @param value - Result of the assertion hook.
+ * @param message - Message for the TypeError.
+ * @returns Nothing, or a promise resolved once the awaited assertion passed.
+ * @throws TypeError When the hook does not finish with `undefined`.
+ */
 export function maybeAssertion(value, message) {
     if (isPromiseLike(value))
-        return Promise.resolve(value).then(result => assertion(result, message));
+        return Promise.resolve(value).then((result) => assertion(result, message));
     assertion(value, message);
 }
+/**
+ * Require a synchronous boolean decision.
+ *
+ * Truthiness is not accepted: routing must receive an explicit `true` or `false` so a
+ * predicate that forgets to return a value is reported instead of silently skipping.
+ *
+ * @param value - Result of the predicate.
+ * @param message - Message for the thenable TypeError.
+ * @param invalidMessage - Message for the non-boolean TypeError; defaults to `message`.
+ * @returns The validated boolean.
+ * @throws TypeError When the result is thenable or not boolean.
+ */
 export function booleanResult(value, message, invalidMessage = message) {
     const result = synchronous(value, message);
     if (typeof result !== 'boolean')

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

@@ -1,2 +1,16 @@
-/** Native prefix comparisons avoid a JavaScript character loop on long prompts. */
+/**
+ * Small string helpers used for prompt accounting.
+ *
+ * Exports: `commonPrefixLength`.
+ */
+/**
+ * Length of the longest common prefix of two strings.
+ *
+ * Implemented as a binary search over slice comparisons so long prompts stay on the
+ * native string comparison path instead of running a JavaScript character loop.
+ *
+ * @param left - First string.
+ * @param right - Second string.
+ * @returns Number of leading characters both strings share, bounded by the shorter length.
+ */
 export declare function commonPrefixLength(left: string, right: string): number;

package/dist/esm/utils/text.js

@@ -1,4 +1,18 @@
-/** Native prefix comparisons avoid a JavaScript character loop on long prompts. */
+/**
+ * Small string helpers used for prompt accounting.
+ *
+ * Exports: `commonPrefixLength`.
+ */
+/**
+ * Length of the longest common prefix of two strings.
+ *
+ * Implemented as a binary search over slice comparisons so long prompts stay on the
+ * native string comparison path instead of running a JavaScript character loop.
+ *
+ * @param left - First string.
+ * @param right - Second string.
+ * @returns Number of leading characters both strings share, bounded by the shorter length.
+ */
 export function commonPrefixLength(left, right) {
     let low = 0;
     let high = Math.min(left.length, right.length);