@@ -0,0 +1,34 @@
+---
+'@objectstack/formula': minor
+'@objectstack/spec': minor
+---
+
+fix(formula)!: the formula gate refuses bare date subtraction, which reads null or `{}` at runtime
+
+Clause-②: yes (narrowing)
+Metadata-protocol: narrowed
+
+<!-- adr-0087: registered formula-date-subtraction-refused -->
+
+**BREAKING** accept-set narrowing at the authoring type-soundness gate (`@objectstack/formula` `validateExpression`), shipped as `minor`. The gate declared a `date` / `datetime` field a CEL Timestamp, so `record.end_date - record.start_date` checked as a legal Duration. The runtime never holds a Timestamp there: every read door serves a date field as its `YYYY-MM-DD` text and a datetime field as its ISO-8601 instant text. So the subtraction faulted and the formula read `null` on every record, and `today() - record.start_date` evaluated to a Duration, which a field serialises as `{}`. Both shapes now get the same verdict at every door that runs the gate: `os validate`, `os build`, `os lint`, and the object save door with the other doors of the active authoring gate (`runRuntimeAuthoringRules`). Every door asks one judge.
+
+- **Before.** A formula `record.end_date - record.start_date` or `today() - record.start_date` built green (exit 0), and `PUT /api/v1/meta/object/NAME` answered 200. A read then returned `null` (with a server WARN) or `{}`. The same was true for two datetime fields, and for `now() - record.start_at`.
+- **Now.** The same formula is refused at build (exit 1) and at the save door (422 `INVALID_METADATA`, rule `expression-invalid`), located at the field's `expression`. There are two new refusal codes. `date-text-arithmetic` covers arithmetic on a date field's text that the evaluator faults on, in any role, so a predicate `record.end_date - record.start_date > duration("72h")` is refused too. `date-duration-value` covers a formula whose value is a `google.protobuf.Duration`, whether or not a date field is named (`today() - daysAgo(3)` too). Each message names the runtime outcome and prescribes `daysBetween(a, b)`.
+- **Unchanged.** `(record.end_date - record.start_date) + 1` and `record.d + 1` keep their `date-arithmetic` refusal word for word, because the existing check still answers first. Date comparisons (`<`, `==`, against a literal, against `today()`), concatenation, `daysBetween` / `addDays`, number arithmetic, and a predicate that compares a duration (`today() - record.start_date > duration("72h")`) all stay accepted.
+- **Who sees it.** An author whose formula subtracts dates. That formula already reads `null` or `{}` for every record. No shipped formula in this repository's `packages/` or `examples/` has this shape.
+
+## FROM → TO
+
+```ts
+// before: built green, read null (end minus start) or {} (since a date)
+span: Field.formula({ expression: 'record.end_date - record.start_date' }),
+age: Field.formula({ expression: 'today() - record.start_date' }),
+
+// after: the span in whole days
+span: Field.formula({ expression: 'daysBetween(record.start_date, record.end_date)' }),
+age: Field.formula({ expression: 'daysBetween(record.start_date, today())' }),
+```
+
+The upgrade guide entry is `formula-date-subtraction-refused`. There is no automatic rewrite, because which span the author meant (days, inclusive or not, or hours) is a judgement about the field.
+
+The closed refusal-code set (`EXPRESSION_REFUSAL_CODES`) gains `date-text-arithmetic` (`params: { operands, reference? }`) and `date-duration-value` (`params: { reference? }`).
@@ -244,6 +244,7 @@ come at two severities: **errors** fail the build; **warnings** are advisory
 | **Unknown function** — a misspelled or nonexistent stdlib call. | `isBlnk(record.x)` | error |
 | **Type soundness** — a text or boolean field used with an arithmetic (`+ - * / %`) or ordering (`< > <= >=`) operator against a number faults at runtime and evaluates to `null`. Store it as a number field, or drop the arithmetic. | `record.title * 2` | warning |
 | **Date arithmetic** — a `date` / `datetime` field used with `+` / `-` against a number (a `YYYY-MM-DD` value is a string at runtime, so this always faulted to `null`). Use the date helpers instead. | `record.end_date - record.start_date + 1` → `daysBetween(record.start_date, record.end_date) + 1`; `today() + 30` → `daysFromNow(30)`; `record.date + n` → `addDays(record.date, n)` | error (#3306) |
+| **Date subtraction** — the runtime holds a `date` / `datetime` field as its text (`YYYY-MM-DD`, or an ISO-8601 instant), so subtracting two of them faults and the formula reads `null`; a timestamp minus one computes a duration, which a field reads as `{}`. Use `daysBetween`. A condition may still compare a duration (`today() - record.start_date > duration("72h")`). | `record.end_date - record.start_date` → `daysBetween(record.start_date, record.end_date)`; `today() - record.start_date` → `daysBetween(record.start_date, today())` | error |
 
 > **Integer literals in arithmetic are fine.** `record.amount / 100`,
 > `record.price * 2`, `record.total - fee` all work — the engine handles mixed
 
@@ -302,6 +302,34 @@ describe('validateStackExpressions (ADR-0032 build-time)', () => {
       expect(issues[0].message).toMatch(/daysBetween/);
     });
 
+    // #28944 — the bare subtraction, and a timestamp minus a date field: the
+    // runtime holds a date field as its text, so the first reads null and the
+    // second a Duration (`{}`). Both are refused by the stack gate, located at
+    // the formula's expression; the daysBetween form beside them stays clean.
+    it('flags bare date subtraction and a timestamp minus a date field in a formula field', () => {
+      const issues = validateStackExpressions({
+        objects: [{
+          name: 'qa_doctor_time_off',
+          fields: {
+            start_date: { type: 'date' },
+            end_date: { type: 'date' },
+            qa_span_bare: { type: 'formula', name: 'qa_span_bare', expression: 'record.end_date - record.start_date' },
+            qa_span_daysbetween: {
+              type: 'formula', name: 'qa_span_daysbetween', expression: 'daysBetween(record.start_date, record.end_date)',
+            },
+            qa_since_today: { type: 'formula', name: 'qa_since_today', expression: 'today() - record.start_date' },
+          },
+        }],
+      });
+      expect(issues.map((i) => [i.where, i.severity])).toEqual([
+        ["object 'qa_doctor_time_off' · field 'qa_span_bare' expression", 'error'],
+        ["object 'qa_doctor_time_off' · field 'qa_since_today' expression", 'error'],
+      ]);
+      expect(issues[0].message).toMatch(/evaluates to null/);
+      expect(issues[1].message).toMatch(/reads `\{\}`/);
+      for (const issue of issues) expect(issue.message).toMatch(/daysBetween\(a, b\)/);
+    });
+
     it('accepts the daysBetween rewrite of that formula', () => {
       const issues = validateStackExpressions({
         objects: [{
 
@@ -0,0 +1,35 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+
+import type { SemanticMigration } from '../../types.js';
+
+export const entry: SemanticMigration = {
+  id: 'formula-date-subtraction-refused',
+  surface:
+    'data.Field.expression of a formula field (and any CEL predicate judged with the object\'s field types: '
+    + 'validation conditions, flow conditions) — a date or datetime field subtracted from another '
+    + '(record.end_date - record.start_date), or arithmetic on one with a duration '
+    + '(record.start_date - duration("24h")); and, as a formula value, an expression that computes a '
+    + 'duration (today() - record.start_date, now() - record.start_at)',
+  replacement:
+    'daysBetween(a, b) for the span in whole days: daysBetween(record.start_date, record.end_date) for end '
+    + 'minus start, daysBetween(record.start_date, today()) for the days since a date. addDays(d, n) / '
+    + 'addMonths(d, n) / daysFromNow(n) to shift a date. A predicate may still compare a duration, '
+    + 'today() - record.start_date > duration("72h")',
+  reason:
+    'The authoring type-soundness gate declared a date or datetime field a CEL Timestamp, so the '
+    + 'subtraction of two of them checked as a legal Duration and every door passed it: os validate, '
+    + 'os build, os lint and the object save door. The runtime never holds a Timestamp there: every read '
+    + 'door hands a date field out as its YYYY-MM-DD text and a datetime field as its ISO-8601 instant '
+    + 'text, so the evaluator faulted on the subtraction and the field read null for every record, with '
+    + 'a server WARN as the only trace; a timestamp minus a date field evaluated to a Duration, which a '
+    + 'field serialises as {}. The gate now re-checks what the Timestamp typing passes with the field '
+    + 'declared as that text, and refuses both shapes (date-text-arithmetic, and date-duration-value for a '
+    + 'formula). The (record.end_date - record.start_date) + 1 shape keeps its existing date-arithmetic '
+    + 'refusal and words. There is no mechanical rewrite: which span the author meant (the days between, '
+    + 'inclusive or not, or hours) is a judgement about the field, and a stored formula of the refused '
+    + 'shape read null or {} for every record, so no stored value depends on it.',
+  acceptanceCriteria:
+    'os validate and os build report no date-text-arithmetic or date-duration-value finding; each '
+    + 'rewritten formula field reads a number on GET /api/v1/data/OBJECT/ID where it read null or {} '
+    + 'before; no stored sys_metadata object row reports either finding in its _diagnostics.',
+};