Merge remote-tracking branch 'origin/main' into claude/issue-24289-inprocess-hook-ctx-title

Author: claude

.changeset/24282-ceremony-null-org-guard.md

@@ -0,0 +1,21 @@
+---
+'@objectstack/cli': patch
+'@objectstack/runtime': patch
+'@objectstack/plugin-auth': minor
+---
+
+Clause-②: yes (widening)
+
+fix(cli,runtime): the 17 → 18 organization-ownership upgrade of a single-posture database that holds no organization leaves no row without one, the boot the ceremony prescribes writes nothing before it is refused, and a ceremony that did not verify is never served (ADR-0131 D3, D10)
+
+A 17.x single-posture install whose seed ran before any organization existed holds rows of organization-owned objects with `organization_id` NULL and an empty `sys_organization`. Upgrading it took this path: the ceremony's attribution checkpointed itself done at zero rows; the boot its rewrite step asks for created the Default Organization and let the inline seed stamp some rows before it refused; the second `--apply` did not run attribution again, dropped the columns and recorded discrepancies with `verified_at` NULL; and `os start` then served that database.
+
+- **The ceremony creates the Default Organization (`@objectstack/cli`).** Under the `single` posture, on a database that holds no organization and rows no anchor names, `os migrate organization-ownership` plans those rows as the Default Organization's and says so in a plan warning (`defaultOrganizationCreatedByApply: true` in the plan file). `--apply` creates it before its first write, through plugin-auth's boot invariant (the row a single-posture boot creates), and gives it every such row. A run that cannot create it — a boot without the auth family that declares `sys_organization` — blocks at attribution, naming why, instead of attributing nothing and certifying. Nothing is created under a walled posture, or when the database holds organizations.
+- **The ceremony names the Default Organization as the boot does (`@objectstack/cli`).** Under `single` it is the organization with `slug = 'default'`, else the sole organization whatever its slug — the boot invariant's and the tenancy service's definition (ADR-0093 D3). Before, the plan required `slug = 'default'`, so a database whose only organization had another slug kept its unanchored rows NULL through the ceremony while v18 derives every owner from that organization. Several organizations, none of them `default`, still name none, and their rows are reported. In the plan file (the command's own output, not a published schema) `defaultOrganization.slug` is now that organization's own slug, no longer always `'default'`.
+- **A checkpointed attribution runs again (`@objectstack/cli`)** whenever the plan derives an owner for rows still NULL: a row the operator made attributable since, or one an earlier run found no Default Organization for. It writes only where `organization_id` is NULL, so no owner already written is derived again. A database left by an earlier release's ceremony in that state is completed by re-running `--apply`.
+- **The boot guard judges before any plugin writes (`@objectstack/runtime`, `@objectstack/plugin-auth`).** `OrganizationOwnershipBootGuardPlugin` judges in its own `start()`, after the engine's schema sync (the column the rewrite step waits for is still added) and before every plugin that writes rows at start: `AppPlugin` (the inline seed), `AuthPlugin` and the identity-objects plugin (the Default Organization) name it (`com.objectstack.organization-ownership-boot-guard`) in `optionalDependencies`. A refused boot leaves every row as it found it.
+- **A ceremony that did not verify is refused (`@objectstack/runtime`).** With no table left in the v17 shape, a boot whose `adr-0131-organization-ownership` marker exists and is not verified — the post-check found rows the ceremony has not carried — is refused with `ORGANIZATION_OWNERSHIP_MIGRATION_REQUIRED`, naming the re-run. A database with no marker (a fresh one) boots as before.
+- **The refusal now arrives as a `cause` (`@objectstack/runtime`).** A failed `start()` is reported by the kernel as its own error ("Plugin … failed to start"), with the plugin's error as its `cause`. A host that composes the guard and inspects the boot error asks `isOrganizationOwnershipBootRefusal` of each `cause` down the chain: asked of the kernel's own error it now answers `false`. `assertOrganizationOwnershipMigrated(engine)` still throws the refusal itself. `os serve` and `os dev` read it from the chain.
+- **One new export (`@objectstack/plugin-auth`, `minor`).** `ensureDefaultOrganizationExists(ql, options?)` — the Default Organization's boot invariant, find-or-create under `single` — for the ceremony, so the organization it creates is the row a single-posture boot creates, from one producer. A host composing a kernel still never calls it: `AuthPlugin` and the identity-objects plugin keep the invariant on every boot. No other package entry changes.
+
+Unchanged: the ceremony's steps, fates and refusals otherwise; a walled posture's unattributable rows (reported, never assigned); the boot of a fresh or verified database; and every plugin's order on a kernel that does not compose the guard. Repairing a database whose organization-scoped seed load already inserted twins of NULL-organization rows is an operator's data repair.

.changeset/24309-approval-current-step-label.md

@@ -0,0 +1,11 @@
+---
+"@objectstack/spec": minor
+---
+
+feat(spec): `ApprovalRequestRow` declares `current_step_label`, the `sys_approval_request` column's own name for the step's label
+
+Clause-②: yes (widening)
+
+- **The member.** `ApprovalRequestRow` (`@objectstack/spec/contracts`) gains an optional `current_step_label?: string` beside `step_label`. It names the declared `sys_approval_request.current_step_label` column: the Approval node's authored label as it stood when the request reached the step. A page bound to `sys_approval_request` names the object's declared fields, and `step_label` is not one, so a served row that carries this member lets such a page list the step by its label instead of by `current_step`, the node's machine id.
+- **Nothing moves.** `step_label` stays, at the same shape and with the same value, so no reader changes. The member is optional, so every existing implementer and every row built without it still conforms. It is a member of a TypeScript interface: no Zod schema and no runtime accept set changes.
+- **Its producer.** `@objectstack/plugin-approvals`' request read mapping is the producer; serving the member there is that package's own change.

docs/adr/0079-record-display-name.md

@@ -7,6 +7,7 @@
 - **Builds on**: [ADR-0078](./0078-no-silently-inert-metadata.md) (author-time completeness must not be cloud-only), [ADR-0061](./0061-record-search-architecture.md) (`$search` field resolution reads the display field)
 - **Precedent for**: [ADR-0085](./0085-object-semantic-roles-over-surface-hint-blocks.md) (`compactLayout` → `highlightFields` follows this ADR's alias mechanics "exactly"), [ADR-0098](./0098-pinyin-search-companion-column.md) (the search companion column is fed by this ADR's resolved display field)
 - **Consumers**: `@objectstack/spec` (`data/display-name.ts`, `data/object.zod.ts`, `data/search-fields.ts`, `ai/solution-blueprint.zod.ts`), `@objectstack/objectql` (registry materialization seam, `$search` expansion, search companion), `@objectstack/metadata-protocol` (REST `$searchFields` ingress gate), `@objectstack/lint` (`validate-record-title`, `data-model-rules` R9), `@objectstack/platform-objects` and the first-party plugins/services (41 explicit `nameField:` designations), the `objectstack-data` / `objectstack-formula` skills
+- **Addenda**: [2026-10-18 (#24197) — a formula title reads one hop through a reference, and is not sortable or searchable](#addendum-2026-10-18-24197--a-formula-title-reads-one-hop-through-a-reference-and-is-not-sortable-or-searchable)
 
 ---
 
@@ -335,3 +336,79 @@ the 2026-06-28 discussion.
   gate and a query engine disagreeing about what is searchable.
 - **Accept `primaryField` as an additional tolerated alias.** Rejected
   explicitly by the maintainer in #6326 (D9).
+
+---
+
+## Addendum (2026-10-18, #24197) — a formula title reads one hop through a reference, and is not sortable or searchable
+
+Records ruling 6245544505 (letter A, direction (a), on `objectstack-ai/cloud#2925`),
+shipped by #24274 (`d537a318b`) and #24307 (`1bf5f6e17c`). It states what is on
+`main` after those two changes and decides nothing more; no section above is edited.
+The ruling, verbatim:
+
+> The formula read path preloads one hop of the referenced fields a formula
+> names (page-batched, as validation rules do); lint admits one hop and refuses
+> two; a title formula over lookups sorts and searches by its stored value or is
+> declared unsortable — written as an ADR-0079 note.
+
+**The read path** (`find`, `findOne`, and the insert and update responses;
+`packages/objectql/src/engine.ts`):
+
+1. A formula field reads ONE hop through a reference field (`lookup`,
+   `master_detail`, `user`, `tree`), as `record.FIELD.RELATED`. The read path
+   preloads the related fields the formula names once per page, with one batched
+   read per reference field and never one per row, under the reader's own
+   permissions.
+2. A related record that is missing, or that the reader may not read, leaves the
+   formula `null` with a reported reason, never a computed fallback; the reason
+   does not say which of the two held. An empty reference is not a missing
+   record: the formula is evaluated over the empty value.
+3. A second hop, and a reference read both through and as a plain value, are
+   refused by the lint (`traversal-multi-hop`, `traversal-bare-and-traversed`)
+   and read `null` with the same reason at run time. A related object's own
+   formula that reads a hop of its own reads `null` when it is itself read as a
+   hop.
+4. Field-level security on the carrying object's own reference column does not
+   stop the hop: formulas are computed before the field mask is applied to the
+   result, as for any own column a formula reads. The control for a related name
+   a reader may not see is field-level security on the formula field itself.
+
+**Hook bodies** (`packages/runtime/src/sandbox/body-runner.ts`, the hook face):
+
+5. `ctx.title()` evaluates the object's title formula over the in-flight record
+   state the hook fires on, and serves its one hop the way a read does: one
+   batched read per reference field, on the body's own `ctx.api` channel. That
+   is the channel's identity (SYSTEM under `runAs: 'system'`) and its open
+   transaction's connection. So a title over lookups names the related records
+   the in-flight foreign keys point at, and a related record that channel may
+   not read, a missing one, or a second hop leaves the title `null`, as the REST
+   read of the same record shows no title.
+6. A channel that cannot read (a `runAs: 'user'` hook whose trigger resolved no
+   user) serves no hop: a title over the record's own columns resolves, and a
+   title over a reference answers `null`.
+7. Field-level security on the title field itself is not applied to
+   `ctx.title()`.
+8. `ctx.title('FIELD')` answers the related record's title exactly as its
+   `findOne` served it, that record's own one-hop title included.
+
+**Sort and search — the ruling's "declared unsortable" arm:**
+
+9. A formula value, a composite title over lookups included, is stored nowhere;
+   it is computed on each read. A sort by it is refused (`400 INVALID_SORT`). A
+   search cannot reach it: a request's `searchFields` naming it is refused
+   (`400 INVALID_FIELD`), a `searchableFields` entry naming it is dropped, and
+   the auto-default search set never includes it. An object that needs to sort
+   or search by its composite title must store the value in a field of its own,
+   written when its sources change.
+
+**What this qualifies above, without editing it:**
+
+- The first bullet of [Alternatives considered](#alternatives-considered) says a
+  text formula `nameField` is something the server *can* return and query. For
+  a title formula over lookups, the server returns it (items 1 and 5) but cannot
+  sort or search by it (item 9).
+- D1 lists a text `formula` among the "real STORED" title fields. It is a
+  declared field of the object, but no column holds its value (item 9).
+- The surfaces this addendum describes are the engine read path and the
+  hook-body title accessor. It makes no statement about any other consumer of
+  a record's title.