Merge origin/main into claude/issue-18386-template-option-default

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

Author: claude

.changeset/19518-picklist-wording.md

@@ -0,0 +1,7 @@
+---
+'@objectstack/spec': patch
+---
+
+docs(spec): the `picklist` field key's description, two doc comments and the refusal of `picklist` with `options` no longer say that the reference is resolved and its options served (#19518)
+
+Clause-②: no

.changeset/20234-liveness-ledger-provenance-anchors-4b.md

@@ -0,0 +1,15 @@
+---
+'@objectstack/spec': patch
+---
+
+Notes in the `field` liveness ledger and sentences in the ledger README that cited a tracker number which no longer resolves now either cite a commit in this repository or say in words what the number stood for
+
+Clause-②: no
+
+Eleven citations in the `field` ledger's notes and twenty-nine in `liveness/README.md` pointed at
+a GitHub issue or pull request that no longer exists, so they led nowhere. Each one now either
+names the commit that did or recorded what the number pointed at or, where the number alone
+carried the meaning, says that meaning in words. The `liveness/` ledgers and their README ship in
+this package's tarball, which is why this is a release note at all. Prose only: no row's status,
+evidence, proof, producer or date changes, no README table row or heading is added, removed or
+renamed, and no schema, export or runtime behaviour changes.

.changeset/20694-object-grid-description-empty-state-keyboard-navigation.md

@@ -0,0 +1,17 @@
+---
+'@objectstack/spec': minor
+---
+
+The `object-grid` page block now declares `description`, `emptyState` and `keyboardNavigation`, so a page that authors them validates clean instead of having each reported as a prop the block does not declare (#20694).
+
+Clause-②: yes (widening)
+
+- **`description`** — an `I18nLabel` (a string, or an inline locale map): one line of help text the grid draws above its rows, resolved against the display locale.
+- **`emptyState`** — `{ title?, message?, icon? }`, what the grid draws instead of an empty table. It is the list view's own empty-state shape, now exported as `EmptyStateSchema` (author type `EmptyState`) and taken by reference on both `list-view` and `object-grid`, so the two cannot drift apart.
+- **`keyboardNavigation`** — a boolean, marked `[EXPERIMENTAL — not enforced]`: arrow-key cell navigation on the WAI-ARIA grid pattern, on by default when `editable` is set. No renderer reads it yet, so authoring it changes nothing today.
+
+Nothing that parsed before is refused now. The `object-grid` row still refuses every key it does not declare, and the list view's `emptyState` accepts exactly the values it accepted before the shape was extracted. One refusal message is reworded: an `action` or `button` key inside an empty state is still refused and still points at the list view's `addRecord` block, now phrased so that it also reads true on `object-grid`, which has no add-record block.
+
+On `object-grid`, write `emptyState.title` and `emptyState.message` as plain strings for now: the grid renderer draws both as they are and does not yet resolve an inline locale map there the way it resolves `description`, so a map in either member fails to render.
+
+Where it surfaces: the component-props gate (`os validate`, `os build`, `os lint`) no longer reports these three keys on an `object-grid` node, and the published JSON Schema for `ObjectGridProps` describes them.

.changeset/20771-wall-clock-one-rule.md

@@ -0,0 +1,14 @@
+---
+'@objectstack/core': patch
+---
+
+`isUninterpretableTemporalComparand` reads a bare wall clock on a `time` column by the spec's `ClockTimeValueSchema` (`@objectstack/spec/data`), not by a private copy of it (#20771)
+
+Clause-②: no
+
+The wall-clock half of core's `time` rule (`HH:MM[:SS[.fraction]]`, hours 00 to 23, minutes and seconds 00 to 59, no time zone) was spelled twice: once as the spec's `ClockTimeValueSchema`, the stored form of a `time` value, and once as a private regex in `@objectstack/core`. The two admitted the same strings, but nothing tied them together, so an edit to either one changed one side only. Core now asks the spec schema. Every caller of `isUninterpretableTemporalComparand('time', …)` therefore answers from the rule the spec's `time` default gate uses: the engine's temporal-comparand door, the analytics comparand check, the record validator's `time` arm and the import's `time` coercion.
+
+Unchanged:
+
+- Every string gets the verdict it got before. Measured over 8,655,360 generated strings: 8,640 read by both the old regex and the schema, the rest refused by both, 0 answered differently.
+- An instant, a number or a `Date` on a `time` column is judged as before.

.changeset/20807-analytics-json-dimension-refused.md

@@ -0,0 +1,19 @@
+---
+"@objectstack/service-analytics": minor
+---
+
+fix(service-analytics)!: a cube or dataset dimension on a structured-JSON field is refused with `INVALID_FIELD` / 400 at the analytics door, before any SQL is built
+
+Clause-②: no (narrowing)
+
+<!-- adr-0087: not-required (no-migration-prescription) a refusal of a grouping TARGET at the analytics door: a `dimensions` entry, or a bucketed `timeDimensions` entry, whose column is a declared json, composite, repeater, record, location, address or vector field. No authorable key, spelling, export or stored shape moves (the door module is internal; `@objectstack/service-analytics` exports nothing new and nothing less, and `CubeSchema`, `DatasetSchema` and the analytics query body keep parsing every member), and no stored row is read or rewritten. The grouping had no shared meaning to preserve (one group per serialized document on SQLite, a 500 on PostgreSQL), and which scalar part of the document a caller meant to group on is not something a ledger entry can rewrite. The other categories are closed on facts: the package publishes (not `unpublished`); no ADR-0087 id covers a grouping target (not `already-registered`); and the change is runtime behaviour, not a declaration (not `runtime-interface-only` / `type-surface-only`). -->
+
+**BREAKING**: this narrows what the analytics query doors accept as a dimension. A cube dimension, or a dataset dimension, whose column is a declared field of the structured-JSON class (`json`, `composite`, `repeater`, `record`, `location`, `address`, `vector`) is refused before either strategy builds a statement, when it groups the result: a `dimensions` entry, or a `timeDimensions` entry with a `granularity`. The column is judged where it is declared: on the cube's object, or, for a dotted path such as a dataset dimension over `account.hq`, on the object the cube's declared join for that path names. It holds on `POST /api/v1/analytics/query`, on its dry run `POST /api/v1/analytics/sql`, and on `POST /api/v1/analytics/dataset/query`, on every driver. It ships as `minor` under the launch-window convention for accept-set narrowings. No export or published type changes.
+
+**What an author sees now.** `400 INVALID_FIELD`, naming the member as the request wrote it (the cube dimension, or the dataset dimension), the column it groups by, the object and the column's declared type, saying the query was not run, and naming the route: group by a field that stores one scalar value, storing the part of the document you group on in a field of its own. The thrown error carries `member`, `param` (`dimensions` or `timeDimensions`), `cube`, `field` and `object`.
+
+**Why a refusal.** A JSON document is no group key the SQL dialects share. Measured through `POST /api/v1/analytics/query` over three rows with a different document each, on the service `AnalyticsServicePlugin` composes over a real engine: SQLite answered 200 with one group per serialized document, and PostgreSQL 16 answered 500 `DATABASE_ERROR`. A dataset dimension over a joined object's `json` field answered the same two ways through `POST /api/v1/analytics/dataset/query`. The native-SQL strategy compiled the `GROUP BY` itself, so the engine's own refusal of a structured-JSON `groupBy` never saw the query; the engine-aggregate strategy did reach that refusal, but named the engine's `groupBy[0]` position rather than the member the caller wrote. The class is `@objectstack/spec/data`'s `STRUCTURED_JSON_TYPES`, the one the engine's refusal reads. No producer groups by such a field: no cube or dataset dimension in the example apps names one.
+
+**Who is affected.** A dashboard, report or caller that grouped an analytics query by a structured-JSON field on SQLite and read one group per serialized document as real groups. On PostgreSQL the same query was already a 500.
+
+**Unchanged.** A dimension on any other type; a `timeDimensions` entry with no `granularity`, which bounds a range and groups nothing; measures (this door judges only the members that group); a dotted dimension path the cube declares no join for, whose object is not a declaration; a member naming a column the object does not have, which keeps its existing `INVALID_FIELD` answer first; and a host that wires no `sourceFieldMeta`, where the column's type cannot be read.

.changeset/20860-page-size-entry-advisory.md

@@ -0,0 +1,25 @@
+---
+'@objectstack/spec': patch
+---
+
+fix(spec): the `ui-object-grid-page-size-positive-integer-refused` migration entry states what the platform does with a stored `object-grid` page size of `0` — the page saves and loads, and the finding is advisory on the CLI
+
+Clause-②: no
+
+**`ui-object-grid-page-size-positive-integer-refused` (protocol 18).** The entry's acceptance
+criterion said that a stored page whose `object-grid` node carries `pageSize: 0` "is refused on
+its next authoring-path save with a per-key issue at `pagination.pageSize`". Nothing on the
+metadata save path judges a page component's `properties`. `PageComponentSchema.properties` is an
+open record, and the one judge of the `ComponentPropsMap` row is the component-props gate, an
+advisory rule that runs on the CLI only. Measured through `saveMetaItem`, the call behind
+`PUT /api/v1/meta/page`: such a page saves (`success: true`, and the result carries no `advisories` member), is stored as an
+active row and reads back with `pageSize: 0` intact. On the same page, `os validate`, `os build`
+and `os lint` each report one advisory `component-props-invalid` finding at
+`properties.pagination.pageSize` and no error. The criterion now says exactly that. It also names
+the `pageSizeOptions` entry and the flat `pageSize` shorthand, which are reported the same way at
+their own paths.
+
+Text only: no entry id, conversion or matching logic changes, and `os migrate meta` rewrites
+exactly what it rewrote before. The generated migration registry carries the corrected text. The
+sibling entry `object-grid-default-filters-rule-array` already stated the advisory-only outcome
+and is unchanged.

.changeset/20861-host-sign-in-handoff.md

@@ -0,0 +1,36 @@
+---
+'@objectstack/plugin-auth': minor
+---
+
+feat(plugin-auth): a host declares its own sign-in handoff route with `hostSignInHandoff`, and the `no_sign_in_account_at_boot` boot report stops calling that deployment a dead end (#20861)
+
+Clause-②: yes (widening)
+
+`AuthPluginOptions` gains one option, `hostSignInHandoff?: boolean` (default
+`false`). The HOST that constructs the plugin sets it when it signs people in
+through a handoff route of its own: a route that is not a login-page provider
+and that creates the session without writing a `sys_account` row. A hosted
+kernel whose owner signs in through the control plane is the case it is for.
+That owner can still sign in when the login page shows no platform sign-in
+button:
+
+```ts
+new AuthPlugin({ /* … */ hostSignInHandoff: true });
+```
+
+With it declared, human `sys_user` rows and zero `sys_account` rows are that
+deployment's normal state. The boot report then logs the shape at `debug` and
+names `hostSignInHandoff` as the reason. It no longer logs an `error` saying
+nobody can sign in. The option's only reader is that boot report.
+
+- It is a declaration, not a detection. The option is the only way to set it:
+  there is no environment variable or setting. Nothing infers it from an
+  environment's name, from a control plane's platform-SSO flag, or from missing
+  rows.
+- The login page is not changed. `getPublicConfig()` returns the same value with
+  or without the option, and no provider is registered.
+- Set it only where the host really serves such a route. On a deployment with
+  no such route, the option turns the error for a deployment nobody can sign in
+  to into a quiet `debug` line.
+- A deployment that does not declare it gets the same report as before. That
+  includes every self-hosted deployment with no delegated sign-in path.

.changeset/20864-precedence-loader-set.md

@@ -0,0 +1,17 @@
+---
+'@objectstack/service-automation': minor
+---
+
+fix(automation): boot-time flow precedence takes which same-named flow is the packaged one from the package loader's set, not from the flow definitions' own provenance (#20864)
+
+Clause-②: yes (widening)
+
+When several flow definitions share one name at startup, the automation plugin arms one of them and shadows the rest: a flow authored in the deployment wins over the packaged flow of that name (ADR-0005). Which contender counts as the packaged one is now the answer of the set of flows a managed package's loader registered. That is the same answer the ADR-0126 §7.3 subflow guards, the arming gate and the activation switch read since #20761. The package provenance a flow definition carries is kept for display only.
+
+- `resolveFlowPrecedence(items, logger?, packagedFlowOwner?)` and `describeFlowContender(item, packagedFlowOwner?)` take the reader as a new optional last argument, typed `PackagedFlowSource` (the reader `AutomationEngine.setPackagedFlowSource` takes). `AutomationServicePlugin` passes the engine's own `packagedFlowOwner` for you.
+- A definition that claims a package's provenance for a name no package loaded ranks as a flow of the deployment. The shadowing record (`getShadowedFlows()`, and the startup warnings) no longer names that package as its source.
+- With no reader, no contender is packaged. That is the engine's own answer when no reader is attached.
+- Two contenders that both rank as the deployment's keep the order they were listed in. The package id orders packaged contenders only, as before.
+- A startup whose registry the package loader and the stored-flow hydration filled arms the same flows as before: those entries already agree with the loader's set.
+
+**If you call `resolveFlowPrecedence` or `describeFlowContender` yourself:** pass the loader's-set reader as the last argument, for example `(name) => engine.packagedFlowOwner(name)`. Without it no contender ranks as packaged.

content/docs/deployment/self-hosting.mdx

@@ -540,6 +540,17 @@ first thing to look for — and note that it asks only whether *an* account row
 exists, so a row you wrote yourself silences it whether or not anyone can
 actually authenticate with it.
 
+The same shape is logged at **debug** instead, under the same token and naming
+the reason, when the deployment has a sign-in path that needs no `sys_account`
+row of its own: SSO-only mode (`OS_AUTH_SSO_ONLY` or `ssoOnlyMode`), a
+configured social or OIDC provider, enterprise SSO with at least one registered
+identity provider, or a host that constructs `AuthPlugin` with
+`hostSignInHandoff: true` because it signs people in through a handoff route of
+its own. A deployment with none of these still reports at **error**.
+`hostSignInHandoff` is a statement by the code that serves such a route, not a
+way to quiet the report: set on a deployment without one, it hides exactly the
+dead end this section describes.
+
 **The recovery is out of band, and it is one row.** Write a pending invitation
 directly against the store the deployment reads, then have that person register
 through the ordinary sign-up endpoint — the invitation carve-out admits that

content/docs/references/data/field.mdx

@@ -75,7 +75,7 @@ const result = CurrencyConfigSchema.parse(data);
 | **accept** | `string[]` | optional | Permitted upload types for media fields, as MIME types or extensions (e.g. ["image/*", ".pdf"]). Offered to the file picker AND enforced on write. |
 | **maxSize** | `integer` | optional | Maximum permitted file size in BYTES for media fields. Enforced on write against the stored file size, not just checked in the browser. |
 | **options** | `{ label: string; value: string; description?: string; color?: string; … }[]` | optional | Static options for select/multiselect |
-| **picklist** | `string` | optional | Name of a shared `picklist` whose options this field offers — instead of `options`, never with it. Option types only (select, radio, multiselect, checkboxes, tags). The server resolves the reference: the field clients read carries the resolved `options`. |
+| **picklist** | `string` | optional | Name of a shared `picklist` whose options this field offers — instead of `options`, never with it. Option types only (select, radio, multiselect, checkboxes, tags). |
 | **reference** | `string` | optional | Target object name (snake_case) for lookup/master_detail fields. Required for relationship types. Used by $expand to resolve foreign key IDs into full objects. On a `tree` field it is optional and, if given, must be the declaring object's own name — the object schema refuses any other target. |
 | **referenceVia** | `string` | optional | Declares this text field as the id half of a polymorphic pointer pair (ADR-0052 §5 ActivityPointer): the value is a record id of the object named by the SIBLING FIELD this key names — e.g. `record_id` with `referenceVia: 'object_name'`. The sibling must be a declared field on the same object holding an object machine name. Text fields only; mutually exclusive with `reference` (a static and a per-record target contradict). Enforced today at seed load: the value resolves as a natural key against the object the sibling column names, and an unresolvable pointer is refused loudly instead of stored verbatim. Adds no referential integrity or $expand behavior. |
 | **deleteBehavior** | `Enum<'set_null' \| 'cascade' \| 'restrict'>` | optional (default: `"set_null"`) | What happens if referenced record is deleted |