@jangts/agent-core 0.1.1 → 0.2.1

package/dist/esm/structs/capabilities/tools.d.ts

@@ -1,34 +1,62 @@
+/**
+ * Tool definition, execution and registry contracts.
+ *
+ * A tool declares its model-visible schema, a host authorization step and one execution unit. The
+ * registry binds an App context, validates input/output at the boundary and produces receipts, so
+ * individual tools never handle transportation, budget accounting or event emission.
+ *
+ * Exports: `ToolDefinition`, `ToolExecutionContext`, `ExecutableTool`, `RegisteredTool`,
+ * `ToolExecutionEvent`, `ToolRegistryPorts`, `ToolInvocationRequest`, `ToolRegistryOptions`.
+ */
 import type { InvocationMetadata } from '../invocation.js';
 import type { ExecutionContext, MaybePromise, OperationContext, SchemaAdapter } from '../common.js';
 import type { DiagnosticContext } from '../diagnostics.js';
 import type { RegistrationProjection } from '../../utils/registration.js';
 import type { NodeReportingContext } from '../debug.js';
+/** One registered tool, typed by its input, output, host context and id literal. */
 export interface ToolDefinition<Input = unknown, Output = unknown, App = unknown, Id extends string = string> {
+    /** Stable id; also the name the model calls. */
     readonly id: Id;
+    /** Declared grouping used by registries and documentation; not an authorization boundary. */
     readonly kind: string;
+    /** Model-visible explanation of when to call the tool. */
     readonly description: string;
+    /** Schema applied to raw model arguments before `authorize` and `execute`. */
     readonly inputSchema: SchemaAdapter<Input>;
+    /** Host permission check. Runs before execution and may be asynchronous. */
     authorize(input: Input, context: OperationContext<App>): MaybePromise<void>;
+    /** Executes the already-authorized input; must not repeat authorization decisions. */
     execute(input: Input, context: OperationContext<App> & import('../debug.js').NodeReportingContext): MaybePromise<Output>;
+    /** Optional reporting hook that turns the result into self-reported sub-steps. */
     debugSteps?(result: Output, context: import('../debug.js').NodeReportingContext): import('../debug.js').SubFlowLogger;
+    /** Validates untrusted output (for example a cached replay) before it is returned. */
     parseOutput(value: unknown): Output;
 }
+/** Execution facts handed to a tool for one invocation. */
 export interface ToolExecutionContext extends ExecutionContext, NodeReportingContext {
+    /** Diagnostic scope of the invocation, when recording is enabled. */
     readonly diagnostics?: DiagnosticContext;
+    /** Declared execution discipline; mirrors whether the registry accepted an async tool. */
     readonly mode: 'sync' | 'async';
+    /** Opaque invocation id shared by receipt, events and diagnostics. */
     readonly invocationId: string;
+    /** Non-optional cancellation for this invocation. */
     readonly signal: AbortSignal;
 }
+/** Type-erased tool shape the registry executes after parsing at the boundary. */
 export interface ExecutableTool {
     readonly id: string;
     readonly kind: string;
+    /** Optional here because the erased view does not require model-facing prose. */
     readonly description?: string;
     readonly debugSteps?: (result: unknown, context: NodeReportingContext) => import('../debug.js').SubFlowLogger;
     parseInput(value: unknown): unknown;
     parseOutput(value: unknown): unknown;
     execute(input: unknown, context: ToolExecutionContext): unknown;
 }
+/** Registered snapshot: public data is retained, implementation helpers are not a contract. */
 export type RegisteredTool<Tool extends ExecutableTool = ExecutableTool> = RegistrationProjection<Tool, ExecutableTool>;
+/** Fact emitted when one tool call settles, correlated by `invocationId`. */
 export interface ToolExecutionEvent<Kind extends string = string> extends InvocationMetadata {
     toolId: string;
     /** Opaque identity shared by result and diagnostic records; not an App message ID. */
@@ -36,22 +64,32 @@ export interface ToolExecutionEvent<Kind extends string = string> extends Invoca
     kind: Kind;
     durationMs: number;
     status: import('../common.js').InvocationStatus;
+    /** Error classification when the call failed. */
     errorCode?: string;
 }
+/** Host ports a tool registry needs in addition to the tool definitions. */
 export interface ToolRegistryPorts {
     /** Request lifetime; late external results cannot become successful receipts. */
     signal?: AbortSignal;
     diagnostics?: DiagnosticContext;
+    /** Builds the error for a tool id that is not available in this request. */
     unavailable?(name: string): Error;
+    /** Maps an arbitrary thrown value to a stable error code for events. */
     errorCode?(error: unknown): string;
 }
+/** One invocation request; the registry supplies signal and diagnostics when omitted. */
 export interface ToolInvocationRequest<Id extends string = string> {
     readonly toolId: Id;
+    /** Raw model arguments; parsed by the tool's input schema before authorization. */
     readonly input: unknown;
+    /** Per-call cancellation; can only shorten the surrounding execution lifetime. */
     readonly signal?: AbortSignal;
     readonly diagnostics?: DiagnosticContext;
 }
+/** Registry construction options. */
 export interface ToolRegistryOptions {
+    /** Execution defaults applied to invocations that do not pass their own. */
     readonly execution?: import('../common.js').ExecutionOptions;
+    /** Error factories shared by every tool in the registry. */
     readonly errors?: Pick<ToolRegistryPorts, 'unavailable' | 'errorCode'>;
 }

package/dist/esm/structs/common.d.ts

@@ -1,58 +1,118 @@
-/** Shared API vocabulary. Application identities are deliberately absent. */
+/**
+ * Package-wide vocabulary shared by every agent-core contract.
+ *
+ * These aliases and envelopes are the neutral layer between App-owned business types and the
+ * Core runtime modules: identifiers stay opaque, application identities are deliberately absent,
+ * and every catalog or result shape is read-only so a registered snapshot cannot be mutated later.
+ *
+ * Exports: `Id`, `TimestampMs`, `DurationMs`, `Observer`, `AsyncSink`, `InvocationStatus`,
+ * `JsonSchema`, `MaybePromise`, `SchemaAdapter`, `Issue`, `CheckResult`, `ReadonlyCatalog`,
+ * `Registry`, `ExecutionOptions`, `ExecutionContext`, `OperationContext`, `SearchHit`.
+ */
+/** Opaque identifier. Format and meaning belong to the App or to the registering module. */
 export type Id = string;
+/** Wall-clock instant in milliseconds since the Unix epoch. */
 export type TimestampMs = number;
+/** Elapsed time in milliseconds; never an absolute instant. */
 export type DurationMs = number;
+/** Notification callback. A rejected promise propagates to the emitter. */
 export type Observer<Event> = (event: Readonly<Event>) => void | Promise<void>;
+/** Awaitable sink for an ordered stream. A rejection propagates to the emitter. */
 export type AsyncSink<Event> = (event: Readonly<Event>) => Promise<void>;
+/** Terminal state of one invocation; `cancelled` is distinct from a failure. */
 export type InvocationStatus = 'success' | 'error' | 'cancelled';
+/** JSON Schema as consumed by the App's validator; Core never interprets its contents. */
 export type JsonSchema = Readonly<Record<string, unknown>>;
+/** A value that may already be resolved or still pending. */
 export type MaybePromise<Value> = Value | Promise<Value>;
+/** Compiled schema pair: the JSON form shown to the model and the runtime parser. */
 export interface SchemaAdapter<Value = unknown> {
+    /** Schema advertised to the model and used for documentation. */
     readonly jsonSchema: JsonSchema;
+    /** Validates or coerces untrusted input into `Value`; throws when the input is invalid. */
     parse(input: unknown): Value;
 }
+/** One validation problem, locatable by code and, when available, by field path. */
 export interface Issue {
+    /** Stable machine-readable reason code; the primary key for programmatic handling. */
     readonly code: string;
+    /** Human-readable description; not guaranteed stable for matching. */
     readonly message: string;
+    /** Path of the offending field inside the checked value, outermost segment first. */
     readonly path?: readonly (string | number)[];
+    /** Registered check that produced the issue, when the check belongs to a catalog. */
     readonly checkId?: string;
 }
+/**
+ * Verdict of one registered check.
+ *
+ * `unavailable` and `not-run` are not verdicts on the value: they state that the check could not
+ * produce an answer, so callers must not treat them as failures.
+ */
 export interface CheckResult<Value = never> {
     readonly status: 'passed' | 'failed' | 'unavailable' | 'not-run';
+    /** Problems found; expected to be empty when the status is `passed`. */
     readonly issues: readonly Issue[];
+    /** Checked or produced value; present only when the check yields one. */
     readonly value?: Value;
 }
+/** Read-only projection of a definition set; the implementation owns ordering and validation. */
 export interface ReadonlyCatalog<Definition extends {
     readonly id: string;
 }> {
+    /** Definitions in registration order; each entry is frozen by the implementation. */
     readonly definitions: readonly Readonly<Definition>[];
+    /** Ids in the same order as `definitions`. */
     ids(): readonly string[];
     values(): IterableIterator<Readonly<Definition>>;
     entries(): IterableIterator<readonly [string, Readonly<Definition>]>;
     has(id: string): boolean;
+    /** Returns the definition or `undefined`; the caller decides whether absence is an error. */
     get(id: string): Readonly<Definition> | undefined;
+    /** Returns the definition or throws; use when the id is a required reference. */
     require(id: string): Readonly<Definition>;
 }
+/** Mutable catalog. Registrations append; `seal` freezes the set against later writes. */
 export interface Registry<Definition extends {
     readonly id: string;
 }> extends ReadonlyCatalog<Definition> {
+    /** Adds one definition; implementations reject blank or duplicate ids. */
     register(definition: Definition): this;
     registerAll(definitions: Iterable<Definition>): this;
+    /** Rejects every later registration on this instance. */
     seal(): this;
 }
+/** Optional controls accepted by any public Core call. */
 export interface ExecutionOptions {
+    /** Cancellation for the whole call; children must not extend it. */
     readonly signal?: AbortSignal;
+    /** Diagnostic scope that records the call; omission disables recording. */
     readonly diagnostics?: import('./diagnostics.js').DiagnosticContext;
+    /** Live observation of the same facts that diagnostics would record. */
     readonly observe?: import('./execution/events.js').ExecutionObserver;
 }
+/** Required execution facts available inside a running call. */
 export interface ExecutionContext {
+    /** Non-optional cancellation signal; never `undefined` once execution has started. */
     readonly signal: AbortSignal;
+    /** Diagnostic scope of the enclosing call, when recording is enabled. */
     readonly diagnostics?: import('./diagnostics.js').DiagnosticContext;
 }
+/**
+ * Execution context plus the App-owned host object.
+ *
+ * `app` carries services, identity and per-request dependencies supplied by the host; Core treats
+ * it as opaque and must not depend on application-specific fields.
+ */
 export interface OperationContext<App = unknown> extends ExecutionContext {
     readonly app: Readonly<App>;
 }
-/** Retrieval score semantics remain algorithm-specific; document may be a stored-field projection. */
+/**
+ * One search result.
+ *
+ * `score` semantics stay algorithm-specific (direction and scale are not part of this contract),
+ * and `document` may be a projection that only exposes stored fields rather than the full record.
+ */
 export interface SearchHit<Document> {
     readonly id: string;
     readonly score: number;

package/dist/esm/structs/common.js

@@ -1 +1,12 @@
+/**
+ * Package-wide vocabulary shared by every agent-core contract.
+ *
+ * These aliases and envelopes are the neutral layer between App-owned business types and the
+ * Core runtime modules: identifiers stay opaque, application identities are deliberately absent,
+ * and every catalog or result shape is read-only so a registered snapshot cannot be mutated later.
+ *
+ * Exports: `Id`, `TimestampMs`, `DurationMs`, `Observer`, `AsyncSink`, `InvocationStatus`,
+ * `JsonSchema`, `MaybePromise`, `SchemaAdapter`, `Issue`, `CheckResult`, `ReadonlyCatalog`,
+ * `Registry`, `ExecutionOptions`, `ExecutionContext`, `OperationContext`, `SearchHit`.
+ */
 export {};

package/dist/esm/structs/context/fragments.d.ts

@@ -1,26 +1,54 @@
+/**
+ * Context fragment contract: the unit of model-visible input assembled by Core.
+ *
+ * Fragments carry both content and provenance. Trust and lifetime are declarations by the
+ * producing module, while `maxChars` is enforced when the fragment is formatted and counted into
+ * the shared input budget. A system-role fragment may only carry trusted string content.
+ *
+ * Exports: `ContextTrust`, `ContextLifetime`, `ContextFragment`, `ContextFragmentUsage`,
+ * `BuiltContext`.
+ */
 import type { ModelMessage } from '../model/messages.js';
+/** Who produced the content, and therefore how much it may influence the model. */
 export type ContextTrust = 'instruction' | 'server' | 'user' | 'tool';
+/** Declared validity window of a fragment's content. */
 export type ContextLifetime = 'configuration' | 'turn' | 'step';
+/** One piece of model-visible input before assembly. */
 export interface ContextFragment {
+    /** Unique, stable id matching `^[a-z][a-zA-Z0-9:._-]*$`; duplicates are rejected. */
     id: string;
+    /** Owning source (module or registration) used to explain where the content came from. */
     sourceId: string;
+    /** Producer trust level. `user` and `tool` content cannot become a system message. */
     trust: ContextTrust;
+    /** Declared validity window of this content. */
     lifetime: ContextLifetime;
+    /** Hard upper bound in JSON characters; must be a positive safe integer. */
     maxChars: number;
+    /** Message slot the fragment occupies when assembled. */
     role: 'system' | 'user';
+    /** Rendered content. A system message accepts a string only, never a record. */
     value: string | Record<string, unknown>;
 }
+/** Accounting entry reported for one fragment that actually entered the context. */
 export interface ContextFragmentUsage {
     id: string;
     sourceId: string;
     trust: ContextTrust;
     lifetime: ContextLifetime;
+    /** Characters consumed after formatting. */
     chars: number;
+    /** Budget that applied to this fragment. */
     maxChars: number;
 }
+/** Assembled context plus the accounting needed to explain the budget decision. */
 export interface BuiltContext {
+    /** Messages in final model order. */
     messages: ModelMessage[];
+    /** Per-fragment accounting in the same order as the fragments were merged. */
     fragmentUsage: ContextFragmentUsage[];
+    /** Total counted characters across messages and usage. */
     inputChars: number;
+    /** Budget the assembly was validated against; `Infinity` means unbounded. */
     maxInputChars: number;
 }

package/dist/esm/structs/context/journal.d.ts

@@ -1,18 +1,43 @@
+/**
+ * Request journal contract: the ordered record of what one request actually did.
+ *
+ * A journal is request-local. It records model and tool facts with a monotonic sequence so an App
+ * can rebuild context or receipts without reading Core diagnostics; the record payloads are opaque
+ * to Core.
+ *
+ * Exports: `ContextRecord`.
+ */
 import type { InvocationMetadata } from '../invocation.js';
+/** Identity every journal record carries, in addition to its type-specific fields. */
 type RecordIdentity = InvocationMetadata & {
+    /** Invocation that produced the record. */
     readonly invocationId: string;
+    /** Monotonic order within this journal; starts at 1 and never repeats. */
     readonly producerSequence: number;
+    /** Instant the record was written, in epoch milliseconds. */
     readonly occurredAtMs: number;
 };
-export type ContextRecord = RecordIdentity & ({
+/**
+ * One journal entry: a model call, a tool request or a tool result.
+ *
+ * The three variants are distinguished by `type`; `value`/`input` stay `unknown` because their
+ * domain meaning belongs to the App.
+ */
+export type ContextRecord = RecordIdentity & 
+/** A model call was made for `stageId`; `value` is what the call produced. */
+({
     readonly type: 'model';
     readonly stageId: string;
     readonly value: unknown;
-} | {
+}
+/** A tool call was requested; `input` is the raw request payload. */
+ | {
     readonly type: 'tool';
     readonly toolId: string;
     readonly input: unknown;
-} | {
+}
+/** A tool call settled; `value` carries the result or the failure detail. */
+ | {
     readonly type: 'tool-result';
     readonly toolId: string;
     readonly status: 'success' | 'error' | 'cancelled';

package/dist/esm/structs/context/processing.d.ts

@@ -1,8 +1,19 @@
+/**
+ * Context plan contract: the unassembled input handed to the Core budget boundary.
+ *
+ * App-side nodes may still process a plan (mutate declared fragments, add protected messages)
+ * before Core assembles and validates it. The plan therefore separates sendable content from the
+ * trusted originals used to audit structural mutation.
+ *
+ * Exports: `ContextPlan`.
+ */
 import type { ContextFragment } from './fragments.js';
 import type { ModelMessage } from '../model/messages.js';
 /** Unassembled input; App-side nodes may process it before the Core budget boundary. */
 export interface ContextPlan {
+    /** Fragments in the order supplied by the App; assembly preserves it. */
     readonly fragments: readonly ContextFragment[];
+    /** Character budget Core validates after assembly. */
     maxInputChars: number;
     /** Protected user messages (for example image inputs); text counts toward the same budget. */
     additionalMessages?: readonly (ModelMessage & {

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

@@ -1,13 +1,33 @@
-/** Optional node-reported debug material, never proof of internal execution. */
+/**
+ * Self-reported execution detail supplied by App nodes and tools.
+ *
+ * The data here is optional evidence of what an App chose to report, never proof that Core
+ * performed the work, and it is collected only through the diagnostic context that owns the
+ * current node visit. The status catalog below is the single source of truth for legal reported
+ * statuses, their terminal flag and the transitions that `fix` may apply.
+ *
+ * Exports: `reportedStepStatusCatalog`, `reportedStepStatuses`, `ReportedStepStatus`,
+ * `ReportedStep`, `SubFlowValue`, `RecordedSubStep`, `SubFlowStepInput`, `SubFlowStepFix`,
+ * `SubFlowLogger`, `NodeReportingContext`, `SubStepProgress`, `DebugStepsOutput`.
+ */
+/**
+ * Legal self-reported step statuses and their transitions.
+ *
+ * `terminal: true` means the step is finished and its status can no longer change; `next` lists the
+ * statuses a later `fix` may assign to a non-terminal step.
+ */
 export declare const reportedStepStatusCatalog: {
+    /** No status reported yet; only `fix` uses this as an intermediate state. */
     readonly unknown: {
         readonly terminal: false;
         readonly next: readonly ["unknown", "planned", "running", "success", "error", "cancelled", "skipped"];
     };
+    /** Declared by the node but not started. */
     readonly planned: {
         readonly terminal: false;
         readonly next: readonly ["planned", "running", "success", "error", "cancelled", "skipped"];
     };
+    /** Started and still active; may only stay running or finish. */
     readonly running: {
         readonly terminal: false;
         readonly next: readonly ["running", "success", "error", "cancelled"];
@@ -29,38 +49,59 @@ export declare const reportedStepStatusCatalog: {
         readonly next: readonly [];
     };
 };
+/** Frozen list of reported statuses in catalog order, used for membership validation. */
 export declare const reportedStepStatuses: readonly (keyof typeof reportedStepStatusCatalog)[];
+/** A status a node may report; derived from the catalog, never declared separately. */
 export type ReportedStepStatus = keyof typeof reportedStepStatusCatalog;
+/** One step as reported by a node; fields beyond identity are optional detail. */
 export interface ReportedStep {
+    /** Step identity, unique within one node visit. */
     readonly stepId: string;
+    /** Reported parent step, forming a tree; absent for a top-level step. */
     readonly parentStepId?: string;
     /** Self-reported reference only; never a workflow dispatch identity. */
     readonly relatedDefinitionId?: string;
+    /** Short reported label. */
     readonly name: string;
+    /** Reported step kind (for example a tool or model call); free-form and node-owned. */
     readonly kind: string;
+    /** Reported lifecycle status; omission means the node did not report one. */
     readonly status?: ReportedStepStatus;
     /** This step's own reported model use, never a descendant rollup. */
     readonly usedModel?: boolean;
+    /** Reported start instant in epoch milliseconds. */
     readonly startedAtMs?: number;
+    /** Reported end instant in epoch milliseconds; only meaningful for terminal statuses. */
     readonly endedAtMs?: number;
+    /** Reported successor step ids, for display only. */
     readonly nextStepIds?: readonly string[];
+    /** Reported case or variant id, interpreted by the App. */
     readonly caseId?: string;
+    /** Reported one-line summary. */
     readonly summary?: string;
 }
+/** JSON-like value accepted in reported payloads; depth and size are bounded by the recorder. */
 export type SubFlowValue = null | boolean | number | string | readonly SubFlowValue[] | {
     readonly [key: string]: SubFlowValue;
 };
+/** A step already accepted by a logger, carrying recorder-assigned bookkeeping fields. */
 export interface RecordedSubStep extends ReportedStep {
+    /** Historical marker: only self-reported steps are recorded. */
     readonly origin: 'reported';
+    /** One-based write order within the node visit. */
     readonly sequence: number;
     /** Optional only for historical records produced before the logger contract. */
     readonly createdAtMs?: number;
+    /** Revision number, incremented by each accepted `fix`. */
     readonly revision?: number;
+    /** Reported payload; the recorder snapshots it and bounds the total size. */
     readonly payload?: Readonly<Record<string, SubFlowValue>>;
 }
+/** Input accepted by `write`; the logger assigns the step id and sequence. */
 export interface SubFlowStepInput extends Omit<ReportedStep, 'stepId'> {
     readonly payload?: Readonly<Record<string, SubFlowValue>>;
 }
+/** Fields a later `fix` may change on an already written step. */
 export interface SubFlowStepFix {
     readonly status?: ReportedStepStatus;
     readonly usedModel?: boolean;
@@ -74,27 +115,43 @@ export interface SubFlowStepFix {
 declare const subFlowLoggerBrand: unique symbol;
 /** Execution-owned instance. Obtain it from the active node/tool context. */
 export interface SubFlowLogger {
+    /** Brand makes structural lookalikes incompatible with the recorder's own instance. */
     readonly [subFlowLoggerBrand]: true;
+    /** Appends one step and returns its assigned step id. */
     write(input: SubFlowStepInput): string;
+    /** Applies a partial update; illegal status transitions and replacements are rejected. */
     fix(stepId: string, patch: SubFlowStepFix): void;
+    /** Snapshot of the steps recorded so far, in write order. */
     readAll(): readonly Readonly<RecordedSubStep>[];
 }
+/** Reporting surface handed to a node or tool for the duration of one visit. */
 export interface NodeReportingContext {
+    /** Reports progress for the active node; Core supplies the execution identity. */
     report(update: import('./execution/workflow.js').WorkflowNodeReport): void;
     /** One logger per node visit; repeated calls return the same instance. */
     createSubFlowLogger(): SubFlowLogger;
 }
+/** Compact progress notification emitted for each accepted sub-step write or fix. */
 export interface SubStepProgress {
     readonly operation: 'write' | 'fix';
+    /** Step the operation applied to. */
     readonly stepId: string;
+    /** Write sequence of that step within the node visit. */
     readonly sequence: number;
+    /** Revision after the operation; `write` starts at 1. */
     readonly revision: number;
+    /** Instant the progress fact was recorded, in epoch milliseconds. */
     readonly createdAtMs: number;
+    /** Status after the operation. */
     readonly status: ReportedStepStatus;
+    /** Reported model use after the operation, when the node stated it. */
     readonly usedModel?: boolean;
 }
+/** Debug material a handler contributes to a diagnostic event. */
 export interface DebugStepsOutput {
+    /** Model use reported by this handler; omitted when unknown. */
     readonly usedModel?: boolean;
+    /** Accessor invoked at emit time so recording can be skipped when disabled. */
     readonly subSteps?: () => SubFlowLogger | undefined;
 }
 export {};

package/dist/esm/structs/debug.js

@@ -1,9 +1,38 @@
-/** Optional node-reported debug material, never proof of internal execution. */
+/**
+ * Self-reported execution detail supplied by App nodes and tools.
+ *
+ * The data here is optional evidence of what an App chose to report, never proof that Core
+ * performed the work, and it is collected only through the diagnostic context that owns the
+ * current node visit. The status catalog below is the single source of truth for legal reported
+ * statuses, their terminal flag and the transitions that `fix` may apply.
+ *
+ * Exports: `reportedStepStatusCatalog`, `reportedStepStatuses`, `ReportedStepStatus`,
+ * `ReportedStep`, `SubFlowValue`, `RecordedSubStep`, `SubFlowStepInput`, `SubFlowStepFix`,
+ * `SubFlowLogger`, `NodeReportingContext`, `SubStepProgress`, `DebugStepsOutput`.
+ */
+/**
+ * Legal self-reported step statuses and their transitions.
+ *
+ * `terminal: true` means the step is finished and its status can no longer change; `next` lists the
+ * statuses a later `fix` may assign to a non-terminal step.
+ */
 export const reportedStepStatusCatalog = {
-    unknown: { terminal: false, next: ['unknown', 'planned', 'running', 'success', 'error', 'cancelled', 'skipped'] },
-    planned: { terminal: false, next: ['planned', 'running', 'success', 'error', 'cancelled', 'skipped'] },
+    /** No status reported yet; only `fix` uses this as an intermediate state. */
+    unknown: {
+        terminal: false,
+        next: ['unknown', 'planned', 'running', 'success', 'error', 'cancelled', 'skipped'],
+    },
+    /** Declared by the node but not started. */
+    planned: {
+        terminal: false,
+        next: ['planned', 'running', 'success', 'error', 'cancelled', 'skipped'],
+    },
+    /** Started and still active; may only stay running or finish. */
     running: { terminal: false, next: ['running', 'success', 'error', 'cancelled'] },
-    success: { terminal: true, next: [] }, error: { terminal: true, next: [] },
-    cancelled: { terminal: true, next: [] }, skipped: { terminal: true, next: [] },
+    success: { terminal: true, next: [] },
+    error: { terminal: true, next: [] },
+    cancelled: { terminal: true, next: [] },
+    skipped: { terminal: true, next: [] },
 };
+/** Frozen list of reported statuses in catalog order, used for membership validation. */
 export const reportedStepStatuses = Object.freeze(Object.keys(reportedStepStatusCatalog));