ai-workflow-flow-dsl-reference 0.1.2 → 0.1.4
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/resource-module/content/.depa-flow-dsl-provenance.json +5 -5
- package/dist/resource-module/content/spec/ai-workflow/data-workflow.md +21 -0
- package/dist/resource-module/content/spec/flow-core/instance-run.md +66 -2
- package/dist/resource-module/content/spec/work-ctrl-flow/domains.md +6 -1
- package/package.json +1 -1
|
@@ -2,10 +2,10 @@
|
|
|
2
2
|
"schemaVersion": "depa.flow-dsl-reference/v1",
|
|
3
3
|
"moduleId": "DepaFlowsFlowDslReference",
|
|
4
4
|
"packageName": "ai-workflow-flow-dsl-reference",
|
|
5
|
-
"packageVersion": "0.1.
|
|
5
|
+
"packageVersion": "0.1.4",
|
|
6
6
|
"resourcePackageVersion": "1.0.1",
|
|
7
7
|
"source": "depa-flows/docs/flow-dsl",
|
|
8
|
-
"sourceTreeDigest": "sha256:
|
|
8
|
+
"sourceTreeDigest": "sha256:d74e06fd2511fc74a948fb549dc6940e3d7c677447c59cc544b2c6a81b8fb2eb",
|
|
9
9
|
"files": [
|
|
10
10
|
{
|
|
11
11
|
"path": "README.md",
|
|
@@ -29,7 +29,7 @@
|
|
|
29
29
|
},
|
|
30
30
|
{
|
|
31
31
|
"path": "spec/ai-workflow/data-workflow.md",
|
|
32
|
-
"contentDigest": "sha256:
|
|
32
|
+
"contentDigest": "sha256:23a619fb81856f70bb99fba0a33e0b8b6b15012b80392c21269c4fc146287ede"
|
|
33
33
|
},
|
|
34
34
|
{
|
|
35
35
|
"path": "spec/ai-workflow/resources.md",
|
|
@@ -69,7 +69,7 @@
|
|
|
69
69
|
},
|
|
70
70
|
{
|
|
71
71
|
"path": "spec/flow-core/instance-run.md",
|
|
72
|
-
"contentDigest": "sha256:
|
|
72
|
+
"contentDigest": "sha256:99f31a0e4775c0655e2a7f6b51badb3613cf2622202dde798dc5578f165b2fc2"
|
|
73
73
|
},
|
|
74
74
|
{
|
|
75
75
|
"path": "spec/flow-core/nodes.md",
|
|
@@ -93,7 +93,7 @@
|
|
|
93
93
|
},
|
|
94
94
|
{
|
|
95
95
|
"path": "spec/work-ctrl-flow/domains.md",
|
|
96
|
-
"contentDigest": "sha256:
|
|
96
|
+
"contentDigest": "sha256:feebd80d291b9c8899d9558fb81e1bf2262277320a9ec542dc8eb2fb6eb176c9"
|
|
97
97
|
},
|
|
98
98
|
{
|
|
99
99
|
"path": "spec/work-ctrl-flow/nodes.md",
|
|
@@ -40,6 +40,27 @@
|
|
|
40
40
|
|
|
41
41
|
`flow-port://#node/port` creates a data dependency. `flow-node://#node` creates a completion dependency through `waitFor`.
|
|
42
42
|
|
|
43
|
+
## Modular StepSpace form
|
|
44
|
+
|
|
45
|
+
大型 definition 可以把根内联 nodes 替换为一个精确的 `StepSpaceRef`：
|
|
46
|
+
|
|
47
|
+
```xnl
|
|
48
|
+
<AIDataWorkflow #depa.examples.SupportEvidenceDag apiVersion="depa.flows/v1" version="1.0.0" (
|
|
49
|
+
<FlowContract #depa.examples.SupportEvidenceDag {
|
|
50
|
+
inputPorts = ["ticket"]
|
|
51
|
+
outputPorts = ["summary"]
|
|
52
|
+
}>
|
|
53
|
+
<StepSpaceRef { src = "step-space.xnl" }>
|
|
54
|
+
)>
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
`step-space.xnl` 通过显式 `StepRef` 定位每个 `step.xnl`；每个 Step 的唯一
|
|
58
|
+
`Core` 保存一个 `EntryNode`、`TransformNode`、`SinkNode`、`SubFlowNode` 或
|
|
59
|
+
`ReturnNode`。loader 将 Core 投影回同一个 canonical EagerDataFlow plan，所以
|
|
60
|
+
ports、dependency edges、declaration order 和 scheduler 语义与等价 inline
|
|
61
|
+
definition 完全相同。StepGroup 只表达 authoring ownership，不推导 DAG edges。
|
|
62
|
+
inline nodes 与 `StepSpaceRef` 同时出现会在 materialization 前关闭失败。
|
|
63
|
+
|
|
43
64
|
## RunGraph checkpoint profile
|
|
44
65
|
|
|
45
66
|
The XNL definition produces an EagerDataFlow authoring plan. At run time, AIDataWorkflow stores a RunGraph inside the run's single `FlowRunCheckpoint` typed profile, with:
|
|
@@ -20,6 +20,24 @@ Run checkpoints v0..n
|
|
|
20
20
|
|
|
21
21
|
Definition 更新只影响之后创建的 instance。已有 instance 的新 run 和已有 run 的恢复均不得重新读取 live Definition。
|
|
22
22
|
|
|
23
|
+
## Modular StepSpace definition
|
|
24
|
+
|
|
25
|
+
Flow root 可以继续在 `[]` 内联 topology，也可以在 `()` 中声明一个精确的
|
|
26
|
+
`<StepSpaceRef { src = "step-space.xnl" }>`；两种 topology authority 不能同时存在。
|
|
27
|
+
`StepSpace` 只通过显式 `StepRef`、`StepGroupRef` 和 step 内的 `ExtensionRef`
|
|
28
|
+
形成闭包，目录名和目录枚举不产生语义成员。所有 ref 都是 bundle-local virtual ref，
|
|
29
|
+
不是宿主物理路径；traversal、symbolic link、重复 id、循环引用、未注册 extension
|
|
30
|
+
或 schema identity 不匹配均在 instance admission 前关闭失败。extension registration 必须提供
|
|
31
|
+
runtime-only 的纯 codec；schema ref 相等本身不足以录取 value。codec 的 normalized closed value
|
|
32
|
+
参与 step digest，codec 函数本身不进入 Definition forest 或任何持久化数据。
|
|
33
|
+
|
|
34
|
+
每个 `Step` 恰好有一个 `Core`，Core 内保存原 profile 的 canonical statement/node。
|
|
35
|
+
`StepGroup` 是 definition ownership/authoring hierarchy，不是第二个 scheduler：Ctrl 按
|
|
36
|
+
Core hierarchy 投影既有 control tree；Data 的 port、dependency 与 `waitFor` 仍由各
|
|
37
|
+
Core node 事实拥有。`DefinitionStepForest` 是冻结定义投影，不能用作 runtime state
|
|
38
|
+
index。完整显式闭包及其逐文件 digest 随 bundle 复制进 Instance；live source 的后续
|
|
39
|
+
修改或删除不会影响 fresh run/resume。
|
|
40
|
+
|
|
23
41
|
## Canonical physical projection
|
|
24
42
|
|
|
25
43
|
存储根由 runtime 显式注入，不从 Definition 路径、当前工作目录或环境变量推导。reference filesystem projection 为：
|
|
@@ -31,10 +49,17 @@ Definition 更新只影响之后创建的 instance。已有 instance 的新 run
|
|
|
31
49
|
instance.json
|
|
32
50
|
definition/
|
|
33
51
|
manifest.xnl
|
|
52
|
+
step-space.xnl # 使用模块化 topology 时
|
|
53
|
+
steps/<step-id>/step.xnl # 只由显式 ref 构成闭包
|
|
34
54
|
...完整 bundle...
|
|
35
55
|
runs/
|
|
36
56
|
<run-id>/
|
|
37
|
-
checkpoint.json
|
|
57
|
+
checkpoint.json # root-last current head
|
|
58
|
+
step-space/
|
|
59
|
+
controls/<digest>.json # immutable binding/control records
|
|
60
|
+
records/<digest>.json # Ctrl/Data step-local facts
|
|
61
|
+
trees/<digest>.json # immutable Merkle nodes
|
|
62
|
+
receipts/<version>.json # head dependency receipt
|
|
38
63
|
legacy-import.receipt.json # 仅显式旧数据导入后可有
|
|
39
64
|
run-index.json # 可删除并从 checkpoint 重建
|
|
40
65
|
```
|
|
@@ -45,7 +70,7 @@ Descriptor 与调用方 source identity 都是 exact closed data：authority、a
|
|
|
45
70
|
|
|
46
71
|
`support-root`、`instances/` 和 instance candidate/live 目录同时是物理 authority boundary。materializer 在任何 `mkdir`、copy、descriptor write 或 rename 前都必须用 `lstat` 拒绝已有 symbolic link，核对真实路径仍包含于显式 owner root，并在安全创建后再次 readback。把 `instances/` 指向外部位置不能产生 candidate、instance 或 run，也不能改变外部文件。
|
|
47
72
|
|
|
48
|
-
|
|
73
|
+
公开逻辑 checkpoint 使用 `depa.flow-run-checkpoint/v1` closed public-data envelope：
|
|
49
74
|
|
|
50
75
|
| 字段 | 所有权 |
|
|
51
76
|
|---|---|
|
|
@@ -54,8 +79,34 @@ Descriptor 与调用方 source identity 都是 exact closed data：authority、a
|
|
|
54
79
|
| `input`、`config`、`state`、`output` | 本 run 的公开数据边界；`config` 是本次执行的 effective config，不是 authoring facet 的副本入口 |
|
|
55
80
|
| `controllerSidecars` | 等待、决策、游标等 controller 持久事实 |
|
|
56
81
|
| `nodeSidecars` | 按稳定 node identity 保存的持久节点事实 |
|
|
82
|
+
| `stepExtensions` | 可选的已注册 step extension facts；精确保存 step/kind/schema、单调 revision 与 normalized closed value |
|
|
57
83
|
| `profile` | `WorkCtrlFlow`、`AICtrlWorkflow` 或 `AIDataWorkflow` 的 closed typed state |
|
|
58
84
|
|
|
85
|
+
reference filesystem owner 将该逻辑值无损编码为 `depa.flow-run-checkpoint-head/v1`：head
|
|
86
|
+
只保留 instance/run/definition/version、logical digest、root/control projection 与当前
|
|
87
|
+
RunStepState Merkle root。AI Data 初始 membership 从 frozen binding declaration order 派生，
|
|
88
|
+
后续只由 accepted add/update/remove patch facts 扩展或留下 tombstone；immutable binding 本身
|
|
89
|
+
是内容寻址 control record。Ctrl 初始 membership 必须从 materialized instance 的 frozen canonical
|
|
90
|
+
binding 读取，definition-owned branch/node/wait/orchestration facts 归入其 definition leaf，只有 accepted
|
|
91
|
+
orchestration 中无法归属 frozen step 的 composite/dynamic identity 才产生 runtime leaf。decode 会重新派生
|
|
92
|
+
membership、重建 controller/node sidecars，并再次运行完整 public normalizer；读取者看到的仍是原逻辑
|
|
93
|
+
checkpoint，而不是 storage head。
|
|
94
|
+
|
|
95
|
+
`stepExtensions` 不是额外 store。其 logical facts 属于同一个 checkpoint/version；物理上每个
|
|
96
|
+
RunStepState leaf 引用一个 core record digest 与精确的 `kind -> extension record digest` map。
|
|
97
|
+
初始 extension membership/value 只来自 materialized frozen DefinitionStepForest，codec registry
|
|
98
|
+
是 runtime 的长生命周期依赖并不进入 config 或持久化数据。extension transition 使用 targeted
|
|
99
|
+
Processor `mutateRunStepExtension(runtime, selector, invocation, config)`；selector 精确包含
|
|
100
|
+
`instanceId/runId/stepId/kind`，invocation 使用 expected revision CAS，config 不携带 codec 或路径。
|
|
101
|
+
kind/membership/schema 不可变，每次 checkpoint 最多改变一个 extension fact且 revision 恰加一；
|
|
102
|
+
终态 checkpoint 不接受 extension 更新。Memory 与 filesystem owner 在 commit/load 时使用相同
|
|
103
|
+
frozen-profile + codec admission，unknown kind、invalid/unnormalized value 和直接伪造 state 均关闭失败。
|
|
104
|
+
|
|
105
|
+
immutable control/step record、tree node 和 receipt 均按 file fsync → rename → exact parent-directory
|
|
106
|
+
fsync 录取；首次创建 runs/run/step-space 子目录也会 fsync 其 exact parent。最终 head 使用同一协议且
|
|
107
|
+
最后 rename，因此只有 head 指向的完整闭包是 current authority。未被当前 root 引用的历史 material
|
|
108
|
+
不会参与读取或改变逻辑事实。
|
|
109
|
+
|
|
59
110
|
一次 transition 同时提交 envelope、sidecars 和 profile；不存在一个 profile store、一个 snapshot store、再加一个 system-state store 的并列写入。CAS 失败时不得部分接受任一字段。所有 canonical store 共用同一 transition validator：schema、instance/run identity、冻结 definition identity、profile kind、input 与 config 在 `v0` 后不可改写，version 只能递增一。终态 checkpoint 不再接受任何 commit，包括内容相同但 version 增长的 commit；幂等调用必须直接返回已接受的终态版本。
|
|
60
111
|
|
|
61
112
|
## Definition facets 与 run state
|
|
@@ -115,6 +166,19 @@ output = fn(runtime, input, config)
|
|
|
115
166
|
output = fn(runtime, selector, invocation, config)
|
|
116
167
|
```
|
|
117
168
|
|
|
169
|
+
StepSpace profile assembly 的 public authority 是
|
|
170
|
+
`assembleDefinitionStepProfile(runtime, input, config)`；filesystem root 只存在于
|
|
171
|
+
`createFilesystemDefinitionStepProfileRuntime({ rootDir })` adapter，domain input 不携带物理路径。
|
|
172
|
+
filesystem checkpoint store 同样通过 runtime adapter + `(runtime, input, config)` factory 组合；
|
|
173
|
+
旧 source/root convenience 只作为 compatibility wrapper。
|
|
174
|
+
|
|
175
|
+
AI Data filesystem runtime 还注入只读 frozen profile authority。它从
|
|
176
|
+
`instances/<instance-id>/definition` 装配 frozen binding、StepSpace membership 与 extension descriptors，
|
|
177
|
+
在创建 run 目录前 exact 核对 candidate binding，并在 fresh load 时重复核对；缺少 port、错误 profile
|
|
178
|
+
或伪造 binding 均不进入 owner mutation。profile loader 的 codec registry 位于 runtime
|
|
179
|
+
（assembly runtime 为 `sources + extensionCodecs`，step mutation runtime 为
|
|
180
|
+
`steps + extensionCodecs`），普通 config 不保存函数。
|
|
181
|
+
|
|
118
182
|
Agent invocation沿用同一Definition/Instance/Run authority。canonical Processor为 `runAgent(runtime, input, config)` / `runTargetedAgent(runtime, selector, invocation, config)`；同名bound facade只在组合边界隐去runtime。instance id/name index与pending/completed receipt属于 `checkpoint.profile.ai`，不创建平行store，也不复制actor/session history。
|
|
119
183
|
|
|
120
184
|
可运行边界证据见 [WorkCtrl materialized engine fixture](../../../../packages/work-ctrl-flow-logic/test/materialized-engine.test.ts) 与 [filesystem checkpoint fixture](../../../../packages/ai-workflow-logic/test/checkpoint-filesystem.test.ts)。前者验证完整本地依赖和 seed bytes，后者验证 canonical path、fresh store 与同一 checkpoint owner。
|
|
@@ -6,7 +6,8 @@
|
|
|
6
6
|
|
|
7
7
|
| fact / domain | file | root / scheme | 说明 |
|
|
8
8
|
|---|---|---|---|
|
|
9
|
-
| `<WorkCtrlFlow>` definition | 单文件或 `manifest.xnl` | 根 `[]` | 共享 CtrlFlow statements，可使用 `ExternalJob` / `Timer
|
|
9
|
+
| `<WorkCtrlFlow>` definition | 单文件或 `manifest.xnl` | 根 `[]` 或一个 `StepSpaceRef` | 共享 CtrlFlow statements，可使用 `ExternalJob` / `Timer`；inline 与 StepSpace 互斥 |
|
|
10
|
+
| `step.space` | `step-space.xnl` + 显式 step refs | `<StepSpace>` | 可选 definition ownership forest；不拥有 scheduler 或 run status |
|
|
10
11
|
| `state.def` | `state.def.xnl` | `<StateDef>` / `state-def://` | 可选；声明受版本契约保护的实例 state shape |
|
|
11
12
|
| `state.seed` | `state.seed.xnl` | `<StateSeed>` / `state-seed://` | 可选；新实例的只读初始 state |
|
|
12
13
|
| `task.space` | - | - | 禁用；人工任务事实只属于 BPCtrlFlow |
|
|
@@ -24,6 +25,10 @@
|
|
|
24
25
|
|
|
25
26
|
实例物化必须在首个节点前冻结完整 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 作为语义事实。
|
|
26
27
|
|
|
28
|
+
模块化 authoring 中，每个 `Step` 的 `Core` 仍是原 WorkCtrl statement；嵌套
|
|
29
|
+
`Retry`、`Parallel` 等语义继续由 WorkCtrl runtime 解释。`StepGroup` 只组织文件与
|
|
30
|
+
ownership，不能改变 statement 顺序、等待关系或建立另一套执行状态。
|
|
31
|
+
|
|
27
32
|
## Rejected Authoring Facts
|
|
28
33
|
|
|
29
34
|
`tree.xnl`、`action.types.xnl`、`Tree` 根、独立 `CtrlFlow` 根以及公开 `Sequence` / `Selector` / `Condition` 都必须拒绝。snapshot schema、WaitHandle 列表和 branch decision 也不能被伪装成 definition 子域。
|