@@ -0,0 +1,92 @@
+---
+"@objectstack/service-analytics": minor
+---
+
+feat(service-analytics)!: a dataset measure applying `sum` or `avg` to a field whose declared type cannot carry it is refused at compile time, for every field type and not only the temporal class (#16099)
+
+<!-- adr-0087: not-required (already-registered dataset-measure-aggregate-field-type-refused) the hand-migration prescription for this exact narrowing is already registered under protocol major 18 by #16778 — store the quantity as a numeric field and aggregate that — and this change widens which pairs reach it without changing what an affected author must do. ⚠️ That entry's `acceptanceCriteria` is scoped to a `date`/`datetime`/`time` field and says a field of any other class is "neither refused nor certified by this leg", which is no longer true at HEAD; widening that sentence is a `packages/spec` edit this card is fenced out of and is reported to the `domain:spec` seat rather than done here. -->
+
+**BREAKING** — an accept-set narrowing on a published authoring surface, continuing the
+one #16778 began. A dataset measure pairing `aggregate: 'sum'` with a `text` field (or
+`avg` with a `select`, `json`, `lookup`, `formula`, … field) used to compile and reach
+the backend; it is now refused by `compileDataset` with `DATASET_INVALID` / **400**
+before any query is built. Shipped as `minor` under the repo's launch-window convention
+for accept-set narrowings.
+
+⛔ This changeset adds no rows to any table and restates none. The verdict is
+`AGGREGATE_FIELD_TYPE_COMPATIBILITY`'s — the one table `@objectstack/spec` declared in
+#16353 under the director ruling of decision batch #59 ("both legs, table in spec") —
+read through `isAggregateCompatibleWithFieldType`.
+
+## What was wrong
+
+#16778 landed the compile leg SCOPED to temporal source fields, leaving "every other
+non-temporal pair the table refuses" as a stated residual that had never been driven.
+Driven on this card, through the real service door:
+
+```
+sum × text    the table refuses the pair   the compile leg does NOT throw   SQL IS emitted
+sweep         6 aggregates × 49 field types = 294 pairs; 155 refused by the table;
+              minus 6 temporal (#16778's) minus 42 `min`/`max` × the string classes;
+              residual 107 — and 107 of 107 were ACCEPTED by the compile leg
+control       avg × datetime / date / time → DATASET_INVALID / 400, no SQL emitted
+```
+
+The control is what makes that a reading of the tree rather than of a blind harness: the
+same service, door and `sourceFieldMeta` hook sees the pairs #16778 enforces refused.
+
+So `sum` over a `text` column reached whichever backend the object is bound to, and the
+answer was a property of the dialect rather than of the data — the shape Prime Directive
+#12 exists to remove, and the same shape #16778 closed for one field class.
+
+## What it does now
+
+- `compileDataset` judges a measure whose aggregate DERIVES a number (`sum` / `avg`)
+  against the table for **every** declared field type, and refuses an unaccepted pair
+  with `DATASET_INVALID` / **400** — naming the measure, the field, its declared type
+  and the accepted set read off the table. Nothing reaches the driver.
+- `sum` × `percent` is refused at last: the row `analytics-service.ts` has called
+  "incoherent" in a comment since before the table existed. `avg` × `percent` is still
+  ACCEPTED by the same table, which is what makes it a row and not a class.
+- The refusal's closing prescription is now chosen by the source field's class: the
+  temporal sentence #16778 measured is kept verbatim for temporal fields, and a
+  non-numeric field is pointed at `count` / `count_distinct`, which accept every type
+  because they read no arithmetic off a value.
+- Unchanged: `derived` is covered by construction (a dataset carrying a refused base
+  measure never finishes compiling), and the three "cannot answer, do not block" tiers —
+  no `sourceFieldMeta`, an unresolvable field, a `relationship.field` path.
+
+## ⚠️ Scope: the DERIVING aggregates. `min` / `max` are still not judged here
+
+`min` / `max` SELECT one of the stored values; `sum` / `avg` DERIVE a number. This is the
+line this package already draws — `measureResultType` branches on exactly that pair of
+aggregates — and the defect is about a derived number, so the deriving aggregates are its
+population.
+
+The `min` / `max` rows stay with **#17513**, and that is measured rather than assumed.
+Enforcing the residual whole was tried on this card: with `min` / `max` × the string
+classes subtracted, **15** cases in `measure-result-type.test.ts` still went red, every
+one of them on `min` × `json` — a pair the table refuses, in no ruling's scope, driven
+end to end by the same shared fixture as the string rows. One dataset compiles every
+measure in that fixture, so one refused pair reds the whole section. ⇒ `min` / `max` is
+one question, and it is the table-amendment card's.
+
+## Upgrading — FROM → TO
+
+Nothing an author writes is removed or renamed: `DatasetMeasure.aggregate` and
+`DatasetMeasure.field` keep their spellings and their types. What narrows is which PAIRS of
+values are accepted. The one-line fix, per shape:
+
+| FROM (compiled before, refused now) | TO |
+|---|---|
+| `{ aggregate: 'sum', field: <a text / select / lookup / user / autonumber field> }` | `{ aggregate: 'count_distinct', field: <the same field> }` — counting reads no arithmetic off the value |
+| `{ aggregate: 'sum' | 'avg', field: <a json / file / location / vector / composite field> }` | store the quantity you meant as its own numeric field and aggregate that |
+| `{ aggregate: 'sum', field: <a formula field> }` | aggregate the formula's numeric INPUT column; a `formula` is virtual in SQL storage, so no arithmetic aggregate can be lowered to it |
+| `{ aggregate: 'sum', field: <a percent field> }` | `{ aggregate: 'avg', field: <the same field> }` — a rate averages, it does not add |
+| `{ aggregate: 'sum' | 'avg', field: <a date / datetime / time field> }` | unchanged from #16778: use `min` / `max` for a real instant, or store a duration as a number and aggregate that |
+
+`min` / `max` are **not** affected by this change at all, over any field type.
+
+No shipped dataset in this repository declares a newly-refused pair — every one of the
+eleven shipped dataset measures resolves to `number`, `currency`, `summary` or `progress`.
+The refusal names the accepted set for the aggregate, read off the table.
@@ -41,22 +41,28 @@
  * so a row changed upstream changes these expectations with it rather than
  * leaving a second, drifting account of the contract.
  *
- * ## ⚠️ The compile leg lands SCOPED to temporal source fields, and says why
+ * ## ⚠️ The compile leg lands SCOPED, and #16099 has since moved where the line sits
  *
- * The verdict is the table's; what is scoped is which FIELDS the gate judges.
- * Executing every row of the table today would refuse `min` / `max` over the
- * STRING classes — typed `'string'` by `measureResultType` (#15768) and pinned
- * end to end in `measure-result-type.test.ts` — which this platform answers on
- * purpose. #16785 has since **ruled C** on those rows: the TABLE is to be
- * amended to accept them, so enforcing them from here would pre-empt a ruling
- * that goes the other way. The BOOLEAN rows are settled and are not a collision
- * any more: #16685 was ruled A and #16750 added `boolean` / `toggle` to
- * `sum` / `avg` / `min` / `max` (maintainer ruling #11152 — booleans aggregate
- * as numbers on every backend), so the table ACCEPTS them and nothing refuses
- * them anywhere. The temporal rows carry no such counter-evidence, which is why
- * they are the ones executed here; the full-table leg stays with #16099. The
- * last suite in this file pins that boundary so it cannot widen by accident —
- * ⛔ without pinning any verdict the table itself is still under ruling for.
+ * The verdict is the table's; what is scoped is which PAIRS the gate judges.
+ * #16737 landed that scope as the TEMPORAL source-field class and said why:
+ * executing every row would refuse `min` / `max` over the STRING classes —
+ * typed `'string'` by `measureResultType` (#15768) and pinned end to end in
+ * `measure-result-type.test.ts` — which this platform answers on purpose, and
+ * which are ruled to be AMENDED into the table rather than executed (#17513).
+ *
+ * **#16099 has since re-cut that scope along the AGGREGATE instead**, and the
+ * two boundary cases at the foot of this file are where the move is visible:
+ * the gate now judges the DERIVING aggregates (`sum` / `avg`) over EVERY field
+ * type, and does not judge `min` / `max` at all. So `sum` × `text` — which this
+ * file pinned as compiling, and predicted in writing would go red when the gate
+ * widened — is now refused, while `min` × `text` still compiles and keeps its
+ * row's ruling intact. The BOOLEAN rows were never a collision in either
+ * scope: #16685 was ruled A and #16750 added `boolean` / `toggle` to the
+ * `sum` / `avg` / `min` / `max` rows (maintainer ruling #11152 — booleans
+ * aggregate as numbers on every backend), so the table ACCEPTS them and nothing
+ * refuses them anywhere. The non-temporal deriving population is pinned in
+ * `aggregate-nontemporal-measure-refusal.test.ts`; this file keeps the temporal
+ * population and the boundary.
  *
  * ## Dissolution verification — direction predicted BEFORE running
  *
@@ -481,16 +487,18 @@ describe('#16737 — the gate stands down rather than guessing', () => {
 // The scope boundary, pinned — so it cannot widen (or narrow) unnoticed
 // ─────────────────────────────────────────────────────────────────────────────
 
-describe('#16737 — the compile leg is scoped to temporal source fields, on purpose', () => {
+describe('#16737 — the compile leg is SCOPED, on purpose; #16099 moved where the line sits', () => {
   it('a `min` over a TEXT field still compiles here — WHATEVER the table says about that pair', async () => {
     // ⚠️ Not an endorsement of the pair, and ⛔ deliberately NOT a pin on the
-    // table's verdict for it. `min` × `text` is the row #16785 is ruled C on —
-    // the table is to be AMENDED to accept it — so asserting today's `false`
-    // here would make this file go red when that ruling lands, and would make a
-    // test of this card the thing standing in the way of a decision this card
-    // does not own. What this case owns is one fact, true on either side of
-    // that amendment: a NON-TEMPORAL field is not judged by this gate, so the
-    // measure compiles and reaches the driver.
+    // table's verdict for it. `min` × `text` is the row ruled C — the table is
+    // to be AMENDED to accept it, tracked as **#17513** — so asserting today's
+    // `false` here would make this file go red when that ruling lands, and
+    // would make a test of this card the thing standing in the way of a
+    // decision this card does not own. What this case owns is one fact, true on
+    // either side of that amendment: a `min` / `max` measure is not judged by
+    // this gate, so the measure compiles and reaches the driver. #16099 widened
+    // the gate to every field type, but only for the DERIVING aggregates, and
+    // `min` / `max` stayed outside it precisely so this row keeps its ruling.
     const { svc, sqls } = makeService([{ status: 'open', first_note: 'Archive the backlog' }]);
     const result: any = await svc.queryDataset(
       dataset([{ name: 'first_note', aggregate: 'min', field: 'note' }]),
@@ -502,22 +510,36 @@ describe('#16737 — the compile leg is scoped to temporal source fields, on pur
     expect(sqls.length).toBe(1);
   });
 
-  it('a `sum` over a TEXT field also compiles here — the boundary, on a row no ruling is moving', async () => {
-    // The refutable half of the boundary. #16785 C amends only `min` / `max`
-    // for the string classes, so `sum` × `text` stays a pair the TABLE refuses
-    // and this GATE does not act on — before that amendment and after it. If
-    // the gate ever widened past the temporal class, this case goes red.
+  it('⭐ a `sum` over a TEXT field is now REFUSED — the boundary #16099 moved, replacing this pin', async () => {
+    // ⚠️ This case asserted the OPPOSITE until #16099, and the branch it pinned
+    // is the one that card removed: it read "`sum` × `text` stays a pair the
+    // TABLE refuses and this GATE does not act on", and predicted in writing
+    // that "if the gate ever widened past the temporal class, this case goes
+    // red". It did, and it did — driven, not assumed. So the pin is replaced
+    // rather than deleted or relaxed: the same pair, through the same door,
+    // asserting the answer the platform now gives. The fuller population lives
+    // in `aggregate-nontemporal-measure-refusal.test.ts`; what this case keeps
+    // owning is the BOUNDARY — this is the row that moved, beside the `min`
+    // row above that did not.
     expect(isAggregateCompatibleWithFieldType('sum', 'text')).toBe(false);
     const { svc, sqls } = makeService([{ status: 'open', note_sum: 0 }]);
-    const result: any = await svc.queryDataset(
-      dataset([{ name: 'note_sum', aggregate: 'sum', field: 'note' }]),
-      { dimensions: ['status'], measures: ['note_sum'] },
+    const err = await refusalOf(() =>
+      svc.queryDataset(
+        dataset([{ name: 'note_sum', aggregate: 'sum', field: 'note' }]),
+        { dimensions: ['status'], measures: ['note_sum'] },
+      ),
     );
-    expect(result.rows.length).toBe(1);
-    expect(sqls.length).toBe(1);
+    expect(err.code).toBe('DATASET_INVALID');
+    expect(err.status).toBe(400);
+    expect(err.message).toContain('note_sum');
+    expect(err.message).toContain('text');
+    // Not vacuous in the other direction either: the refusal happens BEFORE any
+    // statement is emitted, which is what makes it a rejected DECLARATION
+    // rather than a query that happened to return nothing.
+    expect(sqls.length).toBe(0);
   });
 
-  it('every temporal member IS judged — the scope is the class, not the one type the card named', async () => {
+  it('every temporal member IS judged — not just the one type the card named', async () => {
     for (const [field, label] of [['submitted_at', 'datetime'], ['close_date', 'date'], ['shift_start', 'time']] as const) {
       const { svc } = makeService();
       const err = await refusalOf(() =>