@jangts/agent-core 0.1.0 → 0.2.0

package/dist/cjs/execution/events.js

@@ -2,24 +2,47 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.createEventScope = createEventScope;
 exports.executionEvents = executionEvents;
+/**
+ * Diagnostic event fact source for the execution loop.
+ *
+ * One `DiagnosticContext` tree serves both live observers and the optional persistent log.
+ * Facts are built once, then each consumer receives its own copy — full content only when
+ * that consumer asked for content, otherwise a metadata projection. No consumer means no
+ * payload work and no sub-step capture.
+ *
+ * Exports: `createEventScope` and `executionEvents`.
+ */
 const debug_js_1 = require("../utils/debug.js");
 const invocation_js_1 = require("../utils/invocation.js");
 const errors_js_1 = require("../errors.js");
 const catalog_js_1 = require("../diagnostics/catalog.js");
-/** One fact source for live observation and optional persistence. No consumer means no payload work. */
+/**
+ * Create the root diagnostic scope.
+ *
+ * @param options - Sink, observer, run id and initial span id.
+ * @returns The root scope; child scopes inherit its consumers.
+ */
 function createEventScope(options = {}) {
     const { output } = options;
     const write = output?.write.bind(output);
     const accepts = output?.accepts?.bind(output);
     const runId = options.runId || (0, invocation_js_1.invocationId)();
     const spanId = options.spanId ?? 'run';
+    // Shared by every child scope so `producerSequence` orders facts across the whole run.
     let sequence = 0;
     const observer = (source) => ({
-        accepts: source.accepts?.bind(source), event: source.event.bind(source),
+        accepts: source.accepts?.bind(source),
+        event: source.event.bind(source),
     });
     const initial = options.observe ? [observer(options.observe)] : [];
     const context = (span, parent, fields = {}, listeners = initial) => {
-        const identity = Object.freeze({ ...fields, runId, spanId: span, ...(parent ? { parentSpanId: parent } : {}) });
+        const identity = Object.freeze({
+            ...fields,
+            runId,
+            spanId: span,
+            ...(parent ? { parentSpanId: parent } : {}),
+        });
+        // A missing accepts hook means the sink takes everything except an explicit refusal.
         const logEnabled = (event, content) => {
             if (!write)
                 return false;
@@ -30,9 +53,12 @@ function createEventScope(options = {}) {
                 return false;
             }
         };
+        // Listeners default to metadata-only; content requires an explicit opt-in.
         const listenerEnabled = (listener, event, content) => {
             try {
-                return listener.accepts ? listener.accepts({ ...identity, event, content }) === true : content === 'metadata';
+                return listener.accepts
+                    ? listener.accepts({ ...identity, event, content }) === true
+                    : content === 'metadata';
             }
             catch {
                 return false;
@@ -40,8 +66,24 @@ function createEventScope(options = {}) {
         };
         const fact = (event, payload, debug) => {
             const value = payload();
-            const reported = scope.enabled(event, 'content') ? (0, debug_js_1.captureSubSteps)(debug?.subSteps, identity) : (0, debug_js_1.captureSubSteps)(undefined);
-            return { ...identity, ...reported, ...(typeof debug?.usedModel === 'boolean' ? { usedModel: debug.usedModel } : {}), version: 2, eventId: event === 'workflow.event' ? value.event.eventId : event === 'loop.event' ? value.eventId : (0, invocation_js_1.invocationId)(), type: event, producerSequence: ++sequence, occurredAtMs: Date.now(), payload: value };
+            const reported = scope.enabled(event, 'content')
+                ? (0, debug_js_1.captureSubSteps)(debug?.subSteps, identity)
+                : (0, debug_js_1.captureSubSteps)(undefined);
+            return {
+                ...identity,
+                ...reported,
+                ...(typeof debug?.usedModel === 'boolean' ? { usedModel: debug.usedModel } : {}),
+                version: 2,
+                eventId: event === 'workflow.event'
+                    ? value.event.eventId
+                    : event === 'loop.event'
+                        ? value.eventId
+                        : (0, invocation_js_1.invocationId)(),
+                type: event,
+                producerSequence: ++sequence,
+                occurredAtMs: Date.now(),
+                payload: value,
+            };
         };
         const publish = (record) => {
             const event = record.type, kind = catalog_js_1.coreEventCatalog[event];
@@ -69,50 +111,117 @@ function createEventScope(options = {}) {
         };
         const scope = {
             identity,
+            /** Whether any consumer would accept this event, optionally requiring content. */
             enabled(event, content) {
                 if (!Object.hasOwn(catalog_js_1.coreEventCatalog, event))
                     return false;
                 const kind = content === 'content' ? 'content' : catalog_js_1.coreEventCatalog[event];
-                return logEnabled(event, kind) || listeners.some(listener => listenerEnabled(listener, event, kind));
+                return (logEnabled(event, kind) ||
+                    listeners.some((listener) => listenerEnabled(listener, event, kind)));
             },
+            /**
+             * Build and publish a fact without waiting for anyone.
+             *
+             * Observation failures are swallowed so reporting cannot change execution.
+             */
             emit(event, payload, debug) {
                 if (!this.enabled(event))
                     return;
                 try {
                     publish(fact(event, payload, debug));
                 }
-                catch { /* Observation must not change execution. */ }
+                catch {
+                    /* Observation must not change execution. */
+                }
             },
+            /**
+             * Publish a fact and then hand a copy of it to a delivery sink.
+             *
+             * Publication comes first so observers retain causal order even if the sink stalls.
+             */
             async deliver(event, payload, sink) {
                 const record = fact(event, payload);
                 publish(record);
                 await sink(eventSnapshot(record));
             },
-            child: (id, childFields = {}) => context(`${span}/${id}`, span, { ...fields,
-                ...(childFields.invocationId && childFields.invocationId !== fields.invocationId && fields.invocationId ? { parentInvocationId: fields.invocationId } : {}), ...childFields }, listeners),
-            withObserver: source => context(span, parent, fields, [...listeners, observer(source)]),
+            /**
+             * Derive a child span.
+             *
+             * A child that starts its own invocation records the parent invocation, which keeps
+             * a request-scoped trace navigable without modelling the whole call tree.
+             */
+            child: (id, childFields = {}) => context(`${span}/${id}`, span, {
+                ...fields,
+                ...(childFields.invocationId &&
+                    childFields.invocationId !== fields.invocationId &&
+                    fields.invocationId
+                    ? { parentInvocationId: fields.invocationId }
+                    : {}),
+                ...childFields,
+            }, listeners),
+            /** Add an observer to an existing scope while keeping its identity and sequence. */
+            withObserver: (source) => context(span, parent, fields, [...listeners, observer(source)]),
         };
         return scope;
     };
     return context(spanId);
 }
-/** Metadata projections are shared by live observers and log consumers. */
+/**
+ * Metadata projections shared by live observers and log consumers.
+ *
+ * Only events listed here are reduced; an unlisted event passes its full payload to a
+ * metadata-only consumer, so any event added to the catalog must also be added here when
+ * its payload contains content.
+ */
 const metadataProjections = {
-    'node.progress': ({ subStep, reportError }) => ({ ...(subStep ? { subStep } : {}), ...(reportError ? { reportError } : {}) }),
+    'node.progress': ({ subStep, reportError }) => ({
+        ...(subStep ? { subStep } : {}),
+        ...(reportError ? { reportError } : {}),
+    }),
     'workflow.event': ({ event }) => ({ event }),
     'tool.call': ({ toolId, invocationId }) => ({ toolId, invocationId }),
-    'tool.result': ({ toolId, invocationId, status, durationMs, errorCode }) => ({ toolId, invocationId, status, durationMs, errorCode }),
+    'tool.result': ({ toolId, invocationId, status, durationMs, errorCode }) => ({
+        toolId,
+        invocationId,
+        status,
+        durationMs,
+        errorCode,
+    }),
     'model.parsed': ({ stageId, callSequence }) => ({ stageId, callSequence }),
     'model.end': ({ stageId, state, receivedParts }) => ({ stageId, state, receivedParts }),
-    'runtime.rejected': ({ stageId, error }) => ({ stageId, error: { code: (0, errors_js_1.getErrorInfo)(error).code } }),
+    'runtime.rejected': ({ stageId, error }) => ({
+        stageId,
+        error: { code: (0, errors_js_1.getErrorInfo)(error).code },
+    }),
     'rule.result': ({ tags, error }) => ({ tags, error: { code: (0, errors_js_1.getErrorInfo)(error).code } }),
 };
+/**
+ * Reduce a payload to its metadata projection.
+ *
+ * @param type - Event type.
+ * @param payload - Full payload built for the fact.
+ * @returns The projected payload, or the original when no projection is declared.
+ */
 function metadataPayload(type, payload) {
     return metadataProjections[type]?.(payload) ?? payload;
 }
-/** Every consumer gets its own copy and the same metadata-only fallback. */
+/**
+ * Copy one record for a single consumer.
+ *
+ * Every consumer gets its own copy so one listener cannot observe another's mutations.
+ * A content-free copy is used when requested, and if the full record cannot be cloned the
+ * metadata-only record is used instead, since observation must never fail the caller.
+ *
+ * @param record - Fact to copy.
+ * @param content - Whether to keep payload content.
+ * @returns A structured clone of either the full record or its metadata projection.
+ */
 function eventSnapshot(record, content = true) {
-    const metadata = () => ({ ...record, ...(0, debug_js_1.captureSubSteps)(undefined), payload: metadataPayload(record.type, record.payload) });
+    const metadata = () => ({
+        ...record,
+        ...(0, debug_js_1.captureSubSteps)(undefined),
+        payload: metadataPayload(record.type, record.payload),
+    });
     try {
         return structuredClone(content ? record : metadata());
     }
@@ -120,7 +229,16 @@ function eventSnapshot(record, content = true) {
         return structuredClone(metadata());
     }
 }
-/** Bind observation to an existing source; child scopes retain the same fact identity and sequence. */
+/**
+ * Resolve the diagnostic scope for one execution.
+ *
+ * An observer forces a scope to exist even when the host installed none; the observer is
+ * attached to the existing scope instead of replacing it, so log and live observation
+ * share one fact identity and one sequence.
+ *
+ * @param options - Execution options carrying a scope and/or an observer.
+ * @returns The scope to use, or undefined when the host observes nothing.
+ */
 function executionEvents(options) {
     const { diagnostics, observe } = options ?? {};
     return observe ? (diagnostics ?? createEventScope()).withObserver(observe) : diagnostics;

package/dist/cjs/execution/index.js

@@ -15,6 +15,13 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ValidationError = exports.BudgetError = void 0;
+/**
+ * Public surface of the execution layer.
+ *
+ * Re-exports the engine, the workflow catalog and its route helpers, the shared budget
+ * and validation errors, and the policy kit. Applications should import the loop and
+ * workflow contracts from here rather than from individual files.
+ */
 __exportStar(require("./engine.js"), exports);
 __exportStar(require("./workflow.js"), exports);
 var errors_js_1 = require("../structs/errors.js");

package/dist/cjs/execution/reporting.js

@@ -1,9 +1,24 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.NodeReports = void 0;
+/**
+ * Per-visit reporting scope for workflow nodes and loop steps.
+ *
+ * A node may report progress and write sub-steps while it runs. This scope guarantees
+ * that reports stop at the end of the visit (`close`), stop on cancellation, and never
+ * fail the execution: invalid reports degrade to an error marker.
+ *
+ * Exports: `NodeReports`.
+ */
 const rules_js_1 = require("../utils/rules.js");
 const sub_flow_js_1 = require("../diagnostics/sub-flow.js");
-/** The existing node report and diagnostic outlet, scoped to one execution visit. */
+/**
+ * The existing node report and diagnostic outlet, scoped to one execution visit.
+ *
+ * One instance exists per node visit. `close` is called in the engine's `finally`, so
+ * reports emitted after the visit ends are dropped rather than attributed to a later
+ * node.
+ */
 class NodeReports {
     diagnostics;
     signal;
@@ -11,29 +26,70 @@ class NodeReports {
     active = true;
     logger;
     usedModel;
+    /**
+     * @param diagnostics - Diagnostic scope of the visit; omitted when observation is off.
+     * @param signal - Execution signal; an aborted signal suppresses all further reports.
+     * @param terminalEvent - Event whose content switch also enables sub-step capture.
+     */
     constructor(diagnostics, signal, terminalEvent = 'workflow.event') {
         this.diagnostics = diagnostics;
         this.signal = signal;
         this.terminalEvent = terminalEvent;
     }
-    close() { this.active = false; }
+    /** End the visit; later reports and logger creation are ignored or rejected. */
+    close() {
+        this.active = false;
+    }
+    /**
+     * Validate a report and retain its model-use flag.
+     *
+     * `usedModel` is monotonic: once a visit reports model use, a later report cannot take
+     * it back, because the observation already claimed a model-assisted step.
+     *
+     * @param update - Report supplied by the node.
+     * @throws TypeError When the report is not an object or its model-use flag conflicts.
+     */
     receive(update) {
         (0, rules_js_1.breakWhile)(!update || typeof update !== 'object', () => new TypeError('Invalid node report'));
         const usedModel = update.usedModel;
-        (0, rules_js_1.breakWhile)(usedModel !== undefined && (typeof usedModel !== 'boolean' || (this.usedModel === true && !usedModel)), () => new TypeError('Invalid reported model use'));
+        (0, rules_js_1.breakWhile)(usedModel !== undefined &&
+            (typeof usedModel !== 'boolean' || (this.usedModel === true && !usedModel)), () => new TypeError('Invalid reported model use'));
         if (usedModel !== undefined)
             this.usedModel = usedModel;
     }
+    /**
+     * Build the debug view of this visit.
+     *
+     * Getters keep the values live while the fact is being built; `subSteps` prefers the
+     * logger supplied in the report and falls back to the visit's own logger.
+     *
+     * @param update - Optional report whose logger replaces the visit logger.
+     * @returns A debug output object consumed by the diagnostic pipeline.
+     */
     debug(update) {
         const self = this;
-        return { get usedModel() { return self.usedModel; }, subSteps: () => {
+        return {
+            get usedModel() {
+                return self.usedModel;
+            },
+            subSteps: () => {
                 const supplied = update?.subs;
                 const logger = supplied === undefined ? this.logger : supplied;
                 if (logger !== undefined)
                     (0, sub_flow_js_1.readSubFlowLogger)(logger, this);
                 return logger;
-            } };
+            },
+        };
     }
+    /**
+     * Publish one progress report.
+     *
+     * Payload content is only included when content logging is enabled; failures become a
+     * fixed `INVALID_NODE_REPORT` marker so a malformed report is visible without breaking
+     * the node.
+     *
+     * @param update - Report supplied by the node.
+     */
     report(update) {
         if (!this.active || this.signal?.aborted)
             return;
@@ -45,9 +101,22 @@ class NodeReports {
             this.diagnostics?.emit('node.progress', () => ({ reportError: 'INVALID_NODE_REPORT' }));
         }
     }
+    /**
+     * Create (once) the logger that records sub-steps for this visit.
+     *
+     * Sub-steps are only collected when progress or the terminal event carries content, so
+     * a metadata-only observer pays no logging cost.
+     *
+     * @returns The visit's logger, identical on repeated calls.
+     * @throws TypeError When the visit is already closed or the execution was aborted.
+     */
     createSubFlowLogger() {
         (0, rules_js_1.breakWhile)(!this.active || this.signal?.aborted, () => new TypeError('Cannot create a logger for a closed execution'));
-        return this.logger ??= (0, sub_flow_js_1.createSubFlowLogger)(this, () => this.active && !this.signal?.aborted, () => this.diagnostics?.enabled('node.progress', 'content') === true || this.diagnostics?.enabled(this.terminalEvent, 'content') === true, (logger, progress) => this.diagnostics?.emit('node.progress', () => ({ subStep: progress }), { usedModel: this.usedModel, subSteps: () => logger }), this.diagnostics?.identity);
+        return (this.logger ??= (0, sub_flow_js_1.createSubFlowLogger)(this, () => this.active && !this.signal?.aborted, () => this.diagnostics?.enabled('node.progress', 'content') === true ||
+            this.diagnostics?.enabled(this.terminalEvent, 'content') === true, (logger, progress) => this.diagnostics?.emit('node.progress', () => ({ subStep: progress }), {
+            usedModel: this.usedModel,
+            subSteps: () => logger,
+        }), this.diagnostics?.identity));
     }
 }
 exports.NodeReports = NodeReports;

package/dist/cjs/execution/state.js

@@ -3,27 +3,67 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.route = void 0;
 exports.requireWorkflowValue = requireWorkflowValue;
 const errors_js_1 = require("../structs/errors.js");
+/**
+ * Read a state field that must already be present.
+ *
+ * Used by `requires` declarations and terminal deliveries, so a node cannot observe a
+ * field as undefined and silently produce a wrong result.
+ *
+ * @param state - Current workflow state.
+ * @param key - Field to read.
+ * @returns The field value, narrowed to exclude undefined.
+ * @throws WorkflowContractError When the field is undefined.
+ */
 function requireWorkflowValue(state, key) {
     const value = state[key];
     if (value === undefined)
         throw new errors_js_1.WorkflowContractError(`Missing workflow state: ${String(key)}`);
     return value;
 }
+/**
+ * Build a reader for one state path.
+ *
+ * Dotted string paths traverse nested objects and stop safely at undefined; any other key
+ * is read directly from the state. Both forms share the returned reader so route
+ * conditions stay uniform.
+ *
+ * @param path - Dotted path or direct key.
+ * @returns A function reading the value from a state object.
+ */
 function readPath(path) {
     const keys = typeof path === 'string' ? path.split('.') : [path];
     return (state) => keys.reduce((value, key) => value?.[key], state);
 }
-/** Unconditional jump with a stable, target-derived route ID. */
+/**
+ * Unconditional jump with a stable, target-derived route ID.
+ *
+ * @param target - Destination node id.
+ * @param id - Optional explicit route id.
+ * @returns A terminal-free route that always matches.
+ */
 const routeTo = function route(target, id) {
     return { id: id ?? `to-${target}`, targetNodeId: target };
 };
-/** One conditional jump, using the same strict equality as a handwritten route. */
+/**
+ * One conditional jump, using the same strict equality as a handwritten route.
+ *
+ * A derived route id is only produced for symbol-free paths and primitive values,
+ * because those are the cases where `String(value)` is stable and unique enough to name
+ * the condition.
+ *
+ * @param target - Destination node id.
+ * @param path - State path to compare.
+ * @param value - Expected value, compared with `===`.
+ * @param options - Optional id, condition id and description.
+ * @returns A route that matches when the path equals `value`.
+ */
 function toIfEqual(target, path, value, options) {
     const stableValue = value === null || ['undefined', 'string', 'boolean', 'number', 'bigint'].includes(typeof value);
     const condition = typeof path !== 'symbol' && stableValue
         ? JSON.stringify([String(path), typeof value, String(value)])
         : undefined;
-    const id = options?.id ?? (condition === undefined ? undefined : `route:${JSON.stringify([condition, target])}`);
+    const id = options?.id ??
+        (condition === undefined ? undefined : `route:${JSON.stringify([condition, target])}`);
     const conditionId = options?.conditionId ?? (id === undefined ? undefined : '{nid}.{rid}');
     const read = readPath(path);
     return {
@@ -34,52 +74,138 @@ function toIfEqual(target, path, value, options) {
         targetNodeId: target,
     };
 }
-/** Jump when two state paths resolve to strictly equal values. */
+/**
+ * Jump when two state paths resolve to strictly equal values.
+ *
+ * No derived route id is produced for symbol paths, because a symbol cannot be embedded
+ * in a stable name.
+ *
+ * @param target - Destination node id.
+ * @param leftPath - First state path.
+ * @param rightPath - Second state path.
+ * @param options - Optional id, condition id and description.
+ * @returns A route that matches when both paths are strictly equal.
+ */
 function toIfEqualWith(target, leftPath, rightPath, options) {
     const left = readPath(leftPath);
     const right = readPath(rightPath);
-    const id = options?.id ?? (typeof leftPath === 'symbol' || typeof rightPath === 'symbol' ? undefined
-        : `route:with:${JSON.stringify([String(leftPath), String(rightPath), target])}`);
+    const id = options?.id ??
+        (typeof leftPath === 'symbol' || typeof rightPath === 'symbol'
+            ? undefined
+            : `route:with:${JSON.stringify([String(leftPath), String(rightPath), target])}`);
     return {
-        ...options, id,
+        ...options,
+        id,
         conditionId: options?.conditionId ?? (id === undefined ? undefined : '{nid}.{rid}'),
         when: (state) => left(state) === right(state),
         targetNodeId: target,
     };
 }
-/** Jump when a state array contains at least one entry. */
+/**
+ * Jump when a state array contains at least one entry.
+ *
+ * A non-array value never matches, so a mistyped field cannot be treated as populated.
+ *
+ * @param target - Destination node id.
+ * @param key - State path expected to hold an array.
+ * @param options - Optional id, condition id and description.
+ * @returns A route that matches for a non-empty array.
+ */
 function toIfNotEmpty(target, key, options) {
     const read = readPath(key);
-    return { ...options, ...routeTo(target, options?.id), conditionId: options?.conditionId ?? '{nid}.{rid}', when: (state) => {
+    return {
+        ...options,
+        ...routeTo(target, options?.id),
+        conditionId: options?.conditionId ?? '{nid}.{rid}',
+        when: (state) => {
             const value = read(state);
             return Array.isArray(value) && value.length > 0;
-        } };
+        },
+    };
 }
-/** Jump once a state field has a value. */
+/**
+ * Jump once a state field has a value.
+ *
+ * `null` counts as present: only `undefined` means the field is still unset.
+ *
+ * @param target - Destination node id.
+ * @param field - State path to inspect.
+ * @param options - Optional id, condition id and description.
+ * @returns A route that matches when the field is not undefined.
+ */
 function toIfDefined(target, field, options) {
     const read = readPath(field);
-    return { ...options, ...routeTo(target, options?.id), conditionId: options?.conditionId ?? '{nid}.{rid}', when: (state) => read(state) !== undefined };
+    return {
+        ...options,
+        ...routeTo(target, options?.id),
+        conditionId: options?.conditionId ?? '{nid}.{rid}',
+        when: (state) => read(state) !== undefined,
+    };
 }
-/** Jump to the node named by a truthy state field. */
+/**
+ * Jump to the node named by a truthy state field.
+ *
+ * The same field is used as the condition and as the destination, which is the usual
+ * shape of a dispatcher that stored its own next node.
+ *
+ * @param target - Field holding the destination node id.
+ * @param options - Optional id, condition id and description.
+ * @returns A route that matches when the field is truthy.
+ */
 function toIf(target, options) {
-    return { ...toIfDefined(target, target, options), when: (state) => Boolean(state[target]) };
+    return {
+        ...toIfDefined(target, target, options),
+        when: (state) => Boolean(state[target]),
+    };
 }
 function toIfError(target, { errorKey = 'error', ...options } = {}) {
     return toIfDefined(target, errorKey, options);
 }
-/** At a terminal node, the result must already exist. */
+/**
+ * At a terminal node, the result must already exist.
+ *
+ * Completing reads the field with `requireWorkflowValue`, so a node that forgot to
+ * produce its result fails instead of returning undefined.
+ *
+ * @param field - State field holding the final result.
+ * @param options - Optional id and description; a condition id is meaningless here.
+ * @returns A completion route with the default id `complete`.
+ */
 function deliver(field, options) {
     const id = options?.id ?? 'complete';
     return {
-        ...options, id,
+        ...options,
+        id,
         complete: (state) => requireWorkflowValue(state, field),
     };
 }
-/** Deliver an available result, or let the next route decide. */
+/**
+ * Deliver an available result, or let the next route decide.
+ *
+ * Unlike `deliver`, this route carries a condition so a following route still has a
+ * chance to match when the field is still unset.
+ *
+ * @param field - State field holding the result.
+ * @param options - Optional route metadata.
+ * @returns A conditional completion route.
+ */
 function deliverIfReady(field, options) {
-    return { ...deliver(field, options), conditionId: options?.conditionId ?? '{nid}.{rid}', when: (state) => state[field] !== undefined };
+    return {
+        ...deliver(field, options),
+        conditionId: options?.conditionId ?? '{nid}.{rid}',
+        when: (state) => state[field] !== undefined,
+    };
 }
-/** Apply the shared continue/complete outcome contract. */
+/**
+ * Apply the shared continue/complete outcome contract.
+ *
+ * The field holds a `StepOutcome`; only the `complete` variant ends the workflow, and the
+ * completion asserts the variant instead of trusting the condition.
+ *
+ * @param field - State field holding the outcome.
+ * @param options - Optional route metadata.
+ * @returns A conditional completion route that unwraps the outcome value.
+ */
 function deliverWhenComplete(field, options) {
     return {
         ...options,
@@ -94,8 +220,21 @@ function deliverWhenComplete(field, options) {
         },
     };
 }
-/** Callable route catalog; aliases share the same function without namespace initialization. */
+/**
+ * Callable route catalog; aliases share the same function without namespace initialization.
+ *
+ * `route(...)` and `route.to(...)` are the same function, so both call styles stay
+ * interchangeable and no module-level setup is required to use either.
+ */
 exports.route = Object.assign(routeTo, {
-    to: routeTo, toIfEqual, toIfEqualWith, toIfNotEmpty, toIfDefined, toIf, toIfError,
-    deliver, deliverIfReady, deliverWhenComplete,
+    to: routeTo,
+    toIfEqual,
+    toIfEqualWith,
+    toIfNotEmpty,
+    toIfDefined,
+    toIf,
+    toIfError,
+    deliver,
+    deliverIfReady,
+    deliverWhenComplete,
 });