ai-workflow-flow-dsl-reference 0.1.3 → 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.
|
@@ -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",
|
|
@@ -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",
|
|
@@ -27,7 +27,9 @@ Flow root 可以继续在 `[]` 内联 topology，也可以在 `()` 中声明一
|
|
|
27
27
|
`StepSpace` 只通过显式 `StepRef`、`StepGroupRef` 和 step 内的 `ExtensionRef`
|
|
28
28
|
形成闭包，目录名和目录枚举不产生语义成员。所有 ref 都是 bundle-local virtual ref，
|
|
29
29
|
不是宿主物理路径；traversal、symbolic link、重复 id、循环引用、未注册 extension
|
|
30
|
-
或 schema identity 不匹配均在 instance admission 前关闭失败。
|
|
30
|
+
或 schema identity 不匹配均在 instance admission 前关闭失败。extension registration 必须提供
|
|
31
|
+
runtime-only 的纯 codec；schema ref 相等本身不足以录取 value。codec 的 normalized closed value
|
|
32
|
+
参与 step digest，codec 函数本身不进入 Definition forest 或任何持久化数据。
|
|
31
33
|
|
|
32
34
|
每个 `Step` 恰好有一个 `Core`，Core 内保存原 profile 的 canonical statement/node。
|
|
33
35
|
`StepGroup` 是 definition ownership/authoring hierarchy，不是第二个 scheduler：Ctrl 按
|
|
@@ -52,7 +54,12 @@ index。完整显式闭包及其逐文件 digest 随 bundle 复制进 Instance
|
|
|
52
54
|
...完整 bundle...
|
|
53
55
|
runs/
|
|
54
56
|
<run-id>/
|
|
55
|
-
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
|
|
56
63
|
legacy-import.receipt.json # 仅显式旧数据导入后可有
|
|
57
64
|
run-index.json # 可删除并从 checkpoint 重建
|
|
58
65
|
```
|
|
@@ -63,7 +70,7 @@ Descriptor 与调用方 source identity 都是 exact closed data：authority、a
|
|
|
63
70
|
|
|
64
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，也不能改变外部文件。
|
|
65
72
|
|
|
66
|
-
|
|
73
|
+
公开逻辑 checkpoint 使用 `depa.flow-run-checkpoint/v1` closed public-data envelope：
|
|
67
74
|
|
|
68
75
|
| 字段 | 所有权 |
|
|
69
76
|
|---|---|
|
|
@@ -72,8 +79,34 @@ Descriptor 与调用方 source identity 都是 exact closed data：authority、a
|
|
|
72
79
|
| `input`、`config`、`state`、`output` | 本 run 的公开数据边界；`config` 是本次执行的 effective config，不是 authoring facet 的副本入口 |
|
|
73
80
|
| `controllerSidecars` | 等待、决策、游标等 controller 持久事实 |
|
|
74
81
|
| `nodeSidecars` | 按稳定 node identity 保存的持久节点事实 |
|
|
82
|
+
| `stepExtensions` | 可选的已注册 step extension facts；精确保存 step/kind/schema、单调 revision 与 normalized closed value |
|
|
75
83
|
| `profile` | `WorkCtrlFlow`、`AICtrlWorkflow` 或 `AIDataWorkflow` 的 closed typed state |
|
|
76
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
|
+
|
|
77
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；幂等调用必须直接返回已接受的终态版本。
|
|
78
111
|
|
|
79
112
|
## Definition facets 与 run state
|
|
@@ -133,6 +166,19 @@ output = fn(runtime, input, config)
|
|
|
133
166
|
output = fn(runtime, selector, invocation, config)
|
|
134
167
|
```
|
|
135
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
|
+
|
|
136
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。
|
|
137
183
|
|
|
138
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。
|