feat(formula,lint): warn on date field == temporal-function silent-miss (#3183)

A `Field.date` deserializes as a "YYYY-MM-DD" string (ADR-0053 Phase 1), and
cel-js's equality hard-codes `string == <timestamp>` to false, so
`record.due_date == today()` compiles clean but silently never matches. cel-js
offers no operator-layer hook to fix the comparison, so this adds a build-time
advisory warning (the established ADR-0032 guardrail strategy) that turns the
silent runtime miss into a loud, self-correcting build signal.

- formula: `ExprSchemaHint.dateFields`; `validateExpression` flags `==`/`!=`
  between a named `date` field and today()/daysFromNow()/daysAgo()/now(), with a
  message pointing at the working idioms (date(...), a range, or daysBetween).
  Warning severity — the write/validation path may carry a real Date, so it never
  fails the build. Ordering operators already work (they fault→hydrate) and are
  not flagged.
- lint: `validateStackExpressions` threads each object's `date` field names into
  the validator so the warning fires across formulas, validations, flow/action/
  sharing/hook predicates. Restricted to `type: 'date'` (unambiguously a string);
  `datetime` excluded to avoid false positives.

A runtime fix (data-layer date hydration) stays tracked in #3183 — a naive
version would trade this silent-miss for another (breaking `dateField ==
"literal"`), so it needs its own design.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01SuiM565BZ3TR1VD3prMguB

Author: claude

.changeset/date-field-equality-guardrail.md

@@ -0,0 +1,43 @@
+---
+"@objectstack/formula": minor
+"@objectstack/lint": minor
+---
+
+feat(formula,lint): warn when a `date` field is compared to a temporal function with `==`/`!=` (#3183)
+
+A `Field.date` deserializes as a `YYYY-MM-DD` **string** (ADR-0053 Phase 1), and
+cel-js's equality hard-codes `string == <timestamp>` to `false` — it returns
+`false` for a string left operand without ever consulting a registered overload,
+and refuses cross-type object equality (`@marcbachmann/cel-js` `overloads.js`
+`isEqual`). So the most natural "is it due today" predicate —
+
+```cel
+record.due_date == today()      // silently false, even when due_date IS today
+record.due_date != today()      // silently true for a same-day record
+```
+
+— compiles clean, throws nothing, and silently never matches. This is the
+silent-miss class the ADR-0032 guardrails exist to eliminate (same family as
+#1928), and it is **timezone-independent** (fails identically at UTC) and
+cross-cutting (every CEL site: formulas, validation, RLS, flow, action predicates).
+
+cel-js gives no hook to fix the comparison in the operator layer, so this adds a
+**build-time advisory warning** (the established guardrail strategy) rather than a
+runtime behavior change:
+
+- `@objectstack/formula` — `ExprSchemaHint` gains `dateFields`; `validateExpression`
+  flags a `==`/`!=` between a named `date` field (`record.`/`previous.`/bare) and
+  `today()`/`daysFromNow()`/`daysAgo()`/`now()`, with a self-correcting message
+  pointing at the working idioms (`date(record.d) == today()`, a range comparison,
+  or `daysBetween(today(), record.d) == 0`). Warning severity — never fails the
+  build, since on the write/validation path the value may legitimately be a `Date`.
+- `@objectstack/lint` — `validateStackExpressions` threads each object's `date`
+  field names into the validator so the warning fires across every predicate site.
+  Restricted to `type: 'date'` (unambiguously a string); `datetime` is excluded to
+  avoid false positives.
+
+The ordering operators (`>=`/`<=`/`<`/`>`) already work — cel-js *throws* for them,
+which trips the engine's existing string-hydration retry — so they are not flagged.
+A runtime fix (hydrating date fields to `Date` in the data layer) remains tracked
+in #3183; a naive version would trade this silent-miss for another (breaking
+`dateField == "2026-06-20"`), so it needs its own design.

packages/formula/src/validate.test.ts

@@ -207,3 +207,55 @@ describe('inferExpressionType — coarse value-type of a formula', () => {
     expect(inferExpressionType('undeclared_field + 1')).toBe('unknown'); // bare ref, no fields given
   });
 });
+
+// #3183 — a `Field.date` reads back as a "YYYY-MM-DD" string, and cel-js's
+// equality hard-codes `string == <timestamp>` to false, so `record.due_date ==
+// today()` silently never matches. Advisory warning that guides the author to a
+// working idiom. Only fires when `dateFields` names the field as calendar-day.
+describe('temporal date-equality guardrail (#3183)', () => {
+  const schema = { objectName: 'task', fields: ['due_date', 'status'], dateFields: ['due_date'], scope: 'record' as const };
+
+  const warns = (src: string, s = schema) => validateExpression('predicate', src, s).warnings;
+
+  it('warns on `dateField == today()` (field on the left)', () => {
+    const r = validateExpression('predicate', 'record.due_date == today()', schema);
+    expect(r.ok).toBe(true); // advisory — never fails the build
+    expect(r.errors).toHaveLength(0);
+    expect(r.warnings).toHaveLength(1);
+    expect(r.warnings[0].message).toMatch(/calendar-day \(date\) field/);
+    expect(r.warnings[0].message).toMatch(/date\(record\.due_date\) == today\(\)/);
+  });
+
+  it('warns on `today() == dateField` (field on the right) and on daysFromNow/daysAgo/now', () => {
+    expect(warns('today() == record.due_date')).toHaveLength(1);
+    expect(warns('record.due_date == daysFromNow(3)')).toHaveLength(1);
+    expect(warns('record.due_date != daysAgo(7)')).toHaveLength(1);
+    expect(warns('record.due_date == now()')).toHaveLength(1);
+  });
+
+  it('warns on a bare date-field ref (flattened flow-condition scope)', () => {
+    const flat = { objectName: 'task', fields: ['due_date'], dateFields: ['due_date'] };
+    expect(warns('due_date == today()', flat)).toHaveLength(1);
+  });
+
+  it('does NOT warn on the working idioms', () => {
+    expect(warns('date(record.due_date) == today()')).toHaveLength(0);
+    expect(warns('record.due_date >= today() && record.due_date <= today()')).toHaveLength(0);
+    expect(warns('daysBetween(today(), record.due_date) == 0')).toHaveLength(0);
+  });
+
+  it('does NOT warn on ordering comparisons (they fault→hydrate and work)', () => {
+    expect(warns('record.due_date >= today()')).toHaveLength(0);
+    expect(warns('record.due_date < daysFromNow(30)')).toHaveLength(0);
+  });
+
+  it('does NOT warn on a non-date field, or when dateFields is absent', () => {
+    expect(warns('record.status == today()')).toHaveLength(0); // status not a date field
+    expect(warns('record.due_date == today()', { objectName: 'task', fields: ['due_date'], scope: 'record' as const }))
+      .toHaveLength(0); // no dateFields supplied → check skipped
+  });
+
+  it('de-duplicates repeated references to the same field', () => {
+    expect(warns('record.due_date == today() || record.due_date == daysFromNow(1)')).toHaveLength(1);
+  });
+});

packages/formula/src/validate.ts

@@ -61,6 +61,17 @@ export interface ExprSchemaHint {
    * role that then silently never matches. Absent => role checks are skipped.
    */
   roleCatalog?: readonly string[];
+  /**
+   * Names of `date`-typed (calendar-day) fields on the object. A `Field.date`
+   * deserializes as a `YYYY-MM-DD` **string** (ADR-0053 Phase 1), and cel-js's
+   * equality hard-codes `string == <timestamp>` to false, so a bare
+   * `record.<dateField> == today()` **silently never matches** (#3183). When
+   * supplied, such `==`/`!=` comparisons against a temporal function are flagged
+   * with the corrective idiom. A non-blocking *warning*: on the write/validation
+   * path the value may legitimately be a `Date`, so this must not fail the build.
+   * Absent => the check is skipped.
+   */
+  dateFields?: readonly string[];
 }
 
 export interface ExprValidationError {
@@ -84,6 +95,15 @@ export interface ExprValidationResult {
 
 /** A bare `{x}` that is NOT part of a `{{x}}` mustache hole. */
 const SINGLE_BRACE_RE = /(?:^|[^{])\{\s*([A-Za-z_$][\w.$]*)\s*\}(?!\})/;
+// #3183 — a date field reference (`record.`/`previous.`/bare) compared with
+// `==`/`!=` against a calendar-day temporal function. Two forms (field on either
+// side). Bounded quantifiers only (`[\w$]*`, a single `[^)]*`) → linear-time, no
+// ReDoS. The `date(...)`/`datetime(...)`/`timestamp(...)` coercions are NOT in the
+// temporal set, so the recommended idiom `date(record.d) == today()` is not flagged.
+const TEMPORAL_EQ_LEFT_RE =
+  /(?:record\.|previous\.)?([A-Za-z_$][\w$]*)\s*(?:==|!=)\s*(?:today|daysFromNow|daysAgo|now)\s*\(/g;
+const TEMPORAL_EQ_RIGHT_RE =
+  /(?:today|daysFromNow|daysAgo|now)\s*\([^)]*\)\s*(?:==|!=)\s*(?:record\.|previous\.)?([A-Za-z_$][\w$]*)/g;
 /** `record.<field>` / `previous.<field>` head references for field-existence. */
 const RECORD_REF_RE = /\b(?:record|previous)\.([A-Za-z_$][\w$]*)/g;
 
@@ -199,6 +219,43 @@ function checkRoleCatalog(
   }
 }
 
+/**
+ * Flag `==`/`!=` comparisons of a calendar-day (`date`) field against a temporal
+ * function (`today()`/`daysFromNow()`/`daysAgo()`/`now()`) — the #3183 silent-miss.
+ * A `Field.date` reads back as a `YYYY-MM-DD` string, and cel-js's equality
+ * (`overloads.js` `isEqual`) treats a string and a timestamp as unequal without
+ * ever consulting an overload, so the comparison silently never matches. Advisory
+ * `warning` only (the value may be a `Date` on the write path); no-op unless
+ * `schema.dateFields` is supplied.
+ */
+function checkTemporalDateEquality(
+  source: string,
+  schema: ExprSchemaHint | undefined,
+  warnings: ExprValidationError[],
+): void {
+  const dateFields = schema?.dateFields;
+  if (!dateFields || dateFields.length === 0) return;
+  const dateSet = new Set(dateFields);
+  const seen = new Set<string>();
+  const flag = (field: string): void => {
+    if (!dateSet.has(field) || seen.has(field)) return;
+    seen.add(field);
+    warnings.push({
+      source,
+      message:
+        `\`${field}\` is a calendar-day (date) field, stored as a "YYYY-MM-DD" string, so comparing it to a ` +
+        `timestamp function with \`==\`/\`!=\` silently never matches (CEL treats a string and a timestamp as ` +
+        `unequal). Wrap the field to coerce it — \`date(record.${field}) == today()\` — or use a range ` +
+        `(\`record.${field} >= today() && record.${field} <= today()\`) or \`daysBetween(today(), record.${field}) == 0\`.`,
+    });
+  };
+  let m: RegExpExecArray | null;
+  TEMPORAL_EQ_LEFT_RE.lastIndex = 0;
+  while ((m = TEMPORAL_EQ_LEFT_RE.exec(source)) !== null) flag(m[1]);
+  TEMPORAL_EQ_RIGHT_RE.lastIndex = 0;
+  while ((m = TEMPORAL_EQ_RIGHT_RE.exec(source)) !== null) flag(m[1]);
+}
+
 /**
  * Validate one expression for a given field role. Never throws — returns a
  * structured result. Call sites decide whether to throw (build/registration)
@@ -248,6 +305,7 @@ export function validateExpression(
   } else {
     checkFieldExistence(source, schema, errors);
     checkRoleCatalog(source, schema, errors);
+    checkTemporalDateEquality(source, schema, warnings);
     if (schema?.scope === 'record') {
       // In a `record`-scoped site a bare top-level identifier is a silent bug —
       // it must be `record.<field>` (#1928). Hard error.

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

@@ -394,4 +394,85 @@ describe('validateStackExpressions (ADR-0032 build-time)', () => {
       expect(issues.some(i => /columnName/.test(i.message))).toBe(false);
     });
   });
+
+  // #3183 — `date` field `== today()` silently never matches (cel-js equality).
+  // The stack validator threads the object's `date` field names into the shared
+  // validator, which flags the pattern with an advisory (non-blocking) warning.
+  describe('date-field equality guardrail (#3183)', () => {
+    const objects = [{
+      name: 'task',
+      fields: { due_date: { type: 'date' }, title: { type: 'text' } },
+    }];
+
+    it('warns on a formula field comparing a date field to today()', () => {
+      const issues = validateStackExpressions({
+        objects: [{
+          name: 'task',
+          fields: {
+            due_date: { type: 'date' },
+            is_due_today: { type: 'formula', formula: 'record.due_date == today()' },
+          },
+        }],
+      });
+      const w = issues.filter(i => /calendar-day \(date\) field/.test(i.message));
+      expect(w).toHaveLength(1);
+      expect(w[0].severity).toBe('warning');
+      expect(w[0].where).toMatch(/object 'task'.*formula/);
+    });
+
+    it('warns on a validation-rule predicate, and never fails the build (advisory)', () => {
+      const issues = validateStackExpressions({
+        objects: [{
+          name: 'task',
+          fields: { due_date: { type: 'date' } },
+          validations: [{ name: 'due_check', expression: 'record.due_date != today()' }],
+        }],
+      });
+      const w = issues.filter(i => /calendar-day \(date\) field/.test(i.message));
+      expect(w).toHaveLength(1);
+      expect(w.every(i => i.severity === 'warning')).toBe(true);
+    });
+
+    it('warns on a flattened flow condition using a bare date field', () => {
+      const issues = validateStackExpressions({
+        objects,
+        flows: [{
+          name: 'due_flow',
+          nodes: [
+            { id: 'start', type: 'start', config: { objectName: 'task' } },
+            { id: 'check', type: 'decision', config: { condition: 'due_date == today()' } },
+          ],
+          edges: [],
+        }],
+      });
+      expect(issues.filter(i => /calendar-day \(date\) field/.test(i.message))).toHaveLength(1);
+    });
+
+    it('does not warn on the working idioms or ordering comparisons', () => {
+      const issues = validateStackExpressions({
+        objects: [{
+          name: 'task',
+          fields: {
+            due_date: { type: 'date' },
+            due_soon: { type: 'formula', formula: 'record.due_date >= today() && record.due_date <= daysFromNow(7)' },
+            is_today: { type: 'formula', formula: 'date(record.due_date) == today()' },
+          },
+        }],
+      });
+      expect(issues.filter(i => /calendar-day \(date\) field/.test(i.message))).toHaveLength(0);
+    });
+
+    it('does not warn when the compared field is a datetime (may be a real instant)', () => {
+      const issues = validateStackExpressions({
+        objects: [{
+          name: 'task',
+          fields: {
+            signed_at: { type: 'datetime' },
+            just_signed: { type: 'formula', formula: 'record.signed_at == now()' },
+          },
+        }],
+      });
+      expect(issues.filter(i => /calendar-day \(date\) field/.test(i.message))).toHaveLength(0);
+    });
+  });
 });

packages/lint/src/validate-expressions.ts

@@ -55,6 +55,35 @@ function buildFieldIndex(objects: AnyRec[]): Map<string, string[]> {
   return idx;
 }
 
+/**
+ * object name → its `date`-typed (calendar-day) field names (#3183). A `Field.date`
+ * deserializes as a `YYYY-MM-DD` string, so an `==`/`!=` against a temporal function
+ * silently never matches; the shared validator flags it when these names are passed.
+ * Restricted to `type: 'date'` — a `datetime` may deserialize as a real instant, so
+ * flagging it could false-positive; `date` is unambiguously a string.
+ */
+function buildDateFieldIndex(objects: AnyRec[]): Map<string, string[]> {
+  const idx = new Map<string, string[]>();
+  for (const obj of objects) {
+    const name = typeof obj.name === 'string' ? obj.name : undefined;
+    if (!name) continue;
+    const fields = obj.fields;
+    const dateNames: string[] = [];
+    if (Array.isArray(fields)) {
+      for (const f of fields) {
+        const fr = f as AnyRec;
+        if (typeof fr.name === 'string' && fr.type === 'date') dateNames.push(fr.name);
+      }
+    } else if (fields && typeof fields === 'object') {
+      for (const [fname, fdef] of Object.entries(fields as AnyRec)) {
+        if (fdef && typeof fdef === 'object' && (fdef as AnyRec).type === 'date') dateNames.push(fname);
+      }
+    }
+    idx.set(name, dateNames);
+  }
+  return idx;
+}
+
 /**
  * Validate every predicate in the stack. Returns the list of issues (empty =
  * clean). Caller decides how to surface / whether to fail the build.
@@ -63,6 +92,7 @@ export function validateStackExpressions(stack: AnyRec): ExprIssue[] {
   const issues: ExprIssue[] = [];
   const objects = asArray(stack.objects);
   const fieldIndex = buildFieldIndex(objects);
+  const dateFieldIndex = buildDateFieldIndex(objects);
 
   const check = (
     where: string,
@@ -72,8 +102,9 @@ export function validateStackExpressions(stack: AnyRec): ExprIssue[] {
   ): void => {
     if (raw == null) return;
     const fields = objectName ? fieldIndex.get(objectName) : undefined;
+    const dateFields = objectName ? dateFieldIndex.get(objectName) : undefined;
     const res = validateExpression('predicate', raw as string | { dialect?: string; source?: string },
-      objectName ? { objectName, fields, scope } : { scope });
+      objectName ? { objectName, fields, dateFields, scope } : { scope });
     for (const e of res.errors) issues.push({ where, message: e.message, source: e.source, severity: 'error' });
     for (const w of res.warnings) issues.push({ where, message: w.message, source: w.source, severity: 'warning' });
   };
@@ -193,7 +224,7 @@ export function validateStackExpressions(stack: AnyRec): ExprIssue[] {
         // formulas are `value` role (any return type), still CEL. They are
         // `record`-scoped — `record.<field>`, never bare — so flag bare refs (#1928).
         const res = validateExpression('value', f.formula as string | { dialect?: string; source?: string },
-          objectName ? { objectName, fields: fieldIndex.get(objectName), scope: 'record' } : { scope: 'record' });
+          objectName ? { objectName, fields: fieldIndex.get(objectName), dateFields: dateFieldIndex.get(objectName), scope: 'record' } : { scope: 'record' });
         const fieldWhere = `object '${objectName}' · field '${(f.name as string) ?? '?'}' formula`;
         for (const e of res.errors) issues.push({ where: fieldWhere, message: e.message, source: e.source, severity: 'error' });
         for (const w of res.warnings) issues.push({ where: fieldWhere, message: w.message, source: w.source, severity: 'warning' });