Merge branch 'main' into claude/issue-17883-generate-migration-file-column-width

Author: claude[bot]

.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/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/17783-metrics-jsdoc-durations-unit-in-key.md

@@ -0,0 +1,106 @@
+---
+"@objectstack/spec": minor
+---
+
+feat(spec)!: the five `system/metrics.zod.ts` durations carry their unit in the key name (#17783, ruling A on #15939)
+
+<!-- adr-0087: registered system-metrics-jsdoc-durations-unit-in-key -->
+
+**BREAKING** — the five metrics durations whose unit was stated only in a source JSDoc now carry
+it in the key name, and each published `.describe()` states it too.
+
+| def | before | after |
+|:--|:--|:--|
+| `MetricDefinition` | `summary.maxAge: 600` | `summary.maxAgeSeconds: 600` |
+| `ServiceLevelObjective` | `errorBudget.burnRateWindows[].window: 3600` | `errorBudget.burnRateWindows[].durationSeconds: 3600` |
+| `MetricExportConfig` | `interval: 60` | `intervalSeconds: 60` |
+| `MetricsConfig` | `collectionInterval: 15` | `collectionIntervalSeconds: 15` |
+| `MetricsConfig` | `retention.period: 604800` | `retention.durationSeconds: 604800` |
+
+Every value is seconds, exactly as before, and every default (600, 3600 as authored, 60, 15,
+604800) is unchanged.
+
+## Migration
+
+```diff
+  summary: {
+-   maxAge: 600,
++   maxAgeSeconds: 600,
+  }
+
+  errorBudget: {
+-   burnRateWindows: [{ window: 3600, threshold: 14.4 }],
++   burnRateWindows: [{ durationSeconds: 3600, threshold: 14.4 }],
+  }
+
+  exports: [{
+    type: 'prometheus',
+-   interval: 60,
++   intervalSeconds: 60,
+  }],
+- collectionInterval: 15,
++ collectionIntervalSeconds: 15,
+  retention: {
+-   period: 604800,
++   durationSeconds: 604800,
+  },
+```
+
+Rename the keys. Nothing else on these four defs moves, and the three same-named objects on this
+file — `MetricAggregationConfig.window`, `ServiceLevelIndicator.window` and
+`ServiceLevelObjective.period` — are untouched.
+
+## Why
+
+Each key named its unit in a source JSDoc — "Max age of observations in seconds", "Window size in
+seconds", "Export interval in seconds", "Collection interval in seconds", "Retention period in
+seconds" — and nowhere else. Four of the five carried no `.describe()` at all and the fifth read
+"Window size", so the text `content/docs/references/system/metrics.mdx` publishes named no unit:
+600, 3600, 60, 15 and 604800 are each a plausible number of seconds and a plausible number of
+milliseconds, and nothing on the page decided between them. Executes director-seat ruling A on
+#15939 (2026-09-11, maintainer 「同意」, decision batch #115), the per-file remediation of the
+#14478 rule — under that rule, moving the unit into the describe alone is itself a violation (unit
+in prose, none in the name), so each key is renamed and its describe corrected together.
+
+Three of the five new names are deliberately **not** the mechanical suffix, and this file supplied
+the reason for each:
+
+- `burnRateWindows[].window` → **`durationSeconds`**, not `windowSeconds`. It is the fourth window
+  length on this file, and #15679 already settled that a window length here reads `durationSeconds`
+  so the measurements read alike. `windowSeconds` would stutter against the enclosing
+  `burnRateWindows` array — the same objection #15679 recorded against `window.windowSeconds` — and
+  on this tree `windowSeconds` is not an authorable key at all: its only key-position occurrence is
+  an alias-map entry in `ServerRateLimitConfigSchema` that maps the spelling *away* to `windowMs`.
+- `retention.period` → **`durationSeconds`**, not `periodSeconds`. `period` is calendar vocabulary
+  elsewhere in this spec (`ServiceLevelObjective.period.type` selects rolling or calendar,
+  `PluginRegistryEntry.pricing.billingPeriod` is monthly or yearly), so `periodSeconds` would have
+  kept the ambiguous half of the name — the same objection #15679 raised against `sizeSeconds`.
+- `collectionInterval` → **`collectionIntervalSeconds`**, keeping the qualifier, because
+  `MetricExportConfig.intervalSeconds` is a different cadence one def over that this same change
+  creates.
+
+The two mechanical spellings are attested: `maxAgeSeconds` is the token
+`AccessControlConfig.maxAgeSeconds` already carries after this same rule renamed it on
+`system/object-storage.zod.ts`, and it keeps the `age` stem that the sibling `ageBuckets` counts
+buckets of; `intervalSeconds` is the token four seconds-valued cadences already carry. Counted in
+key position across `packages/spec/src` at `fc28c1d38`, the base of this change, the seconds
+suffixes run `Seconds` 40, `Sec` 1 (`maxExecutionTimeSec`) and `S` 0 — the two bare `*S` keys on
+that corpus, `maxCommitTimeMS` and `enableRLS`, are a millisecond spelling and a boolean. This
+change takes `Seconds` to 45 at `9b62f54671`.
+
+## The kit
+
+- a `retiredKey()` tombstone on each old spelling, so `tsc` types it `never` and a value reaching
+  the parse raises the rename prescription instead of being silently stripped (none of the five
+  enclosing shapes is `.strict()`)
+- the ADR-0087 D3 semantic entry `system-metrics-jsdoc-durations-unit-in-key` and five
+  `RETIRED_KEYS_BY_MAJOR[18]` rows. No D2 conversion: `stack.zod.ts` declares no metrics collection
+  and none of these defs is a stored metadata row — the reading
+  `system-metrics-window-durations-unit-in-key` already recorded for this file
+- pin tests per key: the refusal carries the rename prescription and is not an `unrecognized_keys`
+  issue, the suffixed key parses at the magnitude the retired one carried with the same default,
+  and each describe publishes the unit
+- two authorable-surface rows move, three do not: that ratchet records **top-level** keys per def,
+  so `MetricExportConfig:interval` and `MetricsConfig:collectionInterval` become `[RETIRED]` beside
+  their suffixed rows (and their `authorable-defaults` rows move with them), while
+  `summary.maxAge`, `burnRateWindows[].window` and `retention.period` are nested and move nothing

.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