@jangts/agent-core 0.2.5 → 0.3.6

package/development/docs/api/types.en.md

@@ -37,6 +37,7 @@ interface ExecutionOptions {
   readonly diagnostics?: DiagnosticContext;
 }
 interface OperationContext<App> {
+  readonly logger?: SubFlowLog;
   readonly app: Readonly<App>;
   readonly signal: AbortSignal;
   readonly diagnostics?: DiagnosticContext;

package/development/docs/api/types.md

@@ -37,6 +37,7 @@ interface ExecutionOptions {
   readonly diagnostics?: DiagnosticContext;
 }
 interface OperationContext<App> {
+  readonly logger?: SubFlowLog;
   readonly app: Readonly<App>;
   readonly signal: AbortSignal;
   readonly diagnostics?: DiagnosticContext;

package/development/docs/api/workflow-views.en.md

@@ -0,0 +1,64 @@
+# Workflow graphs and execution chains
+
+`workflow.toGraph()` returns registered topology. `await workflow.toChain(runId)` returns observed visits of this Workflow within a run. Both return deeply readonly JSON data, without handlers, condition functions, layout or renderers.
+
+These interfaces support developer reviews, debugging, observability clients and demonstrations. Export does not participate in Agent decisions, scheduling or task execution and adds no business capability. A chain is a readonly projection of existing records, not a replay or resume entry. Apps can authorize log-based reflection; graphs and chains do not automatically enter learning or rule modification.
+
+## Reading a run
+
+```ts
+const workflow = defineWorkflow({
+  id: 'assistant', nodes,
+  chainSource: async runId => {
+    const capture = await authorizedRunReader.readAll(runId);
+    return { events: capture.events, coverage: capture.coverage };
+  },
+});
+const graph = workflow.toGraph();
+const chain = await workflow.toChain(runId);
+const exported = await workflow.toChain(runId, authorizedSource);
+```
+
+`WorkflowChainSource` receives a runId and returns `Promise<{ events: readonly CoreDiagnosticRecord[]; coverage: WorkflowChainCoverage }>`. The App owns authorization, account isolation, storage paths, retention, pagination and read limits. Core installs no global run store and does not retain the latest run. A per-call source overrides the bound source without modifying the Workflow. `add()` carries the bound source into the derived Workflow.
+
+An empty runId or absent source throws TypeError. Source errors propagate. No matching Workflow visits throws RangeError, rather than returning an apparently successful empty history. Readers must provide a consistent snapshot and state whether the capture is complete, live or uncertain.
+
+## WorkflowGraph
+
+The root contains `schemaVersion: 1`, `workflowId`, optional `revision`, `entryNodeId`, `nodes` and `edges`.
+
+Each `WorkflowGraphNode` contains `id`, `name` (defaults to id), `description`, zero-based `order`, `startsRound`, `requires`, `provides`, `routes`, `incomingEdgeIds` and `outgoingEdgeIds`. Empty collections are arrays. The explicit entry cannot be inferred from incoming edges because loops may lead back to it.
+
+Each `WorkflowGraphRoute` contains zero-based `order`, optional `routeId`, `description` and `conditionId`, a `conditional` boolean, and `edgeId`. Order is matching priority. Export never calls `when` or `complete`.
+
+Each `WorkflowGraphEdge` contains `id`, `kind: transition | error | complete`, `sourceNodeId`, optional `targetNodeId`, `routeOrders` and optional `errorRouteId`. Routes with the same source, kind and target share one edge while retaining their individual orders. Recovery and normal edges remain separate. Completion has no target node. Recovery has an empty routeOrders array and takes errorRouteId from onErrorRouteId. IDs are deterministic JSON tuples `[sourceNodeId, kind, targetNodeId ?? null]`; consumers should treat them as opaque strings.
+
+Registration reads a routes getter exactly once and seals a copied snapshot. The getter must be pure and depend only on immutable definitions. Runtime conditions belong in `when`. Execution and graph export use the same snapshot. Export does not inspect function bodies or infer internal tool calls and custom subnodes.
+
+## WorkflowChain
+
+The root contains `schemaVersion: 1`, `workflowId`, `runId`, `nodes`, `transitions` and `coverage`. Nodes are sorted by first observed producerSequence, transitions by their original producerSequence.
+
+A `WorkflowChainNode` identifies one visit with `spanId` and `nodeId`, plus optional `workflowInvocationId`, `definitionRevision`, `name`, `description`, `kind` and `roundIndex`. Repeated visits and multiple Workflow invocations within one run stay separate. Historical nodes absent from the current graph remain in the chain. Descriptive fields come only from captured events, never from current definitions.
+
+Visit fields also include `firstEventSequence`, `lastEventSequence`, optional `enteredAtMs`, `endedAtMs`, `durationMs`, `usedModel`, and mandatory `status`, `events`, `subflow`. Time is epoch milliseconds. Sequence values are original producer values. Status is `running | success | error | cancelled | unknown` for this visit alone; recovery does not overwrite an error with success. Missing exits in a complete capture yield unknown; an entered visit in an incomplete live capture can remain running. TIMEOUT and CANCELLED map to cancelled.
+
+Each node event contains `eventId`, `producerSequence`, `occurredAtMs`, `type: enter | progress | transition | complete | error`, and optional `phase`, `routeId`, `conditionId`, `errorCode`, `errorEventId`, `payload`. Sub-step progress is represented by subflow rather than duplicated as ordinary progress.
+
+Each `WorkflowChainTransition` contains `eventId`, `producerSequence`, `occurredAtMs`, `type: transition | complete`, `sourceSpanId`, and optional `targetSpanId`, `targetNodeId`, `routeOrder`, `routeId`, `conditionId`, `errorEventId`. Only explicit handoff facts create connections. An error event with a recovery target also creates a transition, with eventId and errorEventId referencing that original error event. Neither adjacency nor timestamps imply a handoff. A selected targetSpanId does not prove that its entry was captured; missing target visits are reported.
+
+### Ordered subflow
+
+`WorkflowSubflowRecord` retains RecordedSubStep fields: `origin`, `stepId`, `operation`, `targetStepId`, `sequence`, `createdAtMs`, `revision`, `subnodeId`, `type`, `kind`, `name`, `status`, `usedModel`, `startedAtMs`, `endedAtMs`, `relatedDefinitionId`, `relatedInvocationId`, `parentStepId`, `nextStepIds`, `caseId`, `summary`, `payload`.
+
+Records stay in node-local sequence order. Every fix retains its own stepId and targetStepId; original writes are never overwritten. Repeated snapshots deduplicate by stepId within one span. Direct progress evidence adds `sourceEventId` and `producerSequence`. Records found only in later snapshots receive no fabricated emission sequence. Historical operation/createdAtMs/revision omissions remain absent and are reported. Metadata captures may omit name, kind, payload and other content.
+
+subnodeId and type are caller-defined strings. Records without subnodeId belong to the main node's own process. Core creates no subnodes array, implicit group, merged view or dependency between subnodes. Consumer DataModels choose grouping, fix projection, filtering and expansion. A group need not be contiguous or sequential.
+
+### Coverage
+
+`complete: boolean | 'unknown'` states source event coverage; projection issues downgrade it to false. `content: included | omitted | mixed | unknown` independently describes content capture. Omitted content does not imply missing events. Each issue has a `code` and optional `spanId`, `eventId`, `count`.
+
+Core issue codes are `conflicting-event`, `invalid-workflow-event`, `missing-node-id`, `conflicting-span`, `subflow-truncated`, `conflicting-subflow`, `invalid-subflow-progress`, `missing-enter`, `missing-exit`, `historical-subflow-fields`, `missing-target-enter`. Apps can supply additional read-side issue codes. Invalid v2 diagnostic envelopes throw through normalizeDiagnosticEvent rather than becoming apparently valid history.
+
+Readonly types are exported from the root, `/engine`, `/types`, and `/structs`. See the [symbol reference](reference.en.md).

package/development/docs/api/workflow-views.md

@@ -0,0 +1,78 @@
+# 工作流图与执行链
+
+`workflow.toGraph()` 返回注册定义的纯拓扑，`await workflow.toChain(runId)` 返回一次运行中该 Workflow 的实际节点执行。两者都是深度只读、可 JSON 序列化的数据，不包含 handler、条件函数、布局或渲染器。
+
+这两个接口用于开发审查、调试、观测界面和演示。导出不参与 Agent 的决策、调度或任务执行，不增加业务能力；执行链是既有记录的只读投影，不是重放或恢复入口。日志可由 App 授权接入复盘，图与执行链没有自动接入学习或规则修改。
+
+## 数据源与调用
+
+```ts
+const workflow = defineWorkflow({
+  id: 'assistant',
+  nodes,
+  chainSource: async runId => {
+    const capture = await authorizedRunReader.readAll(runId);
+    return { events: capture.events, coverage: capture.coverage };
+  },
+});
+const graph = workflow.toGraph();
+const chain = await workflow.toChain(runId);
+// 临时导出可传入本次专用数据源，不修改 Workflow。
+const exported = await workflow.toChain(runId, authorizedSource);
+```
+
+`chainSource: WorkflowChainSource` 是 App 的只读接口，接收 `runId`，返回 `Promise<{ events: readonly CoreDiagnosticRecord[]; coverage: WorkflowChainCoverage }>`。App 负责授权、账户隔离、存储路径解析、保留期、分页和读取边界。Core 不保存全局运行日志，也不从最近一次运行取得数据。`add()` 返回的新 Workflow 沿用绑定的数据源。
+
+空 runId 或未配置数据源抛出 `TypeError`；数据源读取错误原样传播；没有该 run／Workflow 的节点执行记录时抛出 `RangeError`。这与成功返回空图不同。读取期间 App 应返回一致快照，并对正在运行、缺失或无法证明完整的记录准确填写 coverage。
+
+## WorkflowGraph
+
+| 字段 | 类型与含义 |
+| --- | --- |
+| schemaVersion | `1` |
+| workflowId / revision | 定义 ID／可选定义版本 |
+| entryNodeId | 显式入口，不能用入边数推断 |
+| nodes | 按注册顺序排列的 `WorkflowGraphNode[]` |
+| edges | 按节点和路由声明顺序生成的 `WorkflowGraphEdge[]` |
+
+节点字段：`id`、`name`（未声明时为 id）、`description`、`order`（从 0 开始）、`startsRound`、`requires`、`provides`、`routes`、`incomingEdgeIds`、`outgoingEdgeIds`。空合同及边集合返回空数组。
+
+路由字段：`order`（节点内从 0 开始）、可选 `routeId`／`description`／`conditionId`、`conditional: boolean`、`edgeId`。路由顺序是匹配优先级；导图不执行 `when` 或 `complete`。
+
+边字段：`id`、`kind: 'transition' | 'error' | 'complete'`、`sourceNodeId`、可选 `targetNodeId`、`routeOrders: number[]`、可选 `errorRouteId`。同一源节点、种类、目标合成一条边，多条路由通过 `routeOrders` 保留；普通跳转与错误恢复分别成边。完成边没有目标节点；错误边的 routeOrders 为空，errorRouteId 来自 onErrorRouteId。边 ID 是稳定的 JSON 元组 `[sourceNodeId, kind, targetNodeId ?? null]`，使用方将其视为不透明字符串。
+
+注册时仅读取一次 `get routes()`，复制并封存路由。getter 必须是只依赖不可变定义的纯函数；运行条件应写在 `when` 中。执行与导图共享注册快照。导图不分析函数体，因此不包含节点内部工具调用或自定义子节点。
+
+## WorkflowChain
+
+| 字段 | 类型与含义 |
+| --- | --- |
+| schemaVersion | `1` |
+| workflowId / runId | 查询的 Workflow 与运行 ID |
+| nodes | 按首次观察的 producerSequence 排序的节点执行 |
+| transitions | 按 producerSequence 排序的真实跳转／完成事件 |
+| coverage | 完整性、内容策略与缺失诊断 |
+
+`WorkflowChainNode` 的身份是 `spanId`，另含 `nodeId`、可选 `workflowInvocationId`／`definitionRevision`／`name`／`description`／`kind`／`roundIndex`。同一节点的多次进入和同一 run 中多次调用 Workflow 均保留独立执行；历史或图外 nodeId 不丢弃，名称等只取历史日志，不从当前定义补齐。
+
+每次执行还包含 `firstEventSequence`、`lastEventSequence`、可选 `enteredAtMs`／`endedAtMs`／`durationMs`／`usedModel`、`status`、`events`、`subflow`。时间为 epoch 毫秒，序号保留原始 producerSequence，不重新编号。status 为 `running | success | error | cancelled | unknown`，只反映本节点，错误恢复跳转不把失败节点改成成功。完整记录缺少退出时返回 unknown；不完整快照中已经进入但尚未退出的节点为 running。TIMEOUT 与 CANCELLED 均为 cancelled。
+
+`events` 保存节点生命周期和普通 progress：`eventId`、`producerSequence`、`occurredAtMs`、`type: enter | progress | transition | complete | error`，以及可选 `phase`、`routeId`、`conditionId`、`errorCode`、`errorEventId`、`payload`。专用于 subStep 的 progress 归入 subflow，不重复记为普通 progress。
+
+`WorkflowChainTransition` 字段为 `eventId`、`producerSequence`、`occurredAtMs`、`type: transition | complete`、`sourceSpanId`，以及可选 `targetSpanId`、`targetNodeId`、`routeOrder`、`routeId`、`conditionId`、`errorEventId`。只有实际事件才生成连线，不按相邻顺序或时间猜测。错误事件声明恢复目标时也生成 transition，其 eventId 与 errorEventId 均关联该原始错误事件。targetSpanId 只是选择后继的证据，不代替后继 enter；缺失后继记录会进入 coverage。
+
+### 有序 subflow
+
+`subflow` 是按节点内 sequence 排列的原始日志。它保留 `RecordedSubStep` 字段：`origin`、`stepId`、`operation`、`targetStepId`、`sequence`、`createdAtMs`、`revision`、`subnodeId`、`type`、`kind`、`name`、`status`、`usedModel`、`startedAtMs`、`endedAtMs`、`relatedDefinitionId`、`relatedInvocationId`、`parentStepId`、`nextStepIds`、`caseId`、`summary`、`payload`。
+
+每次 fix 保留独立 stepId 和 targetStepId，不合并或改写原记录。重复事件快照按本次 spanId 内的 stepId 去重。直接捕获写入／修正 progress 时补充 `sourceEventId` 和 `producerSequence`；仅在后续快照找到的记录不伪造原始事件序号。旧日志缺失 operation／createdAtMs／revision 时保留缺失并报告 historical-subflow-fields；元数据日志允许 name／kind／payload 等内容字段缺失。
+
+subnodeId 和 type 由调用方定义；没有 subnodeId 的记录属于主节点自己的过程。Core 不生成 subnodes、默认分组、合并视图或子节点之间的连线。展示端可依自己的 DataModel 分组、投影多次 fix、过滤或展开；同组不保证连续，不推导串行或依赖。
+
+### Coverage
+
+`complete: boolean | 'unknown'` 表示数据源声明的事件覆盖；投影发现问题时降为 false。`content: included | omitted | mixed | unknown` 独立说明内容采集策略，未采集正文不等于事件丢失。`issues` 每项含 `code` 和可选 `spanId`／`eventId`／`count`。
+
+Core 会追加 `conflicting-event`、`invalid-workflow-event`、`missing-node-id`、`conflicting-span`、`subflow-truncated`、`conflicting-subflow`、`invalid-subflow-progress`、`missing-enter`、`missing-exit`、`historical-subflow-fields`、`missing-target-enter`。App 可附加自己的读取诊断码。当前 v2 诊断封装不合法时由 normalizeDiagnosticEvent 抛错；Core 不把不可解析的数据伪装成成功历史。
+
+精确的 readonly 类型通过根入口、`/engine`、`/types` 和 `/structs` 导出，见[公开符号参考](reference.md)。

package/development/docs/api/workflow.en.md

@@ -176,7 +176,7 @@ Workflow uniformly handles identifier collisions and placeholders in existing co
 ## Node reports
 
 The Loop automatically records node entry, jumps, completion, and exceptions. When a node needs to add business details, it can provide
-`report(update, context)` in its definition, returning `{ usedModel, payload, subs }`, where every field is optional. `subs` is the `SubFlowLogger` instance provided by that execution context. This completion callback is called only when diagnostics allow content, and it reads a copy of the state update; a `usedModel` that must be retained in metadata mode should be submitted during the run through `context.report`.
+`report(update, context)` in its definition, returning `{ usedModel, payload }`, where every field is optional. Sub-logs use the execution-bound `context.createSubFlowLogger()`; write/fix commit immediately without returning or submitting the instance. This completion callback is called only when diagnostics allow content, and it reads a copy of the state update; a `usedModel` that must be retained in metadata mode should be submitted during the run through `context.report`.
 The Loop attaches this supplementary information to the node's completion or jump record. If reporting fails, the original node event is still recorded.
 
 
@@ -185,7 +185,7 @@ infers the output type from the object contract, and the same field also accepts
 
 ### Reports during node execution
 
-`run(state, context)` can call `context.report({ usedModel, payload, subs })` to report progress. usedModel is optional boolean metadata about this node itself and remains unknown when not reported; payload and subs are read only when content is allowed. subs must be the instance created by `context.createSubFlowLogger()` for this execution, and a hand-written array cannot be submitted. write records the intent first and returns an ID, fix adds later results, and readAll returns an immutable snapshot in a fixed format; writes and completions reuse the existing node.progress, and a short circuit or throw still preserves the start record already sent. Reports do not submit business state and do not determine routing; the Loop adds node identity, time, and event ordinal. Late writes are not accepted after cancellation or node completion. The node's `report(update, context)` at completion continues to serve supplementary reporting when content is allowed. For the contract, see [Child log instances](observability.md#sub-log-instances-and-record-first-then-complete).
+`run(state, context)` can call `context.report({ usedModel, payload })` to report progress. usedModel is optional boolean metadata about this node itself and remains unknown when not reported; payload is read only when content is allowed. `context.createSubFlowLogger()` returns the unique logger for this execution; write/fix commit automatically and readAll is a read-only query for any holder. write records the intent first and returns an ID, fix adds later results, and readAll returns an immutable snapshot in a fixed format; writes and completions reuse the existing node.progress, and a short circuit or throw still preserves the start record already sent. Reports do not submit business state and do not determine routing; the Loop adds node identity, time, and event ordinal. After cancellation or node completion, the detached logger returns write=-1 and fix=false without throwing; readAll remains readable. The node's `report(update, context)` at completion continues to serve supplementary reporting when content is allowed. For the contract, see [Child log instances](observability.md#sub-log-instances-and-record-first-then-complete).
 
 ## Node caches
 
@@ -196,3 +196,7 @@ context.cache belongs to the current node. Only get(key, { nodeId }) may read an
 Optional Engine option agentCache accepts an AgentCachePort. context.agentCache exposes asynchronous get/has/set/delete/clear, or is absent when no port is supplied. The App receives immutable addresses with nodeId, key, persistence and signal; clear receives an address without key. Port callbacks retain their receiver. Cancellation is checked before dispatch and after completion; it does not roll back an App write already started.
 
 Persistence defaults to false. Passing true requires supportsPersistence: true; otherwise the call rejects. Volatile and persistent spaces are independent, with no fallback or mirroring. The App owns capacity, TTL, serialization, user isolation and storage. Cache partitions are not authorization boundaries. Fork resume may explicitly return agentCache to restore a borrowed port; it is never inherited implicitly. Cache data is not checkpoint state or durable business evidence, and captured views must not be used after cancellation.
+
+## Developer aids: workflow graphs and execution chains
+
+These readonly exports do not participate in Agent scheduling or business execution. `toGraph()` exports registered topology; `toChain(runId)` aggregates observed main-node visits and retains ordered subflow records. See [Workflow graphs and execution chains](workflow-views.en.md) for fields, sources, coverage and consumer responsibilities.

package/development/docs/api/workflow.md

@@ -177,7 +177,7 @@ Workflow 统一处理已有配置中的标识冲突和占位符，缺失的标
 ## 节点报告
 
 Loop 自动记录节点进入、跳转、完成和异常。节点需要补充业务细节时，可在定义中提供
-`report(update, context)`，返回 `{ usedModel, payload, subs }`，各字段均可省略。`subs` 是该次执行上下文提供的 `SubFlowLogger` 实例。这个完成回调只在诊断允许内容时调用，读取的是状态更新的副本；需要在元数据模式下保留的 `usedModel` 应在运行中通过 `context.report` 提交。
+`report(update, context)`，返回 `{ usedModel, payload }`，各字段均可省略。子日志通过 `context.createSubFlowLogger()` 绑定当前执行，write／fix 自动实时入账，无需返回或提交实例。这个完成回调只在诊断允许内容时调用，读取的是状态更新的副本；需要在元数据模式下保留的 `usedModel` 应在运行中通过 `context.report` 提交。
 Loop 将这些补充信息附在节点的完成或跳转记录上。报告失败时，原节点事件仍然记录。
 
 
@@ -186,7 +186,7 @@ Loop 将这些补充信息附在节点的完成或跳转记录上。报告失败
 
 ### 节点运行中的报告
 
-`run(state, context)` 可调用 `context.report({ usedModel, payload, subs })` 报告进度。usedModel 是本次节点自身的可选布尔元数据，未上报保持未知；payload 和 subs 仅在内容获准时读取。subs 必须为 `context.createSubFlowLogger()` 创建的本次执行实例，不能提交手写数组。write 先记意图并返回 ID，fix 补后续结果，readAll 返回固定格式不可变快照；写入和补全复用现有 node.progress，短路或抛错也保留已送出的起始记录。报告不提交业务状态，也不决定路由；Loop 补齐节点身份、时间及事件序号。取消或节点结束后不接纳迟到写入。结束时的节点 `report(update, context)` 继续用于内容获准时的补充报告。合同见[子日志实例](observability.md#子日志实例与先记后补)。
+`run(state, context)` 可调用 `context.report({ usedModel, payload })` 报告进度。usedModel 是本次节点自身的可选布尔元数据，未上报保持未知；payload 仅在内容获准时读取。`context.createSubFlowLogger()` 创建本次执行唯一实例，write／fix 自动入账，无需在报告中提交；readAll 向任何实例持有者提供只读查询。write 先记意图并返回 ID，fix 补后续结果，readAll 返回固定格式不可变快照；写入和补全复用现有 node.progress，短路或抛错也保留已送出的起始记录。报告不提交业务状态，也不决定路由；Loop 补齐节点身份、时间及事件序号。取消或节点结束后 logger 解绑，write 返回 -1、fix 返回 false 且不报错，readAll 持续可读。结束时的节点 `report(update, context)` 继续用于内容获准时的补充报告。合同见[子日志实例](observability.md#子日志实例与先记后补)。
 
 ## 节点缓存
 
@@ -209,3 +209,7 @@ if (context.agentCache) {
 agentCache 每个操作默认 persistence: false；true 必须由 supportsPersistence: true 的 App 端口明确支持，否则拒绝。两种空间不回退、不镜像，delete／clear 仅影响指定空间及当前分区。App 负责容量、TTL、序列化、用户／租户隔离和持久化。节点分区不是授权边界，不复用权限结论。
 
 缓存不进入 checkpoint／状态／Durable 恢复。fork 的 resume 可显式返回 agentCache 重新绑定 App 端口；默认不继承。需要重放或持久业务事实的数据仍使用原 state 补丁或 App 存储。取消后不可继续使用捕获的节点缓存视图。
+
+## 开发辅助：工作流图与执行链
+
+这两个只读导出接口不参与 Agent 的实际调度或业务执行。`toGraph()` 导出注册拓扑，`toChain(runId)` 读取并聚合真实主节点执行，节点内部保留有序 subflow。字段、数据源、覆盖与展示边界见[工作流图与执行链](workflow-views.md)。

package/development/skills/agent-core-app/SKILL.md

@@ -74,3 +74,19 @@ A custom response collector is synchronous and request-local. Its outputChars mu
 ## Node cache ownership
 
 Use context.cache for bounded Engine memory; its default capacity is 1024, partitions are node-local and only get may name another node. The low-level step partition is `$step`. An App may explicitly inject an asynchronous AgentCachePort for context.agentCache. Persistence must be supported explicitly, is separate from volatile storage and never falls back. The App owns user isolation, serialization, capacity and expiry; do not cache authorization decisions. Forks start with empty Engine memory and only regain an App port when resume explicitly supplies agentCache. Keep durable facts in state/App storage, not caches.
+
+## Optional definition decorators
+
+Use the standard-only /support/decorators entry for class-based definitions or existing host methods. Classes supply original options except id; the decorator constructs once and supplies id. Host methods bind and register automatically during standard instance initialization; read and execute only after successful construction. Constructor failures do not roll back initializer registration. Use long-lived service hosts, never request-scoped ones. Keep helper methods/private fields in their real class, never a duplicate options metadata block or empty carrier. Existing Nest legacy compilation keeps object definitions. No public metadata-plus-function adapters, Engine factories, automatic DI or request lifecycle wrappers are provided. Use nodePool/toolPool/fragmentPool/workflowPool/agentPool/modelPool, without creating pools or manually registering. Decorator ns is a string or string array, default 'default'; same-kind ids are unique within a namespace. Read get(id, ns?), getAll(ns?) or pick(ids, ns?); get may return undefined. Multi-namespace registration shares one definition and preflights all conflicts. ESM/CJS copies share readers within one realm. Read api/decorators.md for registration, receivers and type limits.
+
+## Optional native sub-flow logging
+
+Use the active context's createSubFlowLogger() when the App chooses to record a node's internal execution. Pass logger explicitly to documented native model/tool requests or Kit execution contexts for fixed lifecycle records; omission adds no native sub-log and does not enable implicit downstream propagation. Keep business steps App-owned. Every successful fix appends its own operation=fix record with a new stepId, append sequence and timestamp, referencing the original write via targetStepId. readAll returns the complete immutable ledger, not a merged view. Detached write returns -1, failed/detached fix returns false, and retained instances remain readable. Follow the shipped API observability chapter for producer-specific call signatures and content policy.
+
+Use subnodeId for grouping and type for an arbitrary business log type; operation alone is write/fix. A node may write subnodeId directly or fork a ScopedSubFlowLogger for helper functions. The scoped class delegates to the original and owns no storage; both readAll methods read the full ledger. Scoped writes cannot override the group, scoped fixes cannot revise other groups, and the scoped class cannot fork or be passed to native invoke. Pass the original full logger to actual invocations so Core binds the real invocation identity. Fix has an explicit patch whitelist; forbidden fields and ownership failures return false with safe deduplicated developer warnings.
+
+Registered subnode IDs use kind:URL-encoded-definition-id:ordinal within one node visit. Ordinals are allocated at call start per kind/definition and are not reused after failure/cancellation; a new node visit resets them. relatedInvocationId separately links the actual invocation. Do not require callers to parse parent span or invocation UUIDs from subnodeId.
+
+### Workflow graph and chain exports
+
+Use `workflow.toGraph()` for registered topology and `await workflow.toChain(runId)` with an App-authorized `chainSource` (or per-call source) for observed visits. Keep routes getters pure. Do not infer tool/subnode topology from handler bodies, merge visits by nodeId, infer handoffs from adjacency, or fold fix records in Core. Keep ordered flat subflow; consumers own grouping and rendering. See `../../docs/api/workflow-views.md`.

package/dist/cjs/capabilities/invocation.js

@@ -11,6 +11,7 @@ exports.executeInvocation = executeInvocation;
  *
  * Exports: `executeInvocation` and the invocation contracts re-exported at the bottom.
  */
+const native_sub_flow_js_1 = require("../diagnostics/native-sub-flow.js");
 const invocation_js_1 = require("../utils/invocation.js");
 const synchronous_js_1 = require("../utils/synchronous.js");
 const index_js_1 = require("../diagnostics/index.js");
@@ -31,12 +32,30 @@ const reporting_js_1 = require("../execution/reporting.js");
  *   signal checks.
  */
 function executeInvocation(invocation, input, context, ports = {}) {
+    let logger;
+    try {
+        logger = ports.logger?.(context);
+    }
+    catch {
+        /* Optional recording cannot block execution. */
+    }
+    const callId = (0, invocation_js_1.invocationId)();
+    return (0, native_sub_flow_js_1.nativeSubFlowSync)({
+        logger,
+        invocationId: callId,
+        get signal() {
+            return ports.signal?.(context);
+        },
+    }, 'invocation', invocation.id, (scopedLogger) => runInvocation(invocation, input, context, ports, scopedLogger, callId));
+}
+/** Execute the existing synchronous lifecycle without changing journal or error precedence. */
+function runInvocation(invocation, input, context, ports, logger, executionId = (0, invocation_js_1.invocationId)()) {
     const toolId = invocation.id;
     // Identify the call before touching the ports: journal and diagnostics records cannot be
     // reconciled with an anonymous handler.
     if (!toolId?.trim())
         throw new TypeError('Invalid invocation handler identity');
-    const journal = ports.journal?.(context), id = (0, invocation_js_1.invocationId)(), startedAtMs = Date.now();
+    const journal = ports.journal?.(context), id = executionId, startedAtMs = Date.now();
     const diagnostics = ports.diagnostics?.(context)?.child(id, {
         invocationId: id,
         nodeRole: 'invocation',
@@ -67,6 +86,7 @@ function executeInvocation(invocation, input, context, ports = {}) {
         // The helper rejects a promise and drains its rejection: a handler that turns async must
         // fail here instead of escaping as an unhandled rejection.
         (0, synchronous_js_1.synchronous)(invocation.call(input, context, {
+            logger,
             mode: 'sync',
             invocationId: id,
             signal: signal ?? new AbortController().signal,

package/dist/cjs/capabilities/tool-runtime.js

@@ -30,7 +30,14 @@ function execute(definition, input, context, execution) {
         signal.throwIfAborted();
         return value;
     };
-    const operation = { app: context, signal, diagnostics, report, createSubFlowLogger };
+    const operation = {
+        app: context,
+        signal,
+        diagnostics,
+        logger: execution.logger,
+        report,
+        createSubFlowLogger,
+    };
     const authorized = (result) => {
         (0, synchronous_js_1.assertion)(result, 'Tool authorization must return void');
         signal.throwIfAborted();

package/dist/cjs/capabilities/tools.js

@@ -14,6 +14,7 @@ exports.executeInvocation = exports.ToolRegistry = void 0;
  *
  * Exports: `ToolRegistry`, `executeInvocation`, and the tool/invocation contracts.
  */
+const native_sub_flow_js_1 = require("../diagnostics/native-sub-flow.js");
 const events_js_1 = require("../execution/events.js");
 const invocation_js_1 = require("../utils/invocation.js");
 const synchronous_js_1 = require("../utils/synchronous.js");
@@ -119,7 +120,8 @@ class ToolRegistry {
      */
     invoke(request) {
         const call = (0, invocation_js_1.toolInvocation)(request, arguments.length);
-        return this.execute(call.toolId, call.input, false, call.diagnostics, call.signal);
+        const callId = (0, invocation_js_1.invocationId)();
+        return (0, native_sub_flow_js_1.nativeSubFlowSync)({ ...call, signal: (0, cancellation_js_1.combineSignals)(this.ports.signal, call.signal), invocationId: callId }, 'tool', call.toolId, (scopedLogger) => this.execute(call.toolId, call.input, false, call.diagnostics, call.signal, scopedLogger, callId));
     }
     /**
      * Invoke a registered tool and await its result.
@@ -131,7 +133,8 @@ class ToolRegistry {
      */
     async invokeAsync(request) {
         const call = (0, invocation_js_1.toolInvocation)(request, arguments.length);
-        return (await this.execute(call.toolId, call.input, true, call.diagnostics, call.signal));
+        const callId = (0, invocation_js_1.invocationId)();
+        return (0, native_sub_flow_js_1.nativeSubFlowAsync)({ ...call, signal: (0, cancellation_js_1.combineSignals)(this.ports.signal, call.signal), invocationId: callId }, 'tool', call.toolId, (scopedLogger) => this.execute(call.toolId, call.input, true, call.diagnostics, call.signal, scopedLogger, callId));
     }
     /**
      * Run one call: validate, parse input, execute, parse output, then record the outcome.
@@ -143,7 +146,7 @@ class ToolRegistry {
      * @param requestSignal Per-call signal, combined with the request-lifetime signal.
      * @returns The frozen result on success; every failure path throws.
      */
-    execute(name, input, asynchronous, parentDiagnostics = this.diagnostics, requestSignal) {
+    execute(name, input, asynchronous, parentDiagnostics = this.diagnostics, requestSignal, logger, callId = (0, invocation_js_1.invocationId)()) {
         // A tool call stays inside the run that invoked it: mixing two diagnostic trees would
         // produce records with two parents and break run-scoped correlation.
         if (this.diagnostics?.identity?.runId &&
@@ -155,7 +158,7 @@ class ToolRegistry {
             throw this.ports.unavailable?.(name) ?? new Error(`Tool is not registered: ${name}`);
         // Either signal may cancel the call; combining them keeps both lifetimes effective.
         const signal = (0, cancellation_js_1.combineSignals)(this.ports.signal, requestSignal);
-        const invocationId = (0, invocation_js_1.invocationId)();
+        const invocationId = callId;
         const diagnostics = parentDiagnostics?.child(invocationId, {
             invocationId,
             nodeRole: 'invocation',
@@ -193,24 +196,15 @@ class ToolRegistry {
         };
         const succeed = (result) => {
             signal.throwIfAborted();
-            let debug = reports.debug();
             if (tool.debugSteps && diagnostics?.enabled('tool.result', 'content')) {
                 try {
-                    debug = reports.debug({
-                        subs: (0, synchronous_js_1.synchronous)(tool.debugSteps(result, reporting), 'Tool debug reports must be synchronous'),
-                    });
+                    (0, synchronous_js_1.synchronous)(tool.debugSteps(result, reporting), 'Tool debug reports must be synchronous');
                 }
-                catch (error) {
-                    // Debug material is optional evidence: it must not turn a successful tool call into
-                    // a failure. Defer the error until a consumer actually asks for the sub-steps.
-                    debug = {
-                        usedModel: reports.debug().usedModel,
-                        subSteps: () => {
-                            throw error;
-                        },
-                    };
+                catch {
+                    diagnostics?.emit('node.progress', () => ({ reportError: 'INVALID_NODE_REPORT' }));
                 }
             }
+            const debug = reports.debug();
             signal.throwIfAborted();
             reports.close();
             diagnostics?.emit('tool.result', () => ({
@@ -280,6 +274,7 @@ class ToolRegistry {
             signal.throwIfAborted();
             phase = 'execute';
             const value = tool.execute(parsed, {
+                logger,
                 mode: asynchronous ? 'async' : 'sync',
                 invocationId,
                 signal,

package/dist/cjs/diagnostics/index.js

@@ -14,7 +14,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.reportedStepStatuses = exports.reportedStepStatusCatalog = void 0;
+exports.reportedStepStatuses = exports.reportedStepStatusCatalog = exports.ScopedSubFlowLogger = exports.SubFlowLogger = void 0;
 exports.createDiagnostics = createDiagnostics;
 exports.diagnosticError = diagnosticError;
 exports.normalizeDiagnosticEvent = normalizeDiagnosticEvent;
@@ -37,6 +37,9 @@ const sub_flow_js_1 = require("./sub-flow.js");
 const rules_js_1 = require("../utils/rules.js");
 __exportStar(require("../structs/diagnostics.js"), exports);
 __exportStar(require("./catalog.js"), exports);
+var sub_flow_js_2 = require("./sub-flow.js");
+Object.defineProperty(exports, "SubFlowLogger", { enumerable: true, get: function () { return sub_flow_js_2.SubFlowLogger; } });
+Object.defineProperty(exports, "ScopedSubFlowLogger", { enumerable: true, get: function () { return sub_flow_js_2.ScopedSubFlowLogger; } });
 var debug_js_2 = require("../structs/debug.js");
 Object.defineProperty(exports, "reportedStepStatusCatalog", { enumerable: true, get: function () { return debug_js_2.reportedStepStatusCatalog; } });
 Object.defineProperty(exports, "reportedStepStatuses", { enumerable: true, get: function () { return debug_js_2.reportedStepStatuses; } });
@@ -129,7 +132,7 @@ function normalizeDiagnosticEvent(input) {
     // The count and size bounds match what the sub-flow logger enforces, so a record produced by
     // Core can never be rejected here; only hand-edited or foreign records can.
     if (!Array.isArray(steps) ||
-        steps.length > 256 ||
+        steps.length > 1024 ||
         new Set(steps.map((step) => step?.stepId)).size !== steps.length ||
         steps.some((step) => !step ||
             step.origin !== 'reported' ||
@@ -140,7 +143,15 @@ function normalizeDiagnosticEvent(input) {
             !Number.isSafeInteger(step.sequence) ||
             step.sequence < 1 ||
             (step.status !== undefined && !debug_js_1.reportedStepStatuses.includes(step.status)) ||
-            ['parentStepId', 'relatedDefinitionId', 'caseId', 'summary'].some((key) => step[key] !== undefined && typeof step[key] !== 'string') ||
+            [
+                'type',
+                'subnodeId',
+                'parentStepId',
+                'relatedDefinitionId',
+                'relatedInvocationId',
+                'caseId',
+                'summary',
+            ].some((key) => step[key] !== undefined && typeof step[key] !== 'string') ||
             (step.usedModel !== undefined && typeof step.usedModel !== 'boolean') ||
             (step.revision !== undefined &&
                 (!Number.isSafeInteger(step.revision) ||
@@ -155,6 +166,37 @@ function normalizeDiagnosticEvent(input) {
             (!Number.isSafeInteger(raw.subStepsDropped) || Number(raw.subStepsDropped) < 0)) ||
         (raw.subStepsTruncated !== undefined && typeof raw.subStepsTruncated !== 'boolean'))
         throw new TypeError('Invalid reported diagnostic steps');
+    const originals = new Map();
+    let lastSequence = 0;
+    for (const step of steps) {
+        if (step.operation === undefined)
+            continue; // Historical projected snapshots remain readable.
+        (0, rules_js_1.breakWhile)(!['write', 'fix'].includes(step.operation) || step.sequence <= lastSequence, () => new TypeError('Invalid sub-flow record order'));
+        lastSequence = step.sequence;
+        if (step.operation === 'write') {
+            (0, rules_js_1.breakWhile)(step.targetStepId !== undefined || step.revision !== 1, () => new TypeError('Invalid sub-flow write record'));
+            originals.set(step.stepId, {
+                revision: 1,
+                subnodeId: step.subnodeId,
+                type: step.type,
+                relatedInvocationId: step.relatedInvocationId,
+            });
+        }
+        else {
+            const previous = originals.get(step.targetStepId);
+            (0, rules_js_1.breakWhile)(previous === undefined ||
+                step.revision !== previous.revision + 1 ||
+                step.subnodeId !== previous.subnodeId ||
+                step.type !== previous.type ||
+                step.relatedInvocationId !== previous.relatedInvocationId, () => new TypeError('Invalid sub-flow fix reference'));
+            originals.set(step.targetStepId, {
+                revision: step.revision,
+                subnodeId: step.subnodeId,
+                type: step.type,
+                relatedInvocationId: step.relatedInvocationId,
+            });
+        }
+    }
     // Structural check only: the returned snapshot is discarded because the clone below already
     // produces the detached copy kept by the normalized record.
     for (const step of steps)
@@ -167,8 +209,14 @@ function normalizeDiagnosticEvent(input) {
         (0, rules_js_1.breakWhile)(progress !== undefined &&
             (!progress ||
                 !['write', 'fix'].includes(progress.operation) ||
+                ['type', 'subnodeId', 'relatedInvocationId'].some((key) => progress[key] !== undefined &&
+                    typeof progress[key] !== 'string') ||
                 typeof progress.stepId !== 'string' ||
                 !progress.stepId ||
+                (progress.targetStepId !== undefined &&
+                    (progress.operation !== 'fix' ||
+                        typeof progress.targetStepId !== 'string' ||
+                        !progress.targetStepId)) ||
                 !Number.isSafeInteger(progress.sequence) ||
                 progress.sequence < 1 ||
                 !Number.isSafeInteger(progress.revision) ||

package/dist/cjs/diagnostics/native-sub-flow.js

@@ -0,0 +1,106 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.nativeSubFlowCatalog = void 0;
+exports.nativeSubFlowSync = nativeSubFlowSync;
+exports.nativeSubFlowAsync = nativeSubFlowAsync;
+const sub_flow_js_1 = require("./sub-flow.js");
+/** Fixed metadata shared by native producers; pure getters and formatters are not producers. */
+exports.nativeSubFlowCatalog = {
+    model: { name: 'Model call', kind: 'model', type: 'model.call' },
+    tool: { name: 'Tool call', kind: 'tool', type: 'tool.call' },
+    invocation: { name: 'Invocation', kind: 'invocation', type: 'handler.call' },
+    retrieval: { name: 'Retrieval', kind: 'retrieval', type: 'retrieval.run' },
+    task: { name: 'Read answer evidence', kind: 'retrieval', type: 'evidence.read' },
+    check: { name: 'Check answer', kind: 'validation', type: 'answer.check' },
+    output: { name: 'Compose output', kind: 'presentation', type: 'output.compose' },
+    answer: { name: 'Answer flow', kind: 'answering', type: 'answer.run' },
+    retry: { name: 'Retry model proposal', kind: 'recovery', type: 'model.retry' },
+    context: { name: 'Process context', kind: 'context', type: 'context.process' },
+    recovery: { name: 'Recovery attempt', kind: 'recovery', type: 'recovery.try' },
+    delivery: { name: 'Deliver result', kind: 'delivery', type: 'delivery.run' },
+    aggregation: { name: 'Aggregate queries', kind: 'retrieval', type: 'queries.collect' },
+    knowledge: { name: 'Read knowledge', kind: 'retrieval', type: 'knowledge.read' },
+};
+/** Start one fixed record; its revision is best-effort and never controls the operation. */
+function begin(context, producer, id) {
+    let logger;
+    try {
+        logger =
+            context.logger instanceof sub_flow_js_1.SubFlowLogger
+                ? (0, sub_flow_js_1.bindNativeSubFlowLogger)(context.logger, producer, id)
+                : context.logger;
+    }
+    catch {
+        /* A recording limit must not turn a valid operation into a failure. */
+    }
+    let step = -1;
+    try {
+        if (logger)
+            step = logger.write({
+                ...exports.nativeSubFlowCatalog[producer],
+                relatedDefinitionId: id,
+                ...(context.invocationId === undefined
+                    ? {}
+                    : { relatedInvocationId: context.invocationId }),
+                status: 'running',
+            });
+    }
+    catch {
+        /* Optional recording must not change execution. */
+    }
+    return {
+        logger,
+        finish: (status) => {
+            try {
+                if (logger && step !== -1)
+                    logger.fix(step, { status });
+            }
+            catch {
+                /* A broken or detached logger cannot replace the operation result. */
+            }
+        },
+    };
+}
+/** Signal access is diagnostic metadata and cannot replace an operation failure. */
+function failureStatus(context) {
+    try {
+        return context.signal?.aborted ? 'cancelled' : 'error';
+    }
+    catch {
+        return 'error';
+    }
+}
+/** Preserve a synchronous boundary while pairing an optional write with one result revision. */
+function nativeSubFlowSync(context, producer, id, invoke) {
+    if (producer === 'model' || producer === 'tool' || producer === 'invocation')
+        (0, sub_flow_js_1.requireSubFlowLogger)(context.logger);
+    if (!context.logger)
+        return invoke();
+    const { logger, finish } = begin(context, producer, id);
+    try {
+        const value = invoke(logger);
+        finish('success');
+        return value;
+    }
+    catch (error) {
+        finish(failureStatus(context));
+        throw error;
+    }
+}
+/** Await the original operation without introducing another timeout or cancellation race. */
+async function nativeSubFlowAsync(context, producer, id, invoke) {
+    if (producer === 'model' || producer === 'tool' || producer === 'invocation')
+        (0, sub_flow_js_1.requireSubFlowLogger)(context.logger);
+    if (!context.logger)
+        return invoke();
+    const { logger, finish } = begin(context, producer, id);
+    try {
+        const value = await invoke(logger);
+        finish('success');
+        return value;
+    }
+    catch (error) {
+        finish(failureStatus(context));
+        throw error;
+    }
+}