Merge remote-tracking branch 'origin/main' into claude/issue-5079-delete-overlay-listing

Author: claude

.changeset/cel-classify-error-by-code.md

@@ -0,0 +1,57 @@
+---
+'@objectstack/formula': patch
+---
+
+fix(formula): `classifyError` grades a CEL fault by error class + code, never by the message (#6223)
+
+`EvalResult.error.kind` is author-facing — `@objectstack/objectql`'s `cel-fault`
+puts it in front of the author as `` `${kind}: ${first line}` `` and
+`packages/rest` re-emits it as the HTTP body's `reason`. cel-js embeds the
+author's own **source line** in `message` (`formatErrorWithHighlight`), so a
+classifier that regex-matches that text is matching text the author writes.
+PR #6202 closed the `ParseError` arm this way and left `type` / `runtime` on the
+keyword table pending a per-code audit. This is that audit, and its verdict is
+that the table goes entirely.
+
+Measured on cel-js 8.0.0 — one `no such overload` **evaluation** fault, four
+field names, three wrong answers:
+
+```text
+record.status        > 1  ->  runtime   (right)
+record.parse_status  > 1  ->  parse     (wrong)
+record.syntax_mode   > 1  ->  parse     (wrong)
+record.type_code     > 1  ->  type      (wrong)
+```
+
+`parse` is the inverse of the #6133 misdirection: the expression is
+syntactically perfect and failed on the data, and the author was told to go fix
+an expression that has nothing wrong with it.
+
+`classifyError` now reads only structured contract:
+
+- `ParseError` -> `bounds` when `code === 'limit_exceeded'`, else `parse`
+  (unchanged, from #6202);
+- `EvaluationError` -> `type` for the one declaration-class code
+  (`unknown_variable`, the root identifier is not bound in this scope at all),
+  else `runtime`;
+- anything that is not a cel-js error -> `runtime`.
+
+Two findings from the audit worth recording. First, the residual keyword arm was
+**not** dormant: `matches()` is an ObjectStack stdlib binding over `new
+RegExp(...)`, so an uncompilable pattern escapes as a native `SyntaxError` whose
+message echoes the pattern — and the pattern can come off the row, not just out
+of the source. `matches(record.name, record.re)` with `re = "type("` was
+graded `type`; with `"Exceeded maxAstNodes("` it was graded `bounds`. A data
+value was picking the error kind. Second, there is deliberately no `TypeError`
+arm: cel-js raises that class only from its non-evaluating `TypeChecker`, which
+runs only inside `Environment#check`, and that method catches it and *returns*
+`{ valid: false, error }`. The check-time `TypeError -> type` mapping already
+lives in `celEngine.compile`, which reads that object.
+
+Six evaluate-time codes change verdict from `type` to `runtime`
+(`int_conversion_error`, `uint_conversion_error`, `double_conversion_error`,
+`invalid_index_type`, `heterogeneous_list_element`,
+`invalid_comprehension_range`). Each is a fault decided against the row; every
+one of them was graded `type` only because cel-js happens to use the word "type"
+in its prose (`int() type error: cannot convert to int`). Every evaluate-time
+code the engine can reach now has a fixture pinning its `kind`.

.changeset/kernel-hook-dispatch-shared.md

@@ -0,0 +1,58 @@
+---
+"@objectstack/core": patch
+---
+
+refactor(core): one implementation per hook-dispatch flavour, plus a paired-pin gate (#5282)
+
+`ObjectKernel` does not extend `ObjectKernelBase` — it is a standalone
+production kernel with its own `hooks` map, and only `LiteKernel` extends the
+base. Lifecycle-hook dispatch therefore existed **twice**, with no shared code
+path: the base's `triggerHook` (isolating) / `triggerHookOrThrow` (propagating) /
+`context.trigger` on one side, and `ObjectKernel`'s private
+`triggerShutdownHookIsolating` / `context.trigger` on the other. The two
+isolating loops printed the same `Hook handler failed: kernel:shutdown` line
+because someone typed it twice.
+
+That seam produced three consecutive bugs, each the same shape — one hook name
+meaning opposite things on the two kernels: `kernel:ready` (#5170),
+`kernel:bootstrapped` / `kernel:listening` (#5257, where a swallowed
+`server.listen()` failure let a process print "✅ Bootstrap complete" with
+nothing listening), and `kernel:shutdown` in the other direction (#5274, where
+one bad handler skipped every `destroy()`).
+
+**No behaviour change.** The two dispatch flavours move verbatim into an
+internal module, `packages/core/src/hook-dispatch.ts`, which both kernels now
+call:
+
+- `dispatchHookIsolating` — a failing handler is logged as
+  `Hook handler failed: <name>` and the remaining handlers still run.
+- `dispatchHookPropagating` — the first failure escapes unwrapped and the
+  handlers behind it are skipped.
+
+Every call path keeps the flavour, the log wording and the trace line it had
+before, including the one asymmetry inside the propagating flavour:
+`PluginContext.trigger` has never emitted the `Triggering hook: <name>` trace on
+either kernel, so it still does not. The kernels' two `hooks` maps are
+deliberately **not** unified, and `ObjectKernel` deliberately does **not** gain a
+base class — both were considered and ruled out of scope.
+
+How "no behaviour change" was proved: the paired kernel pins from #5170 / #5257 /
+#5274 pass untouched, and deleting the shared dispatcher's error log now turns
+**both** kernels' test files red from a single edit — a property the hand-mirrored
+copies could not have (editing `ObjectKernel`'s private loop could never turn
+`lite-kernel.test.ts` red).
+
+Shared dispatch cannot cover the residual two-maps seam, so the pairing of the
+tests is now a gate rather than a convention: `pnpm check:kernel-hook-pairs`
+(`scripts/check-kernel-hook-pairs.mjs`, wired into the ESLint job) requires every
+`kernel:*` hook dispatched in `packages/core/src` to be named in a test title in
+**both** `kernel.test.ts` and `lite-kernel.test.ts`, and fails naming the hook
+and the side that lacks it. A fifth lifecycle hook can no longer arrive paired on
+one kernel only.
+
+Also pinned, deliberately unchanged: `kernel:shutdown` has two dispatch paths
+with different flavours on both kernels — the kernel's own teardown isolates,
+while a plugin calling `ctx.trigger('kernel:shutdown')` by hand propagates.
+Nothing in the repo triggers it by hand today, so this is dormant; it is now a
+documented fact with a named test on each side rather than a surprise found at
+teardown.

.github/workflows/lint.yml

@@ -448,6 +448,32 @@ jobs:
       - name: Engine test-double contract gate
         run: pnpm check:engine-double-contract
 
+      # Paired kernel-hook pin gate (#5282, from #5170 / #5257 / #5274). The two
+      # kernels — ObjectKernel (production) and LiteKernel (vitest / serverless /
+      # edge) — run the same plugin code and the same hook vocabulary, but do NOT
+      # share a class: ObjectKernel does not extend ObjectKernelBase, so each
+      # keeps its own hooks map. #5282 shared the two dispatch LOOPS
+      # (packages/core/src/hook-dispatch.ts); this gate covers what sharing them
+      # cannot: three consecutive bugs were all "one hook name means opposite
+      # things on the two kernels" (kernel:ready swallowed on one side and fatal
+      # on the other; kernel:listening swallowing a failed server.listen() behind
+      # a cheerful "Bootstrap complete"; kernel:shutdown skipping every destroy()
+      # in the other direction), and each was caught by a human noticing the
+      # asymmetry. What held the kernels together afterwards was a pair of
+      # hand-written tests — a convention, not a mechanism: a fifth lifecycle
+      # hook gets no pairing automatically and nothing goes red when it is
+      # missing. So every kernel:* hook DISPATCHED in packages/core/src must be
+      # named in a test title in BOTH kernel.test.ts and lite-kernel.test.ts, and
+      # a missing pair fails naming the hook and the side that lacks it.
+      # Subscriptions (ctx.hook) are deliberately not dispatches. Static AST over
+      # five files, no build needed, so it belongs in this job. Runs its own
+      # --self-test first: the detector can be broken while every hook is fine,
+      # and a scan that stops matching would report OK while reading nothing
+      # (#4868's family). Measured against main's corpus before being pinned
+      # here: 4 dispatched hooks, 0 problems.
+      - name: Paired kernel-hook pin gate
+        run: pnpm check:kernel-hook-pairs
+
       # Resume-authority declaration gate (#5561, from #3823). The #3801 resume
       # gate keys on the SUSPENDED NODE, so it covers a pausing node type exactly
       # when that type's author remembered to declare `resumeAuthority`. #3823 is

content/docs/api/data-api.mdx

@@ -128,6 +128,7 @@ corrupts something the earlier axes do not:
 | `?search=alpha&searchFields=title` | scans only `title` |
 | `?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) |
 | `groupBy: ["status"]` | one bucket per status value |
 | `groupBy: ["no_such_field"]` | `400 INVALID_FIELD` |
 | `aggregations: [{function:"sum", field:"amount", alias:"total"}]` | the real total |
@@ -143,6 +144,18 @@ corrupts something the earlier axes do not:
   `searchableFields`), and a `searchableFields` entry that names no field (a
   stale declaration — the bug is on the object, and clients that echo the
   declaration verbatim are told so).
+
+  A **dotted path** (`project_id.name`) is the typo case with its own hint:
+  `search` scans this object's own columns, so a related record's column can
+  never be a search target, and the search axis does not resolve traversal the
+  way `$select` / `$orderby` / `$filter` do. To search by a related record's
+  title, **mirror** that title into a stored field on this object and declare
+  *that* field searchable — a task list searched by project name carries a
+  `project_name` text column on `task`, maintained on write and listed in
+  `task.searchableFields`. It must be a stored field: a `formula` field is
+  virtual, so no driver has a column for `$contains` to scan. Cross-object
+  search paths are rejected by design, not pending — see
+  [Schema Design → Searching by a related record's title](/docs/data-modeling/schema-design#searching-by-a-related-records-title--mirror-the-value).
 - **`groupBy`** — an unknown column projected `null` for every row, so all
   rows fell into **one bucket** whose count is the true row count:
   structurally perfect, indistinguishable from a column that really holds a

content/docs/data-modeling/queries.mdx

@@ -513,6 +513,30 @@ that exists to narrow a search, silently widening it. Internal callers reaching
 `engine.find()` directly are unaffected.
 </Callout>
 
+### Searching by a related record's title — mirror the value
+
+`search` scans **the queried object's own columns**. A dotted path
+(`project_id.name`) is not a search target — unlike `fields` / `sort` / `filters`,
+the search axis does not resolve traversal, and a dotted entry is refused, not
+silently dropped:
+
+```text
+Unknown field 'project_id.name' on object 'task'. '$searchFields' narrows which
+columns 'search' scans, so a name the object does not declare cannot narrow
+anything — and the engine used to drop it and scan the default columns instead,
+answering a NARROWER search with a WIDER one. 'search' scans this object's own
+columns; a related record's column cannot be a search target.
+```
+
+The answer is a **mirror field**: copy the related record's title into a stored
+field on this object and declare *that* field searchable. A task list searched by
+project name gets a `project_name` text column on `task`, maintained on write and
+listed in `task.searchableFields`. It has to be a **stored** field — a `formula`
+field is virtual, so no driver has a column for `$contains` to scan. Cross-object
+search paths are rejected by design, not pending. Full recipe (the hooks that keep
+the mirror fresh, and the lint wording) in [Schema Design → Searching by a related
+record's title](/docs/data-modeling/schema-design#searching-by-a-related-records-title--mirror-the-value).
+
 ### Pinyin recall (Chinese deployments)
 
 When pinyin search is enabled (`OS_SEARCH_PINYIN_ENABLED` — auto-on when the stack's

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

@@ -103,6 +103,95 @@ Queries then pass a top-level `$search` parameter to match across `searchableFie
 `$searchFields`. When `searchableFields` is unset, search falls back to the
 name/title field plus short-text fields.
 
+#### Searching by a related record's title — mirror the value
+
+`$search` scans **the queried object's own columns**. A dotted path such as
+`project_id.name` is not a search target: unlike `$select` / `$orderby` /
+`$filter`, the search axis does not resolve traversal, and a dotted entry is
+refused rather than silently dropped (#4254). That refusal is deliberate, not a
+missing feature — cross-object search paths are rejected by design.
+
+The declarative answer is a **mirror field**: copy the related record's title
+into a stored field on *this* object, and make that field the search target.
+To let users search a task list by project name:
+
+```typescript
+// `project_name` is a stored, denormalized copy of the parent's title.
+{
+  name: 'task',
+  enable: { searchable: true },
+  fields: {
+    name:         { type: 'text', required: true },
+    project_id:   { type: 'lookup', reference: 'project' },
+    project_name: { type: 'text', label: 'Project Name' },   // ← the mirror
+  },
+  searchableFields: ['name', 'project_name'],
+}
+```
+
+`?search=apollo` now expands to `name $contains 'apollo' OR project_name
+$contains 'apollo'` — one single-table scan, on every driver, with no traversal.
+If the object declares no `searchableFields` at all, a `text` mirror is picked up
+by the auto-default anyway; declare the set explicitly when you want to pin it.
+
+<Callout type="warn">
+**The mirror must be a stored field — a `formula` field does not work.** A
+`formula` field is *virtual*: no driver materializes a column for it, so a
+`$contains` predicate against one has nothing to scan (the SQL driver would emit
+a `WHERE` over a column that does not exist). A CEL formula also only reads this
+record's own fields (`record.<field>`), so it cannot fetch the related title in
+the first place. Nothing catches the mistake for you — `searchableFields` admits
+any field the object declares, so a formula entry passes both lint and the
+ingress gate and then just never matches.
+</Callout>
+
+**Keeping the mirror fresh.** A mirror is denormalized data, only as current as
+whatever maintains it. Two write paths have to be covered:
+
+| When | What maintains the mirror |
+|:-----|:--------------------------|
+| A task is created, or re-pointed at another project | `beforeInsert` / `beforeUpdate` hook on `task` — read the parent's `name` for the incoming `project_id` and stamp `project_name` |
+| A project is renamed | `afterUpdate` hook on `project` — re-stamp `project_name` on that project's tasks |
+
+Rows written by a path that bypasses hooks (bulk import, direct SQL) need a
+one-off backfill. See [Hooks](/docs/automation/hooks) for the hook shapes.
+
+**The errors you get if you try the dotted path.** Both the lint and the runtime
+send you to the same fix, so either message is greppable back to this section.
+
+`os validate` reports `searchable-field-unknown`:
+
+```text
+searchableFields entry "project_id.name" is not a field on object "task". The
+declaration is stale: searching it can never match, and the engine silently
+drops it — leaving a narrower search than declared, or the auto-default set once
+every entry is dropped.
+
+hint: 'search' scans this object's own columns, so a related record's column
+cannot be a search target — expand the relation and search the related object,
+or copy the value onto a formula field here. Clients echo this declaration
+verbatim as the '$searchFields' override, so a stale entry becomes a 400
+INVALID_FIELD on list search (#4254), not just a quietly narrowed one.
+```
+
+(That hint's "text/formula" family of wording is loose — only the **stored**
+half works; see the callout above.)
+
+A request that sends the dotted path is `400 INVALID_FIELD`:
+
+```text
+Unknown field 'project_id.name' on object 'task'. '$searchFields' narrows which
+columns 'search' scans, so a name the object does not declare cannot narrow
+anything — and the engine used to drop it and scan the default columns instead,
+answering a NARROWER search with a WIDER one. 'search' scans this object's own
+columns; a related record's column cannot be a search target.
+```
+
+If the dotted path is in the object's own `searchableFields` (so clients echo it
+back verbatim), the same 400 arrives under its stale-declaration wording
+instead: `Field 'project_id.name' on object 'task' is declared in
+'searchableFields' but does not exist.`
+
 ---
 
 ## Field Types & Configuration

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

@@ -887,6 +887,32 @@ a user typing `acme` does not find `ACME Corp`. Only `select` / `status` option
 `[EXPERIMENTAL — not enforced]` markers (#4286): the schema accepts them, the
 expansion ignores them.
 
+#### Searching by a related record's title — mirror the value
+
+Search targets are **this object's own columns**. A dotted path is not one of
+them: `searchFields: ['project_id.name']` is refused at the ingress rather than
+dropped, because the search axis does not resolve traversal the way `fields`,
+`sort` and `filters` do:
+
+```text
+Unknown field 'project_id.name' on object 'task'. '$searchFields' narrows which
+columns 'search' scans, so a name the object does not declare cannot narrow
+anything — and the engine used to drop it and scan the default columns instead,
+answering a NARROWER search with a WIDER one. 'search' scans this object's own
+columns; a related record's column cannot be a search target.
+```
+
+The declarative answer is a **mirror field**: copy the related record's title
+into a stored field on this object and declare *that* field searchable — a task
+list searched by project name carries a `project_name` text column on `task`,
+maintained on write and listed in `task.searchableFields`, so the expansion stays
+a single-table `$or` of `$contains`. The mirror must be **stored**: a `formula`
+field is virtual, no driver materializes a column for it, and a `$contains`
+against one has nothing to scan. Cross-object search paths are rejected by
+design, not pending — see [Schema Design → Searching by a related record's
+title](/docs/data-modeling/schema-design#searching-by-a-related-records-title--mirror-the-value)
+for the maintenance hooks.
+
 ### Joins — removed (#4286)
 
 `query.joins` was **removed in `@objectstack/spec` 17** (#4286, ADR-0049

content/docs/ui/views.mdx

@@ -103,7 +103,7 @@ A List View controls how a collection of records is presented. It supports multi
 | `data` | `ViewData` | optional | Data source configuration (defaults to the `object` provider) |
 | `filter` | `array` | optional | Base filter criteria |
 | `sort` | `array` | optional | Sort configuration |
-| `searchableFields` | `string[]` | optional | Fields included in search |
+| `searchableFields` | `string[]` | optional | Fields the toolbar search scans — **narrows** the object's set, never widens it (ADR-0061). Entries must be the object's **own** columns: a lookup (`project_id`) or a dotted path (`project_id.name`) is refused, and every toolbar search on the list then returns `400 INVALID_FIELD` (#4254). To search by a related record's title, [mirror it into a stored field](/docs/data-modeling/schema-design#searching-by-a-related-records-title--mirror-the-value) on the object and list that |
 | `grouping` | `object` | optional | Row grouping configuration |
 | `pagination` | `object` | optional | Pagination settings |
 | `selection` | `object` | optional | Row selection mode |