Merge main into the wait-timeout retirement branch (2nd)

Same conflict, one paragraph later: #4286 appended the joins/windowFunctions
sweep to the protocol-18 rationale while CI was running here.

Both are kept and `conversionIds` stays the union. The incoming paragraph is
appended last, and its opener drops the ordinal — "The fourth of the same kind"
became "The same kind of retirement covers". Protocol 18 is collecting an active
sweep of retirements (#3963, #4052, #4196, #4286, #4158), so a positional
self-reference re-conflicts on every one of them; the ordinal-free opener does
not, and matches the "The same major retires" idiom already in the block.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Author: os-zhuang

.changeset/approval-vocabularies-derived.md

@@ -0,0 +1,46 @@
+---
+"@objectstack/spec": minor
+"@objectstack/plugin-approvals": patch
+---
+
+fix(spec,plugin-approvals): the two approval vocabularies are derived, not hand-matched (#3786)
+
+`sys_approval_request.status` and `sys_approval_action.action` spelled their
+option lists out — five values and twelve — each under a "Keep in sync with
+`ApprovalStatus` / `ApprovalActionKind` (spec/contracts)" comment, while the
+contract held the same sets as bare type unions. Seventeen strings matched by
+hand across a package boundary, with nothing checking them. They did all still
+agree; the sweep that found them (#3786) verified that verbatim before changing
+anything.
+
+Agreeing is not the same as being held, and both directions of drift are quiet:
+
+- a value the **column** accepts and the contract omits is invisible to every
+  consumer typed against the contract — the row exists and nothing can narrow it;
+- a value the **contract** declares and the column rejects surfaces only at write
+  time, on whichever tenant first reaches that transition.
+
+An audit vocabulary is a bad place for either. So the contract now publishes the
+lists as values — `APPROVAL_STATUSES` and `APPROVAL_ACTION_KINDS` — with
+`ApprovalStatus` / `ApprovalActionKind` derived from them via
+`(typeof X)[number]`, and the two columns spread the constants. The per-entry
+rationale (which action kinds move the flow, which are thread-only, why
+`returned` differs from `recalled`) moved onto the constants, where the values
+live.
+
+**New exports, no behaviour change.** The emitted option lists are byte-identical
+— verified against the built artifact before and after. Existing imports of the
+two types are unaffected; the types resolve to the same unions.
+
+`approval-vocabularies.test.ts` pins the qualifier that derivation alone cannot:
+the columns agree with the contract *while the spread is there*, and the test
+fails if either is re-inlined as a literal that has drifted. It also guards the
+guard (an unresolvable import would compare two empty lists and pass) and asserts
+the two vocabularies stay distinct, since a copy-paste pointing one column at the
+other constant would satisfy "derived from the contract" while being the wrong
+vocabulary entirely.
+
+Verified by mutation in both directions: adding a value to `APPROVAL_STATUSES`
+propagates into the built `sys_approval_request.status` options (the derivation
+is live, not a stale build), and re-inlining a drifted literal fails
+`sys_approval_request.status offers exactly the contract statuses, in order`.

.changeset/query-ast-inert-request-surface.md

@@ -0,0 +1,80 @@
+---
+"@objectstack/spec": major
+"@objectstack/plugin-security": patch
+---
+
+refactor(data)!: the QueryAST request surface stops declaring what no executor runs — `joins` and `windowFunctions` removed, six search flags and `aggregations[].filter` marked experimental, and the liveness ledger now governs the query surface (#4286)
+
+#4196 removed one declared-but-inert member from `FieldNode`. Applying the same
+method to the rest of the request surface (#4286) found 12 more members of
+`QueryAST` that no executor runs — `packages/objectql`'s `engine.ts` contains
+zero reads of any of them on the query path. This change dispositions the
+mechanical tiers and closes the gate that let the class stay invisible.
+
+**Removed (tombstoned): `query.joins` and `query.windowFunctions`.**
+
+- `joins` — no engine or driver ever read it; a query carrying it silently ran
+  as a single-table query. Related-record retrieval already has a live
+  spelling: `expand`. The orphaned `JoinNode` / `JoinNodeInput` /
+  `JoinNodeSchema` / `JoinType` / `JoinStrategy` exports are deleted with the
+  key (`data/JoinNode`, `data/JoinType`, `data/JoinStrategy` leave the
+  published JSON schemas).
+- `windowFunctions` — `find()` never applied it, so every OVER clause it
+  declared was silently dropped. The one live door is the SQL driver's own
+  `findWithWindowFunctions(object, query)` (driver-level, not on the
+  `IDataDriver` contract), and its input is a flat driver shape the spec
+  vocabulary never matched — `WindowFunctionNodeSchema` declared `field` /
+  `over` / `frame` members that door never read. The `WindowFunction` /
+  `WindowSpec` / `WindowFunctionNode` exports are deleted with the key.
+
+**FROM → TO**
+
+| Was | Now |
+| :--- | :--- |
+| `joins: [{ type: 'inner', object: 'customer', on: … }]` | `expand: { customer_id: { object: 'customer', fields: ['name'] } }` |
+| `joins` for one related column | `fields: ['customer_id.name']` (dotted path) |
+| `windowFunctions: [{ function: 'rank', … }]` in a query | `aggregations` + `groupBy`, or rankings in report/dashboard metadata |
+| OVER-clause SQL from an embedder | `sqlDriver.findWithWindowFunctions(object, { windowFunctions: [{ function, alias, partitionBy?, orderBy? }] })` |
+
+The one-line fix: **delete the key**. Both are `retiredKey()` tombstones on the
+non-strict `BaseQuerySchema`, so authoring either fails `tsc` (input type
+`never`) and a query still carrying one — even as an empty array — fails to
+parse with the prescription itself. `QueryAST` is a request shape, never stored
+in stack metadata, so there is no `os migrate meta` step: the removals are
+registered as protocol-18 **semantic** migrations (`query-joins-retired`,
+`query-window-functions-retired`), the #4196 precedent.
+
+Compat note for the REST boundary: both names remain **reserved** list-query
+parameters while the tombstones live (`retiredKey()` keeps a key in
+`keyof QueryAST`, which feeds `RESERVED_LIST_QUERY_PARAMS`), so nothing changes
+for objects with fields named `joins`/`windowFunctions` — the un-reservation
+happens when the tombstones age out, and is called out in
+`metadata-protocol`'s `QUERY_AST_KEYS` comment for whoever does it.
+
+**Marked `[EXPERIMENTAL — not enforced]` (no wire or compat impact):**
+`search.fuzzy` / `operator` / `boost` / `minScore` / `language` / `highlight`
+(the ADR-0061 expansion reads only `query` + `fields`) and
+`AggregationNode.filter` (a SQL `FILTER (WHERE …)` affordance neither the SQL
+builders nor the in-memory fallback applies). Authoring one is now a
+declaration, not a silent no-op.
+
+**Deliberately NOT dispositioned here** (they want a maintainer call, #4286
+steps 3–4): `having` (the strongest enforce candidate — `engine.aggregate()`
+currently rebuilds the driver AST without it), and `cursor` / `distinct`
+(shipped SDK producers `QueryBuilder.cursor()` / `.distinct()`; `distinct` is
+mis-wired — its only observable effect is suppressing the REST list count).
+All three are recorded `dead` with evidence in the new ledger.
+
+**The gate:** `QuerySchema` joins the liveness ledger through the gate's
+`SPEC_ONLY_SCHEMAS` override (the `webhook` precedent) as governed type
+`query` — the first governance of what *callers* write into a query rather
+than what authors write into metadata files. `packages/spec/liveness/query.json`
+classifies all 27 walked members (15 live with evidence, 7 experimental via
+describe markers, 5 dead), so the next declared-but-inert request member fails
+CI instead of needing a person to notice it.
+
+`@objectstack/plugin-security` (patch): the FLS predicate guard's
+`windowFunctions` walk is pruned — the clause no longer exists to leak through.
+The `having` and `aggregations[].filter` walks stay, deliberately: those
+members remain declared, and the guard being ready is what makes enforcing
+them later safe.

content/docs/automation/approvals.mdx

@@ -395,7 +395,11 @@ On finalization the request row gets `status: 'approved'` (or `'rejected'`),
 mirrored to the same value, and the record unlocks. The parked run resumes down
 the `approve` or `reject` branch.
 
-Statuses in full: `pending`, `approved`, `rejected`, `recalled`, `returned`.
+Statuses in full: `pending`, `approved`, `rejected`, `recalled`, `returned` —
+the `APPROVAL_STATUSES` constant in `@objectstack/spec/contracts`, which is also
+what `sys_approval_request.status` offers and what `ApprovalStatus` is derived
+from. If you add a status there, this line is a fourth copy that nothing updates
+for you.
 
 </Steps>
 

content/docs/data-modeling/queries.mdx

@@ -1,6 +1,6 @@
 ---
 title: Query Syntax Cheat Sheet
-description: One-page reference for ObjectStack QuerySchema — filters, sorts, pagination, aggregations, and joins
+description: One-page reference for ObjectStack QuerySchema — filters, sorts, pagination, aggregations, and expand
 ---
 
 # Query Syntax Cheat Sheet
@@ -387,47 +387,27 @@ on it either. Post-filter grouped results on the client until this is wired up.
 
 ---
 
-## Joins
+## Joins — removed
 
 <Callout type="warn">
-`joins` is defined in `QuerySchema` (`JoinNodeSchema`) and the SQL driver advertises
-`supports.joins: true`, but no driver's `find()` actually executes a join today — the SQL,
-in-memory, and MongoDB drivers all ignore the `joins` array (there is no `.join()`/`.leftJoin()`
-call in the SQL driver's query builder). Use `expand` for relationship traversal instead.
+`query.joins` was **removed in `@objectstack/spec` 18** (#4286, ADR-0049
+enforce-or-remove): no driver's `find()` ever executed a join — the SQL, in-memory, and
+MongoDB drivers all ignored the array, so it only ever declared a capability that did
+not run. The key is tombstoned: authoring it is a `tsc` error, and a query carrying it
+(even `joins: []`) fails to parse with the upgrade prescription. The
+`JoinNode`/`JoinType`/`JoinStrategy` exports left with it.
 </Callout>
 
-### Join Types
-
-| Type | Description |
-|:---|:---|
-| `inner` | Records with matches in both objects |
-| `left` | All records from left + matching from right |
-| `right` | All records from right + matching from left |
-| `full` | All records from both objects |
-
-### Join Strategies
-
-| Strategy | Description |
-|:---|:---|
-| `auto` | Let the engine choose the best strategy |
-| `database` | Push join to the database level |
-| `hash` | In-memory hash join |
-| `loop` | Nested loop join |
-
-### Join Example
+Use `expand` for relationship traversal — the live spelling for related records — or a
+dotted `fields` path (`'customer.name'`) for a single related column:
 
 ```typescript
 {
   object: 'order',
-  fields: ['id', 'total', 'customer.name', 'customer.email'],
-  joins: [
-    {
-      type: 'inner',
-      object: 'customer',
-      on: ['order.customer_id', '=', 'customer.id'],
-      strategy: 'auto'
-    }
-  ]
+  fields: ['id', 'total'],
+  expand: {
+    customer_id: { object: 'customer', fields: ['name', 'email'] }
+  }
 }
 ```
 
@@ -440,13 +420,7 @@ call in the SQL driver's query builder). Use `expand` for relationship traversal
   object: 'article',
   search: {
     query: 'kubernetes deployment',
-    fields: ['title', 'body', 'tags'],
-    fuzzy: true,
-    operator: 'and',
-    boost: { title: 2.0, body: 1.0 },
-    minScore: 0.5,
-    language: 'english',
-    highlight: true
+    fields: ['title', 'body', 'tags']
   }
 }
 ```
@@ -455,19 +429,20 @@ call in the SQL driver's query builder). Use `expand` for relationship traversal
 |:---|:---|:---|
 | `query` | `string` | Search text |
 | `fields` | `string[]` | Fields to search (optional — defaults to all searchable) |
-| `fuzzy` | `boolean` | Enable fuzzy matching for typo tolerance |
-| `operator` | `'and' \| 'or'` | How to combine search terms |
-| `boost` | `Record<string, number>` | Field relevance weights |
-| `minScore` | `number` | Minimum relevance score (0–1) |
-| `language` | `string` | Language for stemming/stopwords |
-| `highlight` | `boolean` | Return highlighted matches |
+| `fuzzy` | `boolean` | `[EXPERIMENTAL — not enforced]` Fuzzy matching for typo tolerance |
+| `operator` | `'and' \| 'or'` | `[EXPERIMENTAL — not enforced]` How to combine search terms |
+| `boost` | `Record<string, number>` | `[EXPERIMENTAL — not enforced]` Field relevance weights |
+| `minScore` | `number` | `[EXPERIMENTAL — not enforced]` Minimum relevance score (0–1) |
+| `language` | `string` | `[EXPERIMENTAL — not enforced]` Language for stemming/stopwords |
+| `highlight` | `boolean` | `[EXPERIMENTAL — not enforced]` Return highlighted matches |
 
 <Callout type="warn">
 Only `query` and `fields` are implemented. The engine expands `search` into a driver-agnostic
 `$and`-of-`$or`-of-`$contains` filter (ADR-0061) — `fuzzy`, `operator`, `boost`, `minScore`,
 `language`, and `highlight` are accepted by `QuerySchema` but read nowhere in
-`expandSearchToFilter()` / `normalizeSearch()`, so they have no effect. Multiple search terms
-are always AND-ed regardless of `operator`.
+`expandSearchToFilter()` / `normalizeSearch()`, so they have no effect; since #4286 their
+`.describe()` markers say so. Multiple search terms are always AND-ed regardless of
+`operator`.
 </Callout>
 
 ### Pinyin recall (Chinese deployments)
@@ -496,46 +471,36 @@ by `@objectstack/plugin-pinyin-search`) recomputes the column on demand.
 
 ---
 
-## Window Functions
+## Window Functions — removed from the request surface
 
 <Callout type="warn">
-`windowFunctions` is only reachable by calling the SQL driver's `findWithWindowFunctions()`
-method directly. `ObjectQL.find()` / `.aggregate()` and the `POST /api/v1/data/:object/query`
-route never call it, so sending `windowFunctions` through the standard client/REST query path
-has no effect.
+`query.windowFunctions` was **removed in `@objectstack/spec` 18** (#4286):
+`ObjectQL.find()` / `.aggregate()` and the `POST /api/v1/data/:object/query` route never
+routed it anywhere, so sending it had no effect. The key is tombstoned — a query carrying
+it fails to parse with the upgrade prescription — and the
+`WindowFunction`/`WindowSpec`/`WindowFunctionNode` exports left with it.
 </Callout>
 
-| Function | Description |
-|:---|:---|
-| `row_number` | Sequential row number within partition |
-| `rank` | Rank with gaps for ties |
-| `dense_rank` | Rank without gaps for ties |
-| `percent_rank` | Relative rank as percentage |
-| `lag` | Access previous row value |
-| `lead` | Access next row value |
-| `first_value` | First value in window |
-| `last_value` | Last value in window |
-| `sum` / `avg` / `count` / `min` / `max` | Running aggregations |
-
-### Window Function Example
+Window functions remain a **SQL-driver door**: `findWithWindowFunctions()`, callable
+directly on a SQL driver instance (it is not on the `IDataDriver` contract). Its input
+is the driver's own flat shape:
 
 ```typescript
-{
-  object: 'employee',
-  fields: ['name', 'department', 'salary'],
+const ranked = await sqlDriver.findWithWindowFunctions('employee', {
   windowFunctions: [
     {
       function: 'rank',
       alias: 'salary_rank',
-      over: {
-        partitionBy: ['department'],
-        orderBy: [{ field: 'salary', order: 'desc' }]
-      }
+      partitionBy: ['department'],
+      orderBy: [{ field: 'salary', order: 'desc' }]
     }
   ]
-}
+});
 ```
 
+For request-level analytics, use `aggregations` + `groupBy`, or model rankings in
+report/dashboard metadata.
+
 ---
 
 ## Distinct & Group By

content/docs/protocol/objectql/index.mdx

@@ -396,6 +396,6 @@ See [Security Protocol](/docs/protocol/objectql/security) for details.
   <Card
     title="Query Syntax"
     href="/docs/protocol/objectql/query-syntax"
-    description="Write database-agnostic queries with filters, joins, and aggregations"
+    description="Write database-agnostic queries with filters, expand, and aggregations"
   />
 </Cards>