@coda-console/protocol 1.6.1 → 1.8.0

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/values.json

@@ -171,10 +171,77 @@
     "UserTask.children": {
       "type": "object",
       "properties": {
-        "choice": {"type": "array", "maxItems": 6, "x-unique-by": [{"key": "id", "nested": "choices"}],
-          "contains": {"type": "object", "properties": {"primary": {"const": true}}, "required": ["primary"]}, "minContains": 0, "maxContains": 1,
-          "description": "最多 6 个 coda:choice，最多一个主按钮；所有答复的 id（包括按住出现的）不重复"}
-      }
+        "choice": {
+          "type": "array",
+          "maxItems": 6,
+          "x-unique-by": [{"key": "id", "nested": "choices"}],
+          "contains": {"type": "object", "properties": {"primary": {"const": true}}, "required": ["primary"]},
+          "minContains": 0,
+          "maxContains": 1,
+          "description": "最多 6 个 coda:choice，最多一个主按钮；所有答复的 id（包括按住出现的）不重复"
+        },
+        "field": {"type": "array", "x-unique-by": ["id"], "description": "coda:fields 须为字段的 JSON 数组", "allOf": [{"maxItems": 12, "description": "最多 12 个字段"}]}
+      },
+      "allOf": [
+        {
+          "if": {"not": {"properties": {"fields": {"minItems": 1}}, "required": ["fields"]}},
+          "then": {
+            "properties": {
+              "choice": {
+                "items": {
+                  "allOf": [
+                    {
+                      "properties": {
+                        "fields": {
+                          "type": "string",
+                          "x-ref": {
+                            "pointer": "/field",
+                            "key": "id",
+                            "split": "[\\s,]+",
+                            "match": {"type": "object", "required": ["type"], "properties": {"type": {"enum": ["text", "secret"]}}}
+                          },
+                          "description": "fields 里的 {value} 不是这个任务的输入字段"
+                        }
+                      }
+                    },
+                    {
+                      "properties": {
+                        "choices": {
+                          "items": {
+                            "properties": {
+                              "fields": {
+                                "type": "string",
+                                "x-ref": {
+                                  "pointer": "/field",
+                                  "key": "id",
+                                  "split": "[\\s,]+",
+                                  "match": {"type": "object", "required": ["type"], "properties": {"type": {"enum": ["text", "secret"]}}}
+                                },
+                                "description": "fields 里的 {value} 不是这个任务的输入字段"
+                              }
+                            }
+                          }
+                        }
+                      }
+                    }
+                  ]
+                }
+              }
+            }
+          }
+        }
+      ]
+    },
+    "Field": {"$ref": "https://coda.pub/schema/bpmn/1.0/fields.json"},
+    "Fields": {
+      "type": "object",
+      "properties": {
+        "value": {"type": "string", "pattern": "^\\s*=", "x-feel": true, "description": "coda:fields 须用 value 写一个「=」开头的表达式（字段的列表）"},
+        "host": {"type": "string", "x-feel": true, "description": "host 是展开后 secret 字段未另写 host 时的备用值"},
+        "dir": {"type": "string", "x-feel": true, "description": "dir 是展开后非 keep=\"use\" 的 secret 字段未另写 dir 时的备用值"}
+      },
+      "required": ["value"],
+      "description": "coda:fields 须用 value 写一个「=」开头的表达式（字段的列表）"
     }
   }
 }

package/workflow.mjs

@@ -3,14 +3,16 @@
 // 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.
-// What JSON Schema cannot say of a value it says with three keywords of its own, besides the manifests' (validate.mjs):
+// 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
 //   element), or only `names`;
 // - `x-duration`: true — the value is an ISO 8601 duration, not negative;
 // - `x-number`: true — the text, read as a number, is a finite one (`1e999` reads as none).
+// workflow/keywords.mjs adds x-deferred (check FEEL now, the result later), x-length (UTF-16 text length, optionally
+// limited by a sibling), x-json (a JSON value or its text, with a byte budget), and absolute-path / https-url formats.
 import { parseDuration } from '@0dep/piso';
 import { BpmnModdle } from 'bpmn-moddle';
 import { parseExpression } from 'feelin';
@@ -19,10 +21,15 @@ import moddle from './workflow/moddle.json' with { type: 'json' };
 import values from './workflow/values.json' with { type: 'json' };
 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;
 export const CODA_VALUES = values;
+export const CODA_FIELDS = fields;
 // Each action by name, with the parameters it takes (`coda:param`).
 export const CODA_ACTIONS = Object.fromEntries(Object.entries(actions.actions).map(([name, action]) => [name, action.params]));
 export const WORKFLOW_KINDS = Object.keys(dialect.kinds);
@@ -30,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;
@@ -72,6 +79,7 @@ export function isDuration(text) {
 }
 
 const ajv = newAjv();
+valueKeywords(ajv, { feelProblem, isExpression });
 ajv.addKeyword({
   keyword: 'x-feel', type: 'string', schemaType: ['boolean', 'object'], errors: true,
   metaSchema: { anyOf: [{ type: 'boolean' }, { type: 'object', properties: { names: { type: 'array', items: { type: 'string' } } }, required: ['names'], additionalProperties: false }] },
@@ -86,11 +94,13 @@ ajv.addKeyword({
 });
 ajv.addKeyword({ keyword: 'x-duration', type: 'string', schemaType: 'boolean', compile: spec => value => !spec || isDuration(value) });
 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 => {
-  if (!checks.has(name)) checks.set(name, values.$defs[name] ? ajv.getSchema(`${values.$id}#/$defs/${name}`) : null);
+  if (!checks.has(name)) checks.set(name, Object.hasOwn(values.$defs, name) ? ajv.getSchema(`${values.$id}#/$defs/${name}`) : null);
   return checks.get(name);
 };
 
@@ -98,6 +108,12 @@ const SIZE_LIMIT = 1_000_000;
 // bpmn-moddle rewrites a descriptor as it takes it in (its names get their prefix), and whoever imports CODA_MODDLE may hand
 // it to one: what is read here is a copy taken as this loads, and each parse is given a copy of its own.
 const DESCRIPTOR = structuredClone(moddle);
+// moddle's Boolean/Integer coercion accepts `no` as false and `1.5` as 1. Keep field attributes as text until their
+// complete spelling is known; valid ones are restored to the descriptor's types before returning the parsed workflow.
+const FIELD_SCALARS = DESCRIPTOR.types.find(type => type.name === 'Field').properties.filter(p => ['Boolean', 'Integer'].includes(p.type));
+const PARSER_DESCRIPTOR = structuredClone(DESCRIPTOR);
+for (const property of PARSER_DESCRIPTOR.types.find(type => type.name === 'Field').properties)
+  if (FIELD_SCALARS.some(p => p.name === property.name)) property.type = 'String';
 const children = element => Object.values(element).flatMap(v => (Array.isArray(v) ? v : [v])).filter(v => v?.$type && v.$parent === element);
 // Everything in the definition under `element`, depth first, by a stack of its own, pushed one at a time: a definition may
 // nest deeper than the call stack goes, and hold more in one place than a call takes arguments.
@@ -130,7 +146,40 @@ function said(error, at, attribute) {
     return `${at} 需要 ${attribute ? 'coda:' : ''}${error.params.missingProperty}${own ? `：${own}` : ''}`;
   }
   if (error.keyword === 'x-unique-by') return `${at}：${error.message}`;
-  return `${at}：${described(error, { schemas: [values] }) ?? error.message}`;
+  return `${at}：${description(error)}`;
+}
+const description = (error, object = {}) => (described(error, { schemas: [values, fields] }) ?? error.message)
+  .replace(/\{(\w+)\}/g, (whole, key) => Object.hasOwn(error.params, key) ? String(error.params[key])
+    : object && Object.hasOwn(object, key) ? String(object[key]) : whole);
+// Required values and allowed attributes come from the same schema as validation; none of the field types is named here.
+function fieldSaid(error, at, field) {
+  if (error.keyword === 'additionalProperties') {
+    const allowed = Object.keys(error.parentSchema.properties), type = error.parentSchema.properties.type.const;
+    const extra = Object.keys(error.data).filter(key => !Object.hasOwn(error.parentSchema.properties, key));
+    return `${at}：${type} 字段没有 ${extra.join('、')}，可写 ${allowed.join('、')}`;
+  }
+  return `${at}：${error.keyword === 'x-feel' ? error.message : description(error, field)}`;
+}
+// A resolved field, at task opening or when accepting an answer. No expression is evaluated and no default is inserted.
+export function fieldProblem(field, where = '字段') {
+  const validate = ajv.getSchema(fields.$id);
+  return validate(field) ? null : fieldSaid(validate.errors[0], where, field);
+}
+// The expanded fields of one task (after reading coda:fields JSON and applying host/dir), checked together as in a
+// definition. Choice references still need the task's choices; Coda checks those after expansion.
+let fieldsBound;
+export function fieldsProblem(list, where = '任务') {
+  const schema = values.$defs['UserTask.children'].properties.field;
+  // Check the bound before visiting items, and individual values before uniqueness can inspect their ids.
+  const { 'x-unique-by': unique, ...shape } = schema;
+  const bound = fieldsBound ??= ajv.compile(shape);
+  if (!bound(list)) return `${where}：${description(bound.errors[0])}`;
+  for (const [index, field] of list.entries()) {
+    const problem = fieldProblem(field, `${where} 的字段 ${typeof field?.id === 'string' ? field.id : index + 1}`);
+    if (problem) return problem;
+  }
+  const validate = ajv.getSchema(`${values.$id}#/$defs/UserTask.children/properties/field`);
+  return validate(list) ? null : `${where}：字段 id 重复：${validate.errors[0].message.slice('id 不能重复：'.length)}`;
 }
 // What of the coda: values in the definition its schemas do not take, or null: each element in order, its coda:
 // attributes by each type of Coda's extending what it is, the coda: elements it holds by kind, and each coda: element.
@@ -141,12 +190,13 @@ function valuesProblem(root) {
   const loops = elements.filter(e => e.$type === 'bpmn:MultiInstanceLoopCharacteristics');
   const names = Object.fromEntries([...RUN_VARIABLES, ...elements.filter(e => e.$type === 'bpmn:Message' || e.$instanceOf?.('bpmn:FlowElement')).map(e => e.id),
     ...loops.map(loop => loop.inputElement).filter(Boolean), ...(loops.length ? ['loopCounter'] : [])].filter(Boolean).map(name => [name, null]));
-  const failed = (validate, object, at, attribute) => validate && !validate.call({ names }, object) ? said(validate.errors[0], at, attribute) : null;
+  const failed = (validate, object, at, attribute, field = false) => validate && !validate.call({ names, definition: true }, object)
+    ? field ? fieldSaid(validate.errors[0], at, object) : said(validate.errors[0], at, attribute) : null;
   for (const element of elements) {
     const type = codaType(element);
     if (type) {
       const name = element.id ?? element.name, kind = type.name === 'Choice' && element.$parent?.$type === 'coda:Choice' ? 'NestedChoice' : type.name;
-      const problem = failed(check(kind), codaObject(element), `${owner(element)?.id} 的 coda:${lower(type.name)}${name ? ` ${name}` : ''}`, false);
+      const problem = failed(check(kind), codaObject(element), `${owner(element)?.id} 的 coda:${lower(type.name)}${name ? ` ${name}` : ''}`, false, ['Field', 'Fields'].includes(kind));
       if (problem) return problem;
       continue;
     }
@@ -160,7 +210,16 @@ function valuesProblem(root) {
     if (!held.length) continue;
     const grouped = {};
     for (const child of held) (grouped[lower(codaType(child).name)] ??= []).push(codaObject(child));
-    const problem = failed(check(`${element.$type.slice(5)}.children`), grouped, at, false);
+    const validate = check(`${element.$type.slice(5)}.children`);
+    let problem = failed(validate, grouped, at, false);
+    if (problem && validate.errors[0].keyword === 'x-ref') {
+      const error = validate.errors[0], path = error.instancePath.split('/').slice(1);
+      let parent = grouped;
+      for (const key of path.slice(0, -1)) parent = parent[key];
+      problem = `${at} 的 coda:choice ${parent.id}：${description(error)}`;
+    }
+    if (problem && validate.errors[0].keyword === 'x-unique-by' && validate.errors[0].instancePath === '/field')
+      problem = `${at}：字段 id 重复：${validate.errors[0].message.slice('id 不能重复：'.length)}`;
     if (problem) return problem;
   }
   return null;
@@ -169,21 +228,28 @@ 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(DESCRIPTOR) }).fromXML(source); }
+  try { parsed = await new BpmnModdle({ coda: structuredClone(PARSER_DESCRIPTOR) }).fromXML(source); }
   catch (e) { return { problem: `${file}.bpmn 不是有效的 BPMN 2.0：${e.message}` }; }
   const { rootElement: root, warnings } = parsed;
   if (warnings.length) return { problem: `${file}.bpmn 有无法识别的内容：${warnings.slice(0, 3).map(w => w.message).join('；')}` };
+  for (const field of all(root).filter(e => e.$type === 'coda:Field')) for (const { name, type } of FIELD_SCALARS) {
+    const value = field[name];
+    if (type === 'Boolean' && ['true', 'false'].includes(value)) field[name] = value === 'true';
+    if (type === 'Integer' && typeof value === 'string' && /^[+-]?\d+$/.test(value)) field[name] = Number(value);
+  }
   for (const task of all(root).filter(e => e.$type === 'bpmn:ServiceTask' && e.action !== undefined)) {
     if (!Object.hasOwn(CODA_ACTIONS, task.action)) return { problem: `${task.id}：coda:action 只能是 ${Object.keys(CODA_ACTIONS).join('、')}` };
     const params = CODA_ACTIONS[task.action];
     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.