fix(spec)!: refuse a flow node config its executor cannot run — a required key left out, or a decision branch list it cannot read — at all three doors (#20316)

[objectstack-fleet]

Fixes #20316

Clause-②: no (narrowing)

A flow node config its executor cannot run is now refused where the flow is built, at all three build doors (FlowSchema.parse, AutomationEngine.registerFlow, objectstack validate), by ONE judge: flowNodeConfigRefusals in @objectstack/spec/automation. It covers the whole family; #20317 is folded into this card:

• a key a builtin's executor contract requires, left out — the census below, loop.collection ([finding] a loop node with no config.collection registers and validates clean, then fails at run time with 'loop config does not satisfy the loop contract' #20317) and map.collection among them;
• a decision branch list its executor cannot read — a branch with no label (the card's shape), a branch that is not an object, and conditions that is not an array.

What was wrong, measured on origin/main a88a1bb399 before the change

Probe scripts drive door 1 (FlowSchema.safeParse, spec dist), door 2 (AutomationEngine.registerFlow with installBuiltinNodes, then execute), and door 3 (the BUILT CLI, node packages/cli/bin/run.js validate --json in a stack directory holding one objectstack.config.ts). The run leg swaps the two marker nodes y / x for a recording executor, so the route taken is observable. The decision has out-edges d → y labelled yes and d → x with isDefault: true.

lit control	door 1	door 2	door 3	run
(a) decision branch { expression: 'true' }, no label	success=true	registered	valid: true, exit 0	success=true, visited ["x","y"]: EVERY out-edge
(a) control: { label: 'yes', expression: 'true' }	success=true	registered	valid: true, exit 0	success=true, visited ["y"]
(b) conditions: ['true']	success=true	registered	valid: true, exit 0	success=false, condition evaluation error: A structural condition …
(c) loop with iteratorVariable and a one-node body, no collection	success=true	registered	valid: true, exit 0	success=false, loop 'l': config does not satisfy the loop contract — config.collection: Invalid input
(c) control: the same loop with collection: [1, 2]	success=true	registered	valid: true, exit 0	success=true, the body ran twice
(d) map with flowName, no collection	success=true	registered	valid: true, exit 0	success=false, map 'm': config does not satisfy the map contract — config.collection: Invalid input

Further shapes measured on the run leg only: conditions: {} and conditions: 5 fail with conditions is not iterable; conditions: 'x' fails with a condition evaluation error, because a string is iterated character by character; a null branch fails with Cannot read properties of null; label: null, '', 0, ' ' and 42 all run green down both out-edges. The last two also log the engine's unclaimed-label warn. conditions: null routes like no conditions at all, which is legal and stays admitted.

After, measured on the merged branch (spec dist built from this head; the CLI reads it at run time)

lit control	door 1	door 2	door 3
(a) no label	custom at nodes.1.config.conditions.0.label	throws the same issue	valid: false, exit 1, custom at flows.0.nodes.1.config.conditions.0.label
(a) control	success=true	registered, run visits ["y"]	valid: true, exit 0
(b) conditions: ['true']	custom at nodes.1.config.conditions.0	throws the same issue	valid: false, exit 1, same path
(c) loop, no collection	custom at nodes.1.config.collection	throws the same issue	valid: false, exit 1, same path
(c) control	success=true	registered, body ran twice	valid: true, exit 0
(d) map, no collection	custom at nodes.1.config.collection	throws the same issue	valid: false, exit 1, same path

The fix: one judge, three doors

• packages/spec/src/automation/flow-node-config-refusals.ts (new). It lives beside the walk file, not inside it, because it reads the executor contracts, and two of their modules import flow-node-expression-paths.ts. A static import there closed a cycle that read LEDGER_DECLARED_NODE_CONFIG_SCHEMAS mid-evaluation (measured: z.toJSONSchema(undefined) in 4 spec tests).
  • getBuiltinNodeConfigContracts() maps a node type to the very schema its executor hands parseNodeConfig, plus loop's parse condition (a legacy flat-graph loop with no body is not parsed, so it stays exempt). It is built on first use, never at module load.
  • flowNodeConfigRefusals(nodeType, config) has two arms:
    • Contract arm. It parses config ?? {} against the contract, on the executor's own condition, and keeps an issue ONLY where the key it names is absent from what was authored. A present value of the wrong type, or an undeclared key, stays where it is judged today. It also skips issues inside an ADR-0031 region (walked as its own graph) and inside a ledger value slot (fields.*, assignments.*), where a malformed envelope is the value-envelope pass's finding. A plain requirement gets node-config-key-missing with a prescription naming the key and the node type. A requirement a rule of the contract states gets node-config-key-required-by-rule, carrying the contract's own message: a notify with no template needs a title, and a lookup screen field needs its reference.
    • Decision arm. decision is parsed by nothing at run time, so this arm states what its executor reads: conditions present and not null is an array (decision-conditions-not-array); every branch is an object (decision-branch-not-object); every branch's label is a non-blank string (decision-branch-label-missing, with found: absent, null, blank, or the kind).
• packages/spec/src/automation/flow-node-expression-paths.ts: the five new codes join FLOW_SLOT_REFUSAL_CODES and FlowSlotRefusalParams in feat(formula,spec): stable refusal codes and params beside every expression refusal message #20352's shape (a stable kebab-case code and typed params beside the message). FlowNodeConfigRefusal adds the path inside config. One walk fix: an ARRAY element is no longer read as an object missing its slot, so conditions: [['true']] gets one refusal (a branch that is not an object), not also a missing expression.
• packages/spec/src/automation/flow.zod.ts: a FlowSchema.superRefine block calls the judge for every node, walked with collectFlowGraphs, so a node in a region body is anchored where the author wrote it. It is a presence rule, not a key-set closure.
• registerFlow: no engine change. It parses first (canonicalizeStoredFlow → FlowSchema.parse), after the ADR-0087 conversions, so the parse's issue is what it throws.
• packages/lint/src/validate-expressions.ts: validateStackExpressions calls the same judge, for a stack handed to it with no parse in front. One exception: a script's absent function stays the existing callable check's finding. That check reads the pre-conversion spellings this pass may be handed (the functionName alias, the retired dispatch keys) and names each.

Route choices.

1. The judge parses the executor's contract and keeps absences. It is not a hand-written table of required keys. Business need: the census is 18 keys over 13 node types, and the contract already states every one of them, rule-required keys included. Long-term design: a table beside the contracts would be a second statement of them, free to drift; the ratchet below reads the executors' own parse calls instead. Guarding AI authors: both forms refuse loudly, but this one uses the contract's own words where the contract has them. No scope growth: keeping absence only leaves every other contract finding exactly where it was.
2. The label rule is "a non-blank string", wider than "the key is absent". Every one of those values sends the matched branch down every out-edge (measured above), and the repo already has one notion of blank (NON_BLANK_STRING). Refusing only the absent key would leave label: '', which misroutes identically.
3. A non-array conditions is refused as well as a non-object branch. It is the container of the same branch walk, and every non-null non-array value fails the run (measured above).

Acceptance notes

Family census: every key a contract-parsing builtin's executor requires

Enumerated from the code: every parseNodeConfig(…) call under service-automation/src/builtin/, cross-checked against the expression-path ledger's required-key reconciliation. The channels require loop.collection and map.collection, which that ratchet had recorded as "no door refuses their absence". It now asserts the judge refuses both. Door status was measured by the probes above on a88a1bb399 (before) and on this branch (after), each row beside its whole-config accept control, which is admitted at every door both before and after.

node kind	key left out	runtime reader	before: parse / register / validate	after: all three doors
get_record	objectName	crud-nodes.ts:264	admit / admit / admit	refused at config.objectName
create_record	objectName	crud-nodes.ts:335	admit / admit / admit	refused
update_record	objectName	crud-nodes.ts:484	admit / admit / admit	refused
delete_record	objectName	crud-nodes.ts:578	admit / admit / admit	refused
notify	recipients	notify-node.ts:250	admit / admit / admit	refused
notify	title (no template; rule)	notify-node.ts:250	admit / admit / admit	refused, in the contract's words
http	url	http-nodes.ts:112 (parsed after interpolation; interpolation never adds a key)	admit / admit / admit	refused
screen	fields[i].name	screen-nodes.ts:158	admit / admit / admit	refused at config.fields.i.name
screen	fields[i].options[j].value / .label	screen-nodes.ts:158	admit / admit / admit	refused
screen	fields[i].reference on a lookup field (rule)	screen-nodes.ts:158	NOT MEASURED before (same arm)	refused, in the contract's words (spec pin)
script	function	screen-nodes.ts:321	admit / admit / REFUSE (the lint callable check)	refused at all three
subflow	flowName	subflow-node.ts:71	admit / admit / admit	refused
map	collection	map-node.ts:96	admit / admit / admit	refused
map	flowName	map-node.ts:96	admit / admit / admit	refused
loop (with body)	collection	loop-node.ts:85 (the no-body form returns at :72 unparsed)	admit / admit / admit	refused
parallel	branches	parallel-node.ts:68	admit / admit / admit	refused
try_catch	try	try-catch-node.ts:100	admit / admit / admit	refused
decision	a branch label (absent, null, blank, non-text)	logic-nodes.ts:48-74 (branchLabel: cond.label)	admit / admit / admit	refused at config.conditions.i.label
decision	a non-object branch; a non-array conditions	logic-nodes.ts:48-51	admit / admit / admit	refused

Controls that stay admitted: a legacy loop with no body and no collection (it still runs); a decision with no conditions, conditions: null or []; assignment, wait and plugin node types; a present value of the wrong type (objectName: 42); an undeclared key.

Outside this census's definition (no parseNodeConfig), measured, not fixed here: connector_action with no connectorConfig is admitted at all three doors and refused at run (connectorConfig.connectorId and .actionId are required). It belongs to the same family, but its input is a FlowNode sibling block, like wait's waitEventConfig, which FlowSchema already requires. Reported to the seat.

Producer census

• examples/** at this head: app-crm 1 flow, 8 nodes; app-showcase 30 flows, 139 nodes; app-todo 4 flows, 26 nodes. 0 refusals. app-multi-package declares no flows.
• packages/**, non-test: no default flow carries a judged node. The Studio create seed for flow has nodes: [].
• objectui at the .objectui-sha pin f8a9d0fb (not edited):
  • FlowObjectListField rowsToList drops a blank cell. So a decision branch row with an empty Label cell is written as { expression }, which is now refused (decision-branch-label-missing). The same writer serves the screen Fields repeater, so a field row with an empty Name cell is written without name, also refused.
  • previews/flow-canvas-parts.tsx defaultNodeExtras seeds a new node with no config, or a partial one: http gets { method: 'GET' } (no url), notify gets { channels, recipients: [] } (no title), and CRUD / script / subflow / map / parallel / try_catch get nothing. So a node added and saved before it is configured is now a loud save error. The designer's live Zod pass (clientValidation.ts → FlowSchema) will locate it at the node's config path once objectui takes this spec.
• cloud: NOT MEASURED (no checkout in this container; the dispatch named examples, packages and objectui).

Fixture triage (disposition per fixture, never a batch rename)

• Completed (the fixture was never runnable; it now carries the key its executor requires): skeleton flows in spec flow.test.ts, region-normalization.test.ts, flow-region-pause-and-end.test.ts, api/zod-issues-to-fields.test.ts; service-automation engine.test.ts and 7 sibling files where script / notify / map nodes stand in for mock executors; runtime automation-put-post-error-parity, automation-register-error-class and automation-flow-clone; types validation-failure.test.ts; verify automation-trigger-terminal-messages.test.ts. The two collectFlowGraphs scope and path pins now chain through try as well as catch, because a try_catch without try is refused.
• Re-judged in place (the pin was about the executor's refusal of a missing key, which the build door now answers first): config-parse.test.ts (7), guard-refusal-inventory.test.ts (7 rows), http-nodes, notify-node (2), subflow-node. Each now asserts the door refusal, then registers the node WHOLE and strips the key from the stored flow, so the executor's guard is still pinned. screen-nodes.test.ts: a stored script carrying only retired dispatch keys no longer registers (leaves out function), rather than registering and refusing at run. conversions.test.ts: the flow parse is still blind to the tombstones, and now refuses the stripped node for its absent function.
• The lint's script callable tests are unchanged. That check keeps a script's function, as described above.

Observed, not filed

• A pre-conversion alias spelling (object, flow, functionName, to / subject) is refused as the canonical key's absence at a DIRECT FlowSchema.parse / defineFlow(). registerFlow, objectstack validate and defineStack convert first, so no measured producer meets it. Carrier: whoever retires those D2 aliases at 18 (the object alias's own docblock says it retires then); otherwise none.
• A present value of the wrong type (objectName: 42, collection: '', function: '' outside the lint) is still admitted at the build doors and refused at run. That is the same family's type half, which this card's direction scoped out. Reported to the seat.

ADR-0087

• One semantic D3 entry for the family, flow-node-config-required-keys-refused (major 18). It uses form D: the decision is stated in words, with no tracker numbers in author-shown text. registry.ts is regenerated.
• No D2 conversion. No lossless repair exists: the platform cannot know the object, URL, collection, function or out-edge label that was left out, and no value it could write would keep what the flow did.
• Changeset .changeset/20316-flow-node-config-required-keys-refused.md: @objectstack/spec and @objectstack/lint minor, BREAKING, with the FROM → TO table. service-automation gets none, because its diff is test files only.

Pins: each refusal at each door, with the lit control

• spec flow-node-config-required.test.ts (FlowSchema.parse):
  • every census row, refused at its key with the judge's own message, beside its whole-config accept control;
  • the two rule-required keys, in the contract's own words;
  • region nesting;
  • the decision arm: six label values, four non-object branches, three non-array conditions;
  • controls: legacy loop, wrong type, undeclared key, value slot, assignment and plugin types, no-branch decisions.
• spec flow-slot-refusal-codes.test.ts: one pin per new code (code, params, full message), the closed set split over three producers, a sweep that reaches every node-config code, and type-level pins.
• service-automation node-config-required-keys.test.ts (registerFlow):
  • the same census, and the decision arm;
  • on the real executors: the refused shapes failed the run, and a matched branch with no label ran GREEN down both out-edges while its labelled twin took one.
• service-automation builtin/node-config-contract-ledger.test.ts: the ratchet. The map equals every executor's parseNodeConfig call, schema by identity; loop alone parses on a condition; every builtin type is classified.
• service-automation config-expression-ledger.test.ts: the cross-check described above.
• lint validate-expressions.test.ts (validateStackExpressions): the same judge through the third door's pass.

Ablation: the pins can fail

The ablation ran once, on the committed state 7f3b9b6742, in one os-verify-lock hold. It went through scripts/ablation-replace.mjs in wrap mode, with the restore trapped on EXIT, INT and TERM.

• Mutation. flowNodeConfigRefusals returns [] unless a global named ABLATION_20316_OFF is set. The anchor went from 1 hit to 0, and the blob from bd1d620a25b6 to 353f92191f9d. After pnpm --filter @objectstack/spec build, ablation-dist-preflight.mjs @objectstack/spec ABLATION_20316_OFF found the marker in 20 built files.
• Red, in the expected direction:
  • spec, the two pin files: 41 failed, 35 passed. Every refused row at FlowSchema.parse went red, as did the five new-code pins and the sweep. Every accept control and CONTROL block stayed green.
  • service-automation, three files: 21 failed, 47 passed. Every refused census and decision row at registerFlow went red, as did the ledger cross-check. The accept controls, the run-time "what it did" pins and the contract-ledger ratchet stayed green.
  • lint validate-expressions.test.ts: 7 failed, 345 passed. The new rows went red; the callable-check rows stayed green.
• Restore leg. The blob is back to bd1d620a25b6, equal to HEAD, and git diff HEAD is empty. After a rebuild, --absent found the marker in none of the 222 built files, and the working tree is clean. Then spec 76/76, service-automation 68/68, lint 352/352.

Verification

Branch head 8171d8537e: origin/main 15bf186f50 merged as 725ffa325e, plus test-only commits after it. Every heavy run went through os-verify-lock, on a closure built from the merge head (turbo run build --filter=@objectstack/cli..., 59/59). The box was shared.

• spec, full suite, both projects: 593 files, 17196 passed, 1 todo. Run on 725ffa325e; no spec source changed after it.
• service-automation, full: 149 files, 1818 passed. Run on 725ffa325e; no source changed after it.
• lint, full: 113 files, 4712 passed, on 7f3b9b6742. validate-expressions.test.ts again on 8171d8537e: 352/352.
• runtime src/domains: 77 files, 1436 passed, on 7f3b9b6742.
• Smaller suites. types: 23 files, 692 passed. verify: 15 files, 116 passed. metadata-protocol, its 10 flow files: 207 passed. plugin-approvals, its 5 flow files: 344 passed. cli --project unit, its flow-building files: 8 files, 112 passed.
• Typecheck exits 0 for spec (test layer included), service-automation, lint, runtime, types and verify.
• Gates. dispatch-gates.mjs --commands on 8171d8537e derives 102 families; 100 exit 0. --ran accounts for all 102: 100 run, 2 NOT MEASURED.
  • check:dual-build-cjs-loads: PREREQUISITE NOT MET. 9 packages outside this diff have no dist/.
  • check:type-check-debt: its --re-measure runs a whole-tree build outside the lock. This diff adds no package.
• eslint. eslint --no-inline-config --format json over this branch's 36 changed .ts files: 36 files, 0 errors, 0 warnings.
  • Population: eslint.config.mjs has files: ['**/*.{ts,tsx,mts,cts,js,jsx,mjs,cjs}'], and none of the 36 files is ignored.
  • Invariance: the config sets no parserOptions.project, so no linting is type-aware, and this diff cannot move a verdict on an untouched file.
• Declared narrowing. Consumer packages beyond these ran on their flow-bearing test files only. The rest of the consumer farm is CI's: cli integration tests, dogfood, and the whole suites of runtime, metadata-protocol and plugin-approvals.
• Behind main. The branch is 7 commits behind origin/main 7db1332f19. A merge-tree probe with no merge driver (a bare shared clone) merges clean. check:migration-registry on that probe merge reports registry.ts current.

Governed surface

skills/objectstack-automation/references/_index.md is regenerated by gen:skill-refs (byte-equal to the generator). flow.zod.ts now reaches schemaless-node-config.zod.ts transitively, so the index gains that one dependency row. Readings: that file 42 → 43 lines; the published catalog's SKILL.md total 4402 → 4402, unchanged.

维护者速读(草稿)

• 改了什么:流程节点的配置如果缺了执行器必需的字段(比如查询节点没写对象名、循环节点没写要遍历的集合、决策分支没写标签),现在保存或校验时就会直接报错,不再等到流程运行时才失败或走错分支。
• 为什么改:以前这类流程能正常保存、正常发布,运行到那个节点才失败;决策分支没写标签更糟,流程会"成功"但同时走了所有分支,业务上悄悄出错。
• 风险与代价(含回滚):已有流程里若有这类残缺节点,升级后会被拒绝注册(启动日志会点名),需要补上字段;Studio 设计器里新加的节点在配置完成前保存会报错。回滚即撤销本 PR。
• 席位意见:
• 你要做的:无需操作;如需确认,关注 objectui 设计器对"空标签行、未配置新节点"的保存报错体验(另立卡跟进)。

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

This PR changes 2 package(s): @objectstack/lint, @objectstack/spec, touching 28 documentable anchor(s). ⚠️ 3 changed file(s) yielded no anchor (packages/spec/api-surface/automation.json, packages/spec/export-origins/automation.json, packages/spec/src/automation/index.ts), so the pages documenting them are NOT COVERED by this run — this is not a clean bill of health for those files.

22 hand-written doc(s) name something this change touched — list omitted above 15 rows. Re-derive on the tree named below: node scripts/docs-audit/affected-docs.mjs --json 40b315b03345e334069dd454aecaf7016adbea4f.

⛔ 4 release-owned page(s) also affected — read-only, see AGENTS.md Documentation Guardrails.

What this run could not see

• 3 changed file(s) yielded no anchor (packages/spec/api-surface/automation.json, packages/spec/export-origins/automation.json, packages/spec/src/automation/index.ts) — pages documenting those are invisible to this run
• 7 name(s) were too generic to anchor anything (single lowercase words)
• the SDK route bridge reached 54 of 206 client-bound route-ledger rows — the other 152 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run. Of those 152: 0 are remediable by widening that discovery convention (an in-repo file declares the path; the convention did not scan it); 55 are structural — on a ledger where NOT ONE row is declared in-repo, so no discovery change reaches them at any price; 97 are undecided (no in-repo declaration, on a ledger that has other in-repo registrars — absence and an unreadable spelling are not distinguishable here). The rows themselves: node scripts/docs-audit/affected-docs.mjs --bridge-coverage
• a page that states a rule by its inputs shares no identifier with the emitter that implements the rule, so an emitter-only diff cannot list it — not on this run and not on any run. Measured on fix(driver-sql): emit varchar(maxLength) for a text field a declared index keys on #11430: content/docs/protocol/objectql/types.mdx documents the text-family column mapping by the ObjectQL type names it maps FROM (text / textarea / html) while the diff changed createColumn; it went unlisted, and it was the page that diff falsified, in four places. No shared token exists to detect this on, so a rule your change carries has to be re-read by hand in the pages that restate it.
• a key NAME is not a key, so the hand re-read the line above prescribes can land on the wrong schema. The same spelling is authorable on one governed type and a [REMOVED] tombstone on another for each of active, aria, joins, objects, template, tools and version (censused on [finding] tools is a key on BOTH AgentSchema (tombstoned, dead) and SkillSchema (live, cloud-attested), so a name-based search attributes skill examples to the agent key — it produced a false stop-the-line alarm on PR #19059 #19093 over the liveness ledger's governed types, top-level keys); nothing in a search result distinguishes the two, so a grep hit on a LIVE example reads as evidence about the DEAD key. Measured on fix(spec): the agent.tools liveness row says dead — it claimed live on a key the schema tombstoned #19059: content/docs/ai/agents.mdx was reported as contradicting the agent.tools tombstone over its tools: example at :161, which is inside the defineSkill({ block opened at :155 — the page was already correct. Settle ownership by PARSING the value against both schemas, never by the name: that literal PASSES SkillSchema, and as an AgentSchema it FAILS at tools with the tombstone prescription. ⛔ These names are not the whole class — a key retired through a .strict() guidance map leaves no tombstone in the walked shape and none of them here (tool.category, live as AIToolDefinition.category).

Coarse fallback — 136 page(s) merely mention a changed package (the pre-#9192 predicate, kept for the deliberately-wide backstop): node scripts/docs-audit/affected-docs.mjs --json 40b315b03345e334069dd454aecaf7016adbea4f → packageMentionDocs.

Which tree this was computed on

This run read content/docs from aef8edecd93d24cd27b01be89e4d3bece6199890 — the merge of head 8171d8537e9efe68310733e9fa4cc9a51f5a2f4a into base 40b315b03345e334069dd454aecaf7016adbea4f, which is what actions/checkout gives a pull_request run. Not the PR head.

A worktree cut from an older main holds a different content/docs, so re-deriving there can legitimately return a different list — that is a different tree, not a wrong row. To answer on the same tree:

# while this PR is open — GitHub drops the merge commit once it closes
git fetch origin aef8edecd93d24cd27b01be89e4d3bece6199890 && git checkout aef8edecd93d24cd27b01be89e4d3bece6199890
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin 40b315b03345e334069dd454aecaf7016adbea4f 8171d8537e9efe68310733e9fa4cc9a51f5a2f4a && git checkout -B drift-repro 40b315b03345e334069dd454aecaf7016adbea4f && git merge --no-ff 8171d8537e9efe68310733e9fa4cc9a51f5a2f4a

node scripts/docs-audit/affected-docs.mjs --json 40b315b03345e334069dd454aecaf7016adbea4f

⚠️ That checkout carried uncommitted changes, so the commit above does not fully identify what was read.

Advisory only, and a precision-first one (#9192): a page is listed because it names a
symbol, wire route or SDK method this diff touched — not because it mentions a changed
package. Each row says which anchor put it there, so a wrong row is reportable rather than
merely annoying. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs 40b315b03345e334069dd454aecaf7016adbea4f → pass the list as
args.docs, on the commit named under Which tree this was computed on.

[objectstack-fleet]

Contract review

Served-tier: 84/84 CONTRACT_REVIEW_TIER
Head-sha: 8171d8537e9efe68310733e9fa4cc9a51f5a2f4a

① Derived judgments

1. Judge true to executors. All 13 parseNodeConfig sites (crud ×4, notify, http, screen, script, subflow, map, loop, parallel, try_catch) parse unconditionally except loop, whose if (raw.body == null) return is mirrored exactly by parsedWhen: body != null (ratchet pins the source line and schema identity). Zod 4.6.1 probe: an absent z.unknown() key IS refused ("expected nonoptional"), so the options[j].value row holds. Live probe of the judge on an exported copy of the head: every census key refused at its path; wrong-type (objectName: 42, collection: '', function: ''), undeclared key, legacy loop, body: null, 1-branch parallel, template-only notify all stay admitted. No over-refusal, no missed key.
2. Decision arm. Engine: if (result.branchLabel) (truthiness) then e.label === branchLabel; unclaimed → warn and EVERY out-edge. So absent/null/''/0/false/42/object all misroute; a blank string could only be claimed by an edge labelled blank (FlowEdgeSchema.label is z.string().optional()), so "non-blank string" is a sound necessary rule. Examples' 3 decisions route by edges; docs/README branches all carry labels; label: 'default' passes. Note (non-blocking): DecisionConditionSchema.label stays bare z.string(), so declared is now looser than enforced on blank.
3. Three doors. Codes module stays a leaf (its only import is NON_BLANK_STRING); the judge reads the contract schemas only inside getBuiltinNodeConfigContracts(); FlowSchema.superRefine walks collectFlowGraphs (probe: loop-body and parallel-branch inner nodes anchored at nodes.1.config.body.nodes.0.config.url / …branches.0.nodes.0.config.flowName); lint applies the same call inside the per-graph node loop, with only the script/function exclusion. Not alias-aware at a direct parse (probe: object, functionName, flow, to/subject refused as the canonical key absent). registerFlow (canonicalizeStoredFlow → FlowSchema.parse) and CLI validate (normalizeStackInput) convert first. Sweep of the 20 in-repo defineFlow() callers: the only alias-shaped keys are start.config.timeRelative.object and a create_record.fields.subject, neither judged; Dogfood gates are green. objectui clientValidation.ts:681 parses FlowSchema with no conversion, so it relies on stored rows being canonical (the engine's persistence half).
4. Codes. Five codes in FLOW_SLOT_REFUSAL_CODE_TABLE satisfies Record, typed params, kebab-case, path added; no tracker numbers in any message; prescriptions true. Nit: node-config-key-missing says "so the flow registers, and then every run … fails there" in present tense at the door that now refuses the flow; prescription still right. Smallest fix: "used to register".
5. Fixture triage (20 files read). Completed: engine.test (script → function: 'noop' under a mock executor), fault-edge, activation-ledger (map collection), runtime ×3, types, verify, spec flow/region/pause, lint region fixtures. Re-judged with the executor pin kept via register-whole-then-strip: config-parse (7), guard-refusal-inventory (7 rows, expect fragments unchanged), http/notify/subflow. screen-nodes script 的 config 契约要接入 #4277 的执行期 parse,先得有判别式(actionType)形态 #4343 rows now pin the door refusal plus getFlow null; the stripped-script run guard is still pinned in config-parse. conversions.test keeps the tombstone-blindness pin and adds the function absence pin. No assertion weakened or deleted.
6. D3 entry. Form D holds (only ADR refs, as fix(spec)!: refuse a decision branch with no expression — absent or null — at all three doors (#19961) #20315's entry); surface, replacement, reason true; the three boot-warn spellings exist in source; "no D2" is right, nothing lossless can supply the value.
7. Skills hunk. Ran build-skill-references.ts --check (tsx) on an exported copy of the head: "9 generated files in sync", so _index.md is byte-equal. Only .zod.ts files are listed, which is why the judge module itself does not appear. SKILL.md line 65 ("decision routed by edge condition predicates, not node config") stays true.
8. Changeset. Every keyed sentence checked true (options row, designer writers, unchanged list, boot behaviour); minor on spec and lint with the BREAKING banner; Clause-②: no (narrowing) stands alone; marker adr-0087: registered flow-node-config-required-keys-refused matches the entry id.

② Semver level

minor BREAKING on @objectstack/spec and @objectstack/lint is correct: the narrowing arm is BREAKING per AGENTS.md, major is refused pre-GA, and #20315 shipped the same shape the same way. On the value: api-surface/automation.json gains 6 rows and FLOW_SLOT_REFUSAL_CODES 5 codes; #20352 declared yes for exactly that kind of growth, #20315 grew no api-surface, and triage wrote yes (narrowing). So yes (narrowing) is the reading that states both facts; no (narrowing) understates the widening half. Level, banner and ADR-0087 arm are unaffected, so non-blocking; a one-word fix in the changeset and PR body.

③ Boundary flags

• connector_action with no connectorConfig: same family (build admits, run refuses), but its input is a FlowNode sibling block like wait.waitEventConfig, which FlowSchema already requires (probe: custom@nodes.1.waitEventConfig); outside this card's parseNodeConfig census by definition; follow-up card should require connectorConfig on FlowNodeSchema the same way.
• objectui at pin f8a9d0fb: rowsToList trims and drops blank string cells; defaultNodeExtras seeds http { method: 'GET' }, notify { channels, recipients: [] }, script {}; all become loud save errors located by the designer's FlowSchema pass; needs the objectui card and back-link, not this PR.
• Present-but-wrong-type values (objectName: 42, collection: '', function: ''): still admitted at the doors (probe), refused at run; the family's type half, scoped out by the direction.
• Driver-free merge-tree onto current origin/main (40b315b0) is clean (tree d7d4519fe3, no conflicted file); check:migration-registry run on that merged tree reports registry.ts current (305 semantic). CI at write time: 27 success, 3 skipped, 4 in progress (Test Core 1/5/6, Lint & Repo Gates), 0 failures.

Implemented-by: claude/issue-20316-flow-node-config-build-doors
Reviewed-by: session_01QcAS3qiYYZNezaxZxaUdMV

VERDICT: PASS

[objectstack-fleet]

维护者速读

PR #20416（修复 #20316，一并解决 #20317）· domain:spec 2 号座位（session_01QcAS3qiYYZNezaxZxaUdMV）· 2026-09-28T10:17Z

改了什么

流程节点的配置如果缺了执行器必需的字段，现在在三个入口都会直接报错，不再等到流程运行时才失败或走错分支：

• 入口：FlowSchema 解析、registerFlow 注册、os validate 校验。
• 例子：查询节点没写对象名、循环节点有循环体却没写要遍历的集合、决策分支没写标签。
• 范围：共 13 种节点的 18 个必填键，外加决策分支的标签。

为什么改

以前这类流程能正常保存、发布，运行到那个节点才失败。决策分支没写标签更糟：流程"成功"了，但同时走了所有出边，业务上悄悄出错。执行器本来就要求这些字段，这次让构建期和运行期的要求一致。

风险与代价（含回滚）

• 破坏性变更： 已有流程里若有这类残缺节点，升级后注册会被拒，启动日志会点名，需要补上字段。本仓示例和平台代码实测 0 个流程受影响。
• Studio 设计器： 留空的分支标签、留空的屏幕字段名，以及新拖入但尚未配置的节点，升级 spec 后保存时会报错，报错会定位到具体节点。这部分已在 objectui 立卡跟进：flow designer: blank branch labels, blank screen field names and unconfigured seeded nodes become save errors on the spec bump that carries objectstack#20316 objectui#10948。
• 为什么是 Tier H： 本 PR 唯一的受管文件是 skills/objectstack-automation/references/_index.md，由生成器重新生成，逐字节一致，已核对。
• 回滚： revert 本 PR 即可。

席位意见

建议合并。at-tier 复核 PASS（记录 5867808391）：

• 18 个键逐个对照执行器源码，并做了实测，既没多拒也没漏拒；
• 被改动的 20 个测试文件，没有一处断言被放宽或删除。

两处不阻塞的小问题，未改动已复核的 head：

1. changeset 的 Clause-② 写成 no (narrowing)，更准确应是 yes (narrowing)：本 PR 也新增了 5 个导出的错误码。版本级别仍是 minor 带 BREAKING，不受影响。
2. 一条报错文案仍是"流程会注册成功"的现在时，已随 objectstack#20418 一并修。

另外，connector_action 缺 connectorConfig 同属这一类问题，但不在本卡范围内，已另立 objectstack#20418。

你要做的

审阅后直接合并本 PR（Tier H 由你人工合并即为审核记录）。