ai-workflow-flow-dsl-reference 0.1.0

package/dist/resource-module/content/std/ai-data-workflow/axioms.md

@@ -0,0 +1,24 @@
+# L2 · AIDataWorkflow axioms
+
+`AIDataWorkflow` is an EagerDataFlow-backed AI workflow profile. It uses EagerDataFlow DAG nodes as the authoring substrate and adds a per-run RunGraph for iterative AI coordination.
+
+## Substrate
+
+- Root tag: `<AIDataWorkflow>`.
+- Root `[]`: EagerDataFlow DAG nodes.
+- Root `()`: `FlowContract` plus optional AI workflow resource references.
+- Runtime substrate: EagerDataFlow plan plus AI RunGraph state.
+
+The definition owns topology and static node config. The RunGraph owns runtime status, patch history, generation history, invalidation records and reuse records.
+
+## RunGraph
+
+Every run has its own mutable RunGraph. A graph patch creates a new generation and records the operation. Mature edits can be promoted by a higher-level authoring workflow, but runtime patch history is not itself the definition.
+
+## Invalidation
+
+When a completed node changes, the changed node and its transitive downstream dependents are invalidated. Old outputs are retained as historical generation results.
+
+## Reuse
+
+The default machine-node reuse policy is `semantic-hash`; manual nodes default to `never`. A canonical manual node is authored with `config = { node_type = "manual" }`; the EagerDataFlow `type` field remains an implementation binding and is not reinterpreted. Reuse is run-local unless a separate shared cache authority is introduced. Generation records history and does not enter the semantic fingerprint.

package/dist/resource-module/content/std/behavior-tree/axioms.md

@@ -0,0 +1,72 @@
+# L2 领域公理 · 内部 BehaviorTreePlan
+
+> BehaviorTreePlan 是 CtrlFlow compiler 的内部执行投影，不是 XNL authoring DSL。编号 `BT-*`；继承 L1 全部公理，但不新增公开文件、root、domain、URI 或 statement。
+
+## BT-1 · Definition 是真源，plan 是派生物
+
+控制流数据链固定为：
+
+```text
+XNL product definition
+  -> canonical FlowSpec / CtrlFlow AST
+  -> BehaviorTreePlan
+  -> profile engine
+```
+
+产品 definition 的根 `[]` 与嵌套 body `[]` 是执行顺序真源。BehaviorTreePlan 必须可由 definition 机械重建，不得被持久化、编辑或加载为另一种 authoring definition。
+
+## BT-2 · 编译映射不泄漏到 authoring
+
+内部 plan 可以复用行为树 engine 的节点 kind；这些名字只存在于 compiler/engine contract：
+
+| public CtrlFlow fact | internal projection |
+|---|---|
+| 根或 body 的有序 statements | `Sequence` plan node |
+| `If` + ordered Branches | `Selector`，每个 Branch 投影为 `Sequence(Condition(predicate), body)`；Otherwise 是末尾无条件 body |
+| `Fallback` + ordered Strategy | `Selector`，只按 technical success/failure 选择 |
+| `Until.when` + body | `Until` plan node + predicate code leaf + body plan |
+| `Run` | code action leaf |
+| `Return` | terminal output leaf |
+
+该映射是实现策略，不构成公开语法承诺。compiler 可以替换内部节点形态，只要 CtrlFlow 的 observable semantics 不变。
+
+## BT-3 · 三个维度必须正交
+
+内部 engine 不得再用一个二值结果同时表达业务结果、技术失败和生命周期挂起：
+
+- **data**：`Run` output、TaskStep 的 approved/refused/forwarded 等业务结果；正常作为后续 statement/predicate 的 input。
+- **fault**：代码异常、不可恢复 effect 错误、协议错误、循环 guard 超限；驱动 Fallback 或向外传播。
+- **suspension**：WorkCtrlFlow/BPCtrlFlow 的 timer、external job、human task 等等待；由 profile runtime 快照与恢复，不等于 fault。
+
+内部 plan 若使用 `Success` / `Failure` / `Running` 等 engine 状态，adapter 必须保持上述区分：业务 data 不能映射成 Failure，挂起也不能被当成 strategy 失败。
+
+## BT-4 · 条件决策是可观察事实
+
+`Branch.when` 与 `Until.when` 都由动态代码按 `output = fn(runtime, input, config)` 求值。compiler 只能生成调用 predicate 的内部叶子，不得把 predicate 复制成表达式字符串或第二份条件定义。
+
+InstantCtrlFlow 可以只在本次执行内持有决策；WorkCtrlFlow/BPCtrlFlow 对已发生 branch selection 必须记录或快照。恢复时 plan 可以重建，但已发生路径不能因 predicate 重算而变化。
+
+## BT-5 · Fallback 只消费技术结果
+
+Fallback 的内部 Selector 只观察 strategy 是否发生技术 fault：
+
+- strategy 正常返回任意业务 data 都是 technical success，停止 fallback。
+- strategy fault 才允许尝试下一项。
+- 全部 strategy fault 时向外传播聚合 fault。
+- suspension 保持当前 strategy 的执行位置，恢复后继续该 strategy，不得偷换到下一项。
+
+这条约束防止内部行为树常见的 success/failure 组合语义反向污染公开业务语言。
+
+## BT-6 · 运行态归 profile owner
+
+BehaviorTreePlan 只描述可执行结构，不拥有实例真源：
+
+- WorkCtrlFlow/BPCtrlFlow snapshot 拥有节点位置、等待句柄和已记录决策。
+- TaskSpace store 拥有人工任务状态与业务结果。
+- editor runtime overlay 只读投影 plan/snapshot 状态，不回写 definition。
+
+plan 节点 path、内部状态枚举和调试 metadata 都是 runtime/compiler 细节，不得出现在 canonical XNL definition 中。
+
+## BT-7 · Authoring Boundary
+
+旧行为树 root、公开组合节点和动作类型目录已从 authoring surface 移除。校验器若在产品 definition 中发现这些结构必须拒绝；只有 compiler 生成的内存 BehaviorTreePlan 能使用内部 kind。

package/dist/resource-module/content/std/bp-ctrl-flow/axioms.md

@@ -0,0 +1,48 @@
+# L2 领域公理 · BPCtrlFlow（人工任务控制流）
+
+> 编号 `BP-*`。继承 L1、[共享 CtrlFlow grammar](../../spec/flow-core/nodes.md)与 [WorkCtrlFlow lifecycle](../work-ctrl-flow/axioms.md)。容器根是 `<BPCtrlFlow>`；只增加 TaskSpace 与 TaskStep 能力。
+
+## BP-1 · TaskSpace 是独立业务事实源
+
+`task.space` 域承载 `TaskSpace -> TaskGroup / Task` 层级与任务状态。TaskSpace store 拥有当前 owner、操作历史、状态和业务 payload；flow snapshot 只保存 TaskStep 的执行位置、等待句柄与已消费结果，不复制或反向覆盖任务事实。
+
+TaskGroup 用 `executionMode = SEQUENTIAL | ANY | ALL` 聚合子任务。任务状态机与组聚合属于任务域，不发明 CtrlFlow 组合节点。
+
+## BP-2 · TaskStep 是唯一生命周期桥
+
+`TaskStep.task = "task-space://#<id>"` 绑定 TaskSpace 的一个直接子节点。首次进入时激活绑定任务、登记任务 WaitHandle、保存 WorkCtrlFlow snapshot 并挂起；合法人工操作到达可恢复结果后，TaskStep 输出普通 `TaskStepResult` data：
+
+```text
+{
+  taskId,
+  status,
+  outcome = "approved" | "refused" | "forwarded" | "abandoned",
+  payload
+}
+```
+
+其中 approve 操作可对应任务终态 `Done`，但 flow 观察到的业务 outcome 是 `approved`。`refused`、`forwarded`、`abandoned` 与 `approved` 一样都是正常 output，不映射成技术 Failure。TaskStep 不使用 `assignTo`；result 直接成为下一条 statement 的 input。
+
+## BP-3 · 任务操作、fault 与 suspension 正交
+
+- approved/refused/forwarded/abandoned：业务 data，由后续 predicate 决定路径。
+- 非法状态迁移、任务存储不可用、恢复协议损坏：技术 fault，可向外传播或由 Fallback 处理。
+- 等待人工操作：suspension，保存 snapshot 后停止当前 tick；既不是 data，也不是 fault。
+
+因此 Fallback 不能把 refused 当作 strategy 失败，内部 engine 也不能用 Failure 偷换任务业务结果。
+
+## BP-4 · 业务路径统一使用 `If`
+
+TaskStep 后的审批、拒绝、转交和升级路径一律使用公共 `If` / `Branches` / `Branch` / `Otherwise`。`Branch.when` 读取 TaskStepResult，并严格遵守 `boolean = fn(runtime, input, config)`；不定义审批专用条件节点或另一套公开条件 authoring。
+
+WorkCtrlFlow 的 branch decision 规则完整适用：一旦 outcome 已选择 Branch，decision 在进入 body 前持久化，后续恢复不得重算已发生路径。
+
+## BP-5 · 人工操作通过 ResumeSignal 进入实例
+
+任务服务先按状态机验证并持久化操作，再向对应 TaskStep WaitHandle 投递幂等 ResumeSignal。UI、通知渠道和组织架构不属于 flow 协议；`ownerAccount` 是任务域的不透明业务值。
+
+重复操作或重复 ResumeSignal 不得重复推进流程。TaskSpace store 与 flow snapshot 的更新必须通过 runtime 的一致性策略关联，不能靠回写 definition 达成同步。
+
+## BP-6 · BPCtrlFlow 是 WorkCtrlFlow capability 超集
+
+BPCtrlFlow 支持 WorkCtrlFlow 的 `ExternalJob`、`Timer`、snapshot/resume 与 branch decision，并追加 `TaskSpace` / `TaskStep`。不使用 TaskStep 的 BPCtrlFlow 仍遵守相同 CtrlFlow grammar 和 WorkCtrlFlow lifecycle；它不会获得另一套 authoring 语言。

package/dist/resource-module/content/std/eager-data-flow/axioms.md

@@ -0,0 +1,57 @@
+# L2 · EagerDataFlow 公理
+
+> EagerDataFlow 是一次调用内主动求值的 DAG 产品。它与 CtrlFlow 的有序 statement 语义、前端 DataGraph 的长生命周期 lazy signal 语义彼此独立。
+
+## EDF-1 · 公开根唯一命名为 EagerDataFlow
+
+可执行 definition 的根是 `<EagerDataFlow>`。根 `[]` 直接保存 DAG nodes；`()` 只保存每种 tag 最多一个的唯一子域，例如 `FlowContract` 或 `FlowAuthoring`。`<DataFlow>` 是已移除的旧根，loader 必须拒绝，不能把它当作 alias。
+
+## EDF-2 · FlowContract 封闭调用边界
+
+每个 EagerDataFlow 有且只有一个 `FlowContract`。它声明公开 input/output type 和端口名；唯一 `EntryNode` 从 input ports 暴露调用输入，唯一 `ReturnNode` 用与 output ports 完全相同的 key 组装调用输出。
+
+调用者不能穿透 flow 内部节点。跨 flow 组合只能通过 `SubFlowNode`，其 inputs 和 outputs 分别由目标 `FlowContract` 的 inputPorts 和 outputPorts 派生。
+
+## EDF-3 · 数据边与完成边是两类事实
+
+`inputs` 中的 `flow-port://#node/port` 产生 data edge；`waitFor` 中的 `flow-node://#node` 产生 completion edge。两类边必须分别保存在 authoring plan 中，并共同参加拓扑无环校验。
+
+即使相同两个节点之间已有 data edge，显式 completion edge 仍然保留。它表达作者要求的完成依赖，不能被编译器归一化、去重或改写成隐式顺序。
+
+## EDF-4 · Eager 表示一次调用内主动收敛
+
+每次 flow invocation 都创建独立运行态；每个节点最多执行一次。节点在全部 input port 已有值且全部 waitFor 目标成功完成后 ready。调度器必须尽快启动所有 ready 节点，因此互不依赖的 ready 节点可以并发运行；根 `[]` 的声明顺序只提供稳定 identity 和诊断顺序，不是执行顺序。
+
+一次调用成功要求所有已定义节点成功完成，并由 ReturnNode 产生公开 output。作者若要求两个副作用的先后顺序，必须声明 data edge 或 waitFor edge，不能依赖数组顺序或运行时碰巧的完成顺序。
+
+## EDF-5 · 端口是不可变的单次赋值数据
+
+节点 output port 在本次 invocation 中只写一次。下游通过具名 input key 读取上游 port；读取视图不可变，节点不能回写上游数据。EntryNode 与 SubFlowNode 的 outputs 来自 FlowContract，TransformNode 显式声明 outputs，SinkNode 和 ReturnNode 不暴露内部 output port。
+
+## EDF-6 · 动态代码遵守 DEPA 四边界
+
+TransformNode 和 SinkNode 的实现统一遵守：
+
+```text
+output = fn(runtime, input, config)
+```
+
+`runtime` 显式提供长生命周期依赖和 effect；`input` 是按节点 inputs key 组装的只读 record；`config` 是节点静态 map；TransformNode 的 `output` 是与声明 outputs 完全匹配的 record，SinkNode 的 `output` 是 `void`。代码可以异步，调度器必须 await 后才发布 ports 或 completion fact。
+
+## EDF-7 · 技术失败沿 DAG 失败通道传播
+
+节点 throw、fault、缺失 output port、subflow fault 或协议不匹配都会使整个 invocation 技术失败。失败节点不发布 output port，也不发布成功 completion fact；其下游不会 ready。调度器停止启动尚未开始的节点，并向已运行节点传播取消信号；已发生的外部副作用不承诺自动回滚。
+
+业务值始终是普通 port data，不会因为字段名或枚举值自动变成失败。并发节点产生多个 fault 时，runtime 可以保留全部 cause，但对外必须给出稳定的 primary fault 和失败节点 identity。
+
+## EDF-8 · SubFlow 是封闭的嵌套 invocation
+
+SubFlowNode 用 `eager-data-flow://<FQN>` 调用另一个 EagerDataFlow。子流拥有独立节点运行态，只接收映射后的 contract input，只返回 contract output；父流的 `flow-port://`、`flow-node://` 不能穿透边界。
+
+SubFlowNode 只有在子流整体成功时才发布 outputs 和 completion fact。子流技术失败作为该 SubFlowNode 的 fault 向父 DAG 传播。unit 级 subflow 调用图也必须无环；递归不能通过直接或间接 SubFlowNode 表达。
+
+## EDF-9 · EagerDataFlow 不是 lazy signal DataGraph
+
+EagerDataFlow 由显式调用触发，读取固定 invocation input，节点单次执行并终止；它没有 signal state、invalidation、subscription、seed 或因依赖变化而重算的语义。
+
+DataGraph 是被 Scope 装配的长生命周期 reactive runtime，依赖变化可以触发 lazy/增量求值。DataGraph 的 SignalNode、ComputedNode、ProcessorNode、AsyncNode、ConsumerNode 以及 local slot refs 都不属于 EagerDataFlow；EagerDataFlow 的 EntryNode、TransformNode、SinkNode、SubFlowNode、ReturnNode、flow-port 和 waitFor 也不属于 DataGraph。

package/dist/resource-module/content/std/instant-ctrl-flow/axioms.md

@@ -0,0 +1,37 @@
+# L2 领域公理 · InstantCtrlFlow（即时控制流）
+
+> 编号 `IF-*`。继承 L1 与[共享 CtrlFlow grammar](../../spec/flow-core/nodes.md)。容器根是 `<InstantCtrlFlow>`；产品根的 `[]` 直接保存有序 statements。
+
+## IF-1 · 语法不分叉
+
+InstantCtrlFlow 使用公共 `Run`、`If` / `Branches` / `Branch` / `Otherwise`、`Fallback` / `Strategy`、`Until`、`Return` authoring grammar。顺序由根或嵌套 body 的 `[]` 表达，InstantCtrlFlow 不定义自己的条件、顺序或返回方言。
+
+所有 `src` 与 `when` 引用的动态代码都遵守：
+
+```text
+output = fn(runtime, input, config)
+```
+
+`input` 是上一条 statement 的 output，`config` 是 definition 中的静态 map，`runtime` 是引擎显式注入的 effect 能力。不得通过隐式全局或可变 input 补充该协议。
+
+## IF-2 · 一次调用内收敛
+
+InstantCtrlFlow 的生命周期边界是一整次调用。它可以 `await` 本次调用内完成的 IO，但不能返回持久挂起状态，也不能等待另一个 tick、进程或外部恢复消息继续执行。
+
+因此以下能力在 InstantCtrlFlow definition 中非法：
+
+- `ExternalJob`、`Timer`、`TaskStep` 等持久挂起 statement。
+- snapshot、WaitHandle、ResumeSignal 或已应用恢复消息集合。
+- `state.def`、`state.seed`、`task.space` 等跨调用实例事实。
+
+需要这些能力时，作者必须选择 WorkCtrlFlow 或 BPCtrlFlow，而不是给 InstantCtrlFlow 增加例外。
+
+## IF-3 · data 与 fault 分离
+
+一次执行只有两种公开完成结果：正常 output 或技术 fault。`refused`、`declined`、`notFound` 等业务结果是正常 data，可由后续 `If` predicate 读取；代码异常、协议错误和不可恢复 effect 错误才是 fault。
+
+InstantCtrlFlow 没有第三种持久 suspension 结果。引擎内部若使用 Running 等推进状态，它只能存在于当前调用中，不能越过调用边界暴露为可恢复实例。
+
+## IF-4 · 调用间无隐藏状态
+
+每次调用从显式 input、definition config 和显式 runtime 能力开始。引擎不得让上一次调用的执行游标、分支选择或临时 data 隐式影响下一次调用；实现缓存只有在不改变可观察语义时才允许存在。

package/dist/resource-module/content/std/work-ctrl-flow/axioms.md

@@ -0,0 +1,54 @@
+# L2 领域公理 · WorkCtrlFlow（可挂起控制流）
+
+> 编号 `WF-*`。继承 L1 与[共享 CtrlFlow grammar](../../spec/flow-core/nodes.md)。容器根是 `<WorkCtrlFlow>`；与 InstantCtrlFlow 的差异只在持久生命周期能力。
+
+## WF-1 · 共享 grammar，不共享生命周期上限
+
+WorkCtrlFlow 使用与 InstantCtrlFlow 完全相同的 `Run`、`If`、`Fallback`、`Until`、`Return` authoring 语法，并追加两种生命周期 statement：`ExternalJob` 与 `Timer`。根和嵌套 body 的 `[]` 仍是唯一顺序真源，不引入另一套条件或组合语法。
+
+所有动态代码仍遵守 `output = fn(runtime, input, config)`。snapshot/resume 是 profile runtime 的职责，不改变 code ref 的参数顺序、数据链或 fault 约定。
+
+## WF-2 · 只有显式 statement 可以持久挂起
+
+- `ExternalJob` 等待与 `(signalKind, signalKey)` 匹配的外部恢复消息。
+- `Timer` 等待声明的 duration 到期。
+
+进入上述 statement 时，引擎登记包含稳定 statement path 与 resume token 的 open WaitHandle，原子保存 snapshot，然后返回 suspension。`Run`、predicate 和其他公共 statements 必须在当前 tick 内正常返回或产生技术 fault，不能暗中跨 tick 挂起。
+
+## WF-3 · snapshot 是实例真源
+
+snapshot 至少保存：
+
+- definition identity/version 与当前 statement path、嵌套 body frame、循环 invocation 等恢复位置。
+- 当前 data 以及恢复后继续数据链所需的 statement output。
+- open/closed WaitHandle、deadline、resume token 与已应用恢复消息标识。
+- 已发生的 branch decision，键由稳定 `If` path 与 invocation identity 构成。
+- profile runtime 明确声明的持久 state；definition 和 `state.seed` 不被回写。
+
+definition 仍是 authoring topology 真源，snapshot 只拥有某个实例的运行事实。definition 变更若会改变已有 statement path，必须显式迁移在途 snapshot。
+
+## WF-4 · branch decision 先记录，后进入 body
+
+`If` 首次执行某次 invocation 时按共享 grammar 求值，并在进入所选 body 前持久记录 `{ decisionKey, selectedBranchId }`；选择 Otherwise 或无匹配也必须记录为明确值。
+
+实例恢复或内部 plan 重建时：
+
+1. 已有 decision 的 invocation 直接复用记录，不重新调用已发生 Branch predicate。
+2. 尚未发生的 `If` 才按当前 input/config 求值并创建新 decision。
+3. decision 与 snapshot 一起持久化，不能只存在于进程内缓存。
+
+这保证挂起前已经发生的业务路径不会因时间、配置或外部数据变化而改道。
+
+## WF-5 · 恢复消息幂等且不混淆 data/fault
+
+ResumeSignal 必须匹配一个 open WaitHandle 并携带其 resume token。成功恢复的 payload 成为 `ExternalJob` output；`Timer` 到期后透传进入 Timer 的 input。重复 token 幂等，未匹配或已关闭的句柄不得改变 snapshot。
+
+恢复消息的 payload 是普通 data，其中的 `refused`、`cancelled` 等业务字段不会自动变成 fault。只有独立的技术 fault 通道（例如外部作业不可恢复失败、超时 policy 或无效恢复协议）才使 statement 技术失败。suspension 本身既不是 data，也不是 fault。
+
+## WF-6 · 中断等价性
+
+从 snapshot 恢复后的最终结果必须等价于同一恢复消息在原进程中即时到达后的结果，已发生外部副作用的时点除外。恢复必须从保存的 statement 位置、data 和 decision 继续，不能通过重跑整条 authoring definition 猜测现场。
+
+## WF-7 · agent 语义留在协议外
+
+agent、人或远端系统都可以是 ExternalJob 的执行方，但 `AgentTask`、`Questionnaire` 等角色特定节点不进入 WorkCtrlFlow grammar。协议只定义等待与恢复，不定义外部执行者的身份。

package/dist/resource-module/manifest.xnl

@@ -0,0 +1,9 @@
+<ResourcePackage #Depa.Flows.FlowDsl.Reference.Package apiVersion="halfcode.resources/v1" version="1.0.0" {
+  lifecycle = "Stable"
+  description = "Canonical depa Flow DSL documentation reference resources for authoring Skills."
+} (
+  <Catalogs [
+    <Catalog #KindDefinitions { kind = "KindDefinition" shape = "directory" root = "vfs://./KindDefinitions/" entry = "manifest.xnl" }>
+    <Catalog #WikiPages { kind = "WikiPage" shape = "directory" root = "vfs://./WikiPages/" entry = "manifest.xnl" }>
+  ]>
+)>

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "ai-workflow-flow-dsl-reference",
+  "version": "0.1.0",
+  "private": false,
+  "description": "Canonical depa Flow DSL reference module for Halfcode authoring assemblies",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "bun run tools/build.ts",
+    "prepack": "bun run build",
+    "test": "bun run build && bun test"
+  },
+  "dependencies": {
+    "halfcode-compiler.xnl": "0.2.3"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}