Merge branch 'main' into claude/issue-17516-permission-set-collision-diagnostic

Author: os-project-manager

.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/17306-screen-field-bound-help-lookup.md

@@ -0,0 +1,94 @@
+---
+'@objectstack/spec': minor
+'@objectstack/service-automation': minor
+---
+
+A flow screen field can now express a numeric bound, help text and a lookup target — spelled with the object field's own key names
+
+<!-- adr-0087: registered screen-field-lookup-reference-required -->
+
+`ScreenFieldConfigSchema` was `.strict` over exactly
+`name`/`label`/`type`/`required`/`options`/`defaultValue`/`placeholder`/`visibleWhen`,
+so three ordinary authoring intents had **no expression at all**. They did not
+degrade quietly — `max`, `helpText` and every lookup-target spelling were
+refused BY NAME — but a loud refusal with no landing key is still a dead end,
+and the reference app worked around all three in prose: a discount ceiling
+interpolated into the `label` and the `placeholder` (with a comment explaining
+why there was no `max`), and a `type: 'lookup'` field whose `placeholder` asked
+a human to type a record id because the picker could not be pointed anywhere.
+
+Four keys land, and **their names are derived from `FieldSchema`, not invented**
+— one platform, one field vocabulary, so a name learned on an object field means
+the same thing on a screen field:
+
+| Key | Derived from | |
+|:---|:---|:---|
+| `min` / `max` | `FieldSchema.min` / `.max` | the bound pair |
+| `inlineHelpText` | `FieldSchema.inlineHelpText` | help under the input — `FieldSchema` renames `help`/`helpText`/`hint`/`tooltip` onto it, so a screen-local `helpText` would have been a second contract for one question |
+| `reference` | `FieldSchema.reference` | the object a `type: 'lookup'` field picks records from |
+
+**The bound is enforced, not advisory.** It rides to the client on
+`ScreenFieldSpec` so the user is stopped at the input, **and**
+`validateScreenInputs` re-checks it when the run resumes (`min_value` /
+`max_value`, both already in the ADR-0114 D2 field-error catalog — no new error
+code). A screen field's declared contract is the only contract behind it, so a
+bound the dialog alone applied would be bypassed by any caller posting to
+`resume` directly — the gap #4477 closed for `required`.
+
+That sentence needs no "when the value is a number" qualifier, because the
+value SHAPE is checked first: on a `type: 'number'` field a present value that
+is not a finite JSON number is refused with `invalid_type` (also already in the
+catalog — still no new code), ⛔ **not coerced**. Before this, a bound pass that
+compares numbers was satisfied by anything that never reached it, so `"25"`
+under a `max` of `20` was conformant. One member of the open `type` vocabulary
+is read as a value domain; every other widget hint stays open, and a bound on a
+non-numeric field still constrains nothing.
+
+**Delivered with its rendering, not ahead of it.** The executor forwards all
+four onto the wire and the Studio designer form offers all four as repeater
+columns; `builtin-node-form-zod-ledger.test.ts` reconciles the two key sets
+against the Zod in both directions, so a key declared here and absent from the
+form fails that test rather than shipping as a field nobody can author.
+
+**BREAKING** in the accept-set sense, in TWO places — landing as `minor` on
+both packages because the launch-window guard (`check-changeset-no-major`)
+keeps breaking changes off `major` outside pre-mode, not because the narrowing
+is small. Both were ruled (maintainer ruling A′, decision batch #130 item 1,
+2026-09-13); this release is **not** purely additive.
+
+1. `reference` is **required** when `type` is `lookup`, as it is on an object
+   field. A picker with no target object resolves nothing — ADR-0078's own
+   example of silently-inert metadata — and a degraded shape that ships today
+   is not a reason to bend the contract to it. A stored flow with a bare
+   `lookup` screen field parsed before and does not now. There is **no lossless
+   conversion**: nothing in the metadata says which object the author meant, so
+   this is an ADR-0087 **semantic** migration entry — a structured TODO
+   (`screen-field-lookup-reference-required`) that names the flow and the field
+   for a human to answer — and ⛔ never a D2 conversion that would have to
+   invent a target.
+2. A non-number submitted for a `type: 'number'` screen field is refused on
+   resume (`invalid_type`) instead of passing silently. A resume bag that was
+   accepted before can be refused now; it was never doing what its author
+   declared.
+
+Everything else is additive: the bound itself fires only on a field that
+declares one, which nothing did before this release.
+
+The neighbouring spellings are refused **with their landing key** rather than
+with a bare key list: `help`/`helpText`/`hint`/`tooltip` name `inlineHelpText`,
+and `object`/`referenceTo`/`targetObject`/`lookupObject`/`relatedTo`/`target`
+name `reference`. ⚠️ `object` means different things one level apart — on the
+screen **node** it renames to `objectName`, on a screen **field** it can only
+mean the lookup target — so it earns its own row on both.
+
+**One stale claim corrected in passing, because this change falsified it.** The
+flows translation surface documented `help`'s exclusion as *"`ScreenFieldConfig`
+declares nothing help-shaped at all"*, in `translation.zod.ts`'s guidance string
+(which enumerated the old key set verbatim), its doc block, and
+`i18n-resolver.ts`'s `FLOW_SCREEN_FIELD_COPY_KEYS`. The screen field now
+declares `inlineHelpText`, so the copy is real. The exclusion **stands** — the
+flows bundle still carries `label` and `placeholder` only, and growing that face
+is a ruled step against the #7646 enumeration, not a resolver-side accretion —
+but its reason is now stated as a not-yet instead of telling an author the field
+has no help copy when it has. ⛔ No translation key was added and no resolver
+behaviour moved.

.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.