`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

[yinlianghui]

[17.0-rc2验收复核] 结论:仍复现(rc.2 上 schema 与引擎两半的缺口原样存在)

证据:

• schema 半:@objectstack/spec@17.0.0-rc.2 的 FlowVariableSchema 仍是 name/type/isInput/isOutput 四字段 $strict(dist/flow.zod-koL_4VyN.d.ts:41)。empirical parse:

FlowVariableSchema.safeParse({name:'x', type:'boolean'})                      → success: true
FlowVariableSchema.safeParse({name:'x', type:'boolean', defaultValue:false})  → success: false
  {"code":"unrecognized_keys","keys":["defaultValue"],"message":"Unrecognized key(s) on this flow variable: `defaultValue`. …"}

• 引擎半:@objectstack/service-automation@17.0.0-rc.2 dist 中变量绑定仍只在 caller 提供时 set(if (v.isInput && context?.params?.[v.name] !== void 0),index.js:1266/3095)——无任何默认值应用步骤,「declaring ≠ binding」不变。
• workaround 仍在承重:实测触发 lead_conversion(trigger → resume),run summary 中 init_defaults assignment 节点每次执行 —— 即 Flow conditions over vars.* / get_record outputs have the same abort exposure #633 fixed for record.* — unmeasured #643 的图内播种仍是唯一让条件可总的手段。

环境:hotcrm@0899b4f + @objectstack 17.0.0-rc.2

建议:仍有效 —— 等上游 objectstack#4697;HotCRM 侧无可修项,lead_conversion 的 assignment workaround 与 test/flow-variable-conditions.test.ts 守卫保持现状,平台落地后按本单正文回收。

---

Generated by Claude Code

[yinlianghui]

Blocked-by: objectstack-ai/objectstack#4697

分诊(PM 循环,消费上方 [17.0-rc2验收复核] 结论,会话 session_01VHrPAGEgFDoHjphqYG4BMa):复核判定「仍复现、hotcrm 侧无可修项」采纳 —— schema 与引擎两半的实测证据充分($strict 拒绝 defaultValue、绑定仅在 caller 提供时发生),workaround(init_defaults assignment)与守卫(flow-variable-conditions.test.ts)保持现状。打 pm:blocked,镜像 objectstack#4697(open,平台队列中);平台落地后按正文回收 workaround。

---

Generated by Claude Code

[huangyiirene]

Re-measured on @objectstack/* 17.0.0-rc.6 during the rc.5 → rc.6 upgrade (#1059, PR #1066). Both halves this card asked for now exist.

1. The schema key. FlowVariableSchema is no longer four strict fields:

declare const FlowVariableSchema: z.ZodObject<{
    name: z.ZodString;
    type: z.ZodString;
    isInput: z.ZodDefault<z.ZodBoolean>;
    isOutput: z.ZodDefault<z.ZodBoolean>;
    defaultValue: z.ZodOptional<z.ZodUnknown>;   // ← new
}, z.core.$strict>;

2. The engine applies it. @objectstack/service-automation's variable seeding now falls through to the declaration:

} else if (v.defaultValue !== void 0) {
  variables.set(v.name, v.defaultValue);
}

The shipped commentary also answers question 1 in this card's "what to establish" — the graph-binds-it model was not deliberate — and resolves the two follow-ons: defaultValue is honoured for non-input variables too, and a caller-supplied param still wins over the default, so it does not have the assignment node's clobbering behavior.

That means the #643 workaround in lead_conversion — the init_defaults assignment node seeding createOpportunity: false — is now removable, along with the duplication it created between the screen field's defaultValue and the node.

Not done here: this PR is the dependency bump only, and rewiring lead_conversion is a metadata change with its own review surface (and test/flow-variable-conditions.test.ts pins the structural property that would need to keep holding). Worth its own card.

Scope note: static read of the shipped schema and engine — no flow was run to confirm a defaulted variable reaches a start condition bound.

---

Generated by Claude Code