Merge remote-tracking branch 'origin/main' into claude/issue-11979-default-org-admin-grant

Author: claude

.changeset/23050-s13e-meta-object-state-published-move.md

@@ -0,0 +1,10 @@
+---
+'@objectstack/rest': patch
+---
+
+The `/meta` object state-machine read and the published read live in their own modules, with no route, handler or answer changed
+
+Clause-②: no (a move: the two routes per base, their place in the `/meta` registration order, every handler, every response and the anonymous-deny gate in front of them are unchanged, and the published declarations are byte-identical)
+
+- `RestServer#registerMetadataEndpointsInner` keeps its name, docblock, place and head, its per-item registrar included. The statement that registers `GET {metaPath}/object/:name/state/:field` (the legal next states of an object field's state machine) moved, re-indented, to `packages/rest/src/meta-object-state-routes.ts`, and the block that registers `GET {metaPath}/:type/:name/published` (an item's published version) moved to `packages/rest/src/meta-item-history-routes.ts`, beside the history family. The method calls each at its old position, inside the umbrella's guarded registration. The state read still answers to `api.enableMetadata` alone, and the published read still registers through the per-item registrar, so the `metadata.endpoints.item` switch gates the same mounts.
+- Nothing to do for a consumer: no export of the package entry, no route, no configuration key and no response moved.

.changeset/24243-plugin-auth-hook-refusal-codes.md

@@ -0,0 +1,15 @@
+---
+"@objectstack/plugin-auth": patch
+---
+
+fix(plugin-auth): the organization, invitation-placement and phone-OTP hook refusals carry their ADR-0112 codes
+
+Clause-②: no
+
+Eight refusals thrown from plugin-auth's better-auth hooks answered with `message` alone, so a client could only show or match English prose. Each now carries a `code` it can branch on, and keeps its HTTP status.
+
+- `POST /auth/organization/create`: the reserved `__global__` id or slug answers 400 `VALIDATION_ERROR`. Where the deployment's effective tenancy posture enforces no organization wall (`/auth/config` publishes `features.multiOrgEnabled: false`), creating an organization answers 403 `ORGANIZATION_CREATION_DISABLED`.
+- `POST /auth/organization/invite-member` with placement intent (`businessUnitId` and `positions`): with no delegated-administration runtime to authorize it, 403 `INVITE_PLACEMENT_UNSUPPORTED`; refused by the delegated-administration gate, 403 `INVITE_PLACEMENT_OUTSIDE_ISSUER_SCOPE`.
+- `POST /auth/organization/update` with a new slug: while the organization has an active environment (any environment that is neither archived nor failed), 403 `ORGANIZATION_SLUG_LOCKED_BY_ACTIVE_ENVIRONMENTS`. Its message no longer says environments "still reference" the organization or tells you to rename their hostnames: the guard reads no hostname, and archiving those environments is the remedy. When the guard's own read cannot answer, 503 `SERVICE_UNAVAILABLE`.
+- Phone OTP sends (`/auth/phone-number/send-otp`, `/auth/phone-number/request-password-reset`): the per-number limit and the deployment's daily SMS quota both answer 429 `RATE_LIMIT_EXCEEDED`. It is one code for both walls, so a caller still cannot tell which budget it hit. The body is better-auth's flat `code` and `message`, with no `Retry-After` header.
+- **One behaviour change:** a placement check that fails before the gate reaches a verdict (the issuer's grants could not be read from the store) now answers 503 `SERVICE_UNAVAILABLE`, not a 403 scope refusal carrying the store's message. No invitation is created either way.

.changeset/24289-inprocess-hook-ctx-title.md

@@ -0,0 +1,9 @@
+---
+'@objectstack/runtime': patch
+---
+
+fix(runtime): a hook's inline `handler` function is handed the same `ctx.title(field?)` a hook `body` gets, so a source boot (`@objectstack/verify`'s `bootStack(config)`, `os serve` over an `objectstack.config.ts`) answers it as `objectstack dev` does (#24289)
+
+Clause-②: no
+
+A source boot runs a hook's inline `handler` in-process, and the accessor existed only in the sandbox a `body` runs in. So a hook calling `await ctx.title()` or `await ctx.title('account_id')` (a lookup column) answered on `objectstack dev` and an artifact boot, and under `bootStack(config)` refused every write with `TypeError: ctx.title is not a function`. `bindAppArtifactHandlers` now hands each inline handler function a view of the engine's hook context that answers `title` through the same accessor the sandbox installs: the same two forms, the same served formula title and related-record read on the context's own `ctx.api`, and `null`, never the record's id, when there is no title. Every other read and every write goes to the engine's context unchanged, and that context gains no key. A `handler` that names a function (the deprecated string form) is not covered by this change.

.changeset/24316-formula-hop-family-refusal.md

@@ -0,0 +1,19 @@
+---
+'@objectstack/objectql': minor
+'@objectstack/lint': minor
+---
+
+fix(objectql)!: the one-hop read through a reference never reads a stored-metadata-body table, and the lint refuses that read where it is written
+
+Clause-②: no (narrowing)
+
+<!-- adr-0087: not-required (no-migration-prescription) No stored metadata moves and nothing is converted: what narrows is a served value (a formula field or a validation rule that reads through a reference into a stored-metadata-body table) and an author-time verdict on such an expression; no spec key, export, option, object definition or stored shape is added, removed, renamed or re-shaped, so there is nothing for `objectstack migrate meta` to rewrite. The other categories are closed on facts: both packages publish (not unpublished); no ADR-0087 id is named or touched (not registered or already-registered); nothing exported is removed (not runtime-export-retired) and no type changes (not type-surface-only or runtime-interface-only). -->
+
+**BREAKING** (a served-set narrowing), shipped as `minor` under the launch-window convention for breaking changes.
+
+The tables of the stored-metadata-body family (`STORED_METADATA_BODY_OBJECTS`) are projected or refused at every door that serves them. The one-hop read a formula field and a validation rule share (`resolveOneHopRelated`) was an ordinary engine read, which the family's projection does not reach.
+
+- **`@objectstack/objectql`.** A hop whose target is a family table is not read, whichever authority the hop is read under. A formula field reading through it is `null` with its reason, on every read, write response and `serveFormulaField` call (the seam a hook body's `ctx.title()` reads through). A validation rule reading through it has no verdict, so the write it judges is refused. The answer is the one an unreadable related record gets, so it says nothing about the row. A hop into any other object is unchanged.
+- **`@objectstack/lint`.** A formula field's `expression`, or a validation rule's hydrated `condition`, that reads through a reference into a family table is an error, with the prescription. `os validate`, `os build` and the object save door run the same pass, so the author learns it at save rather than from a `null`.
+
+What to do. Remove the read through the reference. Stored metadata is read through the metadata API (`GET /api/v1/meta/:type/:name`), where its body is projected. Reading the reference field itself (the stored id) is unchanged.

content/docs/api/data-api.mdx

@@ -23,7 +23,7 @@ Query records with filtering, sorting, selection, and pagination.
 | `top` | query | Max records to return. No default — omitting it returns all matching records. |
 | `skip` | query | Offset |
 | `expand` | query | Comma-separated list of relations to eager-load. Must name a reference field (`lookup` / `master_detail` / `user` / `tree`) — otherwise `400 INVALID_FIELD`. |
-| `search` | query | Full-text search term, scanned case-insensitively across the object's searchable fields (its declared `searchableFields`, or a text-like auto-default when none are declared). |
+| `search` | query | Full-text search term, scanned case-insensitively across the object's searchable fields (its declared `searchableFields`, or a text-like auto-default when none are declared). When that set is empty — no `searchableFields` entry names a stored field, and the auto-default finds none — a non-blank term is `400 INVALID_FIELD`, never every row. |
 | `searchFields` | query | Comma-separated subset of the searchable fields for `search` to scan — narrows the scan, never widens it. A name outside the searchable set is `400 INVALID_FIELD`. |
 
 > **Note:** OData-style `$`-prefixed parameters (`$filter`, `$select`, `$orderby`, `$top`, `$skip`, `$expand`, `$count`, `$search`) are also accepted directly on this same endpoint as aliases — they're normalized internally to the parameter names above. There is no separate standalone OData endpoint.
@@ -156,14 +156,17 @@ corrupts something the earlier axes do not:
 | `?search=alpha&searchFields=no_such_field` | `400 INVALID_FIELD` |
 | `?search=alpha&searchFields=amount` | `400 INVALID_FIELD` — real field, but not searchable |
 | `?search=alpha&searchFields=project_id.name` | `400 INVALID_FIELD` — search scans this object's own columns; mirror the related title instead (see below) |
+| `?search=alpha` on an object with no searchable field (two lookups and a `formula` title, say) | `400 INVALID_FIELD` — nothing to scan; declare a stored field searchable or mirror the title (see below) |
 | `groupBy: ["status"]` | one bucket per status value |
 | `groupBy: ["no_such_field"]` | `400 INVALID_FIELD` |
 | `aggregations: [{function:"sum", field:"amount", alias:"total"}]` | the real total |
 | `aggregations: [{function:"sum", field:"no_such_field", alias:"total"}]` | `400 INVALID_FIELD` |
 | `aggregations: [{function:"count", alias:"n"}]` | `count(*)` — the one legitimate field-less form |
 
-- **`searchFields`** — the only parameter whose failure changed which **rows**
-  came back. An unknown name used to be dropped, and an override left empty
+- **`search`** and **`searchFields`** — the only parameters whose failure
+  changed which **rows** came back. A `search` over an object with nothing to
+  scan added no predicate, so every row came back as if every row matched. An
+  unknown `searchFields` name used to be dropped, and an override left empty
   fell back to scanning *every* searchable column: a parameter that exists
   only to **narrow** a search failed by **widening** it. Three causes get
   three messages, because the fixes differ: a name that is no field (a typo in

content/docs/api/error-catalog.mdx

@@ -159,6 +159,10 @@ aggregation's own `filter`), a sort, a `groupBy`, an `aggregations[].field`, a
 `searchFields` entry, or an `expand` entry's own filter or sort at any depth. Such a
 field is never returned on a generic read, so it cannot be queried by either — the
 refusal names the object that declares it. Query by another field.
+A non-blank `search` is refused (`param: 'search'`), not answered with every row,
+when the object's resolved search set is empty: no `searchableFields` entry names a
+stored field, and the default search scans none (`internal: true` fields never
+count). Declare one that does, or mirror a composed title onto a stored text field.
 Off the request path the same code answers `backfillSummaryNulls`'s
 `recomputeUndefinedOnEmpty` (`os migrate summary-nulls
 --recompute-undefined-on-empty object.field`) when an entry is not a roll-up

content/docs/data-modeling/queries.mdx

@@ -477,7 +477,10 @@ dotted `fields` path (`'customer.name'`) for a single related column:
 
 `search` takes the query text; the server resolves which fields to search from object
 metadata (ADR-0061). Pass `searchFields` to narrow that set — it is intersected with what
-the object allows, so it can only narrow, never widen.
+the object allows, so it can only narrow, never widen. When the object allows nothing —
+no `searchableFields` entry names a stored field, and the default search scans none
+(`internal: true` fields never count) — a non-blank `search` is refused with
+`400 INVALID_FIELD` instead of answering every row, engine calls included.
 
 ```typescript
 {

content/docs/data-modeling/schema-design.mdx

@@ -102,7 +102,10 @@ To control exactly which fields are matched, set `searchableFields` on the objec
 Queries then pass a top-level `$search` parameter to match across `searchableFields`
 (e.g. `{ $search: 'acme' }`); a request may narrow the set with
 `$searchFields`. When `searchableFields` is unset, search falls back to the
-name/title field plus short-text fields.
+name/title field plus short-text fields. When neither leaves a stored field to scan — a
+junction object of lookups with a `formula` title, say — a list search is refused
+`400 INVALID_FIELD` rather than answered with every row, and global search skips the
+object; mirror the title onto a stored text field, as below.
 
 #### Searching by a related record's title — mirror the value
 

content/docs/protocol/kernel/error-handling.mdx

@@ -624,7 +624,7 @@ knows which object was addressed.
 
 The [error catalog's `INVALID_FIELD` entry](/docs/api/error-catalog#invalid_field) carries
 the authoritative cause text — it enumerates every read axis this one code answers on
-(`select`, `expand`, `searchFields`, `groupBy`, `aggregations[].field`) and the
+(`select`, `expand`, `search`, `searchFields`, `groupBy`, `aggregations[].field`) and the
 off-request `backfillSummaryNulls` case.
 
 ### Resource Errors
@@ -738,8 +738,9 @@ have let them count the dependents; `dependentObject` is named either way. Treat
 #### `RATE_LIMIT_EXCEEDED`
 **HTTP Status:** 429  
 **Meaning:** Too many requests, rate limit exceeded  
-**Envelope:** nested — built by the inbound rate limiter, which sits **ahead of every
-route**, so it is never flat whichever family you were calling
+**Envelope:** nested from the inbound rate limiter, which sits **ahead of every
+route**, so its refusal is never flat whichever family you were calling. The phone-OTP
+send walls answer this code too, flat (see the end of `QUOTA_EXCEEDED` below)
 
 **Example:**
 ```json
@@ -835,10 +836,14 @@ Don't feed this 429 to a retry loop that only checks the status, such as the
 `RATE_LIMIT_EXCEEDED` example above. It has no `Retry-After` to wait on, and every
 retry before `resetAt` is refused again.
 
-Other quota enforcement answers with its own code rather than this one
-(the SMS daily quota answers `TOO_MANY_REQUESTS`). For request pacing, the code
-on the wire is `RATE_LIMIT_EXCEEDED` above, whose `Retry-After` header and
-`retryAfterSeconds` / `resetAt` details are what a client acts on.
+Other quota enforcement answers with a code other than this one. The phone-OTP send
+walls (`/auth/phone-number/send-otp` and `/auth/phone-number/request-password-reset`), a
+phone number's own limit and the deployment's daily SMS quota, both answer 429
+`RATE_LIMIT_EXCEEDED`: one code for both, so a caller cannot tell which budget it hit.
+That body is better-auth's flat `code` and `message`, with no `Retry-After` header and no
+`details`. At the inbound rate limiter, the code on the wire is `RATE_LIMIT_EXCEEDED`
+above, whose `Retry-After` header and `retryAfterSeconds` / `resetAt` details are what a
+client acts on.
 
 ### Server Errors
 

content/docs/protocol/objectql/query-syntax.mdx

@@ -1124,7 +1124,11 @@ plus short-text/enum fields), so naming a field outside that set can never widen
 search — and over the REST/protocol ingress it is `400 INVALID_FIELD` outright (#4254),
 because the engine-side intersection alone used to drop the unknown name and fall back to
 scanning the full searchable set. Internal callers reaching `engine.find()` directly keep
-the tolerant intersection. Multiple whitespace-separated terms are AND-ed and
+the tolerant intersection, but not a search with nothing to scan: when no
+`searchableFields` entry names a stored field and the auto-default finds none
+(`internal: true` fields never count), the engine itself refuses a non-blank `search`
+with `400 INVALID_FIELD` (`param: 'search'`) on `find`, `findOne`, `count` and
+`aggregate` alike, rather than answering every row. Multiple whitespace-separated terms are AND-ed and
 fields are OR-ed. Case sensitivity comes from the operator the expansion emits, not
 from the expansion: it emits `$icontains`, which ignores **ASCII case** by the
 rule in [Case Sensitivity](#case-sensitivity) above. So a user typing `acme` does