@qrvey/formula-lang 3.2.0-rc.1104 → 3.2.0-rc.1159

package/QRVEY-DATE-PRESETS.md

@@ -35,7 +35,11 @@ Formats dates, ranges, and partial dates for UI.
 ## Output Types
 
 ```ts
-type DatePresetValue = string | DateRangeValue | PartialDateValue;
+type DatePresetValue =
+    | string
+    | DateRangeValue
+    | PartialDateValue
+    | ScalarValue;
 ```
 
 By default, `date` is represented as a UTC ISO string:
@@ -74,16 +78,51 @@ Supported fields for `partialDate`:
 
 ## Value Types
 
-`TranspileDatePreset` returns `valueType` to describe the nature of the value.
-
-| Value type  | Meaning                                                       | Examples                                                             |
-| ----------- | ------------------------------------------------------------- | -------------------------------------------------------------------- |
-| `fixed`     | Fixed value or materialized range                             | `DATE("2026-07-20")`, `DATE_RANGE(...)`                              |
-| `recurring` | Partial pattern that repeats                                  | `PARTIAL_DATE("ANY", 4)`, `PARTIAL_DATE("ANY", 4, "ANY", "ANY", 15)` |
-| `relative`  | Period relative to the calendar or positioned inside a period | `CALENDAR_PERIOD("MONTH", 0)`, `PERIOD_AT("MONTH", 4, 2026)`         |
-| `rolling`   | Moving window from an anchor                                  | `RELATIVE_PERIOD(-29, "DAY")`                                        |
-
-Current note: `PERIOD_AT("MONTH", 4, 2026)` produces a concrete range, but it is classified as `relative` because the root expression is `PERIOD_AT`. If the business goal requires distinguishing `April 2026` as `fixed`, that would be a classification improvement, not a resolution change.
+`TranspileDatePreset` classifies every expression on two independent axes:
+`valueType` answers *how the value was built*, `temporality` answers *whether it
+moves with the clock*. They are independent — `PERIOD_AT("MONTH", 4, 2026)` is
+`aligned` and `static`, while `PERIOD_AT("MONTH", 4)` is `aligned` and `dynamic`.
+
+| Value type  | Meaning                                                    | Examples                                                             |
+| ----------- | ---------------------------------------------------------- | -------------------------------------------------------------------- |
+| `explicit`  | A named instant or a range between two of them             | `DATE("2026-07-20")`, `TODAY()`, `DATE_RANGE(...)`                   |
+| `aligned`   | Snapped to a calendar boundary, or positioned in a period  | `CALENDAR_PERIOD("MONTH", 0)`, `PERIOD_AT("MONTH", 4, 2026)`         |
+| `rolling`   | Moving window or shift measured from an anchor             | `RELATIVE_PERIOD(-29, "DAY")`, `OFFSET(TODAY(), -7, "DAY")`          |
+| `recurring` | Partial pattern that repeats                               | `PARTIAL_DATE("ANY", 4)`, `PARTIAL_DATE("ANY", 4, "ANY", "ANY", 15)` |
+| `scalar`    | A number extracted from a date                             | `PART(TODAY(), "MONTH")`, `PART(TODAY(), "YEAR") - 1`                |
+| `dataBound` | Resolved from a column value                               | reserved; see QRV-1069 column-bound functions                        |
+
+| Temporality | Meaning                                                          | Examples                                       |
+| ----------- | ---------------------------------------------------------------- | ---------------------------------------------- |
+| `static`    | Resolves to the same value on every run                          | `DATE("2026-07-20")`, `PERIOD_AT("MONTH", 4, 2026)` |
+| `dynamic`   | Depends on the current instant, directly or through a default    | `TODAY()`, `CALENDAR_PERIOD("MONTH", 0)`       |
+| `timeless`  | Has no instant to move — a pattern rather than a point           | `PARTIAL_DATE("ANY", 4)`                       |
+
+`temporality` is optional in the response type; an absent value means `timeless`.
+
+Both axes are structural: they are derived from the expression tree alone. The
+resolution context — timezone, calendar, `weekStartsOn`, `fiscalYearStartMonth`,
+`applyTimezoneToExpression` — changes resolved values, never classification.
+
+`START_OF` and `END_OF` are boundary selectors: they take the `valueType` of
+their operand. `START_OF(CALENDAR_PERIOD("MONTH", 0))` is `aligned`,
+`START_OF(RELATIVE_PERIOD(-6, "DAY"))` is `rolling`, and
+`START_OF(DATE("2026-07-08"))` is `explicit`.
+
+Their optional `UNIT` does not change that. Snapping to a boundary is not what
+makes a value `aligned` — `START_OF(DATE("2026-07-08"))` already snaps to a day
+boundary and stays `explicit`. The unit chooses *which* boundary; it does not
+change how the value was built. So `START_OF(TODAY(), "MONTH")` is `explicit`
+even though it resolves to the same instant as the `aligned`
+`START_OF(CALENDAR_PERIOD("MONTH", 0))`.
+
+A now-bearing argument that is omitted defaults to now, which makes the call
+`dynamic`: the year of `PERIOD_AT` and the anchor of `RELATIVE_PERIOD` both
+behave that way.
+
+The table that drives all of this is exported as
+`DATE_PRESET_CLASSIFICATION_SLOTS`, one row per function, in
+`src/date-presets/date-preset-classification.ts`.
 
 ## Resolution Context
 
@@ -99,6 +138,7 @@ QDP functions can receive `FormulaContext` with date preset configuration:
         fiscalYearStartDay: 1,
         weekStartsOn: 0,
         applyTimezoneToExpression: "default",
+        columnValues: { shipping_date: "2026-03-14T09:20:00.000Z" },
     },
 }
 ```
@@ -107,7 +147,7 @@ Current defaults:
 
 | Option                        | Default     | Notes                                                                                                        |
 | ----------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------ |
-| `timezone.offset`             | `+00:00`    | Supports `default`, `browser`, or custom offsets such as `UTC-5`, `-05:00`, `+5:30`                          |
+| `timezone.offset`             | `+00:00`    | Supports `default`, `browser`, or custom offsets such as `UTC-5`, `-05:00`, `+5:30`. Valid range is `-12:00` to `+14:00`; offsets outside it fall back to `+00:00` |
 | `timezone.timeZone`           | none        | Optional IANA time zone identifier such as `America/Bogota`; when present it is used for calendar resolution |
 | `calendar`                    | `gregorian` | Also supports `corporate-fiscal`, `retail-4-4-5`, `retail-4-5-4`                                             |
 | `locale`                      | `en-US`     | Used by formatting options                                                                                   |
@@ -115,9 +155,12 @@ Current defaults:
 | `fiscalYearStartDay`          | `1`         | Clamped to 1-31 and adjusted to the last valid day of the month                                              |
 | `weekStartsOn`                | `0`         | Sunday. Accepts 0-6 or English weekday names                                                                 |
 | `applyTimezoneToExpression`   | `default`   | Controls the timezone format used in the returned public `expression` value                                  |
+| `columnValues`                | `{}`        | The value of each column for the row being resolved, keyed by column id. Read by `FIELD`                     |
 
 Use `timezone.timeZone` for IANA identifiers. Use `timezone.offset` for admin/default/browser/custom offset values such as `{ offset: "default" }`, `{ offset: "browser" }`, or `{ offset: "-05:00" }`.
 
+Custom offsets accept the full UTC range `-12:00` to `+14:00`, including fractional offsets such as `+05:30` (India), `+05:45` (Nepal), or `-09:30` (Marquesas). Any minute value `00`-`59` is accepted; offsets outside the valid range fall back to `+00:00`.
+
 ### Expression timezone output
 
 Date preset resolution always calculates concrete instants internally. The `datePreset.applyTimezoneToExpression` option controls only the public `expression` format returned by `TranspileDatePreset`.
@@ -174,7 +217,7 @@ NOW();
 
 Output: `date`.
 
-Value type when used as the final result: `fixed`.
+Value type when used as the final result: `explicit`, `dynamic`.
 
 ### `TODAY()`
 
@@ -187,7 +230,7 @@ TODAY();
 
 Output: `date`.
 
-Value type when used as the final result: `fixed`.
+Value type when used as the final result: `explicit`, `dynamic`.
 
 ### `DATE(value)`
 
@@ -221,7 +264,7 @@ Rules:
 
 Output: `date`.
 
-Value type: `fixed`.
+Value type: `explicit`, `static`.
 
 ### `DATE_RANGE(start, end)`
 
@@ -246,7 +289,7 @@ Rules:
 
 Output: `dateRange`.
 
-Value type: `fixed`.
+Value type: `explicit`. Temporality is derived from `START` and `END`.
 
 ### `RELATIVE_PERIOD(offset, unit, anchor?)`
 
@@ -280,7 +323,61 @@ RELATIVE_PERIOD(-2, "WEEK", DATE("2026-07-08T15:30"));
 
 Output: `dateRange`.
 
-Value type: `rolling`.
+Value type: `rolling`. Temporality is derived from the anchor, and is `dynamic`
+when the anchor is omitted.
+
+### `OFFSET(point, offset, unit, mode?)`
+
+Shifts a single instant, keeping its time of day.
+
+```ts
+// Reference date 2026-07-22.
+OFFSET(TODAY(), -7, "DAY");
+// 2026-07-15T00:00:00.000Z
+
+OFFSET(DATE("2026-07-15T14:35:27"), 1, "MONTH");
+// 2026-08-15T14:35:27.000Z
+
+OFFSET(DATE("2025-01-31"), 1, "MONTH");
+// 2025-02-28T00:00:00.000Z -- clamped, February has no 31st
+```
+
+Parameters:
+
+| Parameter | Type             | Required | Notes                                     |
+| --------- | ---------------- | -------- | ----------------------------------------- |
+| `POINT`   | `date`           | Yes      | A single instant, not a range             |
+| `OFFSET`  | Integer `number` | Yes      | Negative, zero, or positive               |
+| `UNIT`    | `string`         | Yes      | `DAY`, `WEEK`, `MONTH`, `QUARTER`, `YEAR` |
+| `OVERFLOW_MODE` | `string`   | No       | `CLAMP` (default) or `OVERFLOW`           |
+
+Rules:
+
+-   `POINT` must be a `date`. A `dateRange` is rejected rather than silently
+    reduced to one of its edges — `START_OF` and `END_OF` exist so the author
+    says which edge is meant.
+-   The shift is on the local wall clock of the resolution timezone, so a day
+    is a calendar day rather than 24 hours.
+-   **`OVERFLOW_MODE` decides what happens when a shift by whole months lands on a day
+    the target month does not have.** `CLAMP`, the default, pins it to the last
+    day that exists: `OFFSET(DATE("2025-01-31"), 1, "MONTH")` is `2025-02-28`.
+    `OVERFLOW` lets it spill: the same call with `"OVERFLOW"` is `2025-03-03`.
+    `OVERFLOW_MODE` has no effect on `DAY` or `WEEK`, which cannot overflow a month.
+-   `OVERFLOW` is the spelling that reproduces `RELATIVE_PERIOD`, which has no
+    mode of its own and always spills. That divergence is deliberate: the
+    default should be the answer a reader expects, and the other one stays
+    reachable by name.
+-   Clamping is not reversible. `OFFSET(OFFSET(DATE("2025-01-31"), 1, "MONTH"), -1, "MONTH")`
+    is `2025-01-28`, not `2025-01-31`; once a day is clamped away it is gone.
+-   Under a timezone the instant is rebuilt from its wall-clock parts, which
+    does not carry milliseconds. In UTC they survive.
+
+Output: `date`.
+
+Value type: `rolling`, always. A shift from an anchor is rolling whether or not
+the anchor itself moves, so it is never delegated to `POINT`. Temporality is
+derived from `POINT`: `OFFSET(TODAY(), -7, "DAY")` is `dynamic`,
+`OFFSET(DATE("2026-01-01"), -7, "DAY")` is `static`.
 
 ### `CALENDAR_PERIOD(period, offset?)`
 
@@ -317,7 +414,47 @@ CALENDAR_PERIOD("QUARTER", -1);
 
 Output: `dateRange`.
 
-Value type: `relative`.
+Value type: `aligned`, `dynamic`.
+
+### `TO_DATE(unit)`
+
+The elapsed part of the current period: from the start of the `UNIT` containing
+today, to the end of today.
+
+```ts
+// Reference date 2026-07-22.
+TO_DATE("MONTH");
+// 2026-07-01T00:00:00.000Z -> 2026-07-22T23:59:59.999Z
+
+TO_DATE("YEAR");
+// 2026-01-01T00:00:00.000Z -> 2026-07-22T23:59:59.999Z
+```
+
+Parameter:
+
+| Parameter          | Type      | Required | Notes                              |
+| ------------------ | --------- | -------- | ---------------------------------- |
+| `UNIT`             | `string`  | Yes      | `WEEK`, `MONTH`, `QUARTER`, `YEAR` |
+| `ANCHOR_INCLUSIVE` | `boolean` | No       | `true` by default                  |
+
+Rules:
+
+-   The range **covers today in full** by default. Ending it at `TODAY()` would
+    admit a single instant, `00:00:00.000`, and drop every row stamped later.
+-   `ANCHOR_INCLUSIVE: false` stops the range at the end of yesterday, so today
+    is left out entirely: `TO_DATE("MONTH", false)` at reference date
+    2026-07-22 is `2026-07-01T00:00:00.000Z -> 2026-07-21T23:59:59.999Z`.
+-   The start is the one `CALENDAR_PERIOD` produces for the same unit, so the
+    calendar, timezone, `weekStartsOn` and `fiscalYearStartMonth` of the
+    resolution context all apply. Under `corporate-fiscal` with
+    `fiscalYearStartMonth: 4`, `TO_DATE("YEAR")` starts on 1 April.
+-   `DAY` is not accepted. `TO_DATE("DAY")` would be the whole of today, which
+    `CALENDAR_PERIOD("DAY", 0)` already spells.
+
+Output: `dateRange`.
+
+Value type: `aligned`, always `dynamic`. Both endpoints are read from the clock,
+so there is no argument for the temporality to be derived from.
 
 ### `PERIOD_AT(period, position, year?)`
 
@@ -358,7 +495,8 @@ Week rules:
 
 Output: `dateRange`.
 
-Current value type: `relative`.
+Value type: `aligned`. Temporality is derived from `YEAR`, and is `dynamic` when
+`YEAR` is omitted, because it then defaults to the current year.
 
 ### `PARTIAL_DATE(year?, month?, quarter?, week?, day?)`
 
@@ -407,15 +545,27 @@ PARTIAL_DATE("ANY", "ANY", "ANY", "ANY", 15);
 // Short format: Day 15
 ```
 
-Value type:
+A pattern that no date could satisfy is rejected where it is written, rather
+than resolving and then matching nothing:
+
+-   The month must fall inside the quarter. `PARTIAL_DATE("ANY", 5, 3)` — May in
+    Q3 — is an error.
+-   The day must exist in the month. `PARTIAL_DATE("ANY", 2, "ANY", "ANY", 30)`
+    is an error, and so is `PARTIAL_DATE(2026, 2, "ANY", "ANY", 29)`, since 2026
+    is not a leap year. Without a year, 29 February is accepted: the pattern
+    matches any year, and leap years exist.
+
+A quarter and a day never contradict, because every quarter contains a 31-day
+month, and a week can fall in any month. Neither pair is checked.
 
--   `fixed` if it includes `year`, `month`, and `day`, without `week`.
--   `relative` if it includes `week`.
--   `recurring` for all other partial dates.
+Value type, always with temporality `timeless`:
 
-### `START_OF(value)`
+-   `explicit` if it includes `year`, `month`, and `day`, without `week`.
+-   `recurring` for every other partial date, `week` included.
 
-Returns the start of a `date` or the `start` of a `dateRange`.
+### `START_OF(value, unit?)`
+
+Returns the start of `VALUE`, or the start of the `UNIT` period containing it.
 
 ```ts
 START_OF(DATE("2026-07-08T15:30"));
@@ -423,21 +573,45 @@ START_OF(DATE("2026-07-08T15:30"));
 
 START_OF(CALENDAR_PERIOD("MONTH", -1));
 // 2026-06-01T00:00:00.000Z
+
+START_OF(DATE("2026-07-15T14:35:27"), "QUARTER");
+// 2026-07-01T00:00:00.000Z
 ```
 
-Parameter:
+Parameters:
+
+| Parameter | Type                  | Required |
+| --------- | --------------------- | -------- |
+| `VALUE`   | `date` or `dateRange` | Yes      |
+| `UNIT`    | `string`              | No       |
 
-| Parameter | Type                  |
-| --------- | --------------------- |
-| `VALUE`   | `date` or `dateRange` |
+`UNIT` accepts `DAY`, `WEEK`, `MONTH`, `QUARTER` and `YEAR`.
+
+Rules:
+
+-   Without `UNIT`, a `dateRange` yields its own `start` verbatim and a `date`
+    yields the start of its day.
+-   **Omitting `UNIT` is not the same as passing `"DAY"`.** On a `dateRange` the
+    bare call preserves the endpoint, while `"DAY"` imposes a day boundary:
+    `START_OF(DATE_RANGE(DATE("2026-07-08T15:30"), DATE("2026-07-25T09:00")))` is
+    `2026-07-08T15:30:00.000Z`, and the same call with `"DAY"` is
+    `2026-07-08T00:00:00.000Z`.
+-   With `UNIT`, a `dateRange` contributes its `start` and the boundary is
+    computed from there.
+-   The boundary is the one `CALENDAR_PERIOD` would produce for the same unit,
+    so it follows the timezone, calendar, `weekStartsOn` and
+    `fiscalYearStartMonth` of the resolution context. Under a timezone the snap
+    is to the local boundary: `START_OF(DATE("2026-07-01T02:00"), "MONTH")` at
+    `-05:00` lands in **June**, because `02:00Z` is 21:00 on 30 June locally.
 
 Output: `date`.
 
-Value type when used as root: `relative`.
+Value type: delegated to `VALUE`, with or without `UNIT`. Temporality is derived
+from `VALUE`.
 
-### `END_OF(value)`
+### `END_OF(value, unit?)`
 
-Returns the end of a `date` or the `end` of a `dateRange`.
+Returns the end of `VALUE`, or the end of the `UNIT` period containing it.
 
 ```ts
 END_OF(DATE("2026-07-08T15:30"));
@@ -445,17 +619,159 @@ END_OF(DATE("2026-07-08T15:30"));
 
 END_OF(CALENDAR_PERIOD("YEAR", -1));
 // 2025-12-31T23:59:59.999Z
+
+END_OF(DATE("2026-07-15T14:35:27"), "QUARTER");
+// 2026-09-30T23:59:59.999Z
+```
+
+Parameters:
+
+| Parameter | Type                  | Required |
+| --------- | --------------------- | -------- |
+| `VALUE`   | `date` or `dateRange` | Yes      |
+| `UNIT`    | `string`              | No       |
+
+`UNIT` accepts `DAY`, `WEEK`, `MONTH`, `QUARTER` and `YEAR`.
+
+The rules mirror `START_OF`, measured from the other edge: without `UNIT` a
+`dateRange` yields its own `end` verbatim, and with `UNIT` the boundary is
+computed from that `end`.
+
+Output: `date`.
+
+Value type: delegated to `VALUE`, with or without `UNIT`. Temporality is derived
+from `VALUE`.
+
+### `SAME_PERIOD(reference, offset, unit, mode?)`
+
+Shifts a range, keeping its calendar shape.
+
+```ts
+SAME_PERIOD(PERIOD_AT("QUARTER", 1, 2026), -1, "YEAR");
+// Q1 2025: 2025-01-01T00:00:00.000Z -> 2025-03-31T23:59:59.999Z
+
+SAME_PERIOD(PERIOD_AT("MONTH", 2, 2026), 1, "MONTH");
+// all of March, not the first 28 days of it
+```
+
+Parameters:
+
+| Parameter   | Type             | Required | Notes                                     |
+| ----------- | ---------------- | -------- | ----------------------------------------- |
+| `REFERENCE` | `dateRange`      | Yes      | A range, not a single date                |
+| `OFFSET`    | Integer `number` | Yes      | Negative, zero, or positive               |
+| `UNIT`      | `string`         | Yes      | `DAY`, `WEEK`, `MONTH`, `QUARTER`, `YEAR` |
+| `OVERFLOW_MODE` | `string`     | No       | `CLAMP` (default) or `OVERFLOW`           |
+
+Rules:
+
+-   The end is shifted as an **exclusive** boundary, one millisecond past the
+    inclusive end. That is what makes a whole period stay a whole period:
+    February plus one month is all of March, not its first 28 days.
+-   `UNIT` is the unit of the shift and is independent of the shape of
+    `REFERENCE`. A quarter can be shifted by a year.
+-   `OVERFLOW_MODE` behaves as it does on `OFFSET`.
+-   **Clamping can pull both shifted edges onto the same day.** 29 and 30
+    January both clamp onto 28 February. When the shifted end lands at or
+    before the shifted start, the result is the whole of the shifted start's
+    day, rather than a range whose end precedes its start or a range of zero
+    width. Under `OVERFLOW` the edges stay apart and no collapse happens.
+-   Clamping loses span, and the collapse only recovers the degenerate case. A
+    26-hour reference whose edges both clamp into the same month comes back
+    shorter: `SAME_PERIOD(DATE_RANGE(DATE("2026-01-29T08:00"), DATE("2026-01-30T10:00")), 1, "MONTH")`
+    is two hours on 28 February. Use `OVERFLOW` when the span matters more than
+    the day-of-month.
+
+Output: `dateRange`.
+
+Value type: delegated to `REFERENCE`. Temporality is derived from `REFERENCE`.
+
+### `PRIOR_PERIOD(reference, unit?)`
+
+The period immediately before `REFERENCE`, in one of two readings.
+
+```ts
+// Reference date 2026-07-22.
+PRIOR_PERIOD(RELATIVE_PERIOD(-44, "DAY"));
+// the 45 days before the reference 45:
+// 2026-04-24T00:00:00.000Z -> 2026-06-07T23:59:59.999Z
+
+PRIOR_PERIOD(CALENDAR_PERIOD("MONTH", 0), "MONTH");
+// the whole of June: 2026-06-01T00:00:00.000Z -> 2026-06-30T23:59:59.999Z
+```
+
+Parameters:
+
+| Parameter       | Type        | Required | Notes                           |
+| --------------- | ----------- | -------- | ------------------------------- |
+| `REFERENCE`     | `dateRange` | Yes      | A range, not a single date      |
+| `OVERFLOW_MODE` | `string`    | No       | `CLAMP` (default) or `OVERFLOW` |
+
+Rules:
+
+-   **It shifts by the calendar unit the reference was built from**, read off
+    the expression rather than the resolved value:
+    `PRIOR_PERIOD(PERIOD_AT("MONTH", 2, 2026))` is January 2026 — the whole
+    month — not the 28 days before February.
+-   The unit is taken from `CALENDAR_PERIOD`'s `PERIOD` and `PERIOD_AT`'s
+    `PERIOD`. It cannot be taken from the value: 
+    `DATE_RANGE(DATE("2026-07-01"), END_OF(DATE("2026-07-31")))` and
+    `CALENDAR_PERIOD("MONTH", 0)` are byte-identical in July 2026, and the two
+    deliberately answer differently.
+-   **A reference with no calendar unit behind it** — a `RELATIVE_PERIOD`, a
+    literal `DATE_RANGE`, anything composed — gets the immediately preceding
+    window of the same duration, abutting to the millisecond. That is the
+    epic's "mechanical comparison, independent of alignment":
+    `PRIOR_PERIOD(RELATIVE_PERIOD(-44, "DAY"))` is the 45 days before the
+    reference 45.
+-   The calendar reading follows the calendar, timezone, `weekStartsOn` and
+    `fiscalYearStartMonth` of the resolution context.
+-   `OVERFLOW_MODE` is accepted for symmetry with `OFFSET` and `SAME_PERIOD`
+    but currently reaches no arithmetic that can overflow — see
+    `docs/TECH-DEBT.md`.
+
+Output: `dateRange`.
+
+Value type: delegated to `REFERENCE`. Temporality is derived from `REFERENCE`.
+
+### `FIELD(column)`
+
+Resolves a dataset column to the date it holds for the row being resolved.
+
+```ts
+FIELD([shipping_date]);
+// with columnValues: { shipping_date: "2026-03-14T09:20:00.000Z" }
+// 2026-03-14T09:20:00.000Z
+
+START_OF(FIELD([shipping_date]), "MONTH");
+// 2026-03-01T00:00:00.000Z
 ```
 
 Parameter:
 
-| Parameter | Type                  |
-| --------- | --------------------- |
-| `VALUE`   | `date` or `dateRange` |
+| Parameter | Type     | Required | Notes                       |
+| --------- | -------- | -------- | --------------------------- |
+| `COLUMN`  | a column | Yes      | `[column]`, not a string    |
+
+Rules:
+
+-   The argument **must be a column node**. `FIELD(TODAY())` and
+    `FIELD("2026-01-01")` are rejected. Using `[column]` rather than a string
+    keeps the dependency visible to the editor, which reads it off the parsed
+    expression.
+-   The value comes from `datePreset.columnValues`, keyed by column id. Three
+    distinct failures, each with its own error: the argument is not a column, no
+    value was supplied (`MISSING_COLUMN_VALUE`), or the value is not a date
+    (`INVALID_COLUMN_VALUE`).
+-   **A bare `[column]` is not a date preset.** It used to resolve to the
+    column's own name in the date slot, marked valid, and `START_OF([column])`
+    threw a `RangeError` out of the public API. `FIELD([column])` is the one
+    sanctioned spelling.
 
 Output: `date`.
 
-Value type when used as root: `relative`.
+Value type: `dataBound`, always `dynamic`. It moves with the data rather than
+with the clock, and nothing in the expression can make it static.
 
 ### `PART(date, part)`
 
@@ -463,7 +779,10 @@ Extracts one part of a date.
 
 ```ts
 PART(DATE("2026-07-08T15:30"), "DAY_OF_WEEK_NAME");
-// Wednesday
+// 3 — the weekday ordinal, tagged as a weekday name
+
+FORMAT(PART(DATE("2026-07-08T15:30"), "DAY_OF_WEEK_NAME"));
+// "Wednesday"
 ```
 
 Parameters:
@@ -475,31 +794,230 @@ Parameters:
 
 Supported parts:
 
+Every part is read from the date **as it falls in the resolution timezone**, so
+a part never disagrees with the calendar day the rest of the engine resolved.
+`PART(DATE("2026-08-01T02:00"), "MONTH")` is `8` in UTC and `7` under
+`America/Bogota`, where that instant is 21:00 on 31 July.
+
 | Value              | Output                                   |
 | ------------------ | ---------------------------------------- |
-| `YEAR`             | UTC year                                 |
+| `YEAR`             | Year                                     |
 | `QUARTER`          | Quarter 1-4                              |
 | `MONTH`            | Month 1-12                               |
-| `MONTH_NAME`       | English month name                       |
+| `MONTH_NAME`       | Month 1-12, tagged as a month name       |
 | `DAY`              | Day of month                             |
 | `DAY_OF_MONTH`     | Day of month                             |
-| `DAY_OF_WEEK`      | UTC weekday, Sunday = 0                  |
-| `DAY_OF_WEEK_NAME` | English weekday name                     |
+| `DAY_OF_WEEK`      | Weekday, Sunday = 0                      |
+| `DAY_OF_WEEK_NAME` | Weekday 0-6, tagged as a weekday name    |
 | `DAY_OF_YEAR`      | Day of year                              |
 | `WEEK_OF_YEAR`     | Week according to the current convention |
-| `HOUR`             | UTC hour                                 |
-| `MINUTE`           | UTC minute                               |
-| `SECOND`           | UTC second                               |
+| `HOUR`             | Hour                                     |
+| `MINUTE`           | Minute                                   |
+| `SECOND`           | Second                                   |
+
+`WEEK_OF_YEAR` is the only part that also consults `weekStartsOn`; the weekday
+ordinal is always Sunday-based.
+
+**`PART` extracts and never localizes.** Every part returns a number, including
+the two `_NAME` values: `MONTH_NAME` is the month number and `DAY_OF_WEEK_NAME`
+the weekday ordinal. They exist so a result can record *what kind* of number it
+is — rendering "September" or "Montag" is a presentation concern and belongs to
+`FORMAT`, which is the one place locale is read.
+
+Because a part is a number, it can fill a numeric argument and take part in
+arithmetic: `PERIOD_AT("MONTH", 4, PART(TODAY(), "YEAR") - 1)` is April of last
+year.
+
+`PART` is a valid final result. It resolves to a **scalar**:
+
+```ts
+type ScalarValue = {
+    value: number | string;
+    sourcePart: DatePresetSourcePart | null;
+};
+```
+
+`sourcePart` records which part the number came from, so a formatter can tell a
+month from a weekday. `PART(TODAY(), "MONTH")` is
+`{ value: 7, sourcePart: "MONTH" }`, and `PART(TODAY(), "MONTH_NAME")` is the
+same number under a different tag — which is the only difference between the
+two, and the whole reason both still exist.
+
+**Arithmetic clears the tag.** `PART(TODAY(), "YEAR") - 1` is
+`{ value: 2025, sourcePart: null }`: once a part has been computed with, there
+is no honest way to say what it means any more. Nine is a month; eighteen is
+not, and the engine cannot tell where it stopped being one.
+
+Both facts are recorded on the node, by the parser, and not recomputed by
+walking the tree. A node carries `dateScalar` when a date produced its value,
+and `dateScalar.sourcePart` names the part it still is; arithmetic keeps the
+first and nulls the second. That is why `1 + 2` is refused while
+`PART(TODAY(), "YEAR") - 1` resolves — the primitive is `number` for both, and
+provenance is the only thing that separates them. The field is declared on its
+own interface, `DateScalarProvenance`, which `CommonAST` extends, and a function
+opts in with `datePresetScalar` and `datePresetSourcePart` on its definition.
+
+A number is a result only when a date produced it. `PART(TODAY(), "YEAR") - 1`
+resolves; `1 + 2` does not, and neither does a bare `5`. The difference is
+provenance, not type.
+
+The response reports `primitive: "dateScalar"` for one. That field answers
+*what shape is `expression`*, and a scalar is a record — reporting `number`
+would describe something the caller never receives.
+
+Inside the expression tree a part is still a number and a rendered value is
+still a string, which is what decides that `PART(TODAY(), "MONTH") + 1` is
+arithmetic while `"texto" + 1` is not, and what lets a part fill a numeric
+argument. That distinction is internal; it does not reach the response.
+
+A scalar's `value` may therefore be a number or a string.
+`FunctionDefinition.primitiveResult` accepts a callable, so a function whose
+result type depends on its arguments computes it per call rather than declaring
+one type and returning another.
+
+Use `isScalarValue` to narrow a `DatePresetValue`; `isDateRangeValue` is
+exported alongside it.
+
+### `FORMAT(value, style?)`
+
+Renders a resolved value for a viewer. It is the one function in the language
+that reads `locale`, and the only way to turn a name tag into a word.
+
+```ts
+FORMAT(TODAY());
+// "Jul 22, 2026"
+
+FORMAT(CALENDAR_PERIOD("MONTH", 0));
+// "Jul 1, 2026 – Jul 31, 2026"
+
+FORMAT(PART(TODAY(), "MONTH"), "full");
+// "July" — and "Julio" or "Juli" for another viewer
+
+FORMAT(PART(NOW(), "HOUR"), "00");
+// "14"
+```
+
+Parameters:
+
+| Parameter | Type                                     | Values                     |
+| --------- | ---------------------------------------- | -------------------------- |
+| `VALUE`   | `date`, `dateRange`, `partialDate`, part | What there is to render    |
+| `STYLE`   | `string`, optional                       | Depends on the value below |
+
+**The style is written, never computed.** It has to be a string literal in the
+formula. A computed style makes validity move with the clock: the inner render
+of `FORMAT(TODAY(), FORMAT(PART(NOW(), "HOUR"), "00"))` spells a valid pattern
+only while the hour is under ten, so the same formula would be accepted in the
+morning and rejected in the afternoon.
+
+**The style has to belong to the shape being rendered.** An unsupported
+combination is `INVALID_ALLOW_VALUE`, never a silent fallback — a permissive
+renderer answers `"0909"` to `FORMAT(TODAY(), "MMMM")`, which is the CLDR
+spelling a user reaches for to get a month name.
+
+For a `date` or a `dateRange`:
+
+| Style                                             | Renders                          |
+| ------------------------------------------------- | -------------------------------- |
+| omitted                                           | Locale medium                    |
+| `full`, `long`, `medium`, `short`, `short-padded` | The corresponding `dateStyle`    |
+| A token pattern                                   | `yyyy-MM-dd`, `dd/MM/yyyy HH:mm` |
+
+A token pattern is read run by run, and every run of a letter has to be a
+supported token: `yyyy`, `yy`, `MM`, `M`, `dd`, `d`, `HH`, `H`, `mm`, `m`, `ss`,
+`s`. So `MMMM` is a run of four `M`s and is rejected rather than read as two
+month numbers, and `yyyyy` is not `yyyy` followed by `y`.
+
+**A date carries a time only when it has one.** `FORMAT(TODAY())` is
+`"Jul 22, 2026"` and `FORMAT(NOW())` is `"Jul 22, 2026, 2:35 PM"`; the value
+decides, read in the timezone it will be rendered in, so `FORMAT(END_OF(TODAY()))`
+still shows `11:59 PM`. A range takes the decision from its start, because an
+endpoint that lands on 23:59:59.999 is a boundary and not a time anyone asked
+to see. `FormatDatePreset` is unchanged: its default still includes the time.
+
+For a `partialDate`, the vocabulary is `long` and `short`. A partial date has no
+instant, so a token pattern has nothing to read.
+
+For a **scalar**, the style depends on the part the number came from — this is
+QRV-1069 §5.7, and it is why `PART` carries a tag at all:
+
+| Scalar source                                                                              | Pattern (`00`) | Name (`full`, `short`) | Omitted   |
+| ------------------------------------------------------------------------------------------ | -------------- | ---------------------- | --------- |
+| Numeric part with a name mapping — `MONTH`, `DAY_OF_WEEK`                                   | yes            | yes                    | the digit |
+| Numeric part with no name mapping — `YEAR`, `QUARTER`, `DAY`, `DAY_OF_MONTH`, `DAY_OF_YEAR`, `WEEK_OF_YEAR`, `HOUR`, `MINUTE`, `SECOND` | yes | rejected | the digit |
+| Name part — `MONTH_NAME`, `DAY_OF_WEEK_NAME`                                                | rejected       | yes                    | the name  |
+| `TIMEZONE()` / `CONTEXT(property)` — neither exists yet                                     | rejected       | rejected               | —         |
+
+A scalar pattern is a run of one to four zeros and means the width to pad to:
+`FORMAT(PART(TODAY(), "MONTH"), "00")` is `"07"`.
+
+**A scalar has to still carry its tag.** `FORMAT(PART(TODAY(), "YEAR") - 1)` is
+rejected: arithmetic clears the tag, and a formatter must not guess it back. So
+is `FORMAT(FORMAT(x))`, since a rendered value has nothing left to render.
 
-Important: `PART` is available as a QDP function, but it is not a valid final result for `TranspileDatePreset` because it returns `string`. It can be used as a helper function when accessing the QDP transpiler directly, but a final date preset expression must return `date`, `dateRange`, or `partialDate`.
+A malformed `locale` in the resolution context is `UNRENDERABLE_VALUE` rather
+than a `RangeError` out of the public API.
+
+Output: `dateScalar`, always with `sourcePart: null`.
+
+Value type: `scalar`. Temporality follows the value it rendered — `FORMAT(TODAY())`
+is `dynamic`, `FORMAT(DATE("2026-07-08"))` is `static`. Presentation is not an
+axis of the classification: the same formula classifies identically for every
+viewer, and only its value differs.
+
+`FORMAT` has no case in `TranspileJSONToDatePreset`, on the same reading that
+gives `PART` and `FIELD` none: the picker constructs date preset nodes, and
+these three are read out of one.
+
+## Calendar-part matching
+
+A field can be matched against a `partialDate` pattern regardless of year — "all
+orders shipped in September", "orders placed on a Monday". QRV-1069 defines that
+as a **filter operator**, not an expression-language function, so there is no
+`MATCHES(...)` to call. What this library ships is the engine behind it:
+
+```ts
+DatePresetMatches(value: string | Date, pattern, context?): boolean
+PartialDateToRanges(pattern: PartialDateValue, horizon: DateRangeValue, context?): DateRangeValue[]
+```
+
+`DatePresetMatches` takes a `partialDate` or a `dateRange`. A range is an
+instant comparison, inclusive at both ends. A partial date is a **conjunction**:
+every stated part must match, an omitted part matches anything.
+
+```ts
+DatePresetMatches("2026-09-14T00:00:00.000Z", { month: 9 });          // true
+DatePresetMatches("2026-09-15T00:00:00.000Z", { month: 9, day: 14 }); // false
+```
+
+Three things worth knowing, all consequences of matching through `PART`:
+
+-   It resolves in the context timezone. `2026-08-01T02:00Z` matches
+    `{ month: 7 }` under `America/Bogota`, where that instant is 31 July.
+-   The week follows `weekStartsOn` and is **not ISO-8601**. The same date is
+    week 30 with Sunday weeks and week 29 with Monday weeks.
+-   The quarter is **Gregorian**, even under a fiscal calendar. Extraction is
+    Gregorian, and a fiscal quarter is a different question from a calendar one.
+
+`PartialDateToRanges` expands a pattern into the concrete ranges it covers
+inside a horizon, so a future SQL emission can be
+`col BETWEEN … OR col BETWEEN …` rather than per-engine `EXTRACT`. The
+boundaries are computed once, by the same code that answers
+`DatePresetMatches`, which is what keeps the two in agreement: PostgreSQL's
+`EXTRACT(WEEK …)` is ISO-only, and `DAYOFWEEK` ships with five different bases
+across the engines. Its cost is linear in the days of the horizon.
 
 ## Differences Between Period Functions
 
-| Function          | Question it answers                          | Example                       | Type               |
-| ----------------- | -------------------------------------------- | ----------------------------- | ------------------ |
-| `CALENDAR_PERIOD` | What is this/previous/next calendar period?  | This month, last week         | `relative`         |
-| `PERIOD_AT`       | What is period N inside a year?              | April 2026, Q2 2026, W40 2026 | Current `relative` |
-| `RELATIVE_PERIOD` | What is the moving window from today/anchor? | Last 30 days                  | `rolling`          |
+| Function          | Question it answers                          | Example                       | Type      |
+| ----------------- | -------------------------------------------- | ----------------------------- | --------- |
+| `CALENDAR_PERIOD` | What is this/previous/next calendar period?  | This month, last week         | `aligned` |
+| `TO_DATE`         | How much of the current period has elapsed?  | Month to date, year to date   | `aligned` |
+| `PERIOD_AT`       | What is period N inside a year?              | April 2026, Q2 2026, W40 2026 | `aligned` |
+| `RELATIVE_PERIOD` | What is the moving window from today/anchor? | Last 30 days                  | `rolling` |
+| `OFFSET`          | What is the single instant N units away?     | 7 days ago, tomorrow          | `rolling` |
+| `SAME_PERIOD`     | What is this range, N units away?            | The same quarter a year back  | delegated |
+| `PRIOR_PERIOD`    | What came immediately before this range?     | The previous 45 days          | delegated |
 
 Examples with current date `2026-07-22`:
 
@@ -530,9 +1048,11 @@ It is not recommended to merge them into a single public function because they e
 { type: "PARTIAL_DATE", value: { year?, quarter?, month?, week?, day? } }
 { type: "RELATIVE_PERIOD", offset: -30, unit: "DAY", anchor?: DatePresetJSON }
 { type: "CALENDAR_PERIOD", period: "MONTH", offset?: 0 }
+{ type: "TO_DATE", unit: "MONTH" }
 { type: "PERIOD_AT", period: "MONTH", position: 4 | "FIRST" | "LAST", year?: 2026 }
-{ type: "START_OF", input: DatePresetJSON }
-{ type: "END_OF", input: DatePresetJSON }
+{ type: "OFFSET", point: DatePresetJSON, offset: -7, unit: "DAY", overflowMode?: "CLAMP" }
+{ type: "START_OF", input: DatePresetJSON, unit?: "MONTH" }
+{ type: "END_OF", input: DatePresetJSON, unit?: "MONTH" }
 ```
 
 Example:
@@ -574,6 +1094,12 @@ Rules:
 
 ## Formatting
 
+There are two doors into rendering, and they are not the same door.
+`FormatDatePreset` is a function a caller applies to a value it already has;
+`FORMAT` is a function the *formula* applies, so its result is the date preset
+and the style is persisted with the expression. Both read the same renderers in
+`src/utils/datePresetFormat.ts`; only `FORMAT` enforces §5.7.
+
 `FormatDatePreset` formats values using `Intl.DateTimeFormat`.
 
 By default, `date` and `dateRange` values include time using `timeStyle: "short"`. When `partialDateStyle: "short"` is used and no explicit `timeStyle` is provided, `date` and `dateRange` values omit time so they align with picker-style labels. Passing `timeStyle` explicitly keeps time in the output.
@@ -669,19 +1195,44 @@ FormatDatePreset(
 
 Legacy tokens are resolved with `TranspileJSONToDatePreset(token)` using `DATE_PRESET_TOKEN_MAP`.
 
+Five of these resolve to a **scalar** rather than a date: `CURRENT_DAY`,
+`CURRENT_DAY_OF_WEEK`, `CURRENT_DAY_OF_YEAR`, `CURRENT_MONTH_NAME` and
+`LAST_MONTH_NAME`. The two `_NAME` ones carry a number with a name tag, which
+`FORMAT` renders as a word. `CURRENT_TIMEZONE` is not here yet — it needs
+`TIMEZONE()`.
+
+`LAST_MONTH_NAME` wraps its period in `START_OF`. Without it, `PART` receives a
+`dateRange` where it validates a `date`, and the expression does not resolve.
+
+The token name is matched case-insensitively, and may be wrapped in `{{ }}`:
+`TODAY-7`, `today-7` and `{{ Today-7 }}` all resolve to the same expression. A
+name that is not a token returns `undefined` from `resolveDatePresetToken` and
+throws from `TranspileJSONToDatePreset`.
+
 | Token                         | QDP expression                                |
 | ----------------------------- | --------------------------------------------- |
 | `NOW`                         | `NOW()`                                       |
 | `TODAY`                       | `TODAY()`                                     |
 | `CURRENT_DATE`                | `TODAY()`                                     |
-| `TODAY-7`                     | `START_OF(RELATIVE_PERIOD(-7, "DAY"))`        |
-| `TODAY-30`                    | `START_OF(RELATIVE_PERIOD(-30, "DAY"))`       |
-| `TODAY-60`                    | `START_OF(RELATIVE_PERIOD(-60, "DAY"))`       |
-| `TODAY-90`                    | `START_OF(RELATIVE_PERIOD(-90, "DAY"))`       |
-| `TODAY-120`                   | `START_OF(RELATIVE_PERIOD(-120, "DAY"))`      |
-| `TODAY-365`                   | `START_OF(RELATIVE_PERIOD(-365, "DAY"))`      |
-| `YESTERDAY`                   | `START_OF(RELATIVE_PERIOD(-1, "DAY"))`        |
-| `TOMORROW`                    | `START_OF(END_OF(RELATIVE_PERIOD(1, "DAY")))` |
+| `CURRENT_TIME`                | `NOW()`                                       |
+| `CURRENT_DAY`                 | `PART(TODAY(), "DAY_OF_WEEK_NAME")`           |
+| `CURRENT_DAY_OF_WEEK`         | `PART(TODAY(), "DAY_OF_WEEK")`                |
+| `CURRENT_DAY_OF_YEAR`         | `PART(TODAY(), "DAY_OF_YEAR")`                |
+| `CURRENT_MONTH_NAME`          | `PART(TODAY(), "MONTH_NAME")`                 |
+| `LAST_MONTH_NAME`             | `PART(START_OF(CALENDAR_PERIOD("MONTH", -1)), "MONTH_NAME")` |
+| `TODAY-7`                     | `OFFSET(TODAY(), -7, "DAY")`                  |
+| `TODAY-30`                    | `OFFSET(TODAY(), -30, "DAY")`                 |
+| `TODAY-60`                    | `OFFSET(TODAY(), -60, "DAY")`                 |
+| `TODAY-90`                    | `OFFSET(TODAY(), -90, "DAY")`                 |
+| `TODAY-120`                   | `OFFSET(TODAY(), -120, "DAY")`                |
+| `TODAY-365`                   | `OFFSET(TODAY(), -365, "DAY")`                |
+| `YESTERDAY`                   | `OFFSET(TODAY(), -1, "DAY")`                  |
+| `LAST_7_DAYS`                 | `RELATIVE_PERIOD(-6, "DAY")`                  |
+| `LAST_30_DAYS`                | `RELATIVE_PERIOD(-29, "DAY")`                 |
+| `TOMORROW`                    | `OFFSET(TODAY(), 1, "DAY")`                   |
+| `MTD`                         | `TO_DATE("MONTH")`                            |
+| `QTD`                         | `TO_DATE("QUARTER")`                          |
+| `YTD`                         | `TO_DATE("YEAR")`                             |
 | `CURRENT_MONTH`               | `CALENDAR_PERIOD("MONTH", 0)`                 |
 | `CURRENT_MONTH_START`         | `START_OF(CALENDAR_PERIOD("MONTH", 0))`       |
 | `CURRENT_MONTH_END`           | `END_OF(CALENDAR_PERIOD("MONTH", 0))`         |
@@ -702,6 +1253,7 @@ Legacy tokens are resolved with `TranspileJSONToDatePreset(token)` using `DATE_P
 | `LAST_QUARTER_END`            | `END_OF(CALENDAR_PERIOD("QUARTER", -1))`      |
 | `CURRENT_YEAR`                | `CALENDAR_PERIOD("YEAR", 0)`                  |
 | `CURRENT_YEAR_START`          | `START_OF(CALENDAR_PERIOD("YEAR", 0))`        |
+| `CURRENT_YEAR_END`            | `END_OF(CALENDAR_PERIOD("YEAR", 0))`          |
 | `LAST_YEAR`                   | `CALENDAR_PERIOD("YEAR", -1)`                 |
 | `LAST_YEAR_START`             | `START_OF(CALENDAR_PERIOD("YEAR", -1))`       |
 | `LAST_YEAR_END`               | `END_OF(CALENDAR_PERIOD("YEAR", -1))`         |
@@ -710,18 +1262,20 @@ Legacy tokens are resolved with `TranspileJSONToDatePreset(token)` using `DATE_P
 
 Tokens can be wrapped like `{{TODAY-7}}`. The normalizer removes braces and outer spaces.
 
-Scalar tokens such as `CURRENT_TIME`, `CURRENT_TIMEZONE`, and `CURRENT_DAY_OF_WEEK` are not supported as date presets because they do not return `date`, `dateRange`, or `partialDate`.
+`CURRENT_TIMEZONE` is not supported yet: it needs `TIMEZONE()`, which reads a property of the resolution context rather than extracting one from a date.
 
 ## Main Equivalences With The Date Picker
 
 | Picker expression           | QDP expression                                               | Note                                               |
 | --------------------------- | ------------------------------------------------------------ | -------------------------------------------------- |
 | Today                       | `TODAY()`                                                    | Fixed date at the start of the current day         |
-| Yesterday                   | `START_OF(RELATIVE_PERIOD(-1, "DAY"))`                       | Start of yesterday                                 |
-| Tomorrow                    | `START_OF(END_OF(RELATIVE_PERIOD(1, "DAY")))`                | Start of tomorrow                                  |
+| Yesterday                   | `OFFSET(TODAY(), -1, "DAY")`                                 | Start of yesterday                                 |
+| Tomorrow                    | `OFFSET(TODAY(), 1, "DAY")`                                  | Start of tomorrow                                  |
 | This month                  | `CALENDAR_PERIOD("MONTH", 0)`                                | Current calendar month                             |
 | Previous month              | `CALENDAR_PERIOD("MONTH", -1)`                               | Previous calendar month                            |
+| Last 7 days inclusive       | `RELATIVE_PERIOD(-6, "DAY")`                                 | Inclusive 7-day rolling window counting today      |
 | Last 30 days inclusive      | `RELATIVE_PERIOD(-29, "DAY")`                                | Inclusive 30-day rolling window counting today     |
+| Month to date               | `TO_DATE("MONTH")`                                           | Start of the month to the end of today             |
 | April                       | `PARTIAL_DATE("ANY", 4)`                                     | Recurring month                                    |
 | April 2026                  | `PERIOD_AT("MONTH", 4, 2026)`                                | Positional month in a year                         |
 | Apr 15                      | `PARTIAL_DATE("ANY", 4, "ANY", "ANY", 15)`                   | Recurring month/day                                |
@@ -762,29 +1316,38 @@ DATE_RANGE(DATE("2026-07-31T00:00"), DATE("2026-07-01T00:00"));
 // INVALID_DATE_RANGE: end before start
 ```
 
-Additionally, any QDP expression whose final result is not `date`, `dateRange`, or `partialDate` returns `INVALID_DATE_PRESET_RESULT`.
+Additionally, any QDP expression whose final result is not `date`, `dateRange`,
+`partialDate`, or a scalar a date produced returns `INVALID_DATE_PRESET_RESULT`.
 
 ## Relevant Files
 
 | File                                          | Responsibility                                                          |
 | --------------------------------------------- | ----------------------------------------------------------------------- |
-| `src/date-presets/date-presets.ts`            | Public API, JSON conversion, formatting, and `valueType` classification |
+| `src/date-presets/date-presets.ts`            | Public API, JSON conversion, and the result guard                       |
+| `src/date-presets/date-preset-classification.ts` | The `valueType` / `temporality` slot map and classifier              |
 | `src/date-presets/date-preset-tokens.ts`      | Legacy token map to QDP expressions                                     |
 | `src/functions/index.ts`                      | Function registration for `ENGINES.QDP`                                 |
+| `src/utils/extractContextInfo.ts`             | Splits the appended resolution context off a transpiler's arguments     |
 | `src/utils/datePresetUtils.ts`                | Date, range, calendar, week, and partial date resolution                |
+| `src/utils/datePresetFormat.ts`               | Every renderer, and the only module that calls `Intl.DateTimeFormat`    |
+| `src/parser/formula-parser.ts`                | Stamps `isDateScalar` and `sourcePart` onto a call node                 |
+| `src/functions/format.ts`                     | `FORMAT`: the §5.7 validity table and the routing to a renderer         |
 | `src/utils/timezone.ts`                       | Timezone definition normalization and offset helpers                    |
 | `src/functions/*.ts`                          | Individual QDP function definitions                                     |
-| `__tests__/unit/datePresetTranspiler.test.ts` | Main transpilation and picker compatibility cases                       |
-| `__tests__/unit/datePresetJson.test.ts`       | JSON to QDP conversion                                                  |
-| `__tests__/unit/datePresetFormat.test.ts`     | Date and partial date formatting                                        |
+| `__tests__/unit/datePreset*.test.ts`          | Transpilation, classification, every function, tokens and JSON conversion   |
+| `__tests__/unit/extractContextInfo.test.ts`   | The context-info split and its registration guard                       |
+| `__tests__/unit/datePresetFormat.test.ts`     | `FormatDatePreset`: date and partial date formatting                    |
+| `__tests__/unit/datePresetFormatFunction.test.ts` | `FORMAT` in the language, and the §5.7 table cell by cell           |
 | `__tests__/unit/datePresetTokens.test.ts`     | Legacy tokens                                                           |
+| `__tests__/unit/datePresetCalendar.test.ts`   | Fiscal, retail and timezone calendar resolution                         |
+| `scripts/generate-date-preset-examples.js`    | Generator for the examples CSV                                          |
 | `date-preset-qdp-examples.csv`                | Generated examples with tokens and picker expressions                   |
 
 ## Current State And Design Notes
 
 -   QDP is limited to date preset functions in `ENGINE_FN_MAP[ENGINES.QDP]`.
--   Date preset expressions can be nested as long as the final result is `date`, `dateRange`, or `partialDate`.
+-   Date preset expressions can be nested as long as the final result is `date`, `dateRange`, `partialDate`, or a scalar read from a date.
 -   `partialDate` was added as a primitive to represent incomplete date picker selections.
 -   Week compatibility with the date picker uses Sunday as the default start day and supports W54.
 -   `PERIOD_AT` supports symbolic positions `FIRST` and `LAST` to reduce ambiguity in variable-length periods.
--   For documentation and example auditing, the CSV `date-preset-qdp-examples.csv` contains resolved, formatted, and classified values.
+-   For documentation and example auditing, the CSV `date-preset-qdp-examples.csv` contains resolved, formatted, and classified values. Regenerate it with `npm run examples:csv`; the reference date defaults to `2026-07-22`, matching this document. Note the unit tests pin a different instant (`2026-07-15T14:35:27.000Z`).