fix(lint): refuse a blank structural condition at author time, by the rule registerFlow already applies (#17495) (#17665)

`validateStackExpressions` — the pass behind `objectstack validate` — reported
NOTHING for a `config.condition` that is blank after trimming, at either
structural node slot (a `start` node's trigger gate, a `decision` node's
predicate) and on an edge. #17322 rebound `AutomationEngine.registerFlow` to the
edge door's non-blank rule, so the same value now stops the flow registering at
boot behind a single `warn` line — an author ran validate, got a clean bill,
deployed, and the trigger was never armed.

`checkStructuralCondition` gains the same second gate the engine's copy has, in
the same position (after the shape refusal, before the CEL pass), asking the
same IMPORTED schema: `EvaluatedExpressionInputSchema`, the rule
`FlowEdgeSchema.condition` has composed since #15807. Not a second hand-written
notion of "blank" — that is the drift #15662 built one shared refusal to
prevent — so the sentence is the spec's published constant and the three doors
cannot answer differently.

Two pins re-judged IN PLACE, with the reason recorded, never deleted:

  * `validate-expressions.test.ts` — "a whitespace-only STRING is untouched —
    ruled correct, not a defect" recorded that author time and run time AGREED
    about the blank. #15807 and #17322 removed that ground; the case is flipped
    and says so, and still pins that the blank refusal and #15662's shape
    refusal stayed distinct.
  * `lint-flow-patterns.test.ts` — the `flow-inert-node-condition` zero still
    stands (that rule is about a key nothing reads, and has no opinion on
    blankness), but it was readable as "validate says nothing about a blank
    condition". A cross-site assertion now pins where the refusal actually
    lives, so the zero cannot be read as silence again.

Measured on `d46deba195`, same probe, both structural node slots at once —
before: blank `'   '` 0, `''` 0; after: 2 and 2. Controls unmoved and proving
the probe reaches both slots: brace trap 2, `ast`-only envelope 2, valid CEL 0.

Closes #17495


Claude-Session: https://claude.ai/code/session_012GKcPZbMoGq7WPzKLfRBTU

Co-authored-by: claude <noreply@anthropic.com>

Author: claude[bot]

.changeset/validate-refuses-blank-structural-condition.md

@@ -0,0 +1,50 @@
+---
+"@objectstack/lint": minor
+---
+
+fix(lint)!: `objectstack validate` refuses a blank structural `condition`, the rule `registerFlow` has carried since #17322 (#17495)
+
+<!-- adr-0087: not-required (already-registered flow-edge-condition-evaluated-slot-source-required) this is the AUTHOR-TIME face of the decision that entry already carries — an evaluated slot requires a non-blank `source`, refused with EVALUATED_EXPRESSION_SOURCE_REQUIRED — reached by importing the same schema rather than deriving a second rule. No key is renamed, retired or given a new meaning here, and no stored document needs rewriting that the entry does not already prescribe. ⚠️ That entry's `surface` / `acceptanceCriteria` name only `edges[].condition` and still want widening to `config.condition`; the registry file is in packages/spec, outside this card's surface, and is already filed as #17493. -->
+
+**BREAKING** in the accept-set sense, landing in the launch window as `minor`
+(the lockstep convention: `major` is refused by `check-changeset-no-major`, and
+breaking-ness is carried by this banner plus the ADR-0087 disposition):
+`validateStackExpressions` — the pass behind `objectstack validate` — now
+reports an `error` for a structural `condition` whose source is blank after
+trimming. It reported nothing at all before.
+
+The value was already refused by two of the three doors. `FlowEdgeSchema.condition`
+composes `EvaluatedExpressionInputSchema` (#15807), so `'   '` on an edge is
+refused at `FlowSchema.parse`; #17322 rebound `AutomationEngine.registerFlow` to
+that same rule, so the same value on a node's `config.condition` stops the flow
+registering. `objectstack validate` was the door that still said nothing — so an
+author got a clean bill, deployed, and the flow never registered: each boot path
+in `service-automation`'s plugin wraps `registerFlow` in `try`/`catch`, logs one
+`warn` naming the flow, and continues. On a `start` node that key is the
+**trigger gate**, so the whole flow is armed by nothing.
+
+FROM → TO, for a build that used to pass and now fails:
+
+```yaml
+# FROM — validate said nothing; registerFlow refuses it at boot
+nodes:
+  - { id: gate,   type: start,    config: { objectName: lead, triggerType: record-after-update, condition: '   ' } }
+  - { id: branch, type: decision, config: { condition: { dialect: cel, source: '   ' } } }
+
+# TO — either write the predicate you meant…
+nodes:
+  - { id: gate,   type: start,    config: { objectName: lead, triggerType: record-after-update, condition: 'record.active == true' } }
+  - { id: branch, type: decision, config: { condition: { dialect: cel, source: 'record.rating >= 4' } } }
+
+# …or drop the key. An ABSENT condition is still not a malformed one: a start
+# node with no `condition` is an ungated trigger, and that is unchanged.
+```
+
+The refusal is the edge door's own sentence, not a second one — the finding
+carries `EVALUATED_EXPRESSION_SOURCE_REQUIRED` verbatim, located at the node and
+slot the author wrote (`flow 'f' · node 'gate' (start) condition`), because all
+three doors now ask one imported schema.
+
+Unchanged, deliberately: the **evaluator**. A condition already stored blank
+still answers `false` at run time — #15662's ruling on that half stands. What
+moved is that it can no longer be authored past validate.

packages/lint/src/lint-flow-patterns.test.ts

@@ -5,6 +5,10 @@ import { TimeRelativeTriggerSchema, LoopConfigSchema, ParallelConfigSchema, TryC
 // [#5659] The shared identity reduction, asserted beside the rule that consumes
 // it — the rule's verdict and the drivers' verdict are one object now.
 import { reduceFilterVerdict } from '@objectstack/spec/data';
+// [#17495] The published sentence the blank-condition refusal leads with,
+// asserted from the spec's own export rather than re-spelled here — see the
+// re-judged pin in `flow-inert-node-condition` below.
+import { EVALUATED_EXPRESSION_SOURCE_REQUIRED } from '@objectstack/spec';
 import { AUTHORING_RULES } from './authoring-rules.js';
 import {
   lintFlowPatterns,
@@ -28,6 +32,10 @@ import {
   FLOW_LOOP_BODY_UNCONTAINED,
   FLOW_TRY_CATCH_WITHOUT_CATCH,
 } from './lint-flow-patterns.js';
+// [#17495] Cross-site pin only — the re-judged `flow-inert-node-condition`
+// case below. This family's own coverage is unaffected by it;
+// `validate-expressions.test.ts` owns the rest of that rule's coverage.
+import { validateStackExpressions } from './validate-expressions.js';
 
 const CEL = (source: string) => ({ dialect: 'cel', source });
 /**
@@ -1274,9 +1282,31 @@ describe('flow-inert-node-condition (#4414)', () => {
     }).filter((f) => f.rule === FLOW_INERT_NODE_CONDITION)).toHaveLength(0);
   });
 
-  it('does NOT flag a node with no condition, or an empty one', () => {
+  it('does NOT flag a node with no condition, or an empty one — but validate no longer stays silent on the blank (#17495)', () => {
     expect(lintFlowPatterns(conditionNodeFlow('decision', {}))).toHaveLength(0);
     expect(lintFlowPatterns(conditionNodeFlow('decision', { condition: '   ' }))).toHaveLength(0);
+    // RE-JUDGED IN PLACE (#17495), not deleted — the two zeros above are
+    // deliberate and they still stand, but the REASON the blank one stands has
+    // changed and the pin now says so.
+    //
+    // What it recorded: this pin sat over the whole `lintFlowPatterns` answer,
+    // taken at a time when `objectstack validate` as a whole admitted a blank
+    // `config.condition` — `registerFlow` admitted it too, and #15662 ruled
+    // that agreement correct. It was therefore readable as "validate says
+    // nothing about a blank condition". Since #17322 rebound `registerFlow` to
+    // the edge door's non-blank rule, that reading would be a false record.
+    //
+    // What it records now: `flow-inert-node-condition` (#4414) is about a key
+    // NOTHING READS, and a blank condition is not that — this family has no
+    // opinion on blankness and never had one, so its zero is unchanged and is
+    // NOT a statement about validate's answer. The refusal lives one pass over,
+    // in `validateStackExpressions` (#17495), and the cross-site assertion
+    // below is what keeps the zero above from being read as silence again.
+    const blank = conditionNodeFlow('decision', { condition: '   ' });
+    const refusals = validateStackExpressions(blank);
+    expect(refusals).toHaveLength(1);
+    expect(refusals[0].message).toBe(EVALUATED_EXPRESSION_SOURCE_REQUIRED);
+    expect(refusals[0].where).toContain("node 'n' (decision) condition");
   });
 
   it('does NOT flag a PLUGIN node type — its executor may legitimately read it', () => {

packages/lint/src/validate-expressions.test.ts

@@ -2923,6 +2923,14 @@ describe('validateStackExpressions — reads only keys the spec declares (meta-t
       // `source` receivers for the reason the entry above it records: a local
       // called `message` here would be excused into masking a genuine read.
       'shapeRefusal',
+      // [#17495] The blank-source half of the same structural refusal, and the
+      // same argument one line up: its keys are that helper's own
+      // `{ message, source }`, never metadata keys, and it is named to stay
+      // clear of the `message` / `source` receivers. The `safeParse` result it
+      // reads reuses the already-excused `verdict` name above — its keys there
+      // are `success` / `error`, SafeParseResult's own, so that excuse covers
+      // both locals for one reason and masks no metadata read either.
+      'blankRefusal',
       // [#14089] NOT a receiver at all — the tail of the `'./flow-variable-scope.js'`
       // import specifier, which this scan cannot tell from `scope.j…`. The two
       // entries above it in this set (`fields`, `guards`) are the same artefact
@@ -3943,9 +3951,29 @@ describe('structural condition shape (#15662)', () => {
       expect(condIssues({ edgeCondition: 'record.rating >= 4' }, "edge 'e1'")).toHaveLength(0);
     });
 
-    it('a whitespace-only STRING is untouched — ruled correct, not a defect', () => {
-      expect(condIssues({ decisionCondition: '   ' }, "node 'branch'")).toHaveLength(0);
-      expect(condIssues({ edgeCondition: '   ' }, "edge 'e1'")).toHaveLength(0);
+    it('a whitespace-only STRING is refused now (#17495) — the ruling MOVED, it was not deleted', () => {
+      // FLIPPED from "a whitespace-only STRING is untouched — ruled correct,
+      // not a defect". The pin was deliberate and it is kept in place, flipped,
+      // rather than removed: #15662 ruled the blank string correct on the
+      // ground that author time and run time AGREED about it — both admitted
+      // it. #15807 removed that ground at the edge door
+      // (`FlowEdgeSchema.condition` refuses a blank source at
+      // `FlowSchema.parse`), #17322 rebound the node door to the same rule at
+      // `registerFlow`, and #17495 is this pass catching up: a value the
+      // runtime refuses must not pass `objectstack validate`.
+      //
+      // It is NOT #15662's shape refusal that answers — a string is still a
+      // well-shaped condition — so this also pins that the two refusals stayed
+      // distinct, exactly as the registration-side pin does.
+      const node = condIssues({ decisionCondition: '   ' }, "node 'branch'");
+      expect(node).toHaveLength(1);
+      expect(node[0].severity).toBe('error');
+      expect(node[0].message).toBe(EVALUATED_EXPRESSION_SOURCE_REQUIRED);
+      expect(node[0].message.startsWith(STRUCTURAL_CONDITION_SHAPE_REFUSAL)).toBe(false);
+      expect(condIssues({ edgeCondition: '   ' }, "edge 'e1'")).toHaveLength(1);
+      // The EVALUATOR half of #15662's ruling is untouched and out of scope
+      // here: a stored blank condition still answers `false`. What changed is
+      // that it can no longer be authored past this pass.
     });
 
     it('a clean bare-CEL condition still passes', () => {
@@ -3954,6 +3982,154 @@ describe('structural condition shape (#15662)', () => {
   });
 });
 
+/**
+ * [#17495] The blank structural condition — `objectstack validate`'s half of
+ * the refusal #17322 landed in `registerFlow`.
+ *
+ * The gap this closes, measured on `main` at `d46deba195` with the runtime half
+ * already in: `validateStackExpressions` returned **0** for `condition: '   '`
+ * carried at BOTH structural slots (a start node's trigger gate and a decision
+ * node's predicate), and **0** for `''` — while `registerFlow` threw on the
+ * same value. An author ran validate, got a clean bill, deployed, and the flow
+ * never registered: each of the three boot paths in
+ * `service-automation/src/plugin.ts` wraps `registerFlow` in `try`/`catch`,
+ * logs one `warn` naming the flow, and continues. On a `start` node that key is
+ * the TRIGGER GATE, so the whole flow is armed by nothing.
+ *
+ * ⚠️ The rule is IMPORTED, never restated: `EvaluatedExpressionInputSchema` is
+ * the edge door's own schema (`FlowEdgeSchema.condition` composes it since
+ * #15807) and the one `registerFlow` asks, so the sentence below comes from the
+ * spec's published constant and the two doors cannot drift apart. A second
+ * hand-written notion of "blank" is precisely what the #15662 campaign built
+ * one shared refusal to prevent.
+ */
+describe('blank structural condition (#17495)', () => {
+  const objects = [
+    { name: 'crm_lead', fields: { rating: { type: 'number' }, status: { type: 'text' } } },
+  ];
+
+  const flowWith = (opts: { startCondition?: unknown; decisionCondition?: unknown; edgeCondition?: unknown }) => ({
+    objects,
+    flows: [{
+      name: 'gate_flow',
+      nodes: [
+        {
+          id: 'start', type: 'start',
+          config: {
+            objectName: 'crm_lead',
+            ...('startCondition' in opts ? { condition: opts.startCondition } : {}),
+          },
+        },
+        {
+          id: 'branch', type: 'decision',
+          config: { ...('decisionCondition' in opts ? { condition: opts.decisionCondition } : {}) },
+        },
+      ],
+      edges: [{
+        id: 'e1', source: 'start', target: 'branch',
+        ...('edgeCondition' in opts ? { condition: opts.edgeCondition } : {}),
+      }],
+    }],
+  });
+
+  /** Both structural NODE slots at once — the two the gap was measured over. */
+  const bothSlots = (condition: unknown) =>
+    validateStackExpressions(flowWith({ startCondition: condition, decisionCondition: condition }));
+
+  /**
+   * ⭐ The control trio, without which every zero below is void. Each drives
+   * the SAME probe over the SAME two slots with a value that is not blank, and
+   * each is answered by a DIFFERENT pass — so between them they prove the probe
+   * reaches the start node's trigger gate and the decision node's predicate,
+   * and that a clean condition is still clean.
+   */
+  describe('CONTROLS — the probe reaches both slots and still discriminates', () => {
+    it('RED CONTROL — the brace trap reports 2, one per slot (the CEL pass)', () => {
+      const control = bothSlots('{record.rating} >= 4');
+      expect(control).toHaveLength(2);
+      expect(control.map((i) => i.where.includes("node 'start'"))).toContain(true);
+      expect(control.map((i) => i.where.includes("node 'branch'"))).toContain(true);
+      for (const issue of control) expect(issue.message).toContain('template brace');
+    });
+
+    it('RED CONTROL — an `ast`-only envelope reports 2, one per slot (the SHAPE pass)', () => {
+      const control = bothSlots({ dialect: 'cel', ast: { kind: 'const', value: true } });
+      expect(control).toHaveLength(2);
+      for (const issue of control) {
+        expect(issue.message.startsWith(STRUCTURAL_CONDITION_SHAPE_REFUSAL)).toBe(true);
+      }
+    });
+
+    it('GREEN CONTROL — valid CEL on both slots reports 0', () => {
+      expect(bothSlots('record.rating >= 4')).toHaveLength(0);
+    });
+  });
+
+  it('refuses a blank condition on the START trigger gate and on the DECISION predicate', () => {
+    for (const blank of ['   ', '']) {
+      const issues = bothSlots(blank);
+      expect(issues, JSON.stringify(blank)).toHaveLength(2);
+      expect(issues.map((i) => i.where)).toEqual([
+        "flow 'gate_flow' · node 'start' (start) condition",
+        "flow 'gate_flow' · node 'branch' (decision) condition",
+      ]);
+      for (const issue of issues) expect(issue.severity).toBe('error');
+    }
+  });
+
+  it('refuses every spelling of blank on the same rule — tabs and newlines included', () => {
+    for (const blank of ['\t', '\n', ' \t\n ']) {
+      expect(bothSlots(blank), JSON.stringify(blank)).toHaveLength(2);
+    }
+  });
+
+  it('refuses a blank `source` INSIDE an envelope too — one seam, two keys, one rule', () => {
+    expect(bothSlots({ dialect: 'cel', source: '   ' })).toHaveLength(2);
+    // No dialect is still CEL at this slot (#4336), and still blank.
+    expect(bothSlots({ source: '' })).toHaveLength(2);
+  });
+
+  it('answers the EDGE door\'s own sentence, not a second one — the two doors do not drift', () => {
+    const [issue] = bothSlots('   ');
+    // The published constant, asserted from the spec's export rather than
+    // re-spelled here: this pass, `FlowSchema.parse` and `registerFlow` all say
+    // it because all three ask `EvaluatedExpressionInputSchema`.
+    expect(issue.message).toBe(EVALUATED_EXPRESSION_SOURCE_REQUIRED);
+    // The author's own text is the attribution, blank though it is.
+    expect(issue.source).toBe('   ');
+  });
+
+  it('refuses ONCE — the value-reading passes do not re-report it as an empty condition', () => {
+    expect(bothSlots('   ')).toHaveLength(2);
+  });
+
+  it('refuses it on an EDGE condition too — the third structural slot', () => {
+    // The edge door refuses this at `FlowSchema.parse` since #15807; on the raw
+    // input path `validateStackExpressions` walks, this pass is the gate.
+    const issues = validateStackExpressions(flowWith({ edgeCondition: '   ' }));
+    expect(issues).toHaveLength(1);
+    expect(issues[0].message).toBe(EVALUATED_EXPRESSION_SOURCE_REQUIRED);
+  });
+
+  it('an ABSENT condition is still not a malformed one', () => {
+    expect(validateStackExpressions(flowWith({}))).toHaveLength(0);
+    expect(bothSlots(undefined)).toHaveLength(0);
+    expect(bothSlots(null)).toHaveLength(0);
+  });
+
+  it('a non-blank condition still earns its pre-existing verdict, never the blank one', () => {
+    // A shape violation is still the SHAPE refusal: the blank gate runs after
+    // it and must not swallow it.
+    const shaped = bothSlots(42);
+    expect(shaped).toHaveLength(2);
+    for (const issue of shaped) {
+      expect(issue.message.startsWith(STRUCTURAL_CONDITION_SHAPE_REFUSAL)).toBe(true);
+    }
+    // And a source that only LOOKS empty to a trimming reader is fine.
+    expect(bothSlots(' record.rating >= 4 ')).toHaveLength(0);
+  });
+});
+
 describe("validateStackExpressions — a non-record entry in an object's `fields:` list (#15742)", () => {
   // `buildFieldIndex` used to cast each member inline
   // (`fields.map(f => (f as AnyRec).name)`), so an empty YAML list item —