@coda-console/protocol 1.7.0 → 1.8.0

package/README.md

@@ -4,9 +4,15 @@ Coda 与插件之间的约定，Coda 和插件都引用它，独立演进：
 
 - **插件清单的类型**（`schemas/plugin/`）：插件目录 `package.json` 里 `contributes` 的每个键是一种类型，各有一份 JSON Schema（draft 2020-12，`$id` 为 `https://coda.pub/schemas/plugin/v1/<文件>`）。`plugin.json` 是整份清单，`setting.json` 是一项设置的声明。插件写的合乎它用到的类型就对；写给别的插件扩展点的键由那个插件声明，扩展点可以带自己的 schema（`extensionPoints.<名>.schema`，声明它的插件目录里的一个文件），写给它的东西合乎那份 schema 才对。
 - **通用校验器**（`validate.mjs`）：用 Ajv 对清单做 schema 校验。JSON Schema 说不了的只用五个通用关键字（`x-unique-by`、`x-max-contains`、`x-ref`、`x-placeholders`、`x-file`，照 Kubernetes 的 `x-kubernetes-*`），每个在哪里写都是同一个意思，写法见文件开头。校验器不随功能变长：类型加字段就是改 schema。
-- **流程方言**（`workflow/`）：项目和插件的流程（`.coda/workflows/*.bpmn`，BPMN 2.0）在 Coda 的命名空间 `https://coda.pub/schema/bpmn/1.0` 里能写什么。`moddle.json` 是 `coda:` 属性与元素（bpmn-moddle 的描述格式），`values.json` 是每个值能写什么（每个 `coda:` 类型的属性组成的对象的 JSON Schema，一个元素里同种 `coda:` 元素成组的 schema），`actions.json` 是 `coda:action` 的各个动作和它们接受的参数，`dialect.json` 是流程种类、Coda 自己发的事件、步骤失败的错误码、表达式能读的运行变量和运行的输入能是哪些类型。`workflow.mjs` 用它们读一份流程：方言里没有的、值不合 schema 的都拒绝，说法是「位置：schema 对那里的说明」。值的 schema 用清单的那几个关键字，另加三个：`x-feel`（是 FEEL：「=」开头是表达式，否则文字里的 `{{ … }}` 是，按这份流程里的名字读得通）、`x-duration`（ISO 8601 时长，不为负）、`x-number`（文字换算成数字是个有限的数）。流程的结构对不对（元素与事件、连接、补偿、走不到的步骤、事件启动），现在仍由 Coda 读流程时检查。
+- **流程方言**（`workflow/`）：项目和插件的流程（`.coda/workflows/*.bpmn`，BPMN 2.0）在 Coda 的命名空间 `https://coda.pub/schema/bpmn/1.0` 里能写什么。`moddle.json` 是 `coda:` 属性与元素（bpmn-moddle 的描述格式），`values.json` 是每个值能写什么（每个 `coda:` 类型的属性组成的对象的 JSON Schema，一个元素里同种 `coda:` 元素成组的 schema），`actions.json` 是 `coda:action` 的各个动作和它们接受的参数，`dialect.json` 是流程种类、Coda 自己发的事件、步骤失败的错误码、表达式能读的运行变量和运行的输入能是哪些类型。`workflow.mjs` 用它们读一份流程：方言里没有的、值不合 schema 的都拒绝，说法是「位置：schema 对那里的说明」。值的 schema 用清单的那几个关键字，另加三个：`x-feel`（是 FEEL：「=」开头是表达式，否则文字里的 `{{ … }}` 是，按这份流程里的名字读得通）、`x-duration`（ISO 8601 时长，不为负）、`x-number`（文字换算成数字是个有限的数）。`structure.json` 声明流程结构规则，`structure.mjs` 负责跨节点检查。
 - **Agent 接入协议**（`docs/agent-protocol.md`）：Coda 怎样用 ACP 接 Agent，以及 Coda 加的扩展（会话指令、插话、`_coda/wait`、执行失败、工具调用的审核）。
 
+流程方言的 **结构规则**从 1.8.0 起也由 `readWorkflow` / `workflowProblem` 检查。`workflow/structure.json` 声明支持的顶层元素与不支持的流程元素、各位置的事件定义、`coda:` 属性的位置限制、任务与多实例的局部写法、脚本数量、定时间隔和生命周期等待类型。`rules` 使用 JSON Schema 检查节点的无环投影（原始标量属性与父级、事件种类等固定事实），复用 `newAjv()` 和已有关键字；`moddle.json` 的 `extends` 仍声明属性可附着的基础类型。`CODA_STRUCTURE` 导出同一份表。新增局部规则改数据，不增加校验器分支。
+
+`structure.mjs` 的固定检查处理数据表无法单独表达的关系：事件子流程与顺序流、连接事件按作用域配对、事件网关的出口、补偿关联、经过子流程与边界事件的可达性、事件启动以及生命周期的「聋状态」。Coda 的事件名通过 `dialect.json` 的 `eventRoles` 读取；等待动作与节点类型也来自数据表。ISO 8601 重复间隔用 `@0dep/piso` 解析，脚本变量边界用固定的词法扫描检查，条件和 documentation 用同一份 FEEL 检查。图和嵌套树使用显式栈与 Map/Set，不递归、不把大数组展开成函数参数。报错尽量保留 Coda 的原位置与原话。
+
+读取定义时原有的 Coda 结构规则已全部纳入协议。Coda 接入 1.8.0 后，`parseBpmn` 只需调用 `readWorkflow`，再把 `root` 编译成引擎、任务、调度和图所需的结构；运行时才能知道的表达式结果、动态字段引用、调度设置实际值及能力是否存在，仍由宿主在运行时检查。
+
 流程方言的 **卡片字段**由 `workflow/fields.json` 定义：七种字段各能写哪些属性、必填项、文字长度与单行限制、路径与网址、视图参数、输入框与密钥选项；`values.json` 的 `Field` 引用它，`Fields` 声明读出 JSON 字段列表的表达式，`UserTask.children` 限定最多 12 个静态字段、id 不重复，以及全部字段已知时答复的 `fields` 只能引用输入字段（含按住出现的答复）。
 
 定义和运行时共用这一份 schema。`x-deferred` 包住一个 schema：读定义时，文字先检查 FEEL，表达式或含 `{{ … }}` 的模板留到打开任务后查；运行时只按包住的 schema 严格检查，不再把结果当表达式。只有内容属性使用它，`type`、`id`、布尔值、枚举和 `maxLength` 不放宽。另有 `x-length`（沿用 Coda 的 UTF-16 长度，可用 `{ "property": "maxLength" }` 读取同一对象的上限）、`x-json`（解析 JSON 文字或检查 JSON 值，按序列化后的 UTF-8 字节数限制大小）；`absolute-path`、`https-url` 两个 format 按本机路径与 URL 解析器检查。已有的 `x-ref` 增加 `key`（按数组元素的属性引用）和 `split`（逐个检查分隔后的名字）。这些操作都不改写输入。
@@ -59,7 +65,7 @@ fieldsProblem(JSON.parse(fieldsJSON), 'ask');
 
 ## 谁在用
 
-- **Coda**：读插件时用它校验清单，再整理成自己的结构；只另看插件身份（ID、设置名在 ID 之下），以及装到一台机器上才知道的（来源、已装插件的冲突）。读流程时先用 `readWorkflow` 按方言解析，再查每个值。
+- **Coda**：读插件时用它校验清单，再整理成自己的结构；只另看插件身份（ID、设置名在 ID 之下），以及装到一台机器上才知道的（来源、已装插件的冲突）。读流程时用 `readWorkflow` 同时校验方言、值与结构，再编译成引擎需要的数据。
 - **coda-plugins 的契约检查包**（`@coda-console/plugin-check`）：在写插件的地方用同一个校验器判清单。
 
 ## 版本

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@coda-console/protocol",
-  "version": "1.7.0",
+  "version": "1.8.0",
   "description": "Coda 的协议：插件清单的类型（JSON Schema）、通用校验器、流程方言与 Agent 接入协议",
   "type": "module",
   "license": "MIT",

package/workflow/dialect.json

@@ -14,6 +14,7 @@
     "workflow.dispatch": "手动发起（workflow_run、客户端的按钮）：由事件启动的流程也订阅它，才能手动发起",
     "workflow.cancel": "要它停下：在等它的运行被告知，走到自己的结束，以取消结束"
   },
+  "eventRoles": {"lifecycleStart": "session.opened", "lifecycleFacts": "session.facts", "dispatch": "workflow.dispatch", "cancel": "workflow.cancel"},
   "userMessage": "^user\\.[a-z][a-z0-9-]{0,39}$",
   "stepFailed": "STEP_FAILED",
   "variables": ["inputs", "run", "github", "vars"],

package/workflow/structure.json

@@ -0,0 +1,920 @@
+{
+  "description": "流程结构：支持的元素、事件位置、局部节点规则与属性位置。rules 对 structure.mjs 的无环节点投影运行 JSON Schema；跨节点引用、配对、可达性与生命周期等待由固定图检查负责。",
+  "unsupported": {
+    "bpmn:SendTask": "Coda 的消息是外部来的事件，流程只收不发；流程里互相通知用信号（signal）",
+    "bpmn:BusinessRuleTask": "Coda 不带决策表：判断写成网关的条件，或一个 scriptTask",
+    "bpmn:ComplexGateway": "引擎不运行复杂网关：写成包容网关，各出口带条件",
+    "bpmn:DataObject": "数据按任务结果与变量传递（见「表达式」），不写数据对象",
+    "bpmn:DataObjectReference": "数据按任务结果与变量传递（见「表达式」），不写数据对象",
+    "bpmn:DataStoreReference": "数据按任务结果与变量传递（见「表达式」），不写数据对象",
+    "bpmn:ImplicitThrowEvent": "它不是流程里的元素",
+    "bpmn:ChoreographyTask": "协作图的元素不在流程里运行",
+    "bpmn:SubChoreography": "协作图的元素不在流程里运行",
+    "bpmn:CallChoreography": "协作图的元素不在流程里运行"
+  },
+  "events": {
+    "start": [
+      "Message",
+      "Timer"
+    ],
+    "eventStart": [
+      "Message",
+      "Timer",
+      "Signal",
+      "Conditional",
+      "Error",
+      "Escalation"
+    ],
+    "innerStart": [],
+    "bpmn:EndEvent": [
+      "Error",
+      "Terminate",
+      "Signal",
+      "Escalation",
+      "Compensate",
+      "Cancel"
+    ],
+    "bpmn:IntermediateCatchEvent": [
+      "Timer",
+      "Message",
+      "Signal",
+      "Conditional",
+      "Link"
+    ],
+    "bpmn:IntermediateThrowEvent": [
+      "Signal",
+      "Escalation",
+      "Link",
+      "Compensate"
+    ],
+    "bpmn:BoundaryEvent": [
+      "Error",
+      "Timer",
+      "Message",
+      "Signal",
+      "Escalation",
+      "Conditional",
+      "Compensate",
+      "Cancel"
+    ]
+  },
+  "eventNames": {
+    "start": "流程的开始事件",
+    "eventStart": "事件子流程的开始事件",
+    "innerStart": "子流程的开始事件",
+    "bpmn:EndEvent": "结束事件",
+    "bpmn:IntermediateCatchEvent": "中间捕获事件",
+    "bpmn:IntermediateThrowEvent": "中间抛出事件",
+    "bpmn:BoundaryEvent": "边界事件"
+  },
+  "kindNames": {
+    "Message": "消息",
+    "Timer": "计时器",
+    "Signal": "信号",
+    "Conditional": "条件",
+    "Error": "出错",
+    "Escalation": "升级",
+    "Terminate": "终止",
+    "Link": "连接",
+    "Compensate": "补偿",
+    "Cancel": "取消"
+  },
+  "topLevel": [
+    "bpmn:Process",
+    "bpmn:Error",
+    "bpmn:Signal",
+    "bpmn:Escalation",
+    "bpmn:Message"
+  ],
+  "id": {
+    "pattern": "^[A-Za-z_][A-Za-z0-9_-]{0,63}$",
+    "description": "id 须为字母开头的字母、数字、「_」「-」"
+  },
+  "requiredEvents": [
+    "eventStart",
+    "bpmn:IntermediateCatchEvent",
+    "bpmn:BoundaryEvent"
+  ],
+  "eventSuffix": {
+    "start": "；运行里发生的信号、条件、出错或升级，交给事件子流程（triggeredByEvent）",
+    "innerStart": "；只有最外层的开始事件能带计时器或消息，子流程里要等事件，用中间捕获事件或事件子流程"
+  },
+  "throwing": [
+    "bpmn:IntermediateThrowEvent",
+    "bpmn:EndEvent"
+  ],
+  "steps": [
+    "bpmn:ScriptTask",
+    "bpmn:ServiceTask",
+    "bpmn:UserTask",
+    "bpmn:CallActivity"
+  ],
+  "maxScripts": 50,
+  "schedule": {
+    "maxLength": 200,
+    "minMilliseconds": 300000,
+    "settingsPattern": "^\\s*=\\s*vars(\\.[A-Za-z0-9_-]+)+\\s*$",
+    "description": "定时开始只接受无限重复、无结束时间、间隔至少 5 分钟；表达式只读插件设置。"
+  },
+  "lifecycle": {
+    "waitTypes": [
+      "bpmn:ReceiveTask",
+      "bpmn:IntermediateCatchEvent",
+      "bpmn:CallActivity",
+      "bpmn:ScriptTask"
+    ],
+    "waitActions": [
+      "run-workflows"
+    ],
+    "description": "这些节点会等待；其余带计时边界的非子流程节点也会等待。生命周期流程的等待必须能收会话事实。"
+  },
+  "userMessages": {
+    "prefix": "user.",
+    "maxLabelLength": 40
+  },
+  "inputFields": [
+    "text",
+    "secret"
+  ],
+  "rules": [
+    {
+      "description": "coda:expect 只写在子流程上",
+      "schema": {
+        "properties": {
+          "subprocess": {
+            "const": true
+          }
+        }
+      },
+      "when": {
+        "required": [
+          "expect"
+        ]
+      }
+    },
+    {
+      "description": "coda:optional 只写在最外层的子流程上（事件子流程不是阶段）",
+      "schema": {
+        "allOf": [
+          {
+            "properties": {
+              "subprocess": {
+                "const": true
+              },
+              "top": {
+                "const": true
+              }
+            }
+          },
+          {
+            "not": {
+              "properties": {
+                "triggeredByEvent": {
+                  "const": true
+                }
+              }
+            }
+          }
+        ]
+      },
+      "when": {
+        "required": [
+          "optional"
+        ]
+      }
+    },
+    {
+      "description": "coda:notify 只写在流程最外层的结束事件上",
+      "schema": {
+        "properties": {
+          "type": {
+            "const": "bpmn:EndEvent"
+          },
+          "top": {
+            "const": true
+          }
+        }
+      },
+      "when": {
+        "required": [
+          "notify"
+        ]
+      }
+    },
+    {
+      "description": "coda:reportTo、coda:reportOn、coda:scope 只写在定时开始事件上（由会话发起的运行交给发起它的会话）",
+      "schema": {
+        "properties": {
+          "position": {
+            "const": "start"
+          },
+          "eventKind": {
+            "const": "Timer"
+          }
+        }
+      },
+      "when": {
+        "anyOf": [
+          {
+            "required": [
+              "reportTo"
+            ]
+          },
+          {
+            "required": [
+              "reportOn"
+            ]
+          },
+          {
+            "required": [
+              "scope"
+            ]
+          }
+        ]
+      }
+    },
+    {
+      "description": "脚本步骤写成 <scriptTask scriptFormat=\"bash\">，脚本放在 <script> 里；serviceTask 只用于 coda:action",
+      "schema": {
+        "required": [
+          "action"
+        ]
+      },
+      "on": [
+        "bpmn:ServiceTask"
+      ],
+      "when": {
+        "properties": {
+          "hasScriptExtension": {
+            "const": true
+          }
+        }
+      }
+    },
+    {
+      "description": "serviceTask 是 Coda 自己做的一步，须写 coda:action；脚本步骤写成 scriptTask",
+      "schema": {
+        "required": [
+          "action"
+        ]
+      },
+      "on": [
+        "bpmn:ServiceTask"
+      ]
+    },
+    {
+      "description": "coda:action 的步骤由 Coda 执行，不写脚本与 coda:audience、coda:group、coda:timeout、coda:checkout、coda:retry 等（要为一段占组用 hold-group）",
+      "schema": {
+        "allOf": [
+          {
+            "properties": {
+              "hasScriptExtension": {
+                "const": false
+              }
+            }
+          },
+          {
+            "not": {
+              "anyOf": [
+                {
+                  "required": [
+                    "audience"
+                  ]
+                },
+                {
+                  "required": [
+                    "group"
+                  ]
+                },
+                {
+                  "required": [
+                    "timeout"
+                  ]
+                },
+                {
+                  "required": [
+                    "cancelTimeout"
+                  ]
+                },
+                {
+                  "required": [
+                    "workingDirectory"
+                  ]
+                },
+                {
+                  "required": [
+                    "checkout"
+                  ]
+                },
+                {
+                  "required": [
+                    "retry"
+                  ]
+                },
+                {
+                  "required": [
+                    "implementation"
+                  ],
+                  "properties": {
+                    "implementation": {
+                      "minLength": 1
+                    }
+                  }
+                }
+              ]
+            }
+          }
+        ]
+      },
+      "on": [
+        "bpmn:ServiceTask"
+      ]
+    },
+    {
+      "description": "callActivity 的 calledElement 写要调用的能力或流程名（小写字母、数字和「-」，以字母开头）",
+      "schema": {
+        "required": [
+          "calledElement"
+        ],
+        "properties": {
+          "calledElement": {
+            "type": "string",
+            "pattern": "^[a-z][a-z0-9-]{0,63}$"
+          }
+        }
+      },
+      "on": [
+        "bpmn:CallActivity"
+      ]
+    },
+    {
+      "description": "scriptTask 写 scriptFormat=\"bash\"（脚本由 bash -e 执行）",
+      "schema": {
+        "required": [
+          "scriptFormat"
+        ],
+        "properties": {
+          "scriptFormat": {
+            "const": "bash"
+          }
+        }
+      },
+      "on": [
+        "bpmn:ScriptTask"
+      ]
+    },
+    {
+      "description": "脚本放在 scriptTask 的 <script> 里，不写 coda:script",
+      "schema": {
+        "properties": {
+          "hasScriptExtension": {
+            "const": false
+          }
+        }
+      },
+      "on": [
+        "bpmn:ScriptTask"
+      ]
+    },
+    {
+      "description": "scriptTask 需要 <script>",
+      "schema": {
+        "required": [
+          "script"
+        ],
+        "properties": {
+          "script": {
+            "pattern": "\\S"
+          }
+        }
+      },
+      "on": [
+        "bpmn:ScriptTask"
+      ]
+    },
+    {
+      "description": "脚本过长",
+      "schema": {
+        "properties": {
+          "script": {
+            "x-length": 20000
+          }
+        }
+      },
+      "on": [
+        "bpmn:ScriptTask"
+      ]
+    },
+    {
+      "description": "coda:output 只写在自动步骤与结束事件上",
+      "schema": {
+        "properties": {
+          "type": {
+            "enum": [
+              "bpmn:ScriptTask",
+              "bpmn:EndEvent"
+            ]
+          }
+        }
+      },
+      "when": {
+        "properties": {
+          "hasOutputs": {
+            "const": true
+          }
+        }
+      }
+    },
+    {
+      "description": "脚本步骤的 coda:output 只写 name，值由脚本写进 $GITHUB_OUTPUT",
+      "schema": {
+        "properties": {
+          "outputHasValue": {
+            "const": false
+          }
+        }
+      },
+      "on": [
+        "bpmn:ScriptTask"
+      ]
+    },
+    {
+      "description": "documentation 过长",
+      "schema": {
+        "properties": {
+          "documentation": {
+            "x-length": 4000
+          }
+        }
+      },
+      "on": [
+        "bpmn:UserTask"
+      ]
+    },
+    {
+      "description": "有输入字段（text、secret 或 coda:fields）的任务只交给用户，写 coda:assignee=\"user\"",
+      "schema": {
+        "required": [
+          "assignee"
+        ],
+        "properties": {
+          "assignee": {
+            "const": "user"
+          }
+        }
+      },
+      "on": [
+        "bpmn:UserTask"
+      ],
+      "when": {
+        "properties": {
+          "hasInputFields": {
+            "const": true
+          }
+        }
+      }
+    },
+    {
+      "description": "不支持标准循环（standardLoopCharacteristics）：重复做一件事写成连回去的连线加网关，按集合或次数做多份写多实例",
+      "schema": {
+        "properties": {
+          "loopType": {
+            "const": "bpmn:MultiInstanceLoopCharacteristics"
+          }
+        }
+      },
+      "when": {
+        "required": [
+          "loopType"
+        ]
+      },
+      "at": "path"
+    },
+    {
+      "description": "多实例只写在任务、子流程与 callActivity 上",
+      "schema": {
+        "allOf": [
+          {
+            "properties": {
+              "type": {
+                "enum": [
+                  "bpmn:Task",
+                  "bpmn:ManualTask",
+                  "bpmn:ScriptTask",
+                  "bpmn:ServiceTask",
+                  "bpmn:UserTask",
+                  "bpmn:ReceiveTask",
+                  "bpmn:CallActivity",
+                  "bpmn:SubProcess",
+                  "bpmn:Transaction",
+                  "bpmn:AdHocSubProcess"
+                ]
+              }
+            }
+          },
+          {
+            "not": {
+              "properties": {
+                "triggeredByEvent": {
+                  "const": true
+                }
+              }
+            }
+          }
+        ]
+      },
+      "when": {
+        "required": [
+          "loopType"
+        ]
+      },
+      "at": "path"
+    },
+    {
+      "description": "多实例要写做几份：coda:inputCollection（按集合，每份一个元素）或 loopCardinality（次数）",
+      "schema": {
+        "anyOf": [
+          {
+            "required": [
+              "collection"
+            ]
+          },
+          {
+            "required": [
+              "cardinality"
+            ]
+          }
+        ]
+      },
+      "when": {
+        "required": [
+          "loopType"
+        ]
+      },
+      "at": "path"
+    },
+    {
+      "description": "loopCardinality 写非负整数，或「=」开头的 FEEL 表达式",
+      "schema": {
+        "properties": {
+          "cardinality": {
+            "pattern": "^(?:\\s*=|\\d+$)"
+          }
+        }
+      },
+      "when": {
+        "required": [
+          "cardinality"
+        ]
+      },
+      "at": "path"
+    },
+    {
+      "description": "completionCondition 须为「=」开头的 FEEL 表达式，如 =deploy.ok",
+      "schema": {
+        "properties": {
+          "loopCompletion": {
+            "pattern": "^\\s*="
+          }
+        }
+      },
+      "when": {
+        "required": [
+          "loopCompletion"
+        ]
+      },
+      "at": "path"
+    },
+    {
+      "description": "completionCondition 须为「=」开头的 FEEL 表达式",
+      "schema": {
+        "properties": {
+          "completion": {
+            "pattern": "^\\s*="
+          }
+        }
+      },
+      "on": [
+        "bpmn:AdHocSubProcess"
+      ],
+      "when": {
+        "required": [
+          "completion"
+        ]
+      }
+    },
+    {
+      "description": "自由子流程里不写开始、结束事件：里面没有进线的节点都会开始",
+      "schema": {
+        "properties": {
+          "hasStartOrEnd": {
+            "const": false
+          }
+        }
+      },
+      "on": [
+        "bpmn:AdHocSubProcess"
+      ]
+    },
+    {
+      "description": "出错开始的事件子流程总是打断它所在的范围，不写 isInterrupting=\"false\"",
+      "schema": {
+        "not": {
+          "properties": {
+            "isInterrupting": {
+              "const": false
+            }
+          }
+        }
+      },
+      "when": {
+        "properties": {
+          "position": {
+            "const": "eventStart"
+          },
+          "eventKind": {
+            "const": "Error"
+          }
+        }
+      },
+      "at": "path"
+    },
+    {
+      "description": "事件子流程的计时器写 timeDuration 或 timeDate，从它所在的范围开始时算起",
+      "schema": {
+        "properties": {
+          "hasTimeCycle": {
+            "const": false
+          }
+        }
+      },
+      "when": {
+        "properties": {
+          "position": {
+            "const": "eventStart"
+          },
+          "eventKind": {
+            "const": "Timer"
+          }
+        }
+      },
+      "at": "path"
+    },
+    {
+      "description": "消息须引用一个有 name 的 <message>（name 是 Coda 的事件名，如 session.facts）",
+      "schema": {
+        "properties": {
+          "messageNamed": {
+            "const": true
+          }
+        }
+      },
+      "when": {
+        "properties": {
+          "eventKind": {
+            "const": "Message"
+          }
+        }
+      },
+      "at": "path"
+    },
+    {
+      "description": "receiveTask 须引用一个有 name 的 <message>（name 是 Coda 的事件名，如 session.facts）",
+      "schema": {
+        "properties": {
+          "messageNamed": {
+            "const": true
+          }
+        }
+      },
+      "on": [
+        "bpmn:ReceiveTask"
+      ],
+      "at": "path"
+    },
+    {
+      "description": "信号须引用一个 <signal>，抛出与捕获按它配对",
+      "schema": {
+        "properties": {
+          "signalReferenced": {
+            "const": true
+          }
+        }
+      },
+      "when": {
+        "properties": {
+          "eventKind": {
+            "const": "Signal"
+          }
+        }
+      },
+      "at": "path"
+    },
+    {
+      "description": "抛出的升级须引用一个 <escalation>",
+      "schema": {
+        "properties": {
+          "escalationReferenced": {
+            "const": true
+          }
+        }
+      },
+      "on": [
+        "bpmn:IntermediateThrowEvent",
+        "bpmn:EndEvent"
+      ],
+      "when": {
+        "properties": {
+          "eventKind": {
+            "const": "Escalation"
+          }
+        }
+      },
+      "at": "path"
+    },
+    {
+      "description": "连接事件须写 name，抛出与捕获按它配对",
+      "schema": {
+        "properties": {
+          "linkNamed": {
+            "const": true
+          }
+        }
+      },
+      "when": {
+        "properties": {
+          "eventKind": {
+            "const": "Link"
+          }
+        }
+      },
+      "at": "path"
+    },
+    {
+      "description": "条件只支持 FEEL 表达式，不运行脚本",
+      "schema": {
+        "properties": {
+          "conditionLanguage": {
+            "enum": [
+              "",
+              "feel"
+            ]
+          }
+        }
+      },
+      "when": {
+        "required": [
+          "conditionLanguage"
+        ]
+      },
+      "at": "path"
+    },
+    {
+      "description": "条件事件的条件须为「=」开头的 FEEL 表达式，如 =checks.passed",
+      "schema": {
+        "required": [
+          "condition"
+        ],
+        "properties": {
+          "condition": {
+            "pattern": "^\\s*="
+          }
+        }
+      },
+      "when": {
+        "properties": {
+          "eventKind": {
+            "const": "Conditional"
+          }
+        }
+      },
+      "at": "path"
+    },
+    {
+      "description": "条件须为「=」开头的 FEEL 表达式，如 =check.go",
+      "schema": {
+        "required": [
+          "condition"
+        ],
+        "properties": {
+          "condition": {
+            "pattern": "^\\s*="
+          }
+        }
+      },
+      "on": [
+        "bpmn:SequenceFlow"
+      ],
+      "when": {
+        "properties": {
+          "hasCondition": {
+            "const": true
+          }
+        }
+      },
+      "at": "path"
+    },
+    {
+      "description": "取消结束事件只写在事务子流程（transaction）里",
+      "schema": {
+        "properties": {
+          "parentType": {
+            "const": "bpmn:Transaction"
+          }
+        }
+      },
+      "on": [
+        "bpmn:EndEvent"
+      ],
+      "when": {
+        "properties": {
+          "eventKind": {
+            "const": "Cancel"
+          }
+        }
+      }
+    },
+    {
+      "description": "取消边界事件只挂在事务子流程（transaction）上",
+      "schema": {
+        "properties": {
+          "attachedType": {
+            "const": "bpmn:Transaction"
+          }
+        }
+      },
+      "on": [
+        "bpmn:BoundaryEvent"
+      ],
+      "when": {
+        "properties": {
+          "eventKind": {
+            "const": "Cancel"
+          }
+        }
+      }
+    }
+  ],
+  "readable": [
+    {
+      "property": "condition",
+      "where": "path"
+    },
+    {
+      "property": "cardinality",
+      "where": "path 的 loopCardinality"
+    },
+    {
+      "property": "loopCompletion",
+      "where": "path 的 completionCondition"
+    },
+    {
+      "property": "completion",
+      "where": "id 的 completionCondition"
+    },
+    {
+      "property": "documentation",
+      "where": "id 的 documentation"
+    },
+    {
+      "property": "timeDuration",
+      "where": "path 的 timeDuration"
+    },
+    {
+      "property": "timeDate",
+      "where": "path 的 timeDate"
+    },
+    {
+      "property": "timeCycle",
+      "where": "path 的 timeCycle"
+    }
+  ],
+  "projection": {
+    "description": "rules.schema 和 rules.when 检查节点的无环投影；on 是精确 BPMN 类型列表；at 为 path 时使用 process/子流程/节点，其余用节点 id。未提供的属性为 undefined（Ajv 当作缺失）。原始标量属性按原名保留。",
+    "facts": {
+      "type": "BPMN 类型",
+      "top": "是否直属 process",
+      "parentType": "父元素类型",
+      "subprocess": "是否属于 SubProcess（含 transaction 与 adHoc）",
+      "position": "开始事件按 start / innerStart / eventStart 区分，其余为 BPMN 类型",
+      "eventKind": "第一个事件定义的种类；事件数量另按 events 表检查",
+      "messageNamed": "引用的 message 是否有 name",
+      "signalReferenced": "是否引用 signal",
+      "escalationReferenced": "是否引用 escalation",
+      "linkNamed": "link 是否有非空 name",
+      "attachedType": "边界事件挂靠节点的类型",
+      "condition": "条件正文",
+      "conditionLanguage": "条件声明的语言",
+      "hasCondition": "是否写了条件",
+      "timeDuration / timeDate / timeCycle": "第一个事件定义中对应时间的正文",
+      "loopType / collection / cardinality / loopCompletion": "多实例类型、集合、次数和完成条件",
+      "completion": "自由子流程的完成条件",
+      "hasStartOrEnd": "直接子节点是否有开始或结束事件",
+      "hasScriptExtension": "是否写 coda:script",
+      "hasOutputs / outputHasValue": "是否有 coda:output，以及是否有输出声明 value",
+      "documentation": "人工任务 documentation 合并后的文字",
+      "hasInputFields": "是否有 inputFields 中类型的字段或动态 coda:fields",
+      "hasTimeCycle": "是否声明 timeCycle 元素（包括空元素）"
+    }
+  }
+}

package/workflow/structure.mjs

@@ -0,0 +1,256 @@
+// Fixed BPMN topology checks. Local constraints and vocabulary live in structure.json; Coda's event names live in
+// dialect.json. No engine compilation or expression evaluation takes place here. Maps keep arbitrary BPMN ids safe.
+import { ISOInterval } from '@0dep/piso';
+import structure from './structure.json' with { type: 'json' };
+import dialect from './dialect.json' with { type: 'json' };
+
+export const CODA_STRUCTURE = structure;
+const extras = (node, type) => (node.extensionElements?.values ?? []).filter(v => v.$type === type);
+const kinds = node => (node.eventDefinitions ?? []).map(d => d.$type.slice(5).replace(/EventDefinition$/, ''));
+const hasEvent = (node, kind) => kinds(node).includes(kind);
+const own = (table, key) => Object.hasOwn(table, key) ? table[key] : undefined;
+const linkName = node => node.eventDefinitions?.find(d => d.$type === 'bpmn:LinkEventDefinition')?.name?.trim();
+const check = (ok, message) => { if (!ok) throw new StructureProblem(message); };
+class StructureProblem extends Error {}
+
+// Only scalar values and derived facts go into Ajv, never moddle's cyclic references or a nested subtree.
+function facts(n, process) {
+  const data = Object.fromEntries(Object.entries(n).filter(([, v]) => v !== undefined && (v === null || typeof v !== 'object')));
+  const event = n.eventDefinitions?.[0], loop = n.loopCharacteristics;
+  const condition = n.conditionExpression ?? event?.condition;
+  return { ...data, type: n.$type, top: n.$parent === process, parentType: n.$parent?.$type,
+    subprocess: !!n.$instanceOf('bpmn:SubProcess'), triggeredByEvent: !!n.triggeredByEvent,
+    isInterrupting: n.isInterrupting !== false, attachedType: n.attachedToRef?.$type ?? '',
+    position: n.$type !== 'bpmn:StartEvent' ? n.$type : n.$parent === process ? 'start' : n.$parent.triggeredByEvent ? 'eventStart' : 'innerStart',
+    eventKind: kinds(n)[0] ?? '', messageNamed: !!(event?.messageRef?.name ?? n.messageRef?.name),
+    signalReferenced: !!event?.signalRef, escalationReferenced: !!event?.escalationRef, linkNamed: !!linkName(n),
+    hasCondition: !!condition, condition: condition?.body, conditionLanguage: condition?.language,
+    timeDuration: event?.timeDuration?.body, timeDate: event?.timeDate?.body, timeCycle: event?.timeCycle?.body, hasTimeCycle: !!event?.timeCycle,
+    loopType: loop?.$type, collection: loop?.inputCollection, cardinality: loop?.loopCardinality?.body?.trim(),
+    loopCompletion: loop?.completionCondition?.body, completion: n.completionCondition?.body,
+    hasStartOrEnd: (n.flowElements ?? []).some(e => ['bpmn:StartEvent', 'bpmn:EndEvent'].includes(e.$type)),
+    hasScriptExtension: extras(n, 'coda:Script').length > 0, hasOutputs: extras(n, 'coda:Output').length > 0,
+    outputHasValue: extras(n, 'coda:Output').some(o => o.value !== undefined),
+    documentation: n.$type === 'bpmn:UserTask' ? (n.documentation ?? []).map(d => d.text ?? '').join('\n').trim() : undefined,
+    hasInputFields: extras(n, 'coda:Fields').length > 0 || extras(n, 'coda:Field').some(f => structure.inputFields.includes(f.type)),
+  };
+}
+
+// Shell variable boundaries are lexical, not a shell parser: preserve Coda's treatment of escapes, $$, comments and quotes.
+function scriptProblem(script, where) {
+  for (let i = 0; i < script.length; i++) {
+    if (script[i] === '\\') { i++; continue; }
+    if (script[i] !== '$') continue;
+    if (script[i + 1] === '$') { i++; continue; }
+    const name = /^[A-Za-z_][A-Za-z0-9_]*/.exec(script.slice(i + 1))?.[0];
+    if (!name) continue;
+    const after = i + 1 + name.length;
+    if (script.codePointAt(after) > 0x7f) {
+      const next = String.fromCodePoint(script.codePointAt(after));
+      return `${where} 里的 \`$${name}\` 后面紧跟「${next}」，macOS 的 bash 会把它读进变量名而展开为空：` +
+        `要展开变量写成 \`\${${name}}${next}\`，要原样输出这几个字写成 \`\\$${name}${next}\`（不放在单引号里）；这条检查不区分引号与注释`;
+    }
+    i = after - 1;
+  }
+  return null;
+}
+function scheduleCycle(text, where) {
+  check(typeof text === 'string' && text.trim() && text.length <= structure.schedule.maxLength, `${where} 须为 ISO 8601 重复间隔，如 R/PT6H`);
+  let interval;
+  try { interval = new ISOInterval(text.trim()).parse(); }
+  catch { check(false, `${where} 不是 ISO 8601 重复间隔：${text}（如 R/PT6H）`); }
+  check(interval.repeat === -1 && interval.duration && !interval.end,
+    `${where} 只接受不限次数、不写结束时间的重复间隔：R/<时长> 或 R/<开始时刻>/<时长>，如 R/PT6H；现为 ${text}`);
+  check(interval.duration.toMilliseconds(new Date()) >= structure.schedule.minMilliseconds, `${where} 的间隔至少 5 分钟：${text}`);
+}
+
+export function structureChecker(ajv, { feelProblem, isExpression }) {
+  const rules = structure.rules.map(rule => ({ ...rule, validate: ajv.compile(rule.schema), applies: rule.when && ajv.compile(rule.when) }));
+  const idPattern = new RegExp(structure.id.pattern), settingsPattern = new RegExp(structure.schedule.settingsPattern);
+  return (root, file) => {
+    try { validate(root, file); return null; }
+    catch (error) { if (error instanceof StructureProblem) return error.message; throw error; }
+  };
+
+  function validate(root, file) {
+    const roots = root.rootElements ?? [], processes = roots.filter(e => e.$type === 'bpmn:Process');
+    check(processes.length === 1, `${file}.bpmn 须恰好有一个 process，现有 ${processes.length} 个`);
+    const [process] = processes;
+    check(process.isExecutable === true, `${file}.bpmn 的 process 须写明可执行（isExecutable="true"）`);
+    const others = roots.filter(e => !structure.topLevel.includes(e.$type));
+    check(!others.length, `${file}.bpmn 里有 Coda 不支持的顶层元素：${others.map(e => e.$type).join('、')}`);
+    const nodes = new Map(), flows = [], associations = [], entries = [];
+    // Stack frames retain the scope rather than constructing every ancestor path up front (quadratic in nesting depth).
+    const stack = [{ container: process, index: 0 }];
+    while (stack.length) {
+      const frame = stack.at(-1), children = frame.container.flowElements ?? [];
+      if (frame.index === 0) for (const a of frame.container.artifacts ?? []) if (a.$type === 'bpmn:Association') associations.push(a);
+      if (frame.index === children.length) { stack.pop(); continue; }
+      const n = children[frame.index++];
+      entries.push(n);
+      if (n.$type === 'bpmn:SequenceFlow') flows.push(n); else nodes.set(n.id, n);
+      if (n.$instanceOf('bpmn:SubProcess')) stack.push({ container: n, index: 0 });
+    }
+    const path = n => { const parts = []; for (let at = n; at && at !== root; at = at.$parent) parts.push(at.id); return parts.reverse().join('/'); };
+    const names = Object.create(null);
+    for (const name of dialect.variables) names[name] = null;
+    for (const n of roots) if (n.$type === 'bpmn:Message') names[n.id] = null;
+    for (const n of entries) names[n.id] = null;
+    const ids = new Set(Object.keys(names));
+    for (const n of entries) if (n.loopCharacteristics) {
+      if (n.loopCharacteristics.inputElement !== undefined) names[n.loopCharacteristics.inputElement] = null;
+      names.loopCounter = null;
+    }
+    const readable = (value, where) => { const problem = feelProblem(value, names); check(!problem, `${where}：${problem}`); };
+    for (const n of entries) {
+      if (!idPattern.test(n.id ?? '')) check(false, `${path(n)}：${structure.id.description}`);
+      if (dialect.variables.includes(n.id)) check(false, `${path(n)}：id 不能是 ${dialect.variables.join('、')}：表达式按这些名字读运行自带的变量，任务的结果按 id 读`);
+      const unsupported = own(structure.unsupported, n.$type);
+      if (unsupported) check(false, `${path(n)}：Coda 不运行 ${n.$type.slice(5)}：${unsupported}`);
+      const data = facts(n, process), allowed = own(structure.events, data.position);
+      if (allowed) {
+        const definitions = kinds(n), listed = allowed.map(k => structure.kindNames[k]).join('、');
+        if (definitions.length > 1) check(false, `${path(n)}：一个事件只带一个事件定义；要等几个事件里先来的一个，在它们前面放一个事件网关（eventBasedGateway）`);
+        for (const kind of definitions) {
+          if (kind === 'Message' && structure.throwing.includes(data.position)) check(false, `${path(n)}：${structure.unsupported['bpmn:SendTask']}`);
+          if (!allowed.includes(kind)) check(false, `${path(n)}：${structure.eventNames[data.position]}${allowed.length ? `只能是${listed}事件` : '不带事件定义'}${own(structure.eventSuffix, data.position) ?? ''}`);
+        }
+        if (structure.requiredEvents.includes(data.position) && definitions.length !== 1) check(false, `${path(n)}：${structure.eventNames[data.position]}要带一个事件定义（${listed}）`);
+      }
+      for (const rule of rules) {
+        if (rule.on && !rule.on.includes(n.$type) || rule.applies && !rule.applies(data)) continue;
+        if (!rule.validate(data)) check(false, `${rule.at === 'path' ? path(n) : n.id}：${rule.description}`);
+      }
+      for (const spec of structure.readable) if (data[spec.property] !== undefined)
+        readable(data[spec.property], spec.where.replace(/^(path|id)/, kind => kind === 'path' ? path(n) : n.id));
+      const loopName = n.loopCharacteristics?.inputElement;
+      if (loopName !== undefined && ids.has(loopName)) check(false, `${path(n)}：coda:inputElement 不能是节点、消息的 id`);
+      if (n.$type === 'bpmn:ScriptTask') { const problem = scriptProblem(n.script, `${n.id} 的脚本`); check(!problem, problem); }
+      if (n.$type === 'bpmn:EndEvent') for (const output of extras(n, 'coda:Output'))
+        check(output.value !== undefined, `${n.id} 的 coda:output ${output.name} 需要 value（不超过 4000 字）`);
+    }
+    const list = [...nodes.values()], startEvents = list.filter(n => n.$type === 'bpmn:StartEvent' && n.$parent === process);
+    const incoming = new Map(), outgoing = new Map(), attached = new Map();
+    const add = (map, key, value) => { if (!map.has(key)) map.set(key, []); map.get(key).push(value); };
+    for (const f of flows) {
+      if (!nodes.has(f.sourceRef?.id) || !nodes.has(f.targetRef?.id)) check(false, `${path(f)}：顺序流须引用流程中的起点与终点`);
+      add(outgoing, f.sourceRef, f); add(incoming, f.targetRef, f);
+    }
+    for (const n of list) if (n.$type === 'bpmn:BoundaryEvent') {
+      if (!nodes.has(n.attachedToRef?.id)) check(false, `${path(n)}：边界事件须引用挂靠的活动（attachedToRef）`);
+      add(attached, n.attachedToRef, n);
+    }
+    for (const n of list) if (n.$type === 'bpmn:SubProcess' && n.triggeredByEvent) {
+      check((n.flowElements ?? []).filter(e => e.$type === 'bpmn:StartEvent').length === 1, `${n.id}：事件子流程恰好一个开始事件，由它的事件启动`);
+      check(!outgoing.has(n) && !incoming.has(n), `${n.id}：事件子流程不连顺序流，由它开始事件的事件启动`);
+      check(!attached.has(n), `${n.id}：事件子流程上不挂边界事件`);
+    }
+    const catchesByScope = new Map(), links = [];
+    for (const n of list) if (n.$type === 'bpmn:IntermediateCatchEvent' && linkName(n)) {
+      if (!catchesByScope.has(n.$parent)) catchesByScope.set(n.$parent, new Map());
+      const scope = catchesByScope.get(n.$parent), name = linkName(n);
+      check(!scope.has(name), `${n.id}：同一层里只能有一个名为「${name}」的连接捕获事件`);
+      scope.set(name, n);
+    }
+    for (const n of list) if (n.$type === 'bpmn:IntermediateThrowEvent' && linkName(n)) {
+      const to = catchesByScope.get(n.$parent)?.get(linkName(n));
+      check(to, `${n.id}：同一层里没有名为「${linkName(n)}」的连接捕获事件`);
+      links.push([n, to]);
+    }
+    for (const n of list) if (n.$type === 'bpmn:EventBasedGateway') {
+      const out = outgoing.get(n) ?? [];
+      check(out.length >= 2, `${n.id}：事件网关后面至少接两个等待的事件`);
+      check(out.every(f => !f.conditionExpression), `${n.id}：事件网关的出口不写条件，走哪条由先来的事件决定`);
+      check(out.every(f => f.targetRef.$type === 'bpmn:ReceiveTask' || f.targetRef.$type === 'bpmn:IntermediateCatchEvent' && !linkName(f.targetRef)),
+        `${n.id}：事件网关的出口只接中间捕获事件（消息、计时器、信号、条件）或 receiveTask`);
+    }
+    check(startEvents.length, `${file}.bpmn 需要一个开始事件`);
+    const handlers = new Map(), compensations = [], compensated = new Set();
+    for (const a of associations) add(handlers, a.sourceRef, a.targetRef);
+    for (const n of list) if (n.$type === 'bpmn:BoundaryEvent' && hasEvent(n, 'Compensate')) {
+      check(!outgoing.has(n), `${n.id}：补偿边界事件不连顺序流，用关联（association）连到做补偿的节点`);
+      const to = handlers.get(n) ?? [];
+      check(to.length === 1 && to[0]?.isForCompensation, `${n.id}：补偿边界事件用一条关联（association）连到一个标了 isForCompensation="true" 的节点`);
+      compensations.push([n, to[0]]); compensated.add(to[0]);
+    }
+    for (const n of list) if (n.isForCompensation) {
+      check(!outgoing.has(n) && !incoming.has(n), `${n.id}：做补偿的节点（isForCompensation）不连顺序流，由补偿边界事件的关联引到`);
+      check(compensated.has(n), `${n.id}：没有补偿边界事件用关联引到这个做补偿的节点`);
+    }
+    const scripts = list.filter(n => n.$type === 'bpmn:ScriptTask'), services = list.filter(n => n.$type === 'bpmn:ServiceTask');
+    check(scripts.length <= structure.maxScripts, `${file}.bpmn 最多 ${structure.maxScripts} 个 scriptTask`);
+    check(list.some(n => structure.steps.includes(n.$type)), `${file}.bpmn 至少要有一个 scriptTask、serviceTask、userTask 或 callActivity`);
+    // Reachability includes boundary, link, compensation and scope entry/exit edges. Explicit worklists terminate on cycles.
+    const next = new Map();
+    for (const f of flows) add(next, f.sourceRef, f.targetRef);
+    for (const [n, boundaries] of attached) for (const b of boundaries) add(next, n, b);
+    for (const [from, to] of links) add(next, from, to);
+    for (const n of list) if (n.$instanceOf('bpmn:SubProcess')) {
+      const adHoc = n.$type === 'bpmn:AdHocSubProcess';
+      for (const inner of n.flowElements ?? []) {
+        const flowing = !['bpmn:BoundaryEvent', 'bpmn:SequenceFlow'].includes(inner.$type) && !inner.isForCompensation;
+        if (adHoc ? flowing && !incoming.has(inner) : inner.$type === 'bpmn:StartEvent') add(next, n, inner);
+        if (adHoc ? flowing && !outgoing.has(inner) : inner.$type === 'bpmn:EndEvent')
+          for (const to of next.get(n) ?? []) if (to.$parent !== n) add(next, inner, to);
+      }
+    }
+    for (const [from, to] of compensations) add(next, from, to);
+    const seen = new Set(), todo = list.filter(n => n.$type === 'bpmn:StartEvent' && (n.$parent === process || n.$parent.triggeredByEvent));
+    while (todo.length) { const n = todo.pop(); if (seen.has(n)) continue; seen.add(n); for (const to of next.get(n) ?? []) todo.push(to); }
+    const unreachable = scripts.concat(services).filter(n => !seen.has(n));
+    check(!unreachable.length, `从开始事件走不到这些步骤：${unreachable.map(n => n.id).join('、')}`);
+    const unreachableTasks = list.filter(n => n.$type === 'bpmn:UserTask' && !seen.has(n));
+    check(!unreachableTasks.length, `从开始事件走不到这些任务：${unreachableTasks.map(n => n.id).join('、')}`);
+    const timed = n => hasEvent(n, 'Timer'), timers = startEvents.filter(timed);
+    check(timers.length <= 1, `定时开始只能有一个，现有 ${timers.map(n => n.id).join('、')}`);
+    if (timers.length) {
+      const [timer] = timers, timing = timer.eventDefinitions[0];
+      check(!timing.timeDuration && !timing.timeDate && timing.timeCycle?.body?.trim(), `${timer.id}：定时开始写 timeCycle（ISO 8601 重复间隔，如 R/PT6H），不写 timeDuration、timeDate`);
+      const cycle = timing.timeCycle.body.trim();
+      if (isExpression(cycle)) check(settingsPattern.test(cycle), `${timer.id}：timeCycle 的表达式只能读插件的设置，如 =vars.maintenance.schedule`);
+      else scheduleCycle(cycle, `${timer.id} 的 timeCycle`);
+    }
+    const starts = startEvents.flatMap(n => (n.eventDefinitions ?? []).filter(d => d.$type === 'bpmn:MessageEventDefinition').map(d => d.messageRef.name));
+    const roles = dialect.eventRoles;
+    check(!(starts.length || timers.length) || startEvents.every(n => n.eventDefinitions?.length), `由事件或定时启动的流程，开始事件都要带消息或计时器；要手动发起，订阅 ${roles.dispatch}`);
+    if (starts.includes(roles.lifecycleStart)) {
+      const asks = list.filter(n => n.$type === 'bpmn:UserTask');
+      check(!asks.length, `跟随会话的流程（订阅 ${roles.lifecycleStart}）不能有人工任务：${asks.map(n => n.id).join('、')}。它不属于任何会话，任务没有人可交`);
+      const hears = n => n.messageRef?.name === roles.lifecycleFacts || (n.eventDefinitions ?? []).some(d => d.messageRef?.name === roles.lifecycleFacts);
+      const listeningScopes = new Set(list.filter(n => n.$type === 'bpmn:StartEvent' && n.$parent.triggeredByEvent && hears(n)).map(n => n.$parent.$parent));
+      const heard = new Map([[process, false]]);
+      // Entries are in parent-before-child order, so each ancestor's answer is reused once.
+      for (const n of list) heard.set(n, heard.get(n.$parent) || listeningScopes.has(n.$parent) || (attached.get(n) ?? []).some(hears));
+      const waits = list.filter(n => structure.lifecycle.waitTypes.includes(n.$type) || n.$type === 'bpmn:ServiceTask' && structure.lifecycle.waitActions.includes(n.action) ||
+        !n.$instanceOf('bpmn:SubProcess') && (attached.get(n) ?? []).some(timed));
+      const deaf = waits.filter(n => !hears(n) && !heard.get(n));
+      check(!deaf.length, `聋状态：流程在 ${deaf.map(n => n.id).join('、')} 等待时收不到 ${roles.lifecycleFacts}，会话的事实变了没有人回应。` +
+        `跟随会话的流程（订阅 ${roles.lifecycleStart}）每个等待节点都要能收 ${roles.lifecycleFacts}：自己等它，或挂一个等它的消息边界事件（挂在外层子流程上也算）`);
+    }
+    check(process.agents === undefined || starts.includes(roles.lifecycleStart), `coda:agents 只写在生命周期流程上（开始事件订阅 ${roles.lifecycleStart}）`);
+    check(process.key === undefined || !starts.includes(roles.lifecycleStart), '生命周期流程按会话唯一，不能声明 coda:key');
+    check(process.dispatch !== false || starts.length || timers.length, 'coda:dispatch="false" 的流程须由事件或定时启动（开始事件带消息或计时器），否则无法发起');
+    const messageNames = new Set();
+    for (const m of roots.filter(e => e.$type === 'bpmn:Message')) {
+      if (m.name) {
+        check(!messageNames.has(m.name), `<message name="${m.name}"> 写了不止一个：一个事件只写一个 <message>，开始事件与等它的节点都引用它`);
+        messageNames.add(m.name);
+      }
+      check(!dialect.variables.includes(m.id), `<message id="${m.id}">：id 不能是 ${dialect.variables.join('、')}：表达式按这些名字读运行自带的变量，接到的消息按 id 读`);
+    }
+    const caught = new Map();
+    for (const n of list) if (n.$type !== 'bpmn:StartEvent' || n.$parent.triggeredByEvent) {
+      const names = (n.eventDefinitions ?? []).filter(d => d.$type === 'bpmn:MessageEventDefinition').map(d => d.messageRef.name);
+      if (n.messageRef?.name) names.push(n.messageRef.name);
+      for (const name of names) add(caught, name, n);
+    }
+    const userMessage = new RegExp(dialect.userMessage);
+    check(!starts.some(name => userMessage.test(name)), '用户发出的消息（user.…）不能启动流程，只能在运行中等它');
+    check(!starts.includes(roles.cancel), `${roles.cancel} 是要停下运行，不能启动流程；在运行中等它，接到后走自己的收尾`);
+    for (const [name, waiting] of caught) if (name.startsWith(structure.userMessages.prefix)) {
+      check(userMessage.test(name), `<message name="${name}">：用户发出的消息名为 user. 加小写字母、数字和「-」`);
+      const label = waiting.find(n => n.name?.trim())?.name.trim() ?? name;
+      check(label.length <= structure.userMessages.maxLabelLength, `等 ${name} 的节点名须不超过 40 个字（它是运行页上的按钮）`);
+    }
+  }
+}

package/workflow.mjs

@@ -3,8 +3,8 @@
 // ask of Coda itself, each with the parameters it takes (actions.json); and the names workflows share (dialect.json):
 // their kinds, the events Coda sends, the error code of a failed step, the run's variables an expression reads by name,
 // the types a run's inputs take. Coda reads a workflow with them, and coda-plugins' contract check does where a plugin is
-// written. readWorkflow refuses what the dialect does not have and a value of it its schema does not take; how the
-// process itself is put together is still Coda's to check as it reads the workflow.
+// written. readWorkflow checks values and structure: structure.json describes local constraints and structure.mjs
+// checks BPMN topology, leaving only compilation to Coda.
 // What JSON Schema cannot say of a value it says with these keywords, besides the manifests' (validate.mjs):
 // - `x-feel`: true, or { names } — the value is FEEL: an expression when it starts with `=`, else text whose every
 //   `{{ … }}` holds one, each reading by name what the workflow has (its nodes and messages, the run's variables, a loop's
@@ -23,6 +23,8 @@ import actions from './workflow/actions.json' with { type: 'json' };
 import dialect from './workflow/dialect.json' with { type: 'json' };
 import fields from './workflow/fields.json' with { type: 'json' };
 import { valueKeywords } from './workflow/keywords.mjs';
+import { structureChecker } from './workflow/structure.mjs';
+export { CODA_STRUCTURE } from './workflow/structure.mjs';
 
 export const CODA_MODDLE = moddle;
 export const CODA_NAMESPACE = moddle.uri;
@@ -35,7 +37,7 @@ export const WORKFLOW_KINDS = Object.keys(dialect.kinds);
 export const DEPLOYING_KINDS = dialect.deploying;
 // The events Coda sends (dialect.json says what each is).
 export const CODA_EVENTS = Object.keys(dialect.events);
-export const SESSION_OPENED = 'session.opened', SESSION_FACTS = 'session.facts', DISPATCH_EVENT = 'workflow.dispatch', CANCEL_EVENT = 'workflow.cancel';
+export const { lifecycleStart: SESSION_OPENED, lifecycleFacts: SESSION_FACTS, dispatch: DISPATCH_EVENT, cancel: CANCEL_EVENT } = dialect.eventRoles;
 // A message the user sends from a run's page (`user.<what>`), while the run waits on it.
 export const USER_MESSAGE = new RegExp(dialect.userMessage);
 export const STEP_FAILED = dialect.stepFailed;
@@ -94,6 +96,7 @@ ajv.addKeyword({ keyword: 'x-duration', type: 'string', schemaType: 'boolean', c
 ajv.addKeyword({ keyword: 'x-number', type: 'string', schemaType: 'boolean', compile: spec => value => !spec || Number.isFinite(Number(value)) });
 ajv.addSchema(fields);
 ajv.addSchema(values);
+const structureProblem = structureChecker(ajv, { feelProblem, isExpression });
 const checks = new Map();
 // The validator of a definition of values.json, by its name; none for a type it says nothing of.
 const check = name => {
@@ -225,9 +228,11 @@ function valuesProblem(root) {
 // A workflow's definition (`file`, its name without `.bpmn`, for what is said) read with Coda's dialect: `{ root }`, the
 // parsed definitions, or `{ problem }`, what of it the dialect does not have — not BPMN, a coda: attribute or element it
 // does not know, an action it does not have or a parameter that action does not take — or a value of it its schema does
-// not take.
+// not take, or a structure the workflow cannot run with.
 export async function readWorkflow(source, file = 'workflow') {
   if (typeof source !== 'string' || source.length > SIZE_LIMIT) return { problem: `${file}.bpmn 过大` };
+  const old = OLD.exec(source);
+  if (old) return { problem: `${file}.bpmn 第 ${source.slice(0, old.index).split('\n').length} 行：${feelProblem(old[0])}` };
   let parsed;
   try { parsed = await new BpmnModdle({ coda: structuredClone(PARSER_DESCRIPTOR) }).fromXML(source); }
   catch (e) { return { problem: `${file}.bpmn 不是有效的 BPMN 2.0：${e.message}` }; }
@@ -244,7 +249,7 @@ export async function readWorkflow(source, file = 'workflow') {
     const given = (task.extensionElements?.values ?? []).filter(v => v.$type === 'coda:Param');
     if (given.some(p => !params.includes(p.name))) return { problem: `${task.id}：coda:action ${task.action} 只接受参数 ${params.join('、')}` };
   }
-  const problem = valuesProblem(root);
+  const problem = valuesProblem(root) ?? structureProblem(root, file);
   return problem ? { problem } : { root };
 }
 // What of a workflow's definition the dialect does not have, or null.