docs(lint): document the dataset-measure aggregate x field-type rule, with its changeset

The rule reference gains the row and the worked example beside the dataset-axis
section that already covers measures, so an author reading about chart axes
finds the one about the measure itself. The changeset carries the migration the
refusal prescribes, per refused class, and the ADR-0087 disposition: the two
semantic entries that register this surface already exist.

Co-authored-by: Claude <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_019srGWGCBBCBHqcDoRZpQRh

Author: claude

.changeset/lint-dataset-measure-aggregate-field-type.md

@@ -0,0 +1,48 @@
+---
+'@objectstack/lint': minor
+---
+
+Refuse a dataset measure whose `aggregate` the field's declared type cannot carry, at authoring time
+
+A dataset measure pairs an `aggregate` with a `field`, and
+`AGGREGATE_FIELD_TYPE_COMPATIBILITY` (`@objectstack/spec`) declares which of those pairs every
+backend answers the same way. Nothing in the authoring path read that table, so `avg` over a
+`datetime` field validated clean and shipped: one SQL family coerces the column's canonical UTC
+text and returns a plausible number (the average *year*), another has no such function and fails at
+query time — the answer decided by the deployment rather than by the document. The analytics service
+refuses the pair when a query is built (`400 DATASET_INVALID`); this is the same verdict, from the
+same table, at the door the author is standing in front of.
+
+New rule `measure-aggregate-field-type-refused`, gating (`error`), on `os validate` / `os build` /
+`os lint`. It resolves the field's declared type on the object graph lint already indexes — including
+a dotted `relationship.field` path, whose leaf type the compile leg cannot see — and refuses the
+pair when `isAggregateCompatibleWithFieldType` says no. The message names the aggregate, the field,
+its declared type and the accepted set, and the hint names the aggregates that type *does* accept,
+both computed from the table rather than restated. It stays silent wherever the type cannot be
+resolved (an object this stack does not define, a field path that resolves to nothing, an untyped
+field, an aggregate outside the closed `AggregationFunction` vocabulary) rather than guessing.
+
+**BREAKING**: metadata that passed `os validate` / `os build` / `os lint` before can now fail. Every
+pair this refuses is one the analytics service already refuses at query time, so nothing that
+*worked* stops working — but a build that did not fail now does.
+
+Migration, per refused pair — FROM the aggregate the field's type cannot carry, TO one it accepts:
+
+- `avg` / `sum` over a `date` / `datetime` / `time` field → `min` / `max`, which return a real
+  instant of the field's own type, or `count` / `count_distinct`. A DURATION is not recoverable from
+  an aggregate over instants: store it as a number (a computed "days open" field) and aggregate that.
+- `sum` over a `percent` field → `avg`. A rate does not add; the total routinely exceeds 100%.
+- `min` / `max` over the string, option, reference, file, structured-JSON or `formula` classes →
+  `count` / `count_distinct` for "how many distinct values", or a SORT on the record list for "the
+  first / last record". String order is collation-dependent, so two backends answer two different
+  "smallest" values for one document.
+- Any other refused pair → read the row for your aggregate in
+  `AGGREGATE_FIELD_TYPE_COMPATIBILITY`; the refusal message prints it.
+
+A `derived` measure whose `of` names a refused measure is fixed by fixing that measure, not the
+`derived` one. A `date` / `datetime` / `text` field used as a DIMENSION — grouping, bucketing,
+filtering — is untouched: this is about aggregation only.
+
+Clause-②: yes (narrowing)
+
+<!-- adr-0087: not-required (already-registered dataset-measure-aggregate-field-type-refused, dataset-measure-selecting-aggregate-field-type-refused) The two entries register this exact surface — dataset measure `aggregate` x `field` pairs the table refuses — with the prescription above; #16099 likewise declared not-required against the first id when it widened the same leg. This change adds no surface of its own: it is the second consumer of that one table, at the authoring door. -->

content/docs/deployment/validating-metadata.mdx

@@ -189,6 +189,30 @@ The react `<ObjectChart>` block is **object-bound** (`objectName` + an inline
 gate below against a different rule — its result rows are keyed by the raw field
 names, exactly the opposite of the dataset case.
 
+One level down from the axis, the measure itself is checked against the field it
+aggregates. A measure pairs an `aggregate` with a `field`, and
+`AGGREGATE_FIELD_TYPE_COMPATIBILITY` (`@objectstack/spec`) declares which pairs
+every backend answers the same way. A pair outside it is refused
+(`measure-aggregate-field-type-refused`) naming the aggregate, the field, its
+declared type and the accepted set:
+
+```ts
+// object declares `closed_at` as `datetime`
+measures: [{ name: 'avg_closed', aggregate: 'avg', field: 'closed_at' }]
+//                                          ↑ refused: the answer would be the dialect's, not the data's
+```
+
+`avg` over a temporal column is where this bites hardest: one SQL family coerces
+the stored text and returns a plausible number (the average *year*), another has
+no such function and fails at query time. `min`/`max` over the same field are
+**accepted** — they return a real instant of the field's own type — and
+`count`/`count_distinct` are accepted over every type, because they read no
+arithmetic off the value. The analytics service refuses the same pair with
+`400 DATASET_INVALID` when a query is built; this is the identical verdict,
+from the identical table, one door earlier. The rule stays silent wherever the
+field's type cannot be resolved (an object this stack does not define, a
+dangling field path, an untyped field) rather than guessing.
+
 ### 7. Navigation exposing objects nobody can read
 
 Navigation and permissions are separate metadata, each valid on its own — so an
@@ -396,6 +420,7 @@ orthogonal to both, and no cell here can carry it; it is written out in
 | Zod-valid but functionally inert declarations — a `summary` with no operations (ADR-0078), a managed object advertising an API method its affordances refuse (#7521) | ✓ | ✓ | ✓ | ✓ᵒ |
 | View container shape | ✓ | ✓ | ✓ | — |
 | Widget-binding integrity (ADR-0021) | ✓ | ✓ | ✓ | ✓ᵈ |
+| Dataset measure `aggregate` × the field's declared type — a pair the spec's compatibility table refuses, e.g. `avg` over a `datetime` field (#16354) | ✓ | ✓ | ✓ | — |
 | Dashboard action/route references (ADR-0049) | ✓ | ✓ | ✓ | — |
 | Filter placeholder resolvability (#3574) | ✓ | ✓ | ✓ | — |
 | Ordering comparands naming a date-range preset — `last_30_days` in a `>=` position (#8793) | ✓ | ✓ | ✓ | ✓ᵈᵛᵒᵖᶠ |