Merge remote-tracking branch 'origin/main' into claude/issue-17009-patrol-rows-facets-and-stale-finding

Author: claude

.changeset/16236-formula-return-type-measure-column.md

@@ -4,6 +4,19 @@
 
 fix(service-analytics): a `min`/`max` over a `formula` field is typed from the formula's declared `returnType`, not described as `number` (#16236)
 
+> ⚠️ **Superseded within the same release window — ⛔ do not act on this entry.**
+> Everything below was accurate when it was written and is kept as the record of what
+> #16236 measured and built. It never reached a published version: **#17560** (director
+> ruling, decision batch #127, 2026-09-13) refuses `min` / `max` over a `formula` field
+> outright, on the compatibility table's own storage ground — a formula is VIRTUAL in SQL
+> storage, no column is emitted, so no aggregate can be lowered to it whatever
+> `returnType` says. At the version that compiles this entry such a measure answers
+> `DATASET_INVALID` / **400** at compile time instead of carrying any `fields[].type`, and
+> the `returnType?: string` member described at the foot of this entry is **not** on
+> `AnalyticsServiceConfig.sourceFieldMeta` — it was added and removed inside one release
+> window, so no published version ever carried it. ⇒ Read #17560's entry instead; the
+> FROM → TO below never became a shipped behaviour.
+
 **Behaviour change — read this if any dataset measure aggregates a `formula`
 field.** `AnalyticsResult.fields[].type` for such a measure column was always
 `number`, whatever the formula computes. It is now translated from the field's
@@ -47,3 +60,8 @@ a word outside the declared four: left alone, never guessed at.
 host that returns the three-member shape still satisfies the contract and gets
 exactly today's behaviour for every column. `AnalyticsServicePlugin` relays the
 key automatically, so a host on the plugin needs no change at all.
+
+⚠️ **Superseded — see the banner at the top.** #17560 removed that member again in
+the same release window, so the shape a host writes against is the three-member one
+this paragraph calls today's. Nothing to do either way: a host that returns the
+fourth key is ignored, not refused.

.changeset/17053-list-view-sort-string-clause-retired.md

@@ -0,0 +1,68 @@
+---
+"@objectstack/spec": minor
+---
+
+feat(spec)!: `ListViewSchema.sort` retires the bare string clause — the PRODUCER half of the sort seam, so the contract stops minting documents its own consumer refuses (#17053; objectui#8221, decision batch #77 option B)
+
+<!-- adr-0087: registered list-view-sort-string-clause-to-array -->
+
+**BREAKING** accept-set narrowing at `view.sort` — the list-view doors
+(`ListViewSchema`, and the `ObjectListViewSchema` copy behind `object.list` /
+`object.listViews.*`) — shipped as `minor` under this repo's launch-window
+convention for breaking changes, the same grade its sibling
+`object-block-sort-item-array` took for the two `ComponentPropsMap` doors. The
+mechanical prescription is registered under protocol major 18 as
+`list-view-sort-string-clause-to-array`.
+
+**Why this is graded on the seam, not on the string.** objectui ruled one sort
+orthography platform-wide — the array (objectui#8221, decision batch #77,
+2026-09-07, option B) — and objectui PR #8758 executes it: `convertSortToQueryParams`
+refuses a runtime string and its diagnostic names the array form. `ListViewSchema`
+is the producer of exactly those documents: `object.list.sort` is what
+`deriveRelatedLists` reads. So until this release a view authored with
+`sort: 'created_at desc'` **validated here, cleanly, and then failed downstream** —
+the contract minting a shape its consumer rejects, with the author told off by
+the wrong layer. Re-measured on this tree before the change, with `bogusProp`
+refused by name on the same call as the firing control: `'name desc'`, `'-name'`
+and the array form all returned `success: true`, and only a bare number was
+refused (`sort/invalid_union`).
+
+`sort` survives as a key, one union arm lighter, so this is a VALUE narrowing with
+no `retiredKey()` tombstone to hang a prescription on. The surviving array member's
+own `error` map carries it, keyed on `issue.input` being a string — the same shape
+`view.type`'s retired `'page'` value and `view.exportOptions`' retired `'pdf'` value
+already use in this schema. Every other invalid value (a number, an object, a
+string reaching a *descendant* such as a misspelled `order`) keeps zod's default
+report, so nobody is told a clause they never wrote "was removed".
+
+**Migration** (`list-view-sort-string-clause-to-array`, a D2 conversion, not a
+semantic TODO — the rewrite is lossless and wholly mechanical):
+`sort: 'created_at desc'` becomes `sort: [{ field: 'created_at', order: 'desc' }]`;
+a bare field name meant ascending, so `sort: 'created_at'` becomes
+`sort: [{ field: 'created_at', order: 'asc' }]` — `order` is required on the entry
+and is written out rather than omitted; a comma-separated clause becomes one array
+entry per key, in the same order. `os migrate meta --from 17` lists these edits for
+author sources, and stored rows replay them through `applyConversionsToStoredItem`.
+
+**The narrowing was not free, and the population was measured rather than assumed.**
+A tree-wide census over both the TS and JSON spellings of a string-valued `sort`,
+read as STRUCTURES rather than counted as tokens, found the clause authored on
+three live in-tree sites, all converted here: the shipped showcase list view
+`examples/app-showcase/src/ui/views/task.view.ts` (`'estimate_hours desc'`, carried
+since objectui#2601 as a deliberate live coverage fixture for the string form), the
+frozen `packages/lint` snapshot of that same shipped shape, and the published
+`skills/objectstack-ui` list-view rule. The census fired: it *found* documents, and
+`tsc` independently reds on the first two the moment the arm is removed. Sites
+deliberately NOT converted, having been read rather than grepped: ObjectQL
+`query.sort` and the wire `normalizeSortNodes` (different doors, different
+dialects), `packages/spec`'s `book`/`doc` field-mapping records whose `sort: 'order'`
+is an unrelated key of the same name, and the `packages/lint` rule fixtures, which
+feed the PRE-parse walker and never reach this schema.
+
+**Not moved by this release.** `RecordRelatedListProps.sort` keeps its declared
+string arm. That string is the `'field'` / `'-field'` dialect normalised by
+objectui's own `RelatedList.normalizeSortSpec`; it never reaches
+`convertSortToQueryParams`, and retiring it was not ruled. For the same reason the
+conversion above declines any clause that does not parse as `<field> [asc|desc]`:
+guessing a direction for `'-name'` would invent an ordering the author never wrote,
+so on a list view it meets the door's prescription instead.

.changeset/17560-selecting-aggregate-field-type-refused.md

@@ -0,0 +1,103 @@
+---
+"@objectstack/service-analytics": minor
+"@objectstack/spec": minor
+---
+
+feat(service-analytics)!: `min` and `max` are judged by the aggregate × field-type table too — all 74 refused pairs answer `400 DATASET_INVALID` through one compile door (#17560)
+
+<!-- adr-0087: registered dataset-measure-selecting-aggregate-field-type-refused -->
+
+**BREAKING** — an accept-set narrowing on a published authoring surface, and the last
+one this table owed. A dataset measure pairing `aggregate: 'min'` (or `'max'`) with any
+of the **37** field types outside the numeric, temporal and boolean classes — for example
+`text`, `select`, `lookup`, `autonumber`, `json`, `multiselect`, `file`, `location`,
+`vector` or `formula`; the ADR-0087 entry registered below carries the full list — 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
+
+The table refused these 74 pairs from the day it was declared, and **four declarations
+gave three different answers about them**:
+
+| declaration | what it said about `min` × `text` |
+|---|---|
+| `AGGREGATE_FIELD_TYPE_COMPATIBILITY` (spec) | refused |
+| `dataset-compiler`'s compile leg | never judged — `if (!DERIVING_AGGREGATES.has(aggregate)) return;` |
+| `measureResultType` (service-analytics, #15768) | a supported `'string'` result |
+| two shipped test files, in prose | "ruled C — the table is to be AMENDED to accept it" |
+
+Driven through the real service door before anything was written, `min` / `max` over 13
+sampled refused pairs all compiled and emitted SQL, with `avg` × `datetime` as the
+firing control (refused, `DATASET_INVALID` / 400, no SQL) — so the zero was a reading of
+the tree rather than of a blind harness.
+
+The fourth row had nothing behind it. The card it cited (#17513) is closed as a
+duplicate carrying zero rulings, and the one recorded ruling on this table says the
+opposite. ⇒ The director ruling of decision batch #127 (2026-09-13) settled all three
+sub-questions in one pass, because one shared fixture drove members of both halves:
+
+1. **the string classes** (42 pairs) stay refused, as batch #59 ruled — ⛔ the table is
+   not amended;
+2. **the non-string classes** (32 pairs) are refused **and enforced**;
+3. **`formula`** is refused on the table's own storage ground — it is VIRTUAL in SQL
+   storage, no column is emitted, so no aggregate can be lowered to it whatever
+   `returnType` says.
+
+The divergence is real, and for these two aggregates it is the **ORDER** rather than the
+arithmetic: string order is collation-dependent, so two backends answer two different
+"smallest" values for one metadata document, and `min(jsonb)` does not exist on
+PostgreSQL at all.
+
+## What changed
+
+- **`dataset-compiler`**: the scope condition is gone. `assertAggregateFieldTypeCompatible`
+  judges all six `AggregationFunction` members against the table, through the same
+  `DATASET_INVALID` / 400 door. The refusal message names the divergence its own
+  aggregate class really has (`min` / `max` SELECT a stored value and diverge on order;
+  `sum` / `avg` DERIVE a number and diverge on arithmetic) and prescribes accordingly.
+- **`measureResultType`** asks `isAggregateCompatibleWithFieldType` before it answers, so
+  the rule and the table agree **by construction**. Its `STRING_SOURCE_FIELD_TYPES`
+  branch and its `formula` branch are retired with them; `min` / `max` over the temporal
+  class still answers `'time'`, unchanged.
+- **`AnalyticsServiceConfig.sourceFieldMeta`** no longer declares `returnType`. It was
+  carried (#16236) for one reader — the retired `formula` branch — and a declared input
+  nobody consumes is the declared-not-enforced shape Prime Directive #10 refuses.
+
+  ⚠️ **That key was never released, so against every published version this removal is a
+  no-op.** #16236 is still a pending changeset in the same release window as this one;
+  the last published entry (17.4.0) says in as many words that `FieldSchema.returnType`
+  "is not on `AnalyticsServiceConfig.sourceFieldMeta`'s return shape". The key was
+  therefore added and removed inside one window and no published tarball ever carried it.
+
+  **Host fix, one line:** drop `returnType` from whatever your `sourceFieldMeta` returns.
+  You do not have to — the hook is a function RETURN position, so an extra key is not an
+  excess-property error and is simply ignored at runtime — but keeping it declares an
+  input nothing reads. Hosts on `AnalyticsServicePlugin` need no change at all: the plugin
+  stopped relaying the key in this same change.
+
+## FROM → TO, and the one-line fix
+
+| you wrote | write instead |
+|---|---|
+| `{ aggregate: 'min' \| 'max', field: <a text/select/lookup/autonumber field> }` | `count` / `count_distinct` if you were counting; a **sort** on the list/report if you wanted the first or last RECORD |
+| `{ aggregate: 'min' \| 'max', field: <a json/multiselect/file/location/vector field> }` | store the quantity you meant as a numeric or temporal field and aggregate that |
+| `{ aggregate: 'min' \| 'max', field: <a formula field> }` | a formula emits no column; aggregate the stored field the formula reads, or persist the computed value |
+
+⚠️ **Untouched:** those field types used as a **DIMENSION** (grouping, labelling,
+bucketing, filtering), `count` / `count_distinct` over any type, `min` / `max` over the
+numeric, temporal and boolean classes, and every `sum` / `avg` row #16778 and #16099
+already settled. The refusal also still stands down rather than guessing wherever the
+declared type cannot be resolved: no `sourceFieldMeta` wired, an unknown field, or a
+`relationship.field` path whose column lives on a joined object.
+
+⚠️ The hand-migration prescription ships as the ADR-0087 semantic TODO registered above,
+which names the measure and the field type per affected pair — no lossless conversion
+exists, because nothing can compute "the smallest text value" in a way every backend
+agrees on.

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

@@ -60,25 +60,45 @@ schema, not `os validate` / `os lint`, not the analytics service, not the render
 
 ## ⚠️ Scope: the compile leg executes the TEMPORAL rows only
 
+> ⚠️ **Superseded within the same release window.** This section was accurate when it was
+> written and is kept as the record of where the compile leg stopped. Two later cards
+> widened it before any of the three entries shipped, so at the version that compiles this
+> entry the scope below is no longer the platform's: **#16099** judged `sum` / `avg` over
+> every remaining field class (including `sum` over a `percent`), and **#17560** (director
+> ruling, decision batch #127, 2026-09-13) judged `min` / `max` over every class the table
+> refuses. ⇒ Three sentences in this section are false at that version and are corrected
+> where they stand: the string rows are **not** awaiting a table amendment, `sum` over a
+> `percent` does **not** compile as it did before, and `avg` / `sum` over a temporal field
+> are **not** the only pairs whose behaviour changes. Read all three entries together.
+
 The gate judges only a measure whose field is declared `date` / `datetime` /
 `time`; a field of any other class is never handed to the predicate. The
 verdict for the pairs it does judge is the table's — no row is restated — but
 which FIELDS are judged is narrower than the table, on purpose:
 
 - **String rows** (`min` / `max` over `text`, `select`, `lookup`,
-  `autonumber`, …) are **not enforced here**. They are under #16785, **ruled
-  C**: the table itself is to be amended to accept them, because
-  `measureResultType` (#15768) already types those results as `'string'` and
-  pins them end to end. Enforcing them from this card would pre-empt that
-  ruling.
+  `autonumber`, …) are **not enforced here**. ⚠️ This card recorded them as
+  「under #16785, **ruled C** — the table itself is to be amended to accept
+  them」, because `measureResultType` (#15768) already typed those results as
+  `'string'` and pinned them end to end, so enforcing them from here would
+  pre-empt that ruling. **Both halves of that sentence turned out to be
+  wrong.** `16785` resolves to no issue, and decision batch #127 (#17560,
+  2026-09-13) found no ruling C anywhere behind the citation — the one recorded
+  ruling on this table, decision batch #59, refuses the string rows. ⛔ The
+  table is **not** amended; #17560 enforces those rows and retires the
+  `measureResultType` opinion that disagreed with them.
 - **Boolean rows** are not a refusal at all any more: #16685 was ruled A and
   #16750 added `boolean` / `toggle` to `sum` / `avg` / `min` / `max`, so the
   table ACCEPTS them and this gate never judged them.
 - The table's `sum` × `percent` row is likewise **not** executed by this leg;
-  `sum` over a `percent` compiles exactly as it did before.
-
-⇒ The only pairs whose behaviour changes in this release are `avg` / `sum`
-over a `date` / `datetime` / `time` field. The full-table leg remains #16099's.
+  `sum` over a `percent` compiles exactly as it did before. ⚠️ True of this
+  card only — #16099 executes that row in the same release.
+
+⇒ The only pairs whose behaviour changes **because of this card** are `avg` /
+`sum` over a `date` / `datetime` / `time` field. ⚠️ ⛔ Not a statement about the
+release: the full-table leg is #16099's and landed, and the `min` / `max` leg is
+#17560's and landed, so at the shipping version every pair the table refuses is
+refused at the compile door.
 
 ## FROM → TO
 

.changeset/deriving-aggregate-nonnumeric-field-refused.md

@@ -56,14 +56,22 @@ answer was a property of the dialect rather than of the data — the shape Prime
   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
+## ⚠️ Scope: the DERIVING aggregates — and see #17560, which closed the other half
+
+> ⚠️ **Superseded within the same release window.** This section was accurate when it was
+> written and is kept as the record of why this change stopped where it did. #17560
+> (director ruling, decision batch #127, 2026-09-13) then judged `min` / `max` too, so at
+> the version that ships this entry **every** pair the table refuses is refused at the
+> compile door. Read that entry beside this one.
 
 `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.
+The `min` / `max` rows stayed with the table-amendment card (then **#17513**, since closed
+as a duplicate of **#17560**, which ruled and landed them), 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