Merge remote-tracking branch 'origin/main' into claude/issue-17785-tracing-duration-units

# Conflicts:
#	packages/spec/src/migrations/registry.ts

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/16678-admin-set-user-manager.md

@@ -0,0 +1,59 @@
+---
+'@objectstack/plugin-auth': patch
+'@objectstack/lint': patch
+---
+
+`sys_user.manager_id` gains an admin write surface: `POST /api/v1/auth/admin/set-user-manager`
+
+`{ type: 'manager' }` is the canonical first rung of a tiered approval ladder,
+and it resolves `sys_user.manager_id` — a column **no product surface could
+write**. Measured: the generic data path refuses it (the ADR-0092 D2
+managed-update whitelist for `sys_user` is `{name, image, locale}`), the admin
+bulk import does not carry it (`admin-import-users.ts` matches `manager_id` 0
+times, against a control of `phone_number` 8), and the column is `readonly` on
+the user form. So on any install without a directory sync the rung expanded to
+nobody, the request opened on a slate no one could act on, and under the
+default `lockRecord: true` the record stayed locked.
+
+**The endpoint.** A platform admin posts `{ userId, managerId }`; `managerId:
+null` clears the link. It is an ObjectStack mount on the raw app ahead of the
+better-auth catch-all — the same family as `POST /api/v1/auth/admin/unlock-user`
+— platform-admin gated (ADR-0068) and ledgered in `auth-route-ledger.ts`.
+
+**It is not a new editable profile column, and that is the design.** The
+handler runs under a **system context**, so it reaches the column by context
+rather than by a whitelist entry — the same way `admin-import-users` already
+reaches `phone_number` and `role`. `SYS_USER_PROFILE_EDIT_FIELDS` is
+untouched, `MANAGED_EXTENSION_EDITABLE_FIELDS.sys_user` stays `{locale}`, and
+`sys_user.manager_id` keeps `readonly: true`, so ADR-0092 D4 still holds by
+construction. Since ADR-0092 D5's amendment made Tier-1 membership imply
+self-editability, admitting the column to Tier 1 would have handed every member
+their own first-rung approver and a widening of their own `own_and_reports`
+read scope; it is not admitted.
+
+**Five refusals, every one enforced at the write** — the only manager-chain
+walkers in the open tree are single-hop, so nothing downstream catches a bad
+link: self-assignment; a link that closes a cycle (the walk is itself
+cycle-safe, so a pre-existing loop is reported rather than hung on); a chain
+past the depth cap that ADR-0057 D3's bounded rollups require; a manager
+provably outside every organization the user belongs to (beside, not instead
+of, the existing routing-time screen); and any identity whose `sys_user.source`
+is `idp_provisioned`, where the directory stays the one authoring surface.
+
+**`@objectstack/lint`** keeps the `approval-approvers-may-resolve-empty`
+advisory and its `stackWiresManagerChain` silencer — the dead end it reports
+survives the write surface, because a static check still cannot read the
+column; only its *cause* became recoverable. What changed is the remedy text,
+which named a column with no route and now names the endpoint, its body, how to
+clear the link, and what it refuses. The Approvals guide carries the same
+rewrite in prose.
+
+**Why `patch` and not `minor`.** No new exported symbol is reachable from
+either published entry: `admin-set-user-manager.ts` is deliberately not
+re-exported from `plugin-auth/src/index.ts` and is not named in the package's
+`exports` map, so none of `runSetUserManager`, `MAX_MANAGER_CHAIN_DEPTH`,
+`SetUserManagerDeps`, `SetUserManagerEngine`, `SetUserManagerResult` or
+`SetUserManagerRefusalReason` appears in the built `dist/index.d.ts`. No
+already-published payload gains a key — the endpoint's response is a new
+payload, not a new field on an old one. A new **route** is wire, and wire
+compatibility is not the grading floor.

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