@jangts/agent-core 0.1.0 → 0.2.0

package/dist/esm/execution/events.d.ts

@@ -1,5 +1,19 @@
 import type { DiagnosticContext, CreateDiagnosticsOptions } from '../structs/diagnostics.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.
+ */
 export declare function createEventScope(options?: CreateDiagnosticsOptions): DiagnosticContext;
-/** 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.
+ */
 export declare function executionEvents(options?: import('../structs/common.js').ExecutionOptions): DiagnosticContext | undefined;

package/dist/esm/execution/events.js

@@ -1,21 +1,44 @@
+/**
+ * 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`.
+ */
 import { captureSubSteps } from '../utils/debug.js';
 import { invocationId } from '../utils/invocation.js';
 import { getErrorInfo } from '../errors.js';
 import { coreEventCatalog } from '../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.
+ */
 export function createEventScope(options = {}) {
     const { output } = options;
     const write = output?.write.bind(output);
     const accepts = output?.accepts?.bind(output);
     const runId = options.runId || 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;
@@ -26,9 +49,12 @@ export 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;
@@ -36,8 +62,24 @@ export function createEventScope(options = {}) {
         };
         const fact = (event, payload, debug) => {
             const value = payload();
-            const reported = scope.enabled(event, 'content') ? captureSubSteps(debug?.subSteps, identity) : 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 : invocationId(), type: event, producerSequence: ++sequence, occurredAtMs: Date.now(), payload: value };
+            const reported = scope.enabled(event, 'content')
+                ? captureSubSteps(debug?.subSteps, identity)
+                : 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
+                        : invocationId(),
+                type: event,
+                producerSequence: ++sequence,
+                occurredAtMs: Date.now(),
+                payload: value,
+            };
         };
         const publish = (record) => {
             const event = record.type, kind = coreEventCatalog[event];
@@ -65,50 +107,117 @@ export function createEventScope(options = {}) {
         };
         const scope = {
             identity,
+            /** Whether any consumer would accept this event, optionally requiring content. */
             enabled(event, content) {
                 if (!Object.hasOwn(coreEventCatalog, event))
                     return false;
                 const kind = content === 'content' ? 'content' : 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: getErrorInfo(error).code } }),
+    'runtime.rejected': ({ stageId, error }) => ({
+        stageId,
+        error: { code: getErrorInfo(error).code },
+    }),
     'rule.result': ({ tags, error }) => ({ tags, error: { code: 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, ...captureSubSteps(undefined), payload: metadataPayload(record.type, record.payload) });
+    const metadata = () => ({
+        ...record,
+        ...captureSubSteps(undefined),
+        payload: metadataPayload(record.type, record.payload),
+    });
     try {
         return structuredClone(content ? record : metadata());
     }
@@ -116,7 +225,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.
+ */
 export function executionEvents(options) {
     const { diagnostics, observe } = options ?? {};
     return observe ? (diagnostics ?? createEventScope()).withObserver(observe) : diagnostics;

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

@@ -1,3 +1,10 @@
+/**
+ * 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.
+ */
 export * from './engine.js';
 export * from './workflow.js';
 export { BudgetError, ValidationError } from '../structs/errors.js';

package/dist/esm/execution/index.js

@@ -1,3 +1,10 @@
+/**
+ * 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.
+ */
 export * from './engine.js';
 export * from './workflow.js';
 export { BudgetError, ValidationError } from '../structs/errors.js';

package/dist/esm/execution/reporting.d.ts

@@ -1,7 +1,13 @@
 import type { DebugStepsOutput, NodeReportingContext, SubFlowLogger } from '../structs/debug.js';
 import type { DiagnosticContext, CoreEventName } from '../structs/diagnostics.js';
 import type { WorkflowNodeReport } from '../structs/execution/workflow.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.
+ */
 export declare class NodeReports implements NodeReportingContext {
     private readonly diagnostics?;
     private readonly signal?;
@@ -9,10 +15,52 @@ export declare class NodeReports implements NodeReportingContext {
     private active;
     private logger?;
     private 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?: DiagnosticContext | undefined, signal?: AbortSignal | undefined, terminalEvent?: CoreEventName);
+    /** End the visit; later reports and logger creation are ignored or rejected. */
     close(): void;
+    /**
+     * 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: WorkflowNodeReport): void;
+    /**
+     * 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?: WorkflowNodeReport): DebugStepsOutput;
+    /**
+     * 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: WorkflowNodeReport): void;
+    /**
+     * 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(): SubFlowLogger;
 }

package/dist/esm/execution/reporting.js

@@ -1,6 +1,21 @@
+/**
+ * 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`.
+ */
 import { breakWhile } from '../utils/rules.js';
 import { createSubFlowLogger, readSubFlowLogger } from '../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.
+ */
 export class NodeReports {
     diagnostics;
     signal;
@@ -8,29 +23,70 @@ export 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) {
         breakWhile(!update || typeof update !== 'object', () => new TypeError('Invalid node report'));
         const usedModel = update.usedModel;
-        breakWhile(usedModel !== undefined && (typeof usedModel !== 'boolean' || (this.usedModel === true && !usedModel)), () => new TypeError('Invalid reported model use'));
+        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)
                     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;
@@ -42,8 +98,21 @@ export 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() {
         breakWhile(!this.active || this.signal?.aborted, () => new TypeError('Cannot create a logger for a closed execution'));
-        return this.logger ??= 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 ??= 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));
     }
 }

package/dist/esm/execution/state.d.ts

@@ -1,12 +1,49 @@
+/**
+ * Workflow state access and the declarative route catalog.
+ *
+ * Handlers read and write a plain state object; the helpers here keep missing-value
+ * failures explicit and let a workflow declare its routes as data. Every route produced
+ * here is inert until `AgentWorkflow` validates and freezes it.
+ *
+ * Exports: `requireWorkflowValue` and the `route` namespace.
+ */
 import type { StepOutcome } from '../structs/execution/engine.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.
+ */
 export declare function requireWorkflowValue<State, Key extends keyof State>(state: State, key: Key): Exclude<State[Key], undefined>;
+/** Optional route metadata shared by the route helpers. */
 type RouteOptions = {
+    /** Explicit route id; otherwise derived from the target so it stays stable. */
     readonly id?: string;
+    /** Condition identity template; `{nid}` and `{rid}` are replaced when the node registers. */
     readonly conditionId?: string;
+    /** Human-readable description surfaced by `describe()`. */
     readonly description?: string;
 };
+/** Root key of a dotted path such as `session.user`; a symbol path is its own root. */
 type PathRoot<Path extends PropertyKey> = Path extends `${infer Root}.${string}` ? Root : Path;
-/** 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`.
+ */
 declare function toIfEqual<Key extends PropertyKey, Value>(target: string, path: Key, value: Value, options?: RouteOptions): {
     id: string | undefined;
     conditionId: string | undefined;
@@ -14,7 +51,18 @@ declare function toIfEqual<Key extends PropertyKey, Value>(target: string, path:
     targetNodeId: string;
     description?: string;
 };
-/** 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.
+ */
 declare function toIfEqualWith<Left extends PropertyKey, Right extends PropertyKey>(target: string, leftPath: Left, rightPath: Right, options?: RouteOptions): {
     id: string | undefined;
     conditionId: string | undefined;
@@ -22,7 +70,16 @@ declare function toIfEqualWith<Left extends PropertyKey, Right extends PropertyK
     targetNodeId: string;
     description?: string;
 };
-/** 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.
+ */
 declare function toIfNotEmpty<Key extends PropertyKey>(target: string, key: Key, options?: RouteOptions): {
     conditionId: string;
     when: (state: Partial<Record<PathRoot<Key>, unknown>>) => boolean;
@@ -30,7 +87,16 @@ declare function toIfNotEmpty<Key extends PropertyKey>(target: string, key: Key,
     targetNodeId: string;
     description?: string;
 };
-/** 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.
+ */
 declare function toIfDefined<Key extends PropertyKey>(target: string, field: Key, options?: RouteOptions): {
     conditionId: string;
     when: (state: Partial<Record<PathRoot<Key>, unknown>>) => boolean;
@@ -38,7 +104,16 @@ declare function toIfDefined<Key extends PropertyKey>(target: string, field: Key
     targetNodeId: string;
     description?: string;
 };
-/** 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.
+ */
 declare function toIf<Key extends string>(target: Key, options?: RouteOptions): {
     when: (state: Partial<Record<Key, unknown>>) => boolean;
     conditionId: string;
@@ -46,20 +121,47 @@ declare function toIf<Key extends string>(target: Key, options?: RouteOptions):
     targetNodeId: string;
     description?: string;
 };
-/** Route a recorded state error to its recovery node. */
+/**
+ * Route a recorded state error to its recovery node.
+ *
+ * Defaults to the `error` field because that is the convention the engine relies on when
+ * reporting recoverable failures.
+ *
+ * @param target - Recovery node id.
+ * @param options - Optional route metadata plus the field holding the recorded error.
+ * @returns A route that matches once the error field is set.
+ */
 declare function toIfError<Key extends PropertyKey>(target: string, options: RouteOptions & {
     readonly errorKey: Key;
 }): ReturnType<typeof toIfDefined<Key>>;
 declare function toIfError(target: string, options?: RouteOptions & {
     readonly errorKey?: undefined;
 }): ReturnType<typeof toIfDefined<'error'>>;
-/** 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`.
+ */
 declare function deliver<Key extends PropertyKey>(field: Key, options?: Omit<RouteOptions, 'conditionId'>): {
     id: string;
     complete: <State extends Partial<Record<Key, unknown>>>(state: State) => Exclude<State[Key], undefined>;
     description?: string;
 };
-/** 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.
+ */
 declare function deliverIfReady<Key extends PropertyKey>(field: Key, options?: RouteOptions): {
     conditionId: string;
     when: (state: Partial<Record<Key, unknown>>) => boolean;
@@ -67,7 +169,16 @@ declare function deliverIfReady<Key extends PropertyKey>(field: Key, options?: R
     complete: <State extends Partial<Record<Key, unknown>>>(state: State) => Exclude<State[Key], undefined>;
     description?: string;
 };
-/** 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.
+ */
 declare function deliverWhenComplete<Key extends PropertyKey>(field: Key, options?: RouteOptions): {
     id: string;
     conditionId: string;
@@ -75,7 +186,12 @@ declare function deliverWhenComplete<Key extends PropertyKey>(field: Key, option
     complete<Value>(state: Partial<Record<Key, StepOutcome<Value>>>): Value;
     description?: string;
 };
-/** 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.
+ */
 export declare const route: ((target: string, id?: string) => {
     id: string;
     targetNodeId: string;