feat(lint): a flow update_record node writing an undeclared field gates the build (#4271) (#4369)

The write-set family #4305 (hooks) and #4344 (actions) opened had a third
surface, and it was the one the docs had spent the longest recommending as the
safe alternative to the other two. A flow `update_record` node whose
`config.fields` names a field the target object never declares was caught by
NOTHING: `validate-readonly-flow-writes.ts` walks that exact map and explicitly
stepped over the unknown key (`if (!meta) continue; // a form/field-layout lint
concern` — a referral to a rule that does not check writes), and
`validate-flow-template-paths.ts` checks the `{record.<path>}` READ tokens
interpolated into node config, never the write-side key.

New rule `flow-node-write-unknown-field`, wired into REFERENCE_INTEGRITY_RULES
so `os validate`, `os lint` and `os compile` report it at once — one more path
than the hand-wired readonly rule next door reaches.

It GATES where its two siblings advise. The hook and action rules are advisory
because they PARSE JavaScript: the finding is only as good as the extractor.
Nothing here is parsed — `config.fields` is a literal map next to a literal
`objectName`, the same certainty `flow-update-readonly-field` already gates on
one config key over. A rule that errors on a write the engine strips while only
warning on a write that names no column at all would be incoherent in the same
map.

And the runtime consequence is not the benign "consumer skips the unknown name
and renders the rest" that keeps page-field-unknown / form-field-unknown
advisory. Both halves were measured: through the engine an undeclared key
reaches `driver.update` verbatim, and on SQLite/knex it becomes `no such
column: stagee` — the statement is rejected WHOLE, so the correctly named
fields in the same payload never land either. On a schemaless datasource the
stray key is persisted into a column no schema-driven read returns.

One field index and one implicit-field set across all three surfaces:
`indexObjectFields` and `IMPLICIT_FIELDS` are imported from the hook rule
rather than copied. Every skip is silent and exists so the gate only fires on a
certainty — templated `objectName`, non-literal `fields`, cross-package
objects, objects declaring no fields at all (external / introspected schemas),
dotted keys. `runAs` is deliberately not consulted, unlike the readonly rule:
an elevated identity bypasses the readonly strip, but no run identity conjures
a column.

Scope is declared as data: FLOW_WRITE_NODE_TYPES (today `update_record`) and
FLOW_WRITE_NODE_TYPES_DEFERRED (`create_record`, with its reason) are
partition-tested against the CRUD node types that carry a `fields` write map,
derived behaviourally from the spec's executor-written config schemas.

Docs: automation/hook-bodies.mdx and automation/hooks.mdx carried the pre-#4271
framing (write side "not checked", an "accepted gap with no planned closure")
long after both body rules landed. Both now state the real asymmetry, with an
explicit callout that a clean run is not proof.

Co-authored-by: Jack Zhuang <277994282+os-zhuang@users.noreply.github.com>
Co-authored-by: Claude Opus 5 <noreply@anthropic.com>

Author: os-zhuang

.changeset/flow-node-write-set-lint.md

@@ -0,0 +1,85 @@
+---
+"@objectstack/lint": minor
+"@objectstack/spec": patch
+---
+
+feat(lint): a flow `update_record` node writing an undeclared field gates the build (#4271)
+
+The write-set family #4305 (hooks) and #4344 (actions) opened had a third
+surface, and it was the one the docs had spent the longest recommending as the
+safe alternative to the other two. A flow `update_record` node whose
+`config.fields` names a field the target object never declares was caught by
+**nothing**: `validate-readonly-flow-writes.ts` walks that exact map and
+explicitly stepped over the unknown key (`if (!meta) continue; // a
+form/field-layout lint concern` — a referral to a rule that does not check
+writes), and `validate-flow-template-paths.ts` checks the `{record.<path>}`
+READ tokens interpolated into node config, never the write-side key. So the
+surface `hook-bodies.mdx` pointed authors at — "prefer a flow `update_record`
+node, whose structural `fields` config is checked" — was the least checked of
+the three.
+
+**New rule — `flow-node-write-unknown-field`, and it is an `error`.** Wired into
+`REFERENCE_INTEGRITY_RULES`, so `os validate`, `os lint` and `os compile` report
+it at once (one more place than the hand-wired readonly rule next door reaches).
+
+**Why it gates where its two siblings advise.** The hook and action rules are
+advisory because they PARSE JavaScript: the finding is only as good as the
+extractor, and a false positive kills an advisory lint. Nothing here is parsed —
+`config.fields` is a literal map next to a literal `objectName`, the same
+certainty `flow-update-readonly-field` already gates on one config key over. A
+rule that errors on a write the engine *strips* while only warning on a write
+that names no column at all would be incoherent in the same `fields` map.
+
+And the runtime consequence is not the benign "consumer skips the unknown name
+and renders the rest" that keeps `page-field-unknown` / `form-field-unknown`
+advisory. Both halves were measured, not inferred:
+
+- Through the engine, an undeclared key reaches `driver.update` verbatim — the
+  flow executor calls the data engine directly, the UPDATE path strips only
+  readonly/readonlyWhen, and the SQL driver's `formatInput` /
+  `applyWriteColumnMap` pass an unrecognized key straight through (`m[k] ?? k`).
+- On SQLite/knex it becomes `update "deal" set "name" = 'n2', "stagee" = 'won' …
+  → no such column: stagee`. The statement is rejected **whole**: `name` —
+  spelled correctly, in the same payload — does not land either, and the step
+  fails with a driver error naming a column, far from the authoring mistake.
+- On a schemaless datasource nothing rejects it, so the stray key is persisted
+  into a column the object never declares, where no schema-driven read returns
+  it.
+
+That is the call `validate-searchable-fields` makes for a stale entry and
+`validate-flow-template-paths` makes for a filter-position token: gate when the
+miss breaks or corrupts the operation, advise when it merely narrows the output.
+
+**One field index and one implicit-field set across all three surfaces.**
+`indexObjectFields` and `IMPLICIT_FIELDS` are imported from the hook rule rather
+than copied, so the three rules cannot drift on what is writable without being
+authored — the shape #4330 collapsed one package over.
+
+Every skip exists so the gate only ever fires on a certainty, and each is
+silent: a templated `objectName`, a non-literal `fields` map, an object this
+stack does not define, an object that declares no fields at all (external /
+datasource-introspected schemas, the same skip `validate-searchable-fields`
+takes), and dotted keys (a nested-path write, not a top-level column). `runAs`
+is deliberately NOT consulted, unlike the readonly rule that skips
+`runAs:'system'` — an elevated identity bypasses the readonly strip, but no run
+identity conjures a column.
+
+**Scope is declared as data, not left as silence.** `FLOW_WRITE_NODE_TYPES`
+(today `update_record`) and `FLOW_WRITE_NODE_TYPES_DEFERRED` (`create_record`,
+with its reason) are partition-tested against the CRUD node types that carry a
+`fields` write map — derived behaviourally from the spec's executor-written
+config schemas, not restated — so a node type that grows one later fails that
+test until someone classifies it.
+
+`@objectstack/spec`: `ScriptBodySchema`'s "prefer a flow `update_record` node,
+whose structural `fields` config is error-checked" note now names the rule that
+makes it true. Doc comment only — no schema or generated-artifact change.
+
+Docs: #4355 had just rewritten `automation/hook-bodies.mdx` to record this gap
+honestly — "**Prefer a flow `update_record` node when the write set is fixed —
+but not for *this* check** … writing a field the object never declares is
+currently reported by nothing at all. On that one axis an L2 body is now the
+better-checked surface." That bullet, and the matching note in
+`automation/hooks.mdx`, are the two sentences this change makes false. Both now
+say the axis has flipped back — and why the flow side lands a level *stronger*
+than the body side rather than merely level with it.

content/docs/automation/hook-bodies.mdx

@@ -161,7 +161,7 @@ Because the checking is advisory and literal-only:
 
 - **Treat `hook-body-write-unknown-field` as a build failure by convention.** It does not gate, but the rule is tuned for near-zero false positives — in practice a warning is a real typo.
 - **Check by hand what the parser cannot see.** Computed keys, spreads, aliased input and dynamic object names are invisible to the rule; for an array or `"*"` hook, every field must exist on every target.
-- **Prefer a flow `update_record` node when the write set is fixed — but not for *this* check.** A flow node's writes are structured config: they diff field-by-field, render in the Console designer, and a write to a `readonly:true` field is a **gating error** (`flow-update-readonly-field`) that hooks have no counterpart for. What an `update_record` node does *not* get today is a field-existence check — writing a field the object never declares is currently reported by nothing at all. On that one axis an L2 body is now the better-checked surface.
+- **Prefer a flow `update_record` node when the write set is fixed — and for *this* check most of all.** A flow node's writes are structured config: they diff field-by-field, render in the Console designer, and a write to a `readonly:true` field is a **gating error** (`flow-update-readonly-field`) that hooks have no counterpart for. Since [#4271](https://github.com/objectstack-ai/objectstack/issues/4271) the field-existence check gates there too — `flow-node-write-unknown-field` is an **error**, not the advisory warning a body gets, because a node's `fields` is a literal map next to a literal `objectName`: there is no parser in between that could have mis-extracted it, so a finding is a certainty rather than a best effort.
 - **Exercise the hook against a real object before shipping** — on SQL drivers the mistake surfaces on the first write; schemaless drivers won't tell you.
 
 ### Signature conventions

content/docs/automation/hooks.mdx

@@ -39,9 +39,10 @@ Two structural reasons to prefer the flow when either could work:
   hook body's write set is checked too, but only for the literal patterns a
   parser can recognise and only as an advisory warning (see
   [Hook & Action Bodies](/docs/automation/hook-bodies#write-set-checking)).
-  Note the one axis where this reverses: writing a field the target object never
-  declares warns in a hook body, and is reported nowhere in an `update_record`
-  node.
+  Field existence is checked on both surfaces, at different strengths: a hook
+  body gets a warning, an `update_record` node a **gating error**
+  (`flow-node-write-unknown-field`) — its `fields` is a literal map next to a
+  literal `objectName`, so nothing could have mis-read it.
 - **A flow reviews as data.** The node graph diffs field-by-field and renders
   in the Console designer with per-node run history; a hook body reviews as
   code only.

packages/lint/src/index.ts

@@ -296,6 +296,23 @@ export type {
   ActionBodyWriteExclusion,
 } from './validate-action-body-writes.js';
 
+// The same write-set question on the third surface — a flow `update_record`
+// node's structural `config.fields`. Shares the hook rule's field index and
+// implicit-field set so all three agree on what is writable without being
+// authored; gates (`error`) rather than advising, because a literal key against
+// a literal object name is a certainty the parsed-JS rules cannot claim.
+export {
+  validateFlowNodeWrites,
+  FLOW_NODE_WRITE_UNKNOWN_FIELD,
+  FLOW_WRITE_NODE_TYPES,
+  FLOW_WRITE_NODE_TYPES_DEFERRED,
+} from './validate-flow-node-writes.js';
+export type {
+  FlowNodeWriteFinding,
+  FlowNodeWriteSeverity,
+  FlowWriteNodeDeferral,
+} from './validate-flow-node-writes.js';
+
 // One entry point for the reference-resolution rules above (#3583 §5 D5).
 // Adding a rule to `REFERENCE_INTEGRITY_RULES` runs it on `validate`, `lint`
 // and `compile` at once — the CLI call sites do not change.

packages/lint/src/reference-integrity-suite.test.ts

@@ -28,6 +28,7 @@ describe('reference-integrity suite — membership', () => {
       'validateAiAgentAuthoring',
       'validateHookBodyWrites',
       'validateActionBodyWrites',
+      'validateFlowNodeWrites',
     ]);
   });
 
@@ -166,6 +167,15 @@ describe('reference-integrity suite — every member actually runs', () => {
             type: 'get_record',
             config: { objectName: 'crm_lead', filter: { name: '{record.budget}' } },
           },
+          // validateFlowNodeWrites: the node's structural write map names a
+          // field crm_lead does not declare — the third surface in the #4271
+          // family, and the only one whose finding is a certainty rather than
+          // an extraction (so it gates).
+          {
+            id: 'stamp',
+            type: 'update_record',
+            config: { objectName: 'crm_lead', fields: { lead_score: 100 } },
+          },
         ],
       },
     ],
@@ -191,6 +201,7 @@ describe('reference-integrity suite — every member actually runs', () => {
     // The one member that emits a second rule id — see the suite's comment on
     // why it rides along instead of becoming its own entry.
     expect(rules).toContain('action-record-write-discarded');
+    expect(rules).toContain('flow-node-write-unknown-field');
   });
 
   it('carries a gating flow-template finding through the suite (#3810)', () => {
@@ -212,9 +223,9 @@ describe('reference-integrity suite — every member actually runs', () => {
       expect(typeof f.message).toBe('string');
       expect(typeof f.hint).toBe('string');
     }
-    // Object references run first, action-body writes last.
+    // Object references run first, flow-node writes last.
     expect(findings[0].rule).toBe('object-reference-unknown');
-    expect(findings[findings.length - 1].rule).toBe('action-body-write-unknown-field');
+    expect(findings[findings.length - 1].rule).toBe('flow-node-write-unknown-field');
   });
 
   it('returns nothing for an empty stack', () => {

packages/lint/src/reference-integrity-suite.ts

@@ -67,6 +67,7 @@ import { validateAiToolReferences } from './validate-ai-tool-references.js';
 import { validateAiAgentAuthoring } from './validate-ai-agent-authoring.js';
 import { validateHookBodyWrites } from './validate-hook-body-writes.js';
 import { validateActionBodyWrites } from './validate-action-body-writes.js';
+import { validateFlowNodeWrites } from './validate-flow-node-writes.js';
 
 export type ReferenceIntegritySeverity = 'error' | 'warning';
 
@@ -135,6 +136,13 @@ export const REFERENCE_INTEGRITY_RULES: readonly ReferenceIntegrityRule[] = [
   // drift this suite exists to end (`validateReadonlyFlowWrites` is the
   // standing proof — wired into `validate` and `compile`, never into `lint`).
   { name: 'validateActionBodyWrites', run: validateActionBodyWrites },
+  // The third surface that writes a record field set: a flow `update_record`
+  // node's `config.fields`. Same question as the two rules above, but the map
+  // is structural metadata rather than parsed JS, so a finding is a certainty
+  // and gates (`error`) — see that module for why, and why the docs' long-
+  // standing "prefer a flow node, it's checked" advice was the least true of
+  // the three until it landed.
+  { name: 'validateFlowNodeWrites', run: validateFlowNodeWrites },
 ];
 
 /**