@jangts/agent-core 0.3.5 → 0.3.6

package/dist/esm/kits/delivery.js

@@ -1,3 +1,13 @@
+/**
+ * Delivery Kit: run an ordered, synchronous stage pipeline that ends with one result.
+ *
+ * Place in the package: an optional App-side delivery pipeline (for example formatting and
+ * sending one reply). The Kit owns ordering, cancellation checks and outcome validation; the
+ * stages, their state and the actual side effects belong to the App.
+ *
+ * Exports: `defineDelivery`, `Delivery`, and the delivery option/outcome types.
+ */
+import { nativeSubFlowSync } from '../diagnostics/native-sub-flow.js';
 import { synchronous } from '../utils/synchronous.js';
 /**
  * Compile a delivery pipeline from its declared stages.
@@ -38,33 +48,35 @@ export function defineDelivery(options) {
          *   handler results.
          */
         deliver(input, execution) {
-            execution.signal.throwIfAborted();
-            const state = synchronous(createState(input, execution), 'Delivery state creation must be synchronous');
-            const context = {
-                ...execution,
-                signal: execution.signal,
-                diagnostics: execution.diagnostics,
-                app: input,
-            };
-            for (const stage of stages) {
+            return nativeSubFlowSync(execution, 'delivery', 'delivery', () => {
                 execution.signal.throwIfAborted();
-                synchronous(beforeStage?.({ stageId: stage.id, state }, context), 'Delivery hooks must be synchronous');
-                execution.signal.throwIfAborted();
-                if (!stage.handle)
-                    continue;
-                const outcome = synchronous(stage.handle(state, context), 'Delivery handlers must be synchronous');
-                execution.signal.throwIfAborted();
-                if (!outcome ||
-                    !['continue', 'complete'].includes(outcome.type) ||
-                    (outcome.type === 'complete' && !('value' in outcome)))
-                    throw new TypeError('Delivery handlers require explicit continue/complete');
-                if (outcome.type === 'complete') {
-                    const value = outcome.value;
+                const state = synchronous(createState(input, execution), 'Delivery state creation must be synchronous');
+                const context = {
+                    ...execution,
+                    signal: execution.signal,
+                    diagnostics: execution.diagnostics,
+                    app: input,
+                };
+                for (const stage of stages) {
+                    execution.signal.throwIfAborted();
+                    synchronous(beforeStage?.({ stageId: stage.id, state }, context), 'Delivery hooks must be synchronous');
+                    execution.signal.throwIfAborted();
+                    if (!stage.handle)
+                        continue;
+                    const outcome = synchronous(stage.handle(state, context), 'Delivery handlers must be synchronous');
                     execution.signal.throwIfAborted();
-                    return value;
+                    if (!outcome ||
+                        !['continue', 'complete'].includes(outcome.type) ||
+                        (outcome.type === 'complete' && !('value' in outcome)))
+                        throw new TypeError('Delivery handlers require explicit continue/complete');
+                    if (outcome.type === 'complete') {
+                        const value = outcome.value;
+                        execution.signal.throwIfAborted();
+                        return value;
+                    }
                 }
-            }
-            throw synchronous(missingResult(), 'Delivery errors must be synchronous');
+                throw synchronous(missingResult(), 'Delivery errors must be synchronous');
+            });
         },
     });
 }

package/dist/esm/kits/knowledge/catalog.js

@@ -7,6 +7,7 @@
  *
  * Exports: `defineKnowledgeCatalog`, and the knowledge document/read/snapshot types.
  */
+import { nativeSubFlowSync } from '../../diagnostics/native-sub-flow.js';
 import { readonlyCatalog } from '../../utils/catalog.js';
 import { compileKnowledgeDocument, knowledgeText } from './sections.js';
 import { observeSafely } from '../../utils/observer.js';
@@ -65,37 +66,39 @@ export function defineKnowledgeCatalog(documents, options = {}) {
         ...readonlyCatalog([...catalog.values()].map((entry) => entry.document), (id) => new TypeError(`Unknown knowledge document: ${id}`)),
         sectionIds,
         assertSelection,
-        read(input) {
-            const { read, entry } = resolve(input), raw = read.selection;
-            const selection = raw.mode === 'document'
-                ? Object.freeze({ mode: 'document' })
-                : Object.freeze({ mode: raw.mode, sectionIds: Object.freeze([...raw.sectionIds]) });
-            const content = (selection.mode === 'document'
-                ? knowledgeText(entry.document.parts)
-                : selection.sectionIds
-                    .map((id) => knowledgeText(entry.sections.get(id).parts, selection.mode === 'subtree'))
-                    .join('\n\n')).trim();
-            if (maxChars !== undefined && content.length > maxChars)
-                throw new RangeError('Knowledge selection exceeds its budget');
-            // Preserve the existing opaque snapshot identity format.
-            const identitySelection = selection.mode === 'document'
-                ? selection
-                : { mode: selection.mode, sections: selection.sectionIds };
-            const snapshot = Object.freeze({
-                documentId: read.documentId,
-                selection,
-                revision: entry.document.revision,
-                locale: entry.document.locale,
-                content,
-                id: JSON.stringify([
-                    read.documentId,
-                    entry.document.revision,
-                    entry.document.locale,
-                    identitySelection,
-                ]),
+        read(input, context = {}) {
+            return nativeSubFlowSync(context, 'knowledge', input.documentId, () => {
+                const { read, entry } = resolve(input), raw = read.selection;
+                const selection = raw.mode === 'document'
+                    ? Object.freeze({ mode: 'document' })
+                    : Object.freeze({ mode: raw.mode, sectionIds: Object.freeze([...raw.sectionIds]) });
+                const content = (selection.mode === 'document'
+                    ? knowledgeText(entry.document.parts)
+                    : selection.sectionIds
+                        .map((id) => knowledgeText(entry.sections.get(id).parts, selection.mode === 'subtree'))
+                        .join('\n\n')).trim();
+                if (maxChars !== undefined && content.length > maxChars)
+                    throw new RangeError('Knowledge selection exceeds its budget');
+                // Preserve the existing opaque snapshot identity format.
+                const identitySelection = selection.mode === 'document'
+                    ? selection
+                    : { mode: selection.mode, sections: selection.sectionIds };
+                const snapshot = Object.freeze({
+                    documentId: read.documentId,
+                    selection,
+                    revision: entry.document.revision,
+                    locale: entry.document.locale,
+                    content,
+                    id: JSON.stringify([
+                        read.documentId,
+                        entry.document.revision,
+                        entry.document.locale,
+                        identitySelection,
+                    ]),
+                });
+                observeSafely(observe, snapshot);
+                return snapshot;
             });
-            observeSafely(observe, snapshot);
-            return snapshot;
         },
     });
 }

package/dist/esm/kits/policies.d.ts

@@ -38,7 +38,7 @@ export declare function definePolicySet<Input, Kind extends string>(definitions:
  *   boolean `handled` or omits `value` while claiming to have handled the input.
  */
 export declare function defineRecoveryChain<Input, Result>(definitions: readonly RecoveryDefinition<Input, Result>[]): Readonly<{
-    tryRecover: (input: Input) => RecoveryResult<Result>;
+    tryRecover: (input: Input, execution?: Partial<import("../structs/common.js").ExecutionContext>) => RecoveryResult<Result>;
     definitions: readonly Readonly<{
         id: string;
         description: string;

package/dist/esm/kits/policies.js

@@ -7,6 +7,7 @@
  *
  * Exports: `definePolicySet`, `defineRecoveryChain`, `Policies`, and the policy types.
  */
+import { nativeSubFlowSync } from '../diagnostics/native-sub-flow.js';
 import { readonlyCatalog } from '../utils/catalog.js';
 import { synchronous, booleanResult } from '../utils/synchronous.js';
 import { breakWhile } from '../utils/rules.js';
@@ -65,9 +66,9 @@ export function defineRecoveryChain(definitions) {
             },
         });
     });
-    const tryRecover = (input) => {
+    const tryRecover = (input, execution = {}) => {
         for (const policy of catalog) {
-            const result = policy.tryRecover(input);
+            const result = nativeSubFlowSync(execution, 'recovery', policy.id, () => policy.tryRecover(input));
             if (result.handled)
                 return result;
         }

package/dist/esm/kits/presentation/outputs.js

@@ -7,6 +7,7 @@
  *
  * Exports: `defineOutputCatalog`, and the output definition/field/provider/result types.
  */
+import { nativeSubFlowSync } from '../../diagnostics/native-sub-flow.js';
 import { snapshotSchemaAdapter } from '../../utils/schema-adapter.js';
 import { readonlyCatalog } from '../../utils/catalog.js';
 import { synchronous } from '../../utils/synchronous.js';
@@ -321,7 +322,7 @@ export function defineOutputCatalog(definitions, options = {}) {
                 throw new TypeError('Use a named output request');
             if (!context?.signal)
                 throw new TypeError('Output composition requires OperationContext');
-            return composeInternal(request.outputId, request.input, context);
+            return nativeSubFlowSync(context, 'output', request.outputId, () => composeInternal(request.outputId, request.input, context));
         },
     });
 }

package/dist/esm/kits/retrieval.js

@@ -8,6 +8,7 @@
  *
  * Exports: `defineRetrieval`, `retrievalQueryKey`, `Retrieval`, and the retrieval port types.
  */
+import { nativeSubFlowSync } from '../diagnostics/native-sub-flow.js';
 import { assertion, synchronous } from '../utils/synchronous.js';
 import { retrievalQueryKey } from '../utils/query-key.js';
 import { breakWhile } from '../utils/rules.js';
@@ -144,7 +145,12 @@ export function defineRetrieval(definition) {
         }
         return receipt;
     }
-    return Object.freeze({ id, description, effects, run });
+    return Object.freeze({
+        id,
+        description,
+        effects,
+        run: (input, context) => nativeSubFlowSync(context, 'retrieval', id, () => run(input, context)),
+    });
 }
 function reason(value, query, context) {
     return () => (typeof value === 'function' ? value(query, context) : value);

package/dist/esm/kits/tools.js

@@ -89,6 +89,7 @@ export class ToolLifecycleRegistry {
         });
         this.diagnostics = this.options.execution?.diagnostics;
         this.invocationPorts = Object.freeze({
+            logger: this.options.logger,
             diagnostics: this.options.diagnostics ?? (() => this.diagnostics),
             signal: this.options.signal,
             journal: this.options.journal,

package/dist/esm/model/decision-retry.d.ts

@@ -9,6 +9,8 @@
  * @throws The original error when it is not a multi-call rejection, or the fallback error.
  */
 export declare function retryMultipleModelCalls<Value>(request: {
+    readonly logger?: import('../structs/debug.js').SubFlowLogger;
+    readonly signal?: AbortSignal;
     readonly invoke: () => Promise<Value>;
     readonly retry: (error: unknown) => Promise<Value>;
 }): Promise<Value>;

package/dist/esm/model/decision-retry.js

@@ -7,6 +7,7 @@
  *
  * Exports: `retryMultipleModelCalls`.
  */
+import { nativeSubFlowAsync } from '../diagnostics/native-sub-flow.js';
 import { getErrorInfo } from '../errors.js';
 /**
  * Retry once when the failure is a rejected multi-call proposal.
@@ -25,6 +26,6 @@ export async function retryMultipleModelCalls(request) {
     catch (error) {
         if (!getErrorInfo(error).codes.includes('MODEL_MULTIPLE_CALLS'))
             throw error;
-        return request.retry(error);
+        return nativeSubFlowAsync(request, 'retry', 'MODEL_MULTIPLE_CALLS', () => request.retry(error));
     }
 }

package/dist/esm/model/runner.d.ts

@@ -145,6 +145,8 @@ export declare class ModelRunner<TransportId extends string = string, const Tran
     }): Promise<ModelResult<import('../structs/model/runtime.js').RegisteredTransportOutput<Transports, Id>>>;
     /** Invoke without narrowing the transport type. */
     invoke(request: ModelCallRequest<TransportId | ModelTransportDefinition>): Promise<ModelResult<unknown>>;
+    /** Validate and execute a single request; optional recording is owned by invoke. */
+    private invokeRequest;
     /**
      * Acquire the per-runner call slot and execute one call.
      *

package/dist/esm/model/runner.js

@@ -10,6 +10,8 @@
  * Exports: `ModelRunner`, the re-exported `BudgetError`, and the runtime/config type
  * re-exports at the bottom of the file.
  */
+import { requireSubFlowLogger } from '../diagnostics/sub-flow.js';
+import { nativeSubFlowAsync } from '../diagnostics/native-sub-flow.js';
 import { executionEvents } from '../execution/events.js';
 import { ModelCallBudget, parentModelBudget } from './call-budget.js';
 import { synchronous } from '../utils/synchronous.js';
@@ -317,6 +319,19 @@ export class ModelRunner {
         return snapshot;
     }
     async invoke(request) {
+        const context = typeof request === 'string' ? { logger: undefined, signal: undefined } : request;
+        requireSubFlowLogger(context.logger);
+        const callId = invocationId();
+        return nativeSubFlowAsync({
+            logger: context.logger,
+            signal: combineSignals(this.signal, context.signal),
+            invocationId: callId,
+        }, 'model', typeof request === 'string'
+            ? modelRunnerDefaults.stage
+            : (request.stageId ?? request.prepared?.stageId ?? modelRunnerDefaults.stage), () => this.invokeRequest(request, callId));
+    }
+    /** Validate and execute a single request; optional recording is owned by invoke. */
+    async invokeRequest(request, callId) {
         const call = typeof request === 'string' ? { input: request } : request;
         const state = call.prepared === undefined ? undefined : this.preparedCalls.get(call.prepared);
         if (call.prepared !== undefined && (!state || state.used))
@@ -380,7 +395,7 @@ export class ModelRunner {
             throw invalid('Prepared model request settings cannot be replaced');
         if (state)
             state.used = true;
-        return this.invokePrepared(stage, input, tokens, transportId, call.diagnostics, prepared, call.signal);
+        return this.invokePrepared(stage, input, tokens, transportId, call.diagnostics, prepared, call.signal, callId);
     }
     /**
      * Acquire the per-runner call slot and execute one call.
@@ -399,7 +414,7 @@ export class ModelRunner {
      * @returns The parsed result with invocation metadata.
      * @throws Error When a call is already in flight or the request capacity is exhausted.
      */
-    async invokePrepared(stage, input, tokens, transportId, diagnostics = this.ports.diagnostics, prepared, requestSignal) {
+    async invokePrepared(stage, input, tokens, transportId, diagnostics = this.ports.diagnostics, prepared, requestSignal, callId = invocationId()) {
         const configuredRun = this.ports.diagnostics?.identity?.runId, selectedRun = diagnostics?.identity?.runId;
         if (configuredRun && selectedRun && configuredRun !== selectedRun)
             throw recordErrorContext(new TypeError('Model observation parent belongs to a different run'), { stageId: stage, codes: ['MODEL_CONFIG'], isRetryable: false });
@@ -409,7 +424,7 @@ export class ModelRunner {
         this.requestGate.active++;
         let failure;
         try {
-            return await this.execute(stage, input, tokens, transportId, combineSignals(this.signal, requestSignal), diagnostics, prepared);
+            return await this.execute(stage, input, tokens, transportId, combineSignals(this.signal, requestSignal), diagnostics, prepared, callId);
         }
         catch (error) {
             failure = recordErrorContext(error, { stageId: stage });
@@ -440,8 +455,8 @@ export class ModelRunner {
      * @returns The parsed result with invocation metadata.
      * @throws Error or ValidationError from any phase, decorated with stage context.
      */
-    async execute(stage, input, tokens, transportId, signal, parentDiagnostics = this.ports.diagnostics, prepared) {
-        const id = invocationId(), startedAtMs = Date.now();
+    async execute(stage, input, tokens, transportId, signal, parentDiagnostics = this.ports.diagnostics, prepared, callId = invocationId()) {
+        const id = callId, startedAtMs = Date.now();
         this.activeCall = undefined;
         const invocationDiagnostics = parentDiagnostics?.child(id, {
             invocationId: id,

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

@@ -49,6 +49,8 @@ export interface InvocationHandler<Input, Context> {
 }
 /** Optional capabilities the lifecycle resolves from the host context for one invocation. */
 export interface ToolInvocationPorts<Context> {
+    /** Explicit recorder selected for this invocation only. */
+    readonly logger?: (context: Context) => import('../debug.js').SubFlowLogger | undefined;
     /** Diagnostic scope; omitted disables recording for this tool. */
     readonly diagnostics?: (context: Context) => import('../diagnostics.js').DiagnosticContext | undefined;
     /** Extra cancellation; must not replace the tool execution signal. */

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

@@ -27,13 +27,15 @@ export interface ToolDefinition<Input = unknown, Output = unknown, App = unknown
     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;
+    /** Optional result hook; writes through context.createSubFlowLogger() are recorded immediately. */
+    debugSteps?(result: Output, context: import('../debug.js').NodeReportingContext): void;
     /** 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 {
+    /** Delegate bound by Core to this actual invocation. */
+    readonly logger?: import('../debug.js').ScopedSubFlowLogger;
     /** Diagnostic scope of the invocation, when recording is enabled. */
     readonly diagnostics?: DiagnosticContext;
     /** Declared execution discipline; mirrors whether the registry accepted an async tool. */
@@ -49,7 +51,7 @@ export interface ExecutableTool {
     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;
+    readonly debugSteps?: (result: unknown, context: NodeReportingContext) => void;
     parseInput(value: unknown): unknown;
     parseOutput(value: unknown): unknown;
     execute(input: unknown, context: ToolExecutionContext): unknown;
@@ -79,6 +81,8 @@ export interface ToolRegistryPorts {
 }
 /** One invocation request; the registry supplies signal and diagnostics when omitted. */
 export interface ToolInvocationRequest<Id extends string = string> {
+    /** Explicit recorder for this call, also available to its handler for deliberate use. */
+    readonly logger?: import('../debug.js').SubFlowLogger;
     readonly toolId: Id;
     /** Raw model arguments; parsed by the tool's input schema before authorization. */
     readonly input: unknown;

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

@@ -93,6 +93,8 @@ export interface ExecutionOptions {
 }
 /** Required execution facts available inside a running call. */
 export interface ExecutionContext {
+    /** Explicit optional recorder for this operation; never inferred from diagnostics. */
+    readonly logger?: import('./debug.js').SubFlowLog;
     /** Non-optional cancellation signal; never `undefined` once execution has started. */
     readonly signal: AbortSignal;
     /** Diagnostic scope of the enclosing call, when recording is enabled. */

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

@@ -55,12 +55,18 @@ export declare const reportedStepStatuses: readonly (keyof typeof reportedStepSt
 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. */
+    /** App-defined business log type; never a write/fix operation enum. */
+    readonly type?: string;
+    /** Logical subnode grouping within this node visit; independent of individual log ids. */
+    readonly subnodeId?: string;
+    /** Log record identity, unique within one node visit; not a subnode id. */
     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;
+    /** Real model/tool invocation identity, kept separate from the node-local subnode id. */
+    readonly relatedInvocationId?: string;
     /** Short reported label. */
     readonly name: string;
     /** Reported step kind (for example a tool or model call); free-form and node-owned. */
@@ -88,7 +94,11 @@ export type SubFlowValue = null | boolean | number | string | readonly SubFlowVa
 export interface RecordedSubStep extends ReportedStep {
     /** Historical marker: only self-reported steps are recorded. */
     readonly origin: 'reported';
-    /** One-based write order within the node visit. */
+    /** Append-only logging operation, separate from the App-owned business type. */
+    readonly operation?: 'write' | 'fix';
+    /** Original write record revised by this fix; fixes have their own stepId. */
+    readonly targetStepId?: string;
+    /** One-based append order within the node visit, including every fix. */
     readonly sequence: number;
     /** Optional only for historical records produced before the logger contract. */
     readonly createdAtMs?: number;
@@ -98,10 +108,14 @@ export interface RecordedSubStep extends ReportedStep {
     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'> {
+export interface SubFlowStepInput extends Omit<ReportedStep, 'stepId' | 'kind'> {
+    /** Optional family classification; defaults to the custom type when omitted. */
+    readonly kind?: string;
     readonly payload?: Readonly<Record<string, SubFlowValue>>;
 }
-/** Fields a later `fix` may change on an already written step. */
+/** Scoped writes cannot supply or override the identity bound by their delegate. */
+export type ScopedSubFlowStepInput = Omit<SubFlowStepInput, 'subnodeId'>;
+/** Explicit revision whitelist: identity, grouping and business type are never patchable. */
 export interface SubFlowStepFix {
     readonly status?: ReportedStepStatus;
     readonly usedModel?: boolean;
@@ -112,31 +126,34 @@ export interface SubFlowStepFix {
     /** Fill missing result fields; existing facts cannot be replaced. */
     readonly payload?: Readonly<Record<string, SubFlowValue>>;
 }
-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. */
+/** Common read/write surface for both independently implemented logger classes. */
+export interface SubFlowLog {
+    write(input: ScopedSubFlowStepInput): string | -1;
+    fix(stepId: string | -1, patch: SubFlowStepFix): boolean;
+    /** Both logger classes return the same complete immutable ledger. */
     readAll(): readonly Readonly<RecordedSubStep>[];
 }
+/** Nominal classes: only the full logger is accepted by native invocation requests. */
+export type { SubFlowLogger, ScopedSubFlowLogger } from '../diagnostics/sub-flow.js';
+import type { SubFlowLogger } from '../diagnostics/sub-flow.js';
 /** 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. */
+    /** Bound to this context and owned by runtime; repeated calls in one visit return the same instance. */
     createSubFlowLogger(): SubFlowLogger;
 }
 /** Compact progress notification emitted for each accepted sub-step write or fix. */
 export interface SubStepProgress {
+    readonly relatedInvocationId?: string;
     readonly operation: 'write' | 'fix';
-    /** Step the operation applied to. */
+    readonly type?: string;
+    readonly subnodeId?: string;
+    /** Original write record when this operation is a fix. */
+    readonly targetStepId?: string;
+    /** Unique id of this append-only record. */
     readonly stepId: string;
-    /** Write sequence of that step within the node visit. */
+    /** Append sequence of this record within the node visit, including every fix. */
     readonly sequence: number;
     /** Revision after the operation; `write` starts at 1. */
     readonly revision: number;
@@ -151,7 +168,6 @@ export interface SubStepProgress {
 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;
+    /** Runtime-owned immutable snapshot, committed when a logger writes or fixes a step. */
+    readonly recordedSubSteps?: readonly Readonly<RecordedSubStep>[];
 }
-export {};

package/dist/esm/structs/execution/workflow-views.d.ts

@@ -0,0 +1,123 @@
+/** Serializable topology and observed execution contracts; layout belongs to consumers. */
+import type { CoreDiagnosticRecord } from '../diagnostics.js';
+import type { RecordedSubStep, SubFlowValue } from '../debug.js';
+import type { WorkflowEvent } from './workflow.js';
+/** Pure registered topology; routes sharing a target share an edge within one kind. */
+export interface WorkflowGraph {
+    readonly schemaVersion: 1;
+    readonly workflowId: string;
+    readonly revision?: string;
+    readonly entryNodeId: string;
+    readonly nodes: readonly WorkflowGraphNode[];
+    readonly edges: readonly WorkflowGraphEdge[];
+}
+/** Node metadata and derived incident edges, without executable callbacks. */
+export interface WorkflowGraphNode {
+    readonly id: string;
+    readonly name: string;
+    readonly description: string;
+    readonly order: number;
+    readonly startsRound: boolean;
+    readonly requires: readonly string[];
+    readonly provides: readonly string[];
+    readonly routes: readonly WorkflowGraphRoute[];
+    readonly incomingEdgeIds: readonly string[];
+    readonly outgoingEdgeIds: readonly string[];
+}
+/** Declaration order is retained even when multiple routes share a topology edge. */
+export interface WorkflowGraphRoute {
+    readonly order: number;
+    readonly routeId?: string;
+    readonly description?: string;
+    readonly conditional: boolean;
+    readonly conditionId?: string;
+    readonly edgeId: string;
+}
+/** Completion has no target node; recovery edges remain distinct from normal edges. */
+export interface WorkflowGraphEdge {
+    readonly id: string;
+    readonly kind: 'transition' | 'error' | 'complete';
+    readonly sourceNodeId: string;
+    readonly targetNodeId?: string;
+    readonly routeOrders: readonly number[];
+    readonly errorRouteId?: string;
+}
+/** Capture completeness is independent of whether diagnostic content was included. */
+export interface WorkflowChainCoverage {
+    readonly complete: boolean | 'unknown';
+    readonly content: 'included' | 'omitted' | 'mixed' | 'unknown';
+    readonly issues: readonly {
+        readonly code: string;
+        readonly spanId?: string;
+        readonly eventId?: string;
+        readonly count?: number;
+    }[];
+}
+/** App resolves authorization, retention, pagination and storage paths before returning. */
+export type WorkflowChainSource = (runId: string) => Promise<{
+    readonly events: readonly CoreDiagnosticRecord[];
+    readonly coverage: WorkflowChainCoverage;
+}>;
+/** Observed visits, never merged by static node id or synthesized from adjacency. */
+export interface WorkflowChain {
+    readonly schemaVersion: 1;
+    readonly workflowId: string;
+    readonly runId: string;
+    readonly nodes: readonly WorkflowChainNode[];
+    readonly transitions: readonly WorkflowChainTransition[];
+    readonly coverage: WorkflowChainCoverage;
+}
+/** Historical subflow snapshots may omit recorder fields or descriptive content. */
+export type WorkflowSubflowRecord = Omit<RecordedSubStep, 'name' | 'kind'> & {
+    readonly name?: string;
+    readonly kind?: string;
+    readonly sourceEventId?: string;
+    readonly producerSequence?: number;
+};
+/** A single node visit, with flat ordered subflow records including every independent fix. */
+export interface WorkflowChainNode {
+    readonly spanId: string;
+    readonly nodeId: string;
+    readonly workflowInvocationId?: string;
+    readonly definitionRevision?: string;
+    readonly name?: string;
+    readonly description?: string;
+    readonly kind?: string;
+    readonly roundIndex?: number;
+    readonly firstEventSequence: number;
+    readonly lastEventSequence: number;
+    readonly enteredAtMs?: number;
+    readonly endedAtMs?: number;
+    readonly durationMs?: number;
+    readonly status: 'running' | 'success' | 'error' | 'cancelled' | 'unknown';
+    readonly usedModel?: boolean;
+    readonly events: readonly WorkflowChainNodeEvent[];
+    readonly subflow: readonly WorkflowSubflowRecord[];
+}
+/** Node-local lifecycle facts; payload remains subject to the source's content policy. */
+export interface WorkflowChainNodeEvent {
+    readonly eventId: string;
+    readonly producerSequence: number;
+    readonly occurredAtMs: number;
+    readonly type: WorkflowEvent['type'] | 'progress';
+    readonly phase?: WorkflowEvent['phase'];
+    readonly routeId?: string;
+    readonly conditionId?: string;
+    readonly errorCode?: string;
+    readonly errorEventId?: string;
+    readonly payload?: SubFlowValue;
+}
+/** Actual handoff evidence; a target span does not prove its enter event was captured. */
+export interface WorkflowChainTransition {
+    readonly eventId: string;
+    readonly producerSequence: number;
+    readonly occurredAtMs: number;
+    readonly type: 'transition' | 'complete';
+    readonly sourceSpanId: string;
+    readonly targetSpanId?: string;
+    readonly targetNodeId?: string;
+    readonly routeOrder?: number;
+    readonly routeId?: string;
+    readonly conditionId?: string;
+    readonly errorEventId?: string;
+}

package/dist/esm/structs/execution/workflow-views.js

@@ -0,0 +1 @@
+export {};