Merge origin/main into the list-view page-mount retirement branch

os-regen artifacts: main's side taken for the one path both sides moved
(content/docs/references/ui/view.mdx); regeneration follows as its own commit.

Three hand-written conflicts resolved as semantic merges, both intents stacked:
  packages/spec/src/ui/view.zod.ts     #16577 scope docblock + the retirement's
                                       rewritten attachment note
  packages/spec/src/ui/view.test.ts    #16577 module-scoped flattenUnionIssues +
                                       the retirement's door comment
  packages/spec/src/migrations/registry.ts  #16320 and #17063 step-18 paragraphs

Co-authored-by: Claude <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01MkQhmuuJAVDjmeWNixwDDH

Author: claude

.changeset/15052-search-fields-docblock-icontains.md

@@ -0,0 +1,38 @@
+---
+'@objectstack/spec': patch
+---
+
+`search-fields.ts`'s module docblock says `$search` expands to an `$or` of `$icontains`, the operator the engine actually emits
+
+The docblock's ENGINE bullet claimed `@objectstack/objectql`'s
+`expandSearchToFilter` expands a `$search` term into an `$or` of **`$contains`**
+clauses. It has compiled to `$icontains` since objectstack#7641:
+`packages/objectql/src/search-filter.ts:23` carries the ruling verbatim — *"The
+case-insensitive operator is `$icontains`, NOT `$contains`. `$contains` is
+contractually case-SENSITIVE (#4706 Q2 = A)"* — and both return paths of
+`fieldClausesForTerm` (`:109`, `:111`) emit `$icontains`.
+
+**Why the distinction is worth a clause rather than a word swap.** `$contains`
+is contractually case-SENSITIVE, so a reader who trusted the old sentence built
+an ingress gate, a test or a driver **stricter** than the platform is — a false
+refusal, not a leak. The corrected bullet now says that in one clause, so the
+next reader of this module does not have to reconstruct it from two other
+packages.
+
+⛔ No behaviour changes. This is a module docblock; the engine has been right
+since #7641 and no accept set, authorable key or published behaviour moves.
+
+**This is shipped, which is why it carries a changeset rather than
+`skip-changeset`.** `@objectstack/spec`'s published `files[]` ships `dist`, and
+this TSDoc is emitted into `dist/data/index.d.ts` and `dist/data/index.d.mts` —
+measured on the built artifact, with the old spelling absent from all 216 built
+files afterwards and the docblock's own neighbouring sentence present at 2 as
+the lit control. `src/data/search-fields.ts` is not a `.zod.ts`, so it is not
+shipped as source; the emitted declarations are the whole of its published
+reach, and they change.
+
+The sibling INGRESS sentence two lines below — `@objectstack/metadata-protocol`
+`findData` refusing a `$searchFields` override the resolved set does not admit
+(#4254) — was measured on the same tip and is unchanged: `findData` still calls
+`assertSearchFieldsAreSearchable`, which resolves through this module's own
+`resolveSearchFieldResolution` rather than re-implementing the rule.

.changeset/15141-cluster-doc-pointer-site-urls.md

@@ -0,0 +1,39 @@
+---
+'@objectstack/spec': patch
+---
+
+`EventMetadata.cluster` and `ServiceMetadata.cluster` cite the live docs page by SITE URL, not a dead filename
+
+Both `.describe()` strings pointed at `cluster-semantics.mdx`, a page that is no
+longer in the tree — `apps/docs/redirects.mjs` has redirected
+`/docs/concepts/cluster-semantics` to `/docs/kernel/cluster` since the page was
+folded in. The section numbers still resolved, so nothing was broken for a
+reader following a link; what was broken is retrieval by filename, which finds
+nothing.
+
+These two strings are the published half. `gen:docs` copies them into
+`content/docs/references/kernel/events-core.mdx` and `service-registry.mdx`, and
+they also ship as JSON Schema `description` values under `packages/spec/json-schema/`
+and as string literals in `packages/spec/dist/`. So the citation had to become
+something a SITE reader can follow:
+
+```
+- See cluster-semantics.mdx §4.        (a file that does not exist)
++ See /docs/kernel/cluster §4.         (the address the redirect already resolves to)
+```
+
+⛔ Deliberately NOT the in-repo house style. Source comments elsewhere in the
+tree cite `` `content/docs/kernel/cluster.mdx` §N `` — a repo path, correct for a
+reader who has the repo checked out. Copying that convention into a `.describe()`
+would tell a docs-site reader to open a `content/docs/...` file they do not
+have, which is the same class of unfollowable reference pointed the other way.
+There is no in-repo precedent to copy either way: these are the only two
+`.describe()` strings in `packages/spec/src` that cite a docs page at all.
+
+The site URL is also redirect-independent — it is the redirect's own target, so
+the reference survives the redirect being retired.
+
+No accept set moves and no authorable key is added or removed: the schemas,
+their parse behaviour and their exported types are byte-identical apart from
+these two description strings. The two regenerated reference pages carry the
+same one-line change on three rows.

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

@@ -0,0 +1,49 @@
+---
+"@objectstack/service-analytics": minor
+---
+
+fix(service-analytics): a `min`/`max` over a `formula` field is typed from the formula's declared `returnType`, not described as `number` (#16236)
+
+**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
+declared `FieldSchema.returnType`:
+
+```
+FROM  {"rows":[{"first_label":"alpha","latest_due":"2026-06-01"}],
+       "fields":[{"name":"first_label","type":"number"},
+                 {"name":"latest_due","type":"number"}]}
+
+TO    {"rows":[{"first_label":"alpha","latest_due":"2026-06-01"}],
+       "fields":[{"name":"first_label","type":"string"},
+                 {"name":"latest_due","type":"time"}]}
+```
+
+Both values were strings; both descriptors said `number`, so a renderer that
+branches on the declared type never reached its textual or temporal branch.
+
+**The mapping is a TRANSLATION, not a pass-through.** `returnType` speaks the
+authoring vocabulary (`number` / `text` / `boolean` / `date`);
+`fields[].type` speaks `DimensionType` (`string` / `number` / `boolean` /
+`time` / `geo`). Two of the four words do not exist on the wire at all:
+
+| declared `returnType` | `fields[].type` |
+|:---|:---|
+| `text` | `string` |
+| `date` | `time` |
+| `number` | unchanged — the producer's `number` is already correct |
+| `boolean` | unchanged — three readings disagree on what `min`/`max` over a boolean returns |
+
+**A formula with no `returnType` is unchanged.** The key is optional — "absent
+when the type can't be proven (an ambiguous/`dyn` expression)" — and an
+unproven formula's measure column keeps the `number` it had. The absence is not
+read as an answer. That tier is written down as a row in `measureResultType`'s
+own table rather than left as an implied code path, and so is the treatment of
+a word outside the declared four: left alone, never guessed at.
+
+**For hosts wiring `AnalyticsService` directly.** `AnalyticsServiceConfig`'s
+`sourceFieldMeta` hook gains an optional fourth member on its return —
+`returnType?: string` beside `type` / `defaultCurrency` / `max`. Additive: a
+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.

.changeset/16274-initial-completion-history-guard.md

@@ -0,0 +1,23 @@
+---
+"@objectstack/service-automation": patch
+---
+
+A run whose nodes all succeeded is no longer answered `failed` — or, under `errorHandling.strategy: 'retry'`, RE-EXECUTED — because its terminal run-history write threw (#16274)
+
+`AutomationEngine.execute()` and `executeWithoutRetry()` each called `recordLog({ status: 'completed' })` from inside the `try` whose `catch` exists for **node** failures, so a throw out of a history write on a run that had already finished successfully was handled as though a node had thrown. This is the initial-execution half of the pattern fixed on the resume path in 17.4.0; that fix deliberately scoped these two sites out.
+
+**The consequence was measured, and it is a double run, not just a mislabelled one.** `execute()`'s node-failure arm ends at the retry strategy branch, which hands the false `failed` result to the retry loop; the loop reads `result.success` and therefore re-enters `executeWithoutRetry()` — the whole flow, every node, again. Driven with `maxRetries: 2`: a flow whose node always succeeded ran it **three** times and wrote three `failed` rows, unattended, inside one `execute()` call, with the node's side effects repeated each time. Controls on the same instrument: the identical flow on healthy sinks runs the node once, and a genuine node failure runs it three times (retry working correctly).
+
+**What can throw there is a host surface, not in-repo code** — which is why it could not be reproduced from inside the package and why the package owed the fix:
+
+- the run-summary line `logger.info(line, meta)`, on by default (`runSummaryLog: 'info'`) and calling a **host-injected** `Logger`. This one needs no store at all.
+- `store.recordTerminal(record)` throwing **synchronously**, before it returns a promise — the `void write.catch(...)` beneath that call only ever sees a returned promise's rejection. Both stores shipped in this package are `async` methods and cannot do it, but `SuspendedRunStore` is an exported interface whose `recordTerminal` is optional, so a host store is unconstrained. (A store returning a non-thenable escapes identically: `write.catch` is then itself a synchronous `TypeError`.)
+
+On that second variant the old code did not even answer `failed`: the node-failure arm's own `recordLog({ status: 'failed' })` threw again out of the same store and escaped `execute()` entirely — a rejected promise where `AutomationResult` is declared.
+
+What changes:
+
+- **Each completion-path history write is guarded at its own call site**, restoring the invariant that call's own documentation states: a history write must never block or break the run that produced it. The caller is told the truth — `success: true`, no `status`, the flow's `successMessage`, and a `summary` recomputed by the same pure function `recordLog` runs first — the node runs exactly once, and one `completed` row is recorded rather than `1 + maxRetries` `failed` ones.
+- **The swallowed failure is reported once per run at `error`**, with the consequence and the fix in the first line: the run completed, its terminal history row never landed, nothing retries it, and the run must not be re-run. The thrown text rides the structured slot.
+
+⛔ No `catch` arm's meaning is widened: a genuine node failure still reaches the node-failure arm, is still recorded `failed`, still carries the node's own text, and is still retried the full `1 + maxRetries` times.

.changeset/17081-dev-admin-banner-says-what-it-sees.md

@@ -0,0 +1,50 @@
+---
+'@objectstack/cli': patch
+---
+
+fix(cli): the boot banner's `🔑 Dev admin` says what that account will and will not see (#17081)
+
+`--seed-admin` (on by default in `os dev`) prints one credential, and it is the
+**only** one a first-run operator is given. It is also, by construction, the
+account with every *platform* capability and no *app-declared* one: its standing
+is `admin_full_access`, whose `systemPermissions` are `setup.access`,
+`studio.access`, `manage_users`, `manage_metadata`, `manage_platform_settings`
+and `manage_sharing` — all platform built-ins — plus the `'*'`
+view-all/modify-all record bits.
+
+So in any app that gates its apps, tabs or nav entries on
+`requiredPermissions` — the filter `/me/apps` and `/meta/app` apply, and a
+first-class platform feature the docs teach — the credential the terminal hands
+over is the account that resolves to an **empty navigation**. A downstream
+maintainer ran `pnpm dev`, signed in with it, and read the empty shell as a
+broken product. The app was correct. The banner had asserted a login and said
+nothing about its audience, and it outranks whatever the app's own README says,
+because it sits directly under the command that was just run.
+
+FROM → TO, on a boot that seeds:
+
+```
+  🔑  Dev admin: admin@objectos.ai / admin123
+      seeded on empty DB · dev only — do not use in production
++     platform admin — Setup, Studio and every record, but NO app-declared capability, so
++     an app that gates navigation on requiredPermissions may show it an empty menu; grant
++     it a permission set under Setup → Users, or sign in as an account your app seeds
+```
+
+**Nothing about the seed changes.** What the first run creates — the account,
+its address, its password, its promotion to platform admin — is a product-shape
+decision and is untouched; only the banner's words move. The three lines print
+only inside the branch that already prints the credential, so a boot that seeds
+nothing is byte-identical to before.
+
+Dim continuation lines rather than a warning, deliberately: ADR-0115's
+`OS_ALLOW_DEV_PLUGIN` amendment excluded the dev-admin seed from that hazard set
+because "a warning about a non-event spends the attention the real ones need".
+That exclusion is kept — this qualifies an event that just happened, on the line
+that already announces it, and adds no new line where there was none.
+
+The route the sentence names is asserted against the declarations that make it
+reachable, not re-spelled: `SETUP_APP.requiredPermissions` is a subset of what
+this account holds, the `Users` entry is ungated, and the `sys_user` detail page
+carries the "Grant permission set" related list. A rename on any of those reds
+the pin instead of leaving the banner pointing at nothing.

.changeset/17166-object-grid-export-options-describe-members.md

@@ -0,0 +1,52 @@
+---
+'@objectstack/spec': patch
+---
+
+`ComponentPropsMap['object-grid'].exportOptions` names all five members the renderer reads, not two
+
+The entry is `z.unknown()`, so nothing about this key is parsed, refused or
+stripped: a member that does not exist draws no error and has no effect, and a
+member that does exist cannot be discovered from the schema. That makes the
+`.describe()` string the entire account of the key's shape rather than a summary
+of an enforced one — and it projects straight into
+`content/docs/references/ui/component.mdx`, which is what an author (or a
+generating model, ADR-0033) reads.
+
+It named two members, `formats` and `streaming`. The only renderer reads five.
+
+Measured at the `.objectui-sha` pin `53ded82bf7a494f54e344e19099dbf00854b8694`
+— objectui `packages/plugin-grid/src/ObjectGrid.tsx`, through the
+`schema.exportOptions` expression and the `exportConfig` local bound to it, with
+objectui's own scanner (`ObjectGrid.exportOptionsKeys.test.ts`, whose
+comment/string stripping is what stops a prose mention of a key being counted as
+a read): `formats` 2 read sites, `streaming` 2, `maxRecords` 1,
+`includeHeaders` 1, `fileNamePrefix` 1, and an absent-name control
+(`zzzNotAMember`) 0 on the same instrument — which is what makes those five
+counts readings rather than a matcher that matches anything. The same instrument
+answers the same five, with the same per-member counts, at objectui
+`3fbdd4a2dae1`, so the set is not an artefact of the pin's age.
+
+The three missing members are `maxRecords`, `includeHeaders` and
+`fileNamePrefix`. An author reading the old string learned that
+`exportOptions` takes `{ formats, streaming }` and had no way to reach the other
+three short of reading the renderer's source — the shape objectstack#8010
+closed for this same key one layer out, when `streaming` was read for releases
+while no schema declared it.
+
+⛔ The key is unchanged: it stays `z.unknown()` and no accept set moves in either
+direction. Giving `exportOptions` a real shape is a separate and much larger
+change with its own review requirements; this is the docs half only.
+
+The new list is not restated in prose that can drift on its own. A pin holds the
+describe string's member enumeration equal to the members
+`ListViewExportOptionsSchema` declares — the spec's own five-key declaration of
+this same authoring block, reached through `ListViewSchema.exportOptions`'s
+object branch and itself derived from that same read set. Both spellings reach
+one renderer, so narrowing or widening the declared block now reds the
+`z.unknown()` prose instead of leaving it quietly behind: the declared side has
+parse failures to catch drift, this side had nothing. The pin also records that
+the key is unvalidated today, so the day it grows an accept set is a deliberate
+decision rather than a silent one.
+
+`content/docs/references/ui/component.mdx` is regenerated from the string
+(`gen:schema` then `gen:docs`) and carries the same one-line change.

.changeset/action-confirmation-gate-enforced.md

@@ -0,0 +1,28 @@
+---
+"@objectstack/runtime": minor
+"@objectstack/mcp": minor
+---
+
+fix(runtime,mcp): `action.ai.requiresConfirmation` is ENFORCED at the AI-facing action door — an unconfirmed call is refused, and `run_action` grows the `confirm` member that satisfies it (#15942)
+
+**Behaviour change — read this if any of your actions declare `ai.requiresConfirmation: true`.** An AI-facing invocation of such an action (`invokeBusinessAction`, reached from the MCP `run_action` tool) is now REFUSED unless the request carries the confirmation member. A call that succeeded before starts answering `428 ACTION_CONFIRMATION_REQUIRED`, and nothing dispatches: the action body does not run, and the subject record is not even read.
+
+FROM → TO, for a caller of a gated action:
+
+```
+run_action({ actionName: 'archive_lead', recordId: 'lead_1' })                  // was: ran
+run_action({ actionName: 'archive_lead', recordId: 'lead_1', confirm: true })   // now: required
+```
+
+The refusal is machine-readable so the retry is mechanical rather than guessed — `error.details` carries `{ actionName, objectName?, confirmationMember }`, and `confirmationMember` echoes the member's exact spelling (`AI_ACTION_CONFIRMATION_MEMBER`, `@objectstack/spec/contracts`). The `run_action` tool schema advertises `confirm` as an optional boolean, so an agent discovers the retry from the tool definition rather than from prose.
+
+**What is NOT gated**, because this narrows a published accept set and the narrowing is deliberately as small as the author's own declaration:
+
+- Only the DECLARED flag gates. `ai.requiresConfirmation: true`, set by the action's author, and nothing else. The wider `list_actions` heuristic — `mode: 'delete'` / `variant: 'danger'` on an action whose author declared nothing — still reports `requiresConfirmation: true` to advise a client, and still does NOT refuse. An explicit `ai.requiresConfirmation: false` never refuses.
+- Only the boolean `true` confirms. `'true'`, `1` and `false` are not attestations.
+- Only the AI-facing doors. The enforced set is the doors that enforce `ai.exposed` — today `invokeBusinessAction` via MCP `run_action`. REST `/actions` is not `ai.exposed`-gated and sits outside this gate.
+- `list_actions` is unchanged.
+
+**A gate, not a queue.** Nothing is parked, nothing is held for an operator, and there is no resume path: a refused call simply did not run, and the caller confirms with its human and retries. And `confirm: true` is an unverifiable caller claim — an agent that always sends it bypasses the gate. The gate makes FORGETTING loud; it does not prove a human.
+
+Why it is worth the break: the flag was read once and consumed once, to fill a field of the `list_actions` summary. It stopped nothing. That is the failure ADR-0049 retired `tool.requiresConfirmation` for — "a SAFETY flag that is merely accepted is false compliance" — reappearing on the very key the retirement's own ledger entry told authors to move to. The contract this implements landed in `@objectstack/spec` first (#16293).