feat(formula,lint): extend tier-4 type-soundness to flattened flow conditions (#1928)

`firstTypeMismatch` gains a `scope` param: in addition to record-scoped sites
(`record.<field>`), it now covers bare-field flow/automation conditions
(`status - 1`, `is_active + 1`). The flattened env binds each field as a
top-level typed variable with `unlistedVariablesAreDyn: true`, so flow
variables stay `dyn` and are never flagged; equality stays excluded.

`validateExpression` runs the check in the flattened branch too, so the lint's
flow-condition validation surfaces the same advisory warning. Message uses the
bare `field` form in flattened scope, `record.field` in record scope.

Tests: formula 219 (+4 flattened cases), lint 232 (+2 flow-condition cases).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Hnji7EEYR2mGt6pY53a8Bm

Author: claude

.changeset/tier4-type-soundness-warnings.md

@@ -22,9 +22,15 @@ would also fail:
 - Equality (`==` / `!=`) is excluded: a heterogeneous equality is runtime-safe
   (evaluates to `false`), never a fault.
 
-New `firstTypeMismatch` export in `@objectstack/formula` (and an optional
-`fieldTypes` hint on `validateExpression`); `@objectstack/lint`'s
-`validateStackExpressions` threads each object's field types into every
-record-scoped site (formula fields, validation rules, action / hook / sharing
-predicates). Warnings are advisory in `objectstack build` / `validate`
-(fatal only under `--strict`), matching the tier-3 channel.
+New `firstTypeMismatch(source, fieldCelTypes, scope)` export in
+`@objectstack/formula` (and an optional `fieldTypes` hint on
+`validateExpression`); `@objectstack/lint`'s `validateStackExpressions` threads
+each object's field types into every checked site:
+
+- **record-scoped** sites (`record.<field>`) — formula fields, validation rules,
+  action / hook / sharing predicates;
+- **flattened** flow / automation conditions (bare `field`) — where flow
+  variables stay `dyn` and are never flagged, and equality stays runtime-safe.
+
+Warnings are advisory in `objectstack build` / `validate` (fatal only under
+`--strict`), matching the tier-3 channel.

packages/formula/src/cel-engine.ts

@@ -188,13 +188,40 @@ export type FieldCelType = 'string' | 'bool' | 'dyn';
 const UNSOUND_OVERLOAD_RE = /no such overload:\s*([\w.]+)\s*(<=|>=|<|>|\+|-|\*|\/|%)\s*([\w.]+)/;
 
 /**
- * A `record`-typed environment where each field carries a concrete CEL type
- * (`string`/`bool`) or `dyn`. Member access (`record.<field>`) then resolves to
- * the field's type, so cel-js's checker faults an arithmetic/ordering operator
- * applied across incompatible types. Built per call — cheap, and only used at
- * build time.
+ * A typed environment for the soundness check. Each field carries a concrete
+ * CEL type (`string`/`bool`) or `dyn`, so cel-js's checker faults an
+ * arithmetic/ordering operator applied across incompatible types. The `scope`
+ * mirrors how the authoring site binds fields:
+ *  - `'record'`    → `record.<field>` member access, via a typed struct on the
+ *                    `record`/`previous`/`input` namespaces (formula fields,
+ *                    validations, action/hook/sharing predicates).
+ *  - `'flattened'` → bare `<field>` top-level variables (flow / automation
+ *                    conditions). Unlisted identifiers stay `dyn`
+ *                    (`unlistedVariablesAreDyn: true`) so a flow variable never
+ *                    faults — only a typed field misused does.
+ * Built per call — cheap, and only used at build time.
  */
-function buildTypedRecordEnv(fieldCelTypes: Readonly<Record<string, FieldCelType>>): Environment {
+function buildTypedEnv(
+  fieldCelTypes: Readonly<Record<string, FieldCelType>>,
+  scope: 'record' | 'flattened',
+): Environment {
+  if (scope === 'flattened') {
+    const env = new Environment({
+      unlistedVariablesAreDyn: true,
+      enableOptionalTypes: true,
+      limits: DEFAULT_LIMITS,
+    });
+    registerStdLib(env, () => new Date(0));
+    for (const root of SCOPE_ROOTS) {
+      try { env.registerVariable(root, 'map'); } catch { /* duplicate — ignore */ }
+    }
+    // Fields are bound bare at top level; a name that collides with a root
+    // (unlikely) is skipped by the duplicate guard.
+    for (const [name, t] of Object.entries(fieldCelTypes)) {
+      try { env.registerVariable(name, t); } catch { /* duplicate / reserved — ignore */ }
+    }
+    return env;
+  }
   const env = new Environment({
     unlistedVariablesAreDyn: false,
     enableOptionalTypes: true,
@@ -216,19 +243,26 @@ function buildTypedRecordEnv(fieldCelTypes: Readonly<Record<string, FieldCelType
 }
 
 /**
- * The first `record.<field>` (or `previous.`/`input.`) reference in `source`
- * whose declared CEL type matches `celType` — best-effort attribution of an
- * overload fault to the offending field. Returns `null` if none is found.
+ * The first field reference in `source` whose declared CEL type matches
+ * `celType` — best-effort attribution of an overload fault to the offending
+ * field. In `'record'` scope it looks for `record.<field>` (or `previous.`/
+ * `input.`); in `'flattened'` scope for a bare `<field>` not preceded by a dot.
+ * Returns `null` if none is found.
  */
 function offendingField(
   source: string,
   fieldCelTypes: Readonly<Record<string, FieldCelType>>,
   celType: FieldCelType,
+  scope: 'record' | 'flattened',
 ): string | null {
   for (const [name, t] of Object.entries(fieldCelTypes)) {
     if (t !== celType) continue;
-    // Word-bounded so `amount` does not match `amount_total`.
-    if (new RegExp(`(?:record|previous|input)\\.${name}(?![\\w$])`).test(source)) return name;
+    // Word-bounded so `amount` does not match `amount_total`; in flattened
+    // scope the leading lookbehind excludes a member ref like `previous.amount`.
+    const re = scope === 'flattened'
+      ? new RegExp(`(?<![\\w$.])${name}(?![\\w$])`)
+      : new RegExp(`(?:record|previous|input)\\.${name}(?![\\w$])`);
+    if (re.test(source)) return name;
   }
   return null;
 }
@@ -251,16 +285,21 @@ function offendingField(
  *
  * Returns the operand types, the faulting operator, the concrete operand CEL
  * type, and (best-effort) the offending field — or `null` when type-sound.
+ *
+ * `scope` selects how fields are bound: `'record'` (default) for
+ * `record.<field>` sites; `'flattened'` for bare-field flow/automation
+ * conditions.
  */
 export function firstTypeMismatch(
   source: string,
   fieldCelTypes: Readonly<Record<string, FieldCelType>>,
+  scope: 'record' | 'flattened' = 'record',
 ): { operator: string; operands: string; celType: FieldCelType; field: string | null } | null {
   if (typeof source !== 'string' || !source.trim()) return null;
   // An all-`dyn` record can never fault an overload — skip the parse entirely.
   if (!Object.values(fieldCelTypes).some((t) => t === 'string' || t === 'bool')) return null;
   try {
-    const env = buildTypedRecordEnv(fieldCelTypes);
+    const env = buildTypedEnv(fieldCelTypes, scope);
     const result = env.parse(source).check?.() as
       | { valid?: boolean; error?: { message?: string } }
       | undefined;
@@ -277,7 +316,7 @@ export function firstTypeMismatch(
       operator,
       operands: `${m[1]} ${operator} ${m[3]}`,
       celType,
-      field: offendingField(source, fieldCelTypes, celType),
+      field: offendingField(source, fieldCelTypes, celType, scope),
     };
   } catch {
     // A parse/other fault is the syntax checker's job (celEngine.compile); this

packages/formula/src/validate.test.ts

@@ -220,12 +220,49 @@ describe('validateExpression (ADR-0032)', () => {
       expect(validateExpression('predicate', 'record.amount != null && record.amount > 0', schema).warnings).toHaveLength(0);
     });
 
-    it('does not run without field types, or in a flattened (flow) scope', () => {
+    it('does not run without field types', () => {
       // No fieldTypes → nothing to check.
       expect(validateExpression('value', 'record.name * 2', { objectName: 'crm_opportunity', fields: schema.fields, scope: 'record' }).warnings).toHaveLength(0);
-      // Flattened flow conditions reference fields bare and carry flow variables;
-      // the typed check is intentionally record-scope only.
-      expect(validateExpression('predicate', 'name * 2', { ...schema, scope: 'flattened' }).warnings).toHaveLength(0);
+    });
+  });
+
+  // #1928 tier 4 (flattened) — the same soundness check for bare-field flow /
+  // automation conditions. Fields are bound bare (`status - 1`); flow variables
+  // stay `dyn` and are never flagged.
+  describe('type-soundness warnings — flattened flow conditions (#1928 tier 4)', () => {
+    const schema = {
+      objectName: 'crm_opportunity',
+      fields: ['stage', 'amount', 'is_active', 'title'] as const,
+      fieldTypes: { stage: 'select', amount: 'currency', is_active: 'boolean', title: 'text' },
+      scope: 'flattened',
+    } as const;
+
+    it('warns on a bare text field used in arithmetic against a number', () => {
+      const r = validateExpression('predicate', 'title - 1 > 0', schema);
+      expect(r.ok).toBe(true);
+      expect(r.warnings).toHaveLength(1);
+      expect(r.warnings[0].message).toMatch(/type mismatch/i);
+      // Bare form — not `record.title`.
+      expect(r.warnings[0].message).toMatch(/`title`/);
+      expect(r.warnings[0].message).not.toMatch(/record\.title/);
+    });
+
+    it('warns on a bare boolean field used in arithmetic', () => {
+      const r = validateExpression('predicate', 'is_active + 1 > 0', schema);
+      expect(r.ok).toBe(true);
+      expect(r.warnings).toHaveLength(1);
+      expect(r.warnings[0].message).toMatch(/boolean/i);
+    });
+
+    it('does NOT flag a flow variable (unlisted → dyn) or number/date fields', () => {
+      // `expiring_count` is not a schema field → dyn → no fault.
+      expect(validateExpression('predicate', 'expiring_count * 2 > 10', schema).warnings).toHaveLength(0);
+      expect(validateExpression('predicate', 'amount / 100 > 5', schema).warnings).toHaveLength(0);
+    });
+
+    it('does NOT flag a correct bare condition, equality, or a select comparison', () => {
+      expect(validateExpression('predicate', 'stage == "closed_won" && amount > 1000', schema).warnings).toHaveLength(0);
+      expect(validateExpression('predicate', 'title == "VIP"', schema).warnings).toHaveLength(0);
     });
   });
 

packages/formula/src/validate.ts

@@ -117,6 +117,33 @@ function toCelFieldTypes(fieldTypes: Readonly<Record<string, string>>): Record<s
   return out;
 }
 
+/**
+ * #1928 tier 4 — a NON-blocking warning for a text/boolean field used with an
+ * arithmetic/ordering operator against a number (a silent-null bug), or `null`
+ * when the expression is type-sound. `scope` selects `record.<field>` vs bare
+ * field binding, and shapes the referenced form in the message.
+ */
+function typeSoundnessWarning(
+  source: string,
+  fieldTypes: Readonly<Record<string, string>>,
+  scope: 'record' | 'flattened',
+): ExprValidationError | null {
+  const mismatch = firstTypeMismatch(source, toCelFieldTypes(fieldTypes), scope);
+  if (!mismatch) return null;
+  const held = mismatch.celType === 'bool' ? 'a boolean' : 'text';
+  const ref = mismatch.field
+    ? (scope === 'record' ? `\`record.${mismatch.field}\`` : `\`${mismatch.field}\``)
+    : null;
+  const subject = ref ? `${ref} holds ${held}` : `${held === 'a boolean' ? 'a boolean' : 'a text'} field`;
+  return {
+    source,
+    message:
+      `type mismatch \`${mismatch.operands}\` — ${subject} but is used with \`${mismatch.operator}\` ` +
+      `against a number. This faults at runtime, so the expression silently evaluates to null ` +
+      `(unless the value happens to be numeric). Use a number field, or drop the arithmetic/comparison.`,
+  };
+}
+
 /** A bare `{x}` that is NOT part of a `{{x}}` mustache hole. */
 const SINGLE_BRACE_RE = /(?:^|[^{])\{\s*([A-Za-z_$][\w.$]*)\s*\}(?!\})/;
 /** `record.<field>` / `previous.<field>` head references for field-existence. */
@@ -303,20 +330,8 @@ export function validateExpression(
         // value happens to be numeric, so this is a warning, not an error. Only
         // runs when there is no bare-ref error (the typed check needs the
         // canonical `record.<field>` form).
-        const mismatch = firstTypeMismatch(source, toCelFieldTypes(schema.fieldTypes));
-        if (mismatch) {
-          const held = mismatch.celType === 'bool' ? 'a boolean' : 'text';
-          const subject = mismatch.field
-            ? `\`record.${mismatch.field}\` holds ${held}`
-            : `${held === 'a boolean' ? 'a boolean' : 'a text'} field`;
-          warnings.push({
-            source,
-            message:
-              `type mismatch \`${mismatch.operands}\` — ${subject} but is used with \`${mismatch.operator}\` ` +
-              `against a number. This faults at runtime, so the expression silently evaluates to null ` +
-              `(unless the value happens to be numeric). Use a number field, or drop the arithmetic/comparison.`,
-          });
-        }
+        const w = typeSoundnessWarning(source, schema.fieldTypes, 'record');
+        if (w) warnings.push(w);
       }
     } else if (schema?.fields && schema.fields.length > 0) {
       // Flattened flow/automation condition: the record's fields ARE bound at
@@ -337,6 +352,14 @@ export function validateExpression(
           });
         }
       }
+      // #1928 tier 4 — the same type-soundness check, for bare-field conditions:
+      // a text/boolean field compared/arithmetic'd against a number faults at
+      // runtime. Flow variables stay `dyn` (never flagged); equality is
+      // runtime-safe (never flagged). Advisory only.
+      if (schema.fieldTypes) {
+        const w = typeSoundnessWarning(source, schema.fieldTypes, 'flattened');
+        if (w) warnings.push(w);
+      }
     }
   }
   return { ok: errors.length === 0, errors, warnings };

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

@@ -283,6 +283,33 @@ describe('validateStackExpressions (ADR-0032 build-time)', () => {
       expect(w).toHaveLength(1);
       expect(w[0].message).toMatch(/record\.title/);
     });
+
+    it('warns on a flattened flow condition doing arithmetic on a bare text field', () => {
+      const issues = validateStackExpressions({
+        objects: [{ name: 'crm_opportunity', fields: { title: { type: 'text' }, amount: { type: 'currency' } } }],
+        flows: [{
+          name: 'opp_flow',
+          nodes: [{ id: 'start', type: 'start', config: { objectName: 'crm_opportunity', condition: 'title * 2 > 10' } }],
+          edges: [],
+        }],
+      });
+      const w = issues.filter(i => i.severity === 'warning');
+      expect(w).toHaveLength(1);
+      expect(w[0].message).toMatch(/type mismatch/i);
+      expect(w[0].message).toMatch(/`title`/);
+    });
+
+    it('does not flag a numeric flow condition or a flow variable', () => {
+      const issues = validateStackExpressions({
+        objects: [{ name: 'crm_opportunity', fields: { amount: { type: 'currency' } } }],
+        flows: [{
+          name: 'opp_flow',
+          nodes: [{ id: 'start', type: 'start', config: { objectName: 'crm_opportunity' } }],
+          edges: [{ id: 'e1', source: 'start', target: 'end', condition: 'amount / 100 > 5 && expiring_count * 2 > 3' }],
+        }],
+      });
+      expect(issues).toHaveLength(0);
+    });
   });
 
   describe('action visible/disabled predicates (record-scoped) — #2183 class', () => {