ai-workflow-flow-dsl-reference 0.1.0

package/dist/resource-module/content/foundation/naming-axioms.md

@@ -0,0 +1,167 @@
+# L1 元公理 · 命名、寻址与制品组织
+
+> 与领域无关的命名/引用/文件组织公理。任何基于 XNL 的 bundle 化 DSL 都遵守。编号 `M-N*`（Meta-Naming）。
+
+## M-N1 · 内容为真源，路径只是布局
+
+节点的身份、类别一律来自**文件内容**（根节点 tag + `#id`），绝不来自文件名或目录名。文件路径只是物理布局，可自由重组而不改变语义。
+
+推论：每个容器（一个可加载的制品、一个多文件单元）有且只有一个**入口清单**，统一命名 `manifest.xnl`。清单内根节点的 tag 决定容器类别，`#id` 决定容器身份。不允许用文件名编码类别（禁止 `page.xnl`/`component.xnl` 这类 kind-named 入口）。
+
+## M-N2 · 域组织与 entry 寻址分投影
+
+域名、文件名与域根 tag 描述**制品组织**；URI scheme 描述域内被引用的**单个 entry**。两者有关联但不做字符串机械等同：集合/复数词、facet 点分词、PascalCase tag 都不应泄漏进 scheme。
+
+```text
+domain/file/root tag:  commands / commands.xnl / <Commands>
+entry URI scheme:      command://#users.search
+
+domain/file/root tag:  config.def / config.def.xnl / <ConfigDef>
+entry URI scheme:      config-def://#users.search
+```
+
+scheme 必须是单数 kebab-case，并符合：
+
+```text
+^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$
+```
+
+`.` 可以留在 domain/file facet、FQN 与 `#id` 中，但不得出现在 scheme。每个 domain 到 entry scheme 的映射必须在其领域规范中显式登记。不可因为名称相近而臆造新 scheme。
+
+## M-N3 · def / seed 是域的 facet
+
+任何域 `X` 可以带两个伴生 facet：
+
+- `X.def` — 描述 X 的**类型/形状**。
+- `X.seed` — 描述 X 结构的**初始数据**。
+- `X` 本身 — 当前声明/数据。
+
+facet 是完整的域（独立文件、独立 entry scheme、独立节点），按 M-N2 分投影，与主域成对出现、允许缺省。这样“一个事物的类型”和“它的初值”用统一后缀表达，不为每种事物发明专属命名。
+
+## M-N4 · 统一 URI 引用
+
+一切跨节点引用是 URI，写在引号字符串里，分三类：
+
+| 类 | 形态 | 寻址 | 例 |
+|---|---|---|---|
+| 物理 | `vfs://…` | 文件（`@/` 工作区根、`./` 当前目录、`../` 父目录） | `"vfs://@/shared/prefabs.xnl"`、`"vfs://./adapters/core.ts"` |
+| 逻辑 | `<域名>://…` | 域内节点（默认容器私有，见领域层的私有性规则） | `"config://#api"`、`"config-def://#users-page"` |
+| 注册表 | `<注册表名>://…` | 由制品结构派生的具名注册表（如单元表、路由表） | `"page://org.app.UsersPage"`、`"route://#users-route"` |
+
+URI 三种寻址形态：
+
+```text
+<scheme>://<path>            层级路径寻址             "route://reports/:id"
+<scheme>://#<id>             节点 id 寻址（域内唯一）   "scope://#users-filter"
+<scheme>://#<id>/<sub-path>  锚定 id 后走结构路径       "config://#users-filter/keywordInput"
+```
+
+逐条展开：
+
+- **`#id` 寻址**是最常用形态：定位某域中 `#id` 节点本身。`"config://#api"` = config 域里 `<ConfigEntry #api>` 整个节点。
+- **`#id/<sub-path>` 寻址**在锚定节点后继续走**属性结构**：`"config://#api/baseUrl"` = `<ConfigEntry #api { baseUrl = "/api" }>` 里的 `baseUrl` 值；多级用 `/` 连（`"config://#users-filter/keywordInput/placeholder"`）。
+- **`<path>` 寻址**用于本身有层级结构的域（如路由树按 path 匹配：`"route://reports/:id"`）。
+
+分隔符职责固定：**`.` 只做名字空间分隔**（FQN 段、域 facet 段），**`-` 连接 scheme 中的多个词**，**`/` 只做结构层级分隔**。对比：`"config-def://#users-page"` 中 `-` 是 scheme 词间连接，`"config://#api/baseUrl"` 中 `/` 是下钻一层属性——两个符号永不互换职责。
+
+scheme 集合 = 明确登记的 domain-entry 映射 + 注册表名 + `vfs`。**引用必须写在引号字符串里**——`:` 不是 XNL identifier 字符，裸写 `ref = config://#x` 是语法错误。
+
+### 解析边界
+
+URI 解析必须先确定"从哪个容器看出去"：
+
+- **逻辑 scheme 默认在当前容器内解析**：`"config://#api"` 命中的是当前 app / page / component 自己的 config 域，不会按全局搜索去找同名节点。
+- **跨容器引用必须经显式通道**：要么经注册表 scheme 引用某个具名制品整体（如 `page://<FQN>`、`component://<FQN>`），要么经 `vfs://` import 共享文件。不要用逻辑 scheme 偷穿到别的容器内部。
+- **注册表 scheme 的可见性由领域层定义**：L1 只规定它是结构派生的具名表；哪些注册表存在、键是什么、暴露何种公共契约，由 L2/L3 定。
+
+这条规则把"容器内部事实"与"可复用公共制品"分开：逻辑 URI 是私有域内引用，注册表 URI 是公开入口引用，物理 URI 是文件引用。
+
+## M-N5 · FQN 身份
+
+可跨容器复用的定义用**点分限定名（FQN）**作全局身份（`org.pkg.Name`，类比包名+类名）。FQN 写在定义根节点的 `#id` 上；引用处用 FQN 作 tag（M-S3 的点分档）或经注册表 scheme（M-N4）。FQN 与它所在的文件路径**相互独立**（M-N1）——移动文件不改 FQN，改文件名不影响引用。
+
+## M-N6 · 单/多文件同构
+
+一个容器/单元支持两种物理形态，语义完全等价（语法基础见 M-S4）：
+
+- **单文件**：域内联为 `( ... )` 区段节点 + 一个列表主体段。
+- **多文件**：`manifest.xnl` 薄清单 + 每域一个 `<域名>.xnl` 文件；启用哪些域由**文件内容**（各域文件的根节点 tag）发现，不在清单上声明（M-N1 内容为真源）。
+
+单→多文件化是纯机械重构：`(...)` 区段节点原样搬进独立文件，所有引用零改动（M-N4 的逻辑寻址不感知物理布局）。
+
+## M-N7 · 节点二相：内联定义 or `ref` 引用
+
+**每一个节点都有两种可互换的写法**，语义等价，任选其一：
+
+1. **内联定义**——把节点的属性/子节点直接写在原地。
+2. **`ref` 引用**——写一个**空壳 + `ref` 属性**，采用别处（同类型）已定义的节点：`<Scope ref="users-page">` 采用预定义的 `<Scope #users-page {…}>`。
+
+`ref` 的值有两种形态，按目标位置选：
+- **按名**（同域预定义）：`ref="users-page"` —— 采用当前域内 `#users-page` 的定义。
+- **按 URI**（需要显式定位时）：`ref="scope://#users-page"` —— 用 M-N4 的 URI 定位；是否允许跨容器取决于 M-N4 的解析边界与领域层私有性规则。
+
+铁律（消除"Ref 又 ref"）：
+- **引用属性名统一为 `ref`**，不为每种节点发明 `xxxRef`（`scopeRef`/`contractRef`/`commandRef`…全部退役）。一个节点要引用什么，由它的 **tag** 表明（`<Scope ref=…>` 引用的必是 scope，`<Command ref=…>` 引用的必是 command），无需在属性名里重复类别。
+- **不套包装节点**。要引用一个 command 或 event，写 `<Command ref="…">` / `<Event ref="…">`，**不是** `<MessageRef ref="…">`——后者用一个专门的"引用节点"去指向消息，是 tag 已能表达类别时的冗余（Ref 又 ref）。任何 `XxxRef` 包装 tag 都退役。
+- **域绑定字段例外**：一个节点内**多个**指向不同域的绑定（如 Scope 绑定 config），用**裸名字段 + URI 值**（`config = "config://#x"`），因为它们是本节点的属性而非"采用另一个同类节点"。区别：`ref` 是"我就是那个节点"，绑定字段是"我引用那个域的资源作为我的一个属性"。复杂依赖绑定（如 effect 实现）优先放入节点的 `()` 子区段。
+
+**按 id 隐式关联**（第三种、免 `ref` 的手法）：当定义与使用天然同 id 时，定义域中 `#foo` 的条目**自动**作用于结构中的 `#foo`，使用处连 `ref` 都不必写。用于契约↔元素这类一一对应关系。
+
+三种手法并排对照（同一个 Scope 的三种到位方式）：
+
+```xnl
+# 预定义（在 scopes 域里）
+<Scope #users-page { config = "config://#users-page" }>
+
+# ① 内联定义 —— 属性直接写在使用处，不进域
+<Capsule #ad-hoc ( <Scope { config = "config://#ad-hoc" }> )>
+
+# ② ref 引用 —— 空壳 + ref，采用预定义
+<Capsule #users-filter ( <Scope ref="users-page"> )>
+
+# ③ id 隐式关联（适用于契约类）—— 定义域 <ElementContract #users-filter> 自动作用于
+#    树中 #users-filter 元素，使用处什么都不写
+```
+
+更多例子：
+
+```xnl
+# ref 采用：Accepts/Sends 中这个节点本身就是一个 Command 或 Event
+<Accepts [ <Command ref="command://#users.refresh"> ]>
+<Sends [ <Event ref="event://#users.selected"> ]>
+
+# 域绑定字段：Route 不是 Page；只是把 page 字段绑定到某个 Page 注册表条目
+<Route #users-route { path = "/users" page = "page://dg.admin.basic.UsersPage" }>
+
+# 物理引用：FuncEffect 不是采用另一个 FuncEffect 节点；只是把 type 字段绑定到代码类型入口
+<FuncEffect #users.query { type = "vfs://./effects/users.effects.ts#UsersQueryEffect" }>
+```
+
+目标：同一份数据只有一处真源；"定义"与"引用"用 `ref` 的有无区分；类别用 tag 表达，不靠属性名或包装节点。
+
+## M-N8 · 数据自持
+
+一个节点的静态描述数据**内联在该节点上**（不寄存到别的域再引回来）。域之间只用引用表达**归属/绑定**关系，不表达数据搬运。
+
+**裸值 vs 引用的分界**（判据只有一条：这份数据归谁所有）：
+
+- **归本节点所有的静态描述 → 内联裸值**。
+- **指向其他节点的归属/绑定 → 引用**（M-N7 的 `ref` 或裸名 URI 字段）。
+- 一个数据只在一处为真源。
+
+```xnl
+# ✅ 正：effect binding 的类型入口归 binding 自己所有 —— 内联在节点属性上
+<FuncEffect #users.query {
+  type = "vfs://./effects/users.effects.ts#UsersQueryEffect"
+}>
+
+# ❌ 反：把 effect binding 的类型入口寄存到 config 域，再从 binding 引回来 —— 寄存链
+<ConfigEntry #effect-code { usersQuery = "vfs://./effects/users.effects.ts#UsersQueryEffect" }>
+<FuncEffect #users.query { type = "config://#effect-code/usersQuery" }>
+```
+
+反例的问题：`type` 的真源漂到了 config 域（config 应只装静态开关/枚举/常量预设），读者要跨两个域拼出 binding 的全貌；改类型入口要去 config 改、但语义归属在 binding——职责错位。凡出现“A 的数据躺在 B 域、C 再引用回来”的链条，都违反本条。
+
+## M-N9 · 配置皆声明式 XNL
+
+制品内不允许 JSON/XML/YAML 等第二套配置入口——一切配置是 XNL（M-N2 的统一性前提）。可执行代码不是配置：纯函数脚本（`.ts` 等）以文件形式存在、经引用挂接（见 depa-axioms M-D3），但绝不内联进 XNL。

package/dist/resource-module/content/foundation/syntax-axioms.md

@@ -0,0 +1,60 @@
+# L1 元公理 · XNL 语法层
+
+> 这些公理直接源自 XNL 语法本身的特性，与任何领域无关。当前由 depa-flows 的 Flow DSL 遵守。
+> 编号 `M-S*`（Meta-Syntax）。
+
+## M-S1 · 节点四段形态
+
+XNL 节点完整形态：`<Tag #id 元数据 { 属性 } ( 单件段 ) [ 列表段 ]>`。各成分语义固定：
+
+| 成分 | 承载 | 语法特性 |
+|---|---|---|
+| `Tag` | 节点类别 | 决定该节点如何被解释（见 M-S2） |
+| `#id` | 节点身份 | 解析为 `Word{namespace, name}`，可点分（见 naming-axioms） |
+| 元数据位 `key=value` | 系统级元信息 | 紧跟 tag/`#id` 之后、`{ }` 之前；承载 `apiVersion`/`version` 等系统级元数据，与业务属性分离 |
+| `{ ... }` | 属性键值对 | 标量/内联结构数据（业务属性） |
+| `( ... )` | 唯一的**子域概念** | 每种子域概念只出现一次；重复条目由该子域的复数容器承载 |
+| `[ ... ]` | 直接、有序或可重复子节点 | 同 tag 可重复 |
+
+`( ... )` 与 `[ ... ]` 顺序无关、各至多一次，可与 `{ ... }` 共存。
+
+## M-S2 · `()` 是子域，`[]` 是直接条目
+
+`()` 不只是“不会重复的子节点”容器；它表达父节点拥有的**唯一子域概念**。同一个子域概念在 `()` 中只能出现一次。子域中若有多个同类条目，使用该概念的复数容器及其 `[]`：
+
+```xnl
+<If #choose (
+  <Branches [
+    <Branch #active {
+      when = "vfs://./flow-code/route.ts#isActive"
+    } [
+      <Return #done { value = "active" }>
+    ]>
+    <Otherwise [
+      <Return #fallback { value = "inactive" }>
+    ]>
+  ]>
+)>
+```
+
+- `()`：`Branches`、`FlowContract`、`EffectBindings`、`Scope` 这类每父节点唯一的子域。
+- `[]`：元素、语句、图节点、分支条目等父节点的直接顺序或可重复事实。
+- 禁止为“凑层级”引入没有领域语义的 `<Block>`、`<Nodes>` 包装；根直接条目直接进入根 `[]`。
+
+`()` 的 tag 去重是这一规则的语法保护，而不是把所有“单件节点”塞进去的理由。
+
+## M-S3 · tag 形态决定解析路径
+
+一个 DSL 应当让 **tag 的书写形态自身**携带"这个节点怎么解释"的信息，读者与 parser 无需查上下文：
+
+| tag 形态 | 约定含义 |
+|---|---|
+| 小写裸词（`h1`、`div`） | 宿主原生/透传节点 |
+| PascalCase 保留字 | DSL 结构节点（codec 白名单） |
+| 点分限定名（`a.b.C`） | 注册表查找（引用其他定义） |
+
+具体每档映射到什么由领域层（L2）定；L1 只规定"形态分档"这条元规则。
+
+## M-S4 · 单件/列表段的物理可拆分性
+
+因为 `()` 里的节点是父节点的唯一子域，它可以**无损地外提为独立文件**（文件根节点 = 子域节点本身）；`[]` 则承载该域的集合或直接条目。这条语法性质是“单文件 ⟷ 多文件同构”（见 naming-axioms M-N6）的语法基础：内联子域与拆出文件根**完全同型**，互转不改变语义或引用。

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

@@ -0,0 +1,53 @@
+# L3 · AICtrlWorkflow profile
+
+`AICtrlWorkflow` is the AI-facing WorkCtrlFlow profile. Use it when a run may wait for an agent, tool, human review, timer or other durable external signal.
+
+## Root shape
+
+```xnl
+<AICtrlWorkflow #depa.examples.SupportReview apiVersion="depa.flows/v1" version="1.0.0" (
+  <FlowContract #depa.examples.SupportReview {
+    input = "vfs://./flow-code/agent.ts#SupportReviewInput"
+    output = "vfs://./flow-code/agent.ts#SupportReviewResult"
+  }>
+) [
+  <Run #draft-context {
+    src = "vfs://./flow-code/agent.ts#draftContext"
+  }>
+  <ExternalJob #agent-review {
+    signalKind = "ai.agent.reviewed"
+    signalKey = "support-review"
+  }>
+  <Return #done {
+    src = "vfs://./flow-code/agent.ts#toResult"
+  }>
+]>
+```
+
+## Statements
+
+`AICtrlWorkflow` accepts the WorkCtrlFlow statement surface:
+
+- shared CtrlFlow statements such as `Run`, `If`, `Fallback`, `Retry`, `Timeout`, `Until`, `ForEach`, `Parallel`, `Race`, `CallFlow` and `Return`;
+- WorkCtrlFlow interruptible statements such as `ExternalJob` and `Timer`.
+
+It does not accept BPCtrlFlow-only `TaskStep` unless a future profile explicitly extends it.
+
+## Runtime AI context
+
+Dynamic code receives the host runtime. AI-capable runtimes include an `ai` field with roots, state store and embedded effect provider. Effects are invoked by operation name:
+
+```ts
+await runtime.ai.effects.invoke({
+  effectId: "effect-1",
+  operation: "ai.review",
+  input,
+  run,
+  nodeId: "draft-context",
+  materialRefs: ["resource://depa.examples.SupportReview.Materials"]
+})
+```
+
+## State and recovery
+
+Recovery is WorkCtrlFlow-backed. AICtrlWorkflow run records project WorkCtrlFlow snapshots into AI node records and open wait handles. Node positioning must use stable ids/invocation keys, not array index.

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

@@ -0,0 +1,78 @@
+# L3 · AIDataWorkflow profile
+
+`AIDataWorkflow` is the AI-facing EagerDataFlow profile. Use it when AI work is best represented as a DAG whose nodes can be patched, invalidated and reused inside a long-running run.
+
+## Root shape
+
+```xnl
+<AIDataWorkflow #depa.examples.SupportEvidenceDag apiVersion="depa.flows/v1" version="1.0.0" (
+  <FlowContract #depa.examples.SupportEvidenceDag {
+    inputPorts = ["ticket"]
+    outputPorts = ["summary"]
+  }>
+) [
+  <EntryNode #entry>
+  <TransformNode #retrieve {
+    inputs = { ticket = "flow-port://#entry/ticket" }
+    outputs = ["evidence"]
+    src = "vfs://./flow-code/evidence.ts#retrieveEvidence"
+  }>
+  <TransformNode #summarize {
+    inputs = { evidence = "flow-port://#retrieve/evidence" }
+    outputs = ["summary"]
+    src = "vfs://./flow-code/evidence.ts#summarizeEvidence"
+  }>
+  <ReturnNode #return {
+    inputs = { summary = "flow-port://#summarize/summary" }
+  }>
+]>
+```
+
+## Nodes
+
+`AIDataWorkflow` accepts the EagerDataFlow node surface:
+
+- `EntryNode`
+- `TransformNode`
+- `SinkNode`
+- `SubFlowNode`
+- `ReturnNode`
+
+`flow-port://#node/port` creates a data dependency. `flow-node://#node` creates a completion dependency through `waitFor`.
+
+## RunGraph state
+
+The XNL definition produces an EagerDataFlow authoring plan. At run time, AIDataWorkflow creates a RunGraph with:
+
+- node status and generation;
+- patch history;
+- transitive invalidation records;
+- node-level reuse policy and semantic fingerprints.
+
+Definition edits and RunGraph patches are separate surfaces. A run patch does not rewrite the XNL definition.
+
+## Reuse policy
+
+Machine nodes default to `semantic-hash`; manual nodes default to `never`. Author a canonical manual node through AIDataWorkflow config:
+
+```xnl
+<TransformNode #human-review {
+  inputs = { evidence = "flow-port://#retrieve/evidence" }
+  outputs = ["review"]
+  src = "vfs://./flow-code/evidence.ts#reviewEvidence"
+  config = { node_type = "manual" }
+}>
+```
+
+`node_type = "manual"` is AIDataWorkflow policy metadata. EagerDataFlow's legacy `type` field remains an implementation binding. A node may override its reuse policy with config such as:
+
+```xnl
+<TransformNode #fresh-review {
+  inputs = { evidence = "flow-port://#retrieve/evidence" }
+  outputs = ["review"]
+  src = "vfs://./flow-code/evidence.ts#reviewEvidence"
+  config = { reuse_policy = "never" }
+}>
+```
+
+Semantic reuse is run-local. Generation is history metadata and is not part of the reuse fingerprint.

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

@@ -0,0 +1,242 @@
+# L3 · Halfcode-backed AI workflow resources
+
+AI workflow 资源以 Halfcode `ResourcePackage` 为通用 authority。Halfcode 负责 Catalog、KindDefinition、文件发现、URI containment、identity、provenance、layer composition 与 dependency snapshot；depa-flows 只读取规范化 `ResourceRecord`，投影 AI workflow 领域语义。
+
+这意味着 `AIWorkflowAppBundle` 仍然存在，但它不再拥有一套通用 `ResourceCatalog`。它只是工作流领域的 app projection：明确声明哪些 `AICtrlWorkflow` / `AIDataWorkflow` 属于该 app，以及哪些 workflow 是 entrypoint。
+
+## Authority pipeline
+
+```text
+XNL ResourcePackage
+  -> halfcode-compiler.xnl/resource-core loadResourceTree
+  -> ResourceTree.registry / EffectiveResourceRegistry.byKind
+  -> depa-flows projectAIWorkflowAppBundles / projectAIWorkflowAgentResources
+  -> AIWorkflowAppBundleProjection / AIWorkflowAgentResourceProjection
+  -> depa-flows run-freeze (Node-only)
+  -> Halfcode ResourceDependencySnapshot
+```
+
+边界约束：
+
+- depa-flows 不遍历资源目录、不解析第二份 Catalog、不从路径推导 identity。
+- `ResourcePackage`、`Catalog`、`KindDefinition` 和通用 `vfs://` containment 的规范均由 Halfcode 维护。
+- wrapper（例如 Eidolon）绑定真实 root，但 root policy 不进入 workflow definition。
+- workflow projector 只检查明确的 `WorkflowBindings` 结构，不扫描 prompt、任意 property 或自然语言。
+
+## Package shape
+
+AI workflow app 可以与其他资源一起放在标准 Halfcode package 中：
+
+```text
+support-agent/
+  manifest.xnl                         # ResourcePackage（Halfcode authority）
+  KindDefinitions/
+    AIWorkflowAppBundle/manifest.xnl
+    AICtrlWorkflow/manifest.xnl
+    AIDataWorkflow/manifest.xnl
+  Apps/
+    SupportAgent.xnl                   # AIWorkflowAppBundle domain resource
+  CtrlWorkflows/
+    SupportAgent.xnl
+  DataWorkflows/
+    Evidence.xnl
+```
+
+package 根、Catalog 和 KindDefinition 的完整写法以 Halfcode Resource DSL 为准。depa-flows 只拥有下面的 workflow Kind 内容契约。
+
+## AIWorkflowAppBundle
+
+`WorkflowBindings[]` 保留 authoring 顺序。每个 `WorkflowBinding` 必须显式声明：
+
+- `#id`：app 内唯一 binding id；
+- `kind`：精确为 `AICtrlWorkflow` 或 `AIDataWorkflow`；
+- `ref`：`resource://<resource-id>`；
+- `entrypoint`：显式 boolean。
+
+```xnl
+<AIWorkflowAppBundle #depa.flows.demo.SupportAgent apiVersion="depa.flows/v1" version="1.0.0" {
+  lifecycle = "Active"
+  description = "Support agent workflow app"
+} (
+  <WorkflowBindings [
+    <WorkflowBinding #primary {
+      kind = "AICtrlWorkflow"
+      ref = "resource://depa.flows.demo.SupportAgent.Workflow"
+      entrypoint = true
+    }>
+    <WorkflowBinding #evidence {
+      kind = "AIDataWorkflow"
+      ref = "resource://depa.flows.demo.SupportAgent.Evidence"
+      entrypoint = false
+    }>
+  ]>
+)>
+```
+
+projector 会按 exact resource identity 在 Halfcode registry 中解析目标，并核对目标 record 的 kind。任一 binding 缺失、重复、目标不存在或 kind 不一致时，整个 projection fail closed；不会返回 partial app。
+
+至少一个 binding 必须是 entrypoint。entrypoint 是 workflow 领域语义，不会替代 Halfcode package root 或 Catalog。
+
+## AIAgentDefinition
+
+`AIAgentDefinition` 是可复用 Agent 能力的资源定义，不是 Eidolon actor/session 配置，也不是新的 WorkCtrlFlow statement。它只通过固定 child nodes 声明资源关系：
+
+- `Messages[]`：按 authoring 顺序保存 `Message`；`#id` 在 Agent 内唯一，`role` 精确为 `system | developer | user | assistant`，prompt 使用显式 `promptKind + promptRef`；
+- `InputSchemaRef` / `OutputSchemaRef`：可选的单一 typed ref；
+- `ToolRefs[]`：有序 `ToolRef`，每项显式 `kind + ref`；
+- `EffectPolicyRef`：可选的单一 typed ref；
+- `MaterialPortRefs[]`：有序 `MaterialPortRef`，目标 kind 固定为 `MaterialPort`。
+
+```xnl
+<AIAgentDefinition #depa.flows.demo.Agent.Support apiVersion="depa.flows/v1" version="1.0.0" {
+  lifecycle = "Active"
+  description = "Support Agent definition"
+} (
+  <Messages [
+    <Message #system {
+      role = "system"
+      promptKind = "Prompt"
+      promptRef = "resource://depa.flows.demo.Prompt.Support.System"
+    }>
+    <Message #user {
+      role = "user"
+      promptKind = "Prompt"
+      promptRef = "resource://depa.flows.demo.Prompt.Support.User"
+    } (
+      <SchemaRef { kind = "MessageSchema" ref = "resource://depa.flows.demo.Schema.Request" }>
+    )>
+  ]>
+  <InputSchemaRef { kind = "MessageSchema" ref = "resource://depa.flows.demo.Schema.Request" }>
+  <OutputSchemaRef { kind = "MessageSchema" ref = "resource://depa.flows.demo.Schema.Response" }>
+  <ToolRefs [
+    <ToolRef #lookup { kind = "Tool" ref = "resource://depa.flows.demo.Tool.Lookup" }>
+  ]>
+  <EffectPolicyRef { kind = "EffectPolicy" ref = "resource://depa.flows.demo.Policy.Safe" }>
+  <MaterialPortRefs [
+    <MaterialPortRef #request { kind = "MaterialPort" ref = "resource://depa.flows.demo.Port.Request" }>
+  ]>
+)>
+```
+
+projector 只读取这些固定位置。普通 prompt、description、metadata 或其他 property 中即使出现 URI 形式文本或业务词语，也不会产生 tool、policy、task 或 dependency edge。
+
+## MaterialPort and MaterialBinding
+
+`MaterialPort` 定义 Agent 可消费的 material contract：
+
+```xnl
+<MaterialPort #depa.flows.demo.Port.Request apiVersion="depa.flows/v1" version="1.0.0" {
+  materialKind = "RequestMaterial"
+  required = true
+  cardinality = "one"
+} (
+  <SchemaRef { kind = "MessageSchema" ref = "resource://depa.flows.demo.Schema.Request" }>
+)>
+```
+
+`required` 必须是 boolean，`cardinality` 精确为 `one | many`。`SchemaRef` 可选。Agent 的 `MaterialPortRefs[]` 顺序是 run freeze 的 port 顺序 authority；`many` port 内多个 binding 再按 resource id 的固定 UTF-16 code-unit 顺序排列。
+
+`MaterialBinding` 把一个精确 workflow node + Agent tuple 的 port 绑定到一个 material：
+
+```xnl
+<MaterialBinding #depa.flows.demo.Binding.Request apiVersion="depa.flows/v1" version="1.0.0" {
+  lifecycle = "Active"
+} (
+  <AgentTaskRef {
+    workflowKind = "AICtrlWorkflow"
+    workflowRef = "resource://depa.flows.demo.Workflow.Support"
+    nodeId = "collect-request"
+    agentDefinitionRef = "resource://depa.flows.demo.Agent.Support"
+  }>
+  <PortRef { kind = "MaterialPort" ref = "resource://depa.flows.demo.Port.Request" }>
+  <MaterialRef { kind = "RequestMaterial" ref = "resource://depa.flows.demo.Material.Request.001" }>
+)>
+```
+
+`AgentTaskRef` 只是资源选择 tuple，不新增 substrate node，也不包含 run id、session、generation、actor 或 provider。所有 ref 都按完整 resource identity 和目标 kind 精确核对；相似名称没有关联语义。
+
+## Typed dependency relations
+
+depa-flows 只发出闭集 relation：
+
+- `agent-message-prompt`、`agent-message-schema`；
+- `agent-input-schema`、`agent-output-schema`；
+- `agent-tool`、`agent-effect-policy`、`agent-material-port`；
+- `material-port-schema`；
+- `material-binding-port`、`material-binding-material`；
+- run freeze 期间的 `workflow-agent-task`、`workflow-material-binding`。
+
+Halfcode 验证 edge endpoints、计算 reachable closure 并生成 revision；depa-flows 不实现 generic dependency resolver。
+
+## Run resource freeze
+
+纯 projection 仍从 root/browser entry 导出：
+
+```ts
+import { projectAIWorkflowAgentResources } from "ai-workflow-logic"
+
+const projection = projectAIWorkflowAgentResources(effectiveRegistry)
+```
+
+Node/server consumer 使用独立 entry，输入必须是同一个 authentic effective registry、由该 registry 产生的 exact projection，以及 Halfcode loader-owned content identities：
+
+```ts
+import { freezeAIWorkflowRunResources } from "ai-workflow-logic/run-freeze"
+
+const receipt = freezeAIWorkflowRunResources({
+  registry: effectiveRegistry,
+  projection,
+  task: {
+    workflowKind: "AICtrlWorkflow",
+    workflowRef: "resource://depa.flows.demo.Workflow.Support",
+    nodeId: "collect-request",
+    agentDefinitionRef: "resource://depa.flows.demo.Agent.Support",
+  },
+  contentIdentities,
+})
+```
+
+freeze 会检查 port 属于 Agent、required/cardinality 与 material kind，然后直接调用 Halfcode `buildResourceDependencySnapshot`。receipt 深度不可变，包含：
+
+- exact task 与 ordered binding resource ids；
+- 完整 Halfcode `ResourceDependencySnapshot`，用于 proof/recovery；
+- `sha256:` domain semantic fingerprint，只绑定所选 task、Agent/Message/Tool/Policy/Port/Binding、participating edges 与 reachable content digest。
+
+完整 snapshot revision 会绑定 effective registry revision，因此未被选择的资源变化也可能改变 proof。domain semantic fingerprint 排除未被选择的资源以及 host run/session/generation/path facts；两者不得混用。
+
+## Public consumer API
+
+纯 projection 可用于 browser 或任何已取得 normalized registry 的 consumer：
+
+```ts
+import { projectAIWorkflowAppBundles } from "ai-workflow-logic"
+
+const apps = projectAIWorkflowAppBundles(effectiveRegistry)
+const agentResources = projectAIWorkflowAgentResources(effectiveRegistry)
+```
+
+输入是 Halfcode public `Pick<ResourceRegistry, "byKind">` read port；`ResourceTree.registry` 与 `EffectiveResourceRegistry` 都可直接使用。
+
+需要从 filesystem root 加载时，使用单独的 Node entry：
+
+```ts
+import { loadAIWorkflowResourcePackage } from "ai-workflow-logic/filesystem"
+
+const loaded = await loadAIWorkflowResourcePackage({ rootDir: resourceRootDir })
+```
+
+该 adapter 直接调用 Halfcode `loadResourceTree`。depa-flows 没有 fallback scanner 或 containment 实现。`ai-workflow-logic/browser` 仍只导出纯 projector。
+
+## Compatibility surface
+
+早期发布的 `AIWorkflowResourceCatalog`、`AIWorkflowAppBundleManifest`、`AIWorkflowResourceRef` 和 ref helper 在 `0.1.x` 中保留为 deprecated compatibility surface，避免 patch upgrade 破坏既有 import。它们不再出现在 canonical authoring pipeline 中，新 Kind 不得扩展这些旧类型形成第二套 registry。
+
+## Facts and runtime state
+
+- XNL ResourcePackage 和 ResourceRecord：Halfcode-owned authoring facts。
+- AIWorkflowAppBundleProjection：可从 normalized records 重建的 depa domain projection，不反写 source。
+- AIWorkflowAgentResourceProjection：固定 Agent/Message/Material 关系的可重建 depa domain projection，不是第二份 registry。
+- AIWorkflowRunResourceFreezeReceipt：Halfcode snapshot proof + depa selected-resource semantic fingerprint；由运行 host 持久化但不回写 source。
+- AICtrlWorkflow / AIDataWorkflow definition：workflow domain facts。
+- workflow snapshot / RunGraph：运行态，不回写 ResourcePackage 或 app projection。
+- global/workspace root、installation 与 actor/session runtime：host-owned facts，不属于 depa-flows。

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

@@ -0,0 +1,30 @@
+# L3 · BPCtrlFlow 事实与域
+
+> BPCtrlFlow 继承 [flow-core 事实与域](../flow-core/domains.md)和 [WorkCtrlFlow 持久事实](../work-ctrl-flow/domains.md)，只增加 TaskSpace authoring/runtime facts。
+
+## Authoring Facts
+
+| fact / domain | file | root / scheme | 说明 |
+|---|---|---|---|
+| `<BPCtrlFlow>` definition | 单文件或 `manifest.xnl` | 根 `[]` | 共享 CtrlFlow statements，可使用 `ExternalJob` / `Timer` / `TaskStep` |
+| `state.def` / `state.seed` | 同 WorkCtrlFlow | 同 WorkCtrlFlow | 可选实例 state shape 与只读 seed |
+| `task.space` | `task.space.xnl` | `<TaskSpace>` / `task-space://` | TaskGroup/Task 层级与初始任务事实 |
+
+`task-space://#<id>` 只在当前 bundle 内解析，唯一公开消费者是 `TaskStep.task`。目标必须是 TaskSpace 的直接子节点；深层任务由所属 TaskGroup 的 executionMode 推进。
+
+definition 中的 task status 只表示新实例初始值。运行期任务事实写 TaskSpace store，不能回写 authoring bundle；实例目录可提供只读投影，但投影不成为第二份事实源。
+
+## Runtime Ownership
+
+| fact | owner | flow 可见性 |
+|---|---|---|
+| task status/owner/history/payload | TaskSpace store | TaskStep 完成时投影为 TaskStepResult data |
+| TaskStep WaitHandle / applied signal | BPCtrlFlow snapshot | 只用于挂起、恢复与幂等 |
+| TaskStepResult | CtrlFlow data chain | 成为下一条 statement 的 input |
+| branch decision | BPCtrlFlow snapshot | 记录后复用，不重算已发生任务路径 |
+
+TaskSpace store、snapshot 与 definition 三个 owner 不得互相复制语义真源。特别是 `Refused` / `Forwarded` 等任务状态投影成 data 后，不能再写成 engine Failure。
+
+## Rejected Authoring Facts
+
+`tree.xnl`、`action.types.xnl`、`Tree` 根、独立 `CtrlFlow` 根以及公开 `Sequence` / `Selector` / `Condition` 都是已移除语法。TaskSpace 不允许用这些节点描述会签/或签；只能使用 TaskGroup 的 executionMode。