ai-workflow-flow-dsl-reference 0.1.2 → 0.1.3

package/dist/resource-module/content/.depa-flow-dsl-provenance.json

@@ -2,10 +2,10 @@
   "schemaVersion": "depa.flow-dsl-reference/v1",
   "moduleId": "DepaFlowsFlowDslReference",
   "packageName": "ai-workflow-flow-dsl-reference",
-  "packageVersion": "0.1.2",
+  "packageVersion": "0.1.3",
   "resourcePackageVersion": "1.0.1",
   "source": "depa-flows/docs/flow-dsl",
-  "sourceTreeDigest": "sha256:c8268e015607846b72e1946147a8ce20b9f4c8e77cafb63ad6508db723b038f2",
+  "sourceTreeDigest": "sha256:eee5a10072a6767915289567d9f6e01e314ee3ad3c1ea2921a257b8119226732",
   "files": [
     {
       "path": "README.md",
@@ -29,7 +29,7 @@
     },
     {
       "path": "spec/ai-workflow/data-workflow.md",
-      "contentDigest": "sha256:8852359bb530f4053257b9bbf4f1a314da3cf8972ade8c9579406eec82d93de6"
+      "contentDigest": "sha256:23a619fb81856f70bb99fba0a33e0b8b6b15012b80392c21269c4fc146287ede"
     },
     {
       "path": "spec/ai-workflow/resources.md",
@@ -69,7 +69,7 @@
     },
     {
       "path": "spec/flow-core/instance-run.md",
-      "contentDigest": "sha256:c9dad759aa68b4b201875ced2fcfd334c1bcac5cd721946cdbb6c4837ac202e0"
+      "contentDigest": "sha256:17f9b48f75197f90510547bd891afb2c3732e4b0a20d420e5fd312e1acb54392"
     },
     {
       "path": "spec/flow-core/nodes.md",
@@ -93,7 +93,7 @@
     },
     {
       "path": "spec/work-ctrl-flow/domains.md",
-      "contentDigest": "sha256:e68b23b44e2330b6378998d00eb23d75484fe2126280dcb78efdfbdc1711b7de"
+      "contentDigest": "sha256:feebd80d291b9c8899d9558fb81e1bf2262277320a9ec542dc8eb2fb6eb176c9"
     },
     {
       "path": "spec/work-ctrl-flow/nodes.md",

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

@@ -40,6 +40,27 @@
 
 `flow-port://#node/port` creates a data dependency. `flow-node://#node` creates a completion dependency through `waitFor`.
 
+## Modular StepSpace form
+
+大型 definition 可以把根内联 nodes 替换为一个精确的 `StepSpaceRef`：
+
+```xnl
+<AIDataWorkflow #depa.examples.SupportEvidenceDag apiVersion="depa.flows/v1" version="1.0.0" (
+  <FlowContract #depa.examples.SupportEvidenceDag {
+    inputPorts = ["ticket"]
+    outputPorts = ["summary"]
+  }>
+  <StepSpaceRef { src = "step-space.xnl" }>
+)>
+```
+
+`step-space.xnl` 通过显式 `StepRef` 定位每个 `step.xnl`；每个 Step 的唯一
+`Core` 保存一个 `EntryNode`、`TransformNode`、`SinkNode`、`SubFlowNode` 或
+`ReturnNode`。loader 将 Core 投影回同一个 canonical EagerDataFlow plan，所以
+ports、dependency edges、declaration order 和 scheduler 语义与等价 inline
+definition 完全相同。StepGroup 只表达 authoring ownership，不推导 DAG edges。
+inline nodes 与 `StepSpaceRef` 同时出现会在 materialization 前关闭失败。
+
 ## RunGraph checkpoint profile
 
 The XNL definition produces an EagerDataFlow authoring plan. At run time, AIDataWorkflow stores a RunGraph inside the run's single `FlowRunCheckpoint` typed profile, with:

package/dist/resource-module/content/spec/flow-core/instance-run.md

@@ -20,6 +20,22 @@ Run checkpoints v0..n
 
 Definition 更新只影响之后创建的 instance。已有 instance 的新 run 和已有 run 的恢复均不得重新读取 live Definition。
 
+## Modular StepSpace definition
+
+Flow root 可以继续在 `[]` 内联 topology，也可以在 `()` 中声明一个精确的
+`<StepSpaceRef { src = "step-space.xnl" }>`；两种 topology authority 不能同时存在。
+`StepSpace` 只通过显式 `StepRef`、`StepGroupRef` 和 step 内的 `ExtensionRef`
+形成闭包，目录名和目录枚举不产生语义成员。所有 ref 都是 bundle-local virtual ref，
+不是宿主物理路径；traversal、symbolic link、重复 id、循环引用、未注册 extension
+或 schema identity 不匹配均在 instance admission 前关闭失败。
+
+每个 `Step` 恰好有一个 `Core`，Core 内保存原 profile 的 canonical statement/node。
+`StepGroup` 是 definition ownership/authoring hierarchy，不是第二个 scheduler：Ctrl 按
+Core hierarchy 投影既有 control tree；Data 的 port、dependency 与 `waitFor` 仍由各
+Core node 事实拥有。`DefinitionStepForest` 是冻结定义投影，不能用作 runtime state
+index。完整显式闭包及其逐文件 digest 随 bundle 复制进 Instance；live source 的后续
+修改或删除不会影响 fresh run/resume。
+
 ## Canonical physical projection
 
 存储根由 runtime 显式注入，不从 Definition 路径、当前工作目录或环境变量推导。reference filesystem projection 为：
@@ -31,6 +47,8 @@ Definition 更新只影响之后创建的 instance。已有 instance 的新 run
       instance.json
       definition/
         manifest.xnl
+        step-space.xnl              # 使用模块化 topology 时
+        steps/<step-id>/step.xnl    # 只由显式 ref 构成闭包
         ...完整 bundle...
       runs/
         <run-id>/

package/dist/resource-module/content/spec/work-ctrl-flow/domains.md

@@ -6,7 +6,8 @@
 
 | fact / domain | file | root / scheme | 说明 |
 |---|---|---|---|
-| `<WorkCtrlFlow>` definition | 单文件或 `manifest.xnl` | 根 `[]` | 共享 CtrlFlow statements，可使用 `ExternalJob` / `Timer` |
+| `<WorkCtrlFlow>` definition | 单文件或 `manifest.xnl` | 根 `[]` 或一个 `StepSpaceRef` | 共享 CtrlFlow statements，可使用 `ExternalJob` / `Timer`；inline 与 StepSpace 互斥 |
+| `step.space` | `step-space.xnl` + 显式 step refs | `<StepSpace>` | 可选 definition ownership forest；不拥有 scheduler 或 run status |
 | `state.def` | `state.def.xnl` | `<StateDef>` / `state-def://` | 可选；声明受版本契约保护的实例 state shape |
 | `state.seed` | `state.seed.xnl` | `<StateSeed>` / `state-seed://` | 可选；新实例的只读初始 state |
 | `task.space` | - | - | 禁用；人工任务事实只属于 BPCtrlFlow |
@@ -24,6 +25,10 @@
 
 实例物化必须在首个节点前冻结完整 definition bundle，以保证 code、facets 与 topology 版本稳定；冻结副本仍不是新的 authoring 入口。每个 run 的 snapshot、input/config/state/output 与 sidecars 由[单一 checkpoint hierarchy](../flow-core/instance-run.md)共同持有。运行状态可以投影到 editor/runtime overlay；不得向 XNL definition 注入 `status`、执行游标或 decision 作为语义事实。
 
+模块化 authoring 中，每个 `Step` 的 `Core` 仍是原 WorkCtrl statement；嵌套
+`Retry`、`Parallel` 等语义继续由 WorkCtrl runtime 解释。`StepGroup` 只组织文件与
+ownership，不能改变 statement 顺序、等待关系或建立另一套执行状态。
+
 ## Rejected Authoring Facts
 
 `tree.xnl`、`action.types.xnl`、`Tree` 根、独立 `CtrlFlow` 根以及公开 `Sequence` / `Selector` / `Condition` 都必须拒绝。snapshot schema、WaitHandle 列表和 branch decision 也不能被伪装成 definition 子域。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-workflow-flow-dsl-reference",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "private": false,
   "description": "Canonical depa Flow DSL reference module for Halfcode authoring assemblies",
   "type": "module",