feat(formula): 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.

`validateExpression` reuses the shared `ExprSchemaHint.fieldTypes` (the same
per-field type map the #1928 tier-4 soundness check already threads through
`@objectstack/lint`) to flag `==`/`!=` between a `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.
Restricted to `type: 'date'` (unambiguously a string); `datetime` excluded to
avoid false positives. Ordering operators already work (they fault→hydrate) and
are not flagged. Complements the #1874 flow-scheduling lint, which targets a
different root cause (record-change triggers firing only on the exact write day).

A runtime fix (normalizing the peer of a temporal operand in the data layer)
stays tracked in #3183 — a naive "hydrate date fields to Date" version would
trade this silent-miss for another (breaking `dateField == "literal"`).

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,41 @@
+---
+"@objectstack/formula": minor
+---
+
+feat(formula): 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. Same silent-miss
+family as #1928; **timezone-independent** (fails identically at UTC) and
+cross-cutting (formulas, validation, RLS, flow/action/sharing/hook predicates).
+
+cel-js gives no operator-layer hook to fix the comparison, so this adds a
+**build-time advisory warning** (the established ADR-0032 guardrail strategy)
+rather than a runtime behavior change. `validateExpression` reuses the shared
+`ExprSchemaHint.fieldTypes` (the same per-field type map the #1928 tier-4
+soundness check already threads through `@objectstack/lint`) to flag a `==`/`!=`
+between a `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
+(`>= … && <= …`), or `daysBetween(today(), record.d) == 0`.
+
+Warning severity — never fails the build (the write/validation path may carry a
+real `Date`). Restricted to `type: 'date'` (unambiguously a string); `datetime`
+is excluded to avoid false positives. Ordering operators (`>=`/`<=`/`<`/`>`)
+already work — cel-js *throws* for them, tripping the engine's existing
+string-hydration retry — so they are not flagged.
+
+A runtime fix (normalizing the peer of a temporal operand in the data layer)
+remains tracked in #3183; a naive "hydrate date fields to `Date`" 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

@@ -200,9 +200,12 @@ describe('validateExpression (ADR-0032)', () => {
       expect(validateExpression('value', 'record.amount * 2 - 50', schema).warnings).toHaveLength(0);
     });
 
-    it('does NOT warn on a date field compared to today()/daysFromNow()', () => {
+    it('does NOT warn on a date field with an ORDERING comparison (they hydrate at runtime)', () => {
+      // Ordering ops fault → the engine's string-hydration retry fires → they work.
+      // (Equality `==`/`!=` does NOT — that is the #3183 silent-miss, covered in its
+      // own block below; this tier-4 check leaves it to the #3183 guardrail.)
       expect(validateExpression('predicate', 'record.due <= daysFromNow(30)', schema).warnings).toHaveLength(0);
-      expect(validateExpression('predicate', 'record.due == today()', schema).warnings).toHaveLength(0);
+      expect(validateExpression('predicate', 'record.due >= today()', schema).warnings).toHaveLength(0);
     });
 
     it('does NOT warn on a select field ordered against a number (option values may be numeric codes)', () => {
@@ -320,3 +323,61 @@ 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. Derived from the shared `fieldTypes` hint (type === 'date').
+describe('temporal date-equality guardrail (#3183)', () => {
+  const schema = {
+    objectName: 'task',
+    fields: ['due_date', 'status'] as const,
+    fieldTypes: { due_date: 'date', status: 'text' },
+    scope: 'record',
+  } as const;
+  const dateWarns = (src: string, s: Record<string, unknown> = schema) =>
+    validateExpression('predicate', src, s as never).warnings
+      .filter(w => /calendar-day \(date\) field/.test(w.message));
+
+  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);
+    const w = r.warnings.filter(x => /calendar-day \(date\) field/.test(x.message));
+    expect(w).toHaveLength(1);
+    expect(w[0].message).toMatch(/date\(record\.due_date\) == today\(\)/);
+  });
+
+  it('warns on `today() == dateField` and on daysFromNow/daysAgo/now', () => {
+    expect(dateWarns('today() == record.due_date')).toHaveLength(1);
+    expect(dateWarns('record.due_date == daysFromNow(3)')).toHaveLength(1);
+    expect(dateWarns('record.due_date != daysAgo(7)')).toHaveLength(1);
+    expect(dateWarns('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'], fieldTypes: { due_date: 'date' } };
+    expect(dateWarns('due_date == today()', flat)).toHaveLength(1);
+  });
+
+  it('does NOT warn on the working idioms', () => {
+    expect(dateWarns('date(record.due_date) == today()')).toHaveLength(0);
+    expect(dateWarns('record.due_date >= today() && record.due_date <= today()')).toHaveLength(0);
+    expect(dateWarns('daysBetween(today(), record.due_date) == 0')).toHaveLength(0);
+  });
+
+  it('does NOT warn on ordering comparisons (they fault→hydrate and work)', () => {
+    expect(dateWarns('record.due_date >= today()')).toHaveLength(0);
+    expect(dateWarns('record.due_date < daysFromNow(30)')).toHaveLength(0);
+  });
+
+  it('does NOT warn on a non-date field, or when fieldTypes is absent', () => {
+    expect(dateWarns('record.status == today()')).toHaveLength(0); // status is text, not date
+    expect(dateWarns('record.due_date == today()', { objectName: 'task', fields: ['due_date'], scope: 'record' }))
+      .toHaveLength(0); // no fieldTypes → check skipped
+  });
+
+  it('de-duplicates repeated references to the same field', () => {
+    expect(dateWarns('record.due_date == today() || record.due_date == daysFromNow(1)')).toHaveLength(1);
+  });
+});

packages/formula/src/validate.ts

@@ -144,10 +144,56 @@ function typeSoundnessWarning(
   };
 }
 
+/**
+ * #3183 — flag `==`/`!=` between a calendar-day (`date`) field and a temporal
+ * function (`today()`/`daysFromNow()`/`daysAgo()`/`now()`). A `Field.date` reads
+ * back as a `YYYY-MM-DD` string (ADR-0053 Phase 1), and cel-js's equality
+ * (`overloads.js` `isEqual`) treats a string and a timestamp as unequal without
+ * consulting any overload, so the comparison silently never matches. Advisory
+ * `warning` only — on the write/validation path the value may be a real `Date` —
+ * and no-op unless `schema.fieldTypes` marks the referenced field `date`. Derives
+ * the date fields from the shared `fieldTypes` hint (no separate plumbing).
+ */
+function checkTemporalDateEquality(
+  source: string,
+  schema: ExprSchemaHint | undefined,
+  warnings: ExprValidationError[],
+): void {
+  const fieldTypes = schema?.fieldTypes;
+  if (!fieldTypes) return;
+  const seen = new Set<string>();
+  const flag = (field: string): void => {
+    if (fieldTypes[field] !== 'date' || 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]);
+}
+
 /** 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. */
 const RECORD_REF_RE = /\b(?:record|previous)\.([A-Za-z_$][\w$]*)/g;
+// #3183 — a date-field reference (`record.`/`previous.`/bare) compared with
+// `==`/`!=` against a calendar-day temporal function, in either operand order.
+// 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 matched.
+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;
 
 /** The dialect a field role expects (Decision 2). */
 export function expectedDialect(role: FieldRole): 'cel' | 'template' {
@@ -310,6 +356,10 @@ export function validateExpression(
   } else {
     checkFieldExistence(source, schema, errors);
     checkRoleCatalog(source, schema, errors);
+    // #3183 — date-field `==`/`!=` a temporal function silently never matches.
+    // Scope-independent (wrong in both record and flattened sites), so run it
+    // outside the scope branch below.
+    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

@@ -472,4 +472,87 @@ 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 each object's field types 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' } },
+    }];
+    const dateWarns = (issues: { message: string }[]) =>
+      issues.filter(i => /calendar-day \(date\) field/.test(i.message));
+
+    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 = dateWarns(issues);
+      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 = dateWarns(issues);
+      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(dateWarns(issues)).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(dateWarns(issues)).toHaveLength(0);
+    });
+
+    it('does not warn on a datetime field (may deserialize as a real instant)', () => {
+      const issues = validateStackExpressions({
+        objects: [{
+          name: 'task',
+          fields: {
+            signed_at: { type: 'datetime' },
+            just_signed: { type: 'formula', formula: 'record.signed_at == now()' },
+          },
+        }],
+      });
+      expect(dateWarns(issues)).toHaveLength(0);
+    });
+  });
 });