`FlowVariableSchema` has no `defaultValue`, so a flow variable cannot be declared bound — the obvious remedy for an unbound-variable condition does not exist

[os-zhuang]

Found while implementing #643, which prescribed a remedy that turned out not to be expressible.

The gap

#643 asked that an unbound flow variable be fixed by "declaring the variable with a default so it is always bound", rather than by a has() guard. Measured against @objectstack/spec@17.0.0-rc.1, neither half of that is available:

1. The schema has no such key. FlowVariableSchema is z.core.$strict over exactly four fields:

declare const FlowVariableSchema: z.ZodObject< {
    name: z.ZodString;
    type: z.ZodString;
    isInput: z.ZodDefault< z.ZodBoolean >;
    isOutput: z.ZodDefault< z.ZodBoolean >;
}, z.core.$strict >;

Being strict, adding defaultValue to a flow variable is a parse error, not an ignored key.

2. The engine has no default-application step. AutomationEngine.execute binds a declared variable only when the caller supplied it:

if (flow.variables) {
  for (const v of flow.variables) {
    if (v.isInput && context?.params?.[v.name] !== void 0) {
      variables.set(v.name, context.params[v.name]);
    }
  }
}

So declaring a variable in flow.variables binds nothing at runtime. A declared input is unbound on every run whose caller did not pass it, and a strict-CEL condition reading it then aborts with No such key: <name> (Unknown variable: <name> for the bare spelling), the run is recorded failed, and the automation does not happen. That is the exact live defect #643 fixed in lead_conversion.

What #643 did instead, and why it is a workaround

lead_conversion now seeds the variable with an assignment node placed ahead of the screen that collects it:

{
  id: 'init_defaults', type: 'assignment', label: 'Default Conversion Options',
  config: { assignments: { createOpportunity: false } },
}

That achieves the right semantics — bound on every path, guaranteed by the graph rather than by the client — using the mechanism the platform actually has. But it is a workaround in three ways:

• The default now lives twice: once on the screen field's defaultValue, once on the assignment node. Nothing keeps them in step.
• It costs a node and an edge per defaulted variable, in a graph where nodes are the unit of review.
• It would clobber a genuinely-supplied context.params value, because an assignment node is unconditional. Harmless here — the console's flow-action trigger sends only { recordId, objectName }, so createOpportunity cannot arrive as a param — but it is not the general shape.

test/flow-variable-conditions.test.ts pins the structural property (every variable a condition reads is bound on every path to it) so the gap cannot silently reappear, and its house-rule block records "declaring ≠ binding" as the trap it is.

What to establish

1. Is defaultValue on a flow variable an intended-but-missing spec feature, or is the graph-binds-it model deliberate? If deliberate, the authoring story needs to say so — right now flow.variables reads exactly like a declaration that binds, which is what made this a defect rather than a known limitation.
2. If it should exist: it belongs upstream in packages/spec (FlowVariableSchema) and in service-automation's execute/executeWithoutRetry seeding, applied before the start condition is evaluated so a start condition can read a defaulted variable too. Both halves are needed — a schema key with no engine support would be the inert-metadata failure of A decision node's singular config.condition is never evaluated — 24 flows author inert metadata #650.
3. Decide whether a screen field's defaultValue should seed the flow variable of the same name at suspend time, which would remove the duplication above without any new spec key.

This is a platform-side gap; HotCRM can only work around it. Filing here so the workaround in lead_conversion has something to point at and can be removed when the platform closes it.

Filed unassigned.

[os-zhuang]

已就同一处缺口向平台提了 objectstack-ai/objectstack#4697 —— 本件是 HotCRM 侧的追踪点（lead_conversion 里那个 assignment 变通有地方可指，平台补上之后可以照着删），#4697 是要求平台改的那一半。两边互链。

#4697 里还多带了一张实测的中止表，正好补上本件"守卫救不了未绑定变量"那句话的证据：

表达式	X 未绑定	X = null	X = 稀疏行
has(X.f)	ABORT Unknown variable: X	false	false
has(vars.X)	false	true	true

也就是说：唯一能在"变量可能压根没绑定"这种局面下有结论的写法是 has(vars.X)，而最顺手、最像自保的裸写法 has(X.f) 照样把 run 打成 failed。这一条值得单独记住——它意味着"加个 has() 就安全了"这个直觉在变量作用域上是错的，也是本件第 1 条那个问题（flow.variables 读起来像"声明即绑定"）的第二重代价：作者以为自己有两条退路，其实一条都不成立。

本件按 upstream:objectstack 归类，prio:p2 —— 结构性断言已经由 test/flow-variable-conditions.test.ts 钉住（每个条件读到的变量必须在到达它的每条路径上被绑定），所以这个缺口今天不会悄悄回来，等平台。

另：原先打的是裸 upstream 标签（灰色、无描述，不在 .github/labels.yml 里），已换成治理版 upstream:objectstack。

---

Generated by Claude Code