A dataset measure over a date field renders its raw ISO string — `formatMeasure` short-circuits before `format` is read

[os-warren]

Found by opening a dashboard in a real ObjectStack application (objectstack-ai/duly) against published @objectstack/* 17.2.0. Source-confirmed afterwards in this repo.

The claim

A min / max measure over a date or datetime field cannot be rendered as a date on any dataset-bound widget, and the format escape hatch the spec offers for exactly this is unreachable for those values.

The KPI tile renders 2026-07-04T07:00:00.000Z where a date belongs — a 24-character ISO string in text-2xl font-semibold, which wraps to two lines inside the card.

Where it comes from

packages/plugin-dashboard/src/DatasetWidget.tsx:768 renders the dataset-bound metric value:

<span className={cn('text-2xl font-semibold tabular-nums', accentClass)}>
  {formatMeasure(value, f?.format, f?.currency, f?.percentScale, displayLocale)}
</span>

and formatMeasure in packages/core/src/utils/dataset-format.ts opens with:

if (v == null) return '—';
if (typeof v !== 'number') return String(v);

That second line is before format is touched. So for any non-numeric measure value the function is String(v) and nothing else — the format argument the call site carefully threads through is dead on this path. tabular-nums on the span is the same assumption stated in CSS.

Everything downstream of that guard is a numeral-pattern formatter (decimals from format.split('.')[1], %, $, currency), which no date pattern can enter.

Why the escape hatch does not close it

DatasetMeasureSchema in @objectstack/spec carries format: z.ZodOptional<z.ZodString> — an open string, so authoring format: 'YYYY-MM-DD' (or anything else) passes validate and build cleanly. It then has no effect, because the value never reaches the branch that reads it. An author gets a green toolchain and an unchanged raw timestamp, with nothing anywhere saying why.

Reproduce

Declare a measure aggregating a date field and bind it to a type: 'metric' widget:

// dataset
{ name: 'oldest_touch', label: 'Oldest touch', aggregate: 'min', field: 'last_update_at' }

// dashboard widget
{ id: 'oldest', title: 'Oldest untouched task', type: 'metric',
  dataset: '<ds>', values: ['oldest_touch'] }

Open the dashboard. The tile shows the raw ISO string. Adding format: 'YYYY-MM-DD' to the measure changes nothing.

Scope beyond the metric tile

The same formatMeasure call is on three other surfaces, all with the same guard in front of them, so a date measure is raw in each: DatasetWidget.tsx:876 (chart value formatting), DatasetWidget.tsx:1083 (dataset table cells), and views/metadata-admin/previews/DatasetPreview.tsx:235. PivotTable.tsx:46 takes value: number outright.

Suggested direction

The narrow fix is to let formatMeasure recognise a date-shaped string (or a measure whose format names a date pattern) before the numeric short-circuit, and route it through the same date display path list cells already use — the argument for reusing that path rather than adding a second one is the same one the file's own header makes about percent, where two conventions drifted between a list cell and a dashboard measure (objectui#4576).

Whatever the resolution, the silence is the worse half: a format that the schema accepts and the renderer can never read is declared ≠ enforced. If dates are out of scope for measure formatting, the spec's format should say so and a date-typed aggregate should be refused at author time rather than rendered raw.

Application impact

Low severity — the number is correct and legible, just ugly. Reported because the silence is the reusable finding, not the wrapped timestamp.

[os-warren]

Triage — finding · needs-user-decision · domain:ui · priority:p3. Recommendation attached so it is a yes/no.

domain:ui seat (session session_012wwHa4aaFybxXrfmfHioDM). Found in a no:label sweep — this card was carrying no labels at all since filing, so nothing surfaced it (#7211).

Why not dispatched: the two directions are different products

The card's own framing:

The narrow fix is to let formatMeasure recognise a date-shaped string … If dates are out of scope for measure formatting, the spec's format should say so and a date-typed aggregate should be refused at author time rather than rendered raw.

⇒ Implementing date rendering and refusing date aggregates are not two routes to one outcome. If dates are out of scope, implementing rendering blesses a shape meant to be refused. ⛔ A dev must not pick by which is cheaper.

⚠️ I am being deliberate about this because I got the identical call wrong earlier today: on #6318 I wrote a dispatch fence as a binary (renderer honours the key ⇒ fork; does not ⇒ fix the fixture) and it had no true branch for the case in front of it. The lane flagged it instead of forcing it. Same shape here.

⭐ Recommended: implement the narrow fix.

Three reasons, and the third is the one that decides it:

1. min/max over a date is a legitimate aggregate. "Oldest untouched task" is a real KPI, and the card found this in a real application. Refusing it removes a capability someone is already using correctly.
2. The asymmetry is in the tier. Implementing is renderer-side — formatMeasure is in packages/core, no declared surface moves, Clause ② not engaged, landable today. Refusing means narrowing DatasetMeasureSchema.format or the aggregate's field type in @objectstack/spec — Clause ②, and the CONTRACT_REVIEW_TIER quota is exhausted. ⇒ One branch can ship; the other cannot, for reasons unrelated to its merit.
3. ⭐ Reuse the list-cell date path, do not add a second one. The card makes this argument and cites the precedent: [core][fields] A percent renders as 1.234,5 % in a list cell and 1.234,5% as a dashboard measure — two percent conventions for one number #4576, where two percent conventions drifted between a list cell and a dashboard measure. That is the same file's own header warning, and it is why "implement" should mean route through the existing path, not write a date formatter here.

Answer: "implement" or "refuse".

⚠️ The finding is the silence, and it survives either answer

a format that the schema accepts and the renderer can never read is declared ≠ enforced

The format argument is threaded carefully through the call site and is dead on this path — formatMeasure returns String(v) for any non-numeric value before format is touched. An author writes format: 'YYYY-MM-DD', gets a green validate and build, and an unchanged raw timestamp with nothing saying why.

⇒ Whichever direction is ruled, that silence must close. If "refuse", the spec says so and the author is told at build time. If "implement", format becomes reachable. ⛔ What is not acceptable is leaving an open-string format that parses and cannot be read.

Scope, for whoever takes it

The same formatMeasure call sits on four surfaces, all behind the same guard: DatasetWidget.tsx:768 (metric tile), :876 (chart values), :1083 (dataset table cells), and views/metadata-admin/previews/DatasetPreview.tsx:235. PivotTable.tsx:46 takes value: number outright and is a different question.

⇒ A fix at formatMeasure serves all four at once, which is a further argument for fixing it there rather than at the tile.

Grading

p3, and the card grades itself the same way — "the number is correct and legible, just ugly." ⛔ Not p2: nothing is wrong, nothing is lost, and no decision is made on bad data. The reusable half is the declared ≠ enforced silence, which is a p3 correctness-of-contract issue rather than a user-facing defect.

---

Generated by Claude Code

[os-project-manager]

Maintainer ruling recorded — A: implement date rendering in formatMeasure through the list-cell date path; date aggregates stay legal

Director seat (objectstack #12708), summon #8, session session_01ShyhexkB2d1AeRZ85tgAAe, 2026-09-02.

Provenance (who / verbatim / where): maintainer, live PM chat with the director seat, 2026-09-02, replying to decision batch #7 in which this card was item 3 with the recommendation A (fallback B, refuse date aggregates at author time). Verbatim reply: 「7189 A 其他同意」 — "其他同意" covers this card, so A is adopted as recommended.

Ruled: A. min / max over a date or datetime field is a legitimate measure and stays legal. formatMeasure in packages/core/src/utils/dataset-format.ts recognises a date-shaped value before the numeric short-circuit and routes it through the date display path list cells already use. No second date formatter is written in this file (the file's own header records why, from objectui#4576). Because the fix lands in formatMeasure, all four call sites are served at once: the metric tile, chart values, dataset table cells, and the metadata-admin dataset preview. PivotTable.tsx takes a number and is a different question, not touched here.

Option B (narrow DatasetMeasureSchema.format or the aggregate's field type in @objectstack/spec and refuse date aggregates at build time) is not taken: it removes a KPI a real application is already using correctly.

The silence must close either way. The finding's reusable half is that format is accepted by the schema and never read on this path. Under A, format becomes reachable for date values if the shared date path accepts a pattern. If it does not, the implementer states that in the PR and the spec seat adds one sentence to the format describe() on DatasetMeasureSchema ("applies to numeric measures; date measures render by locale"), so the remaining gap is documented rather than silent. That sentence is a spec-lane follow-up of one line, filed by the domain:ui seat when the measurement is in hand, not a rider on this PR.

Execution: domain:ui lane, S. Clause-② no (renderer side, no declared surface moves). @object-ui/core changeset, patch. Pin: a min measure over a datetime renders through the same path a list cell uses for that field, on the metric tile and in the dataset table, and a numeric measure is byte-identical before and after.

State transition, same stroke: needs-user-decision → pm:queue; priority:p3 retained. Ledger: objectstack director seat post #12708, summon #8.

---

Generated by Claude Code