@lotics/app-sdk 0.46.1 → 0.47.0

package/docs/queries.md

@@ -0,0 +1,909 @@
+# Queries — the query engine authoring reference
+
+Every read a custom-code app performs is a **named query**: a fixed AST template declared in
+`package.json#lotics.queries`, validated and compiled at deploy, and invoked by alias via
+`useQuery` / `useInfiniteQuery` / `usePaginatedQuery` (see [data_fetching.md](./data_fetching.md)
+for the hook-side contract). This document is the authoring reference for the query engine
+itself: the node kinds, the source expressions, the per-field-type operator support, filters and
+params, search, cross-table composition, server-side shaping, runtime refinement, and the
+engine's hard limits. Read it before writing any non-trivial query — the engine is deliberately
+a small closed surface, and knowing what composes (and what doesn't) up front saves hours.
+
+---
+
+## 1. The model
+
+### Declaration
+
+Queries live in the app's `package.json` under `lotics.queries` — an alias → declaration map:
+
+```jsonc
+{
+  "lotics": {
+    "queries": {
+      "openOrders": {
+        "ast": {
+          "kind": "project",
+          "from": {
+            "kind": "from_table",
+            "table_id": "tbl_orders",
+            "filter": { "node_type": "condition", "field_key": "status",
+                        "operator": "has_any_of", "value": ["opt_open"] }
+          },
+          "columns": ["order_code", "customer", "total", "created"]
+        }
+      },
+      "orderByCode": {
+        "ast": { /* … a filter with "{{params.code}}" … */ },
+        "params": { "code": { "type": "text" } }
+      }
+    }
+  }
+}
+```
+
+- **`ast`** — a `QueryNode` tree (the 11 node kinds below). It may embed `{{params.<name>}}`
+  tokens in **value positions only**.
+- **`params`** — a typed param schema. Param types reuse the workflow-input vocabulary
+  (`text`, `number`, `boolean`, `date`, `datetime`, `email`, `select`, `member`, `record_link`,
+  `date_range`, `file`, `json`, `object`, `array`); each param may set `required: false`
+  (default is required) and `description`. Nesting is capped at depth 8.
+- Aliases must be valid JS identifiers (`useQuery("openOrders")` and codegen depend on it).
+
+`lotics app deploy` syncs this map to the server. The **server holds the canonical template**;
+the app never sends a raw AST over the wire. This is the exposure model: a public app can read
+exactly what its author's queries project — params fill declared value holes and can never
+widen the query's reach (a token in a `table_id` or field-key position fails deploy validation).
+
+### What deploy validates
+
+Deploy fails — with the compiler's own message, never raw SQL/Postgres text — when any alias:
+
+1. isn't a valid identifier, or the declaration isn't `{ ast, params? }`;
+2. references `{{params.x}}` without declaring param `x` (typos can't silently widen);
+3. doesn't parse as a `QueryNode` **as the raw template** (the runtime parses the stored
+   template before substitution, so a template that only parses after substitution would fail
+   every run);
+4. doesn't parse after typed placeholder substitution (this is what catches a param token in a
+   structural position);
+5. references a table outside the app's workspace (including link-extraction targets and
+   filter-traversal targets);
+6. fails the output-schema pass — unknown field/column references, duplicate or reserved output
+   names, union misalignment, join collisions or type-incompatible ON columns, invalid
+   aggregate-operation × input-type combinations, window-illegal operations, uncastable type
+   overrides, `writable_target` on a computed column;
+7. fails to **compile to SQL** — several rejections exist only in the compiler (the expression
+   allowlist, link extraction over a composed parent, derived-filter operators with no
+   translation). Deploy compiles every query so these fail at deploy, not at first run;
+8. has optional params and the **pruned** shape (all optional params omitted) fails any of the
+   above — each omitted optional param executes a pruned variant of the template, and the
+   all-params shape compiling doesn't prove the pruned one does. Deploy validates both.
+
+What deploy **cannot** catch: data-dependent failures (a statement timeout on a huge unindexed
+scan, the file-presign ceiling) — those surface at run time as clean, safe errors (§10).
+
+### Execution
+
+`useQuery(alias, params)` → the server: validates the caller's params against the declared
+schema (missing required param → 400), **prunes** filter conditions gated on omitted optional
+params (§6), interpolates the rest, wraps the result in the caller's runtime
+filter → sort → limit nodes (§9), resolves IAM scoping, compiles to one SQL statement, and
+executes it inside a bounded transaction.
+
+- **Authority**: the query runs under the **app owner's** principal, not the viewer's. Data
+  scoping is the author's job — see [security.md](./security.md). `is_current_member`
+  conditions bind the signed-in viewer (the *viewed* member under "View as").
+  **Warning:** on an anonymous public-app request there is no viewer — `is_current_member`
+  resolves to the **app owner's** member id. Per-user data must not ship in a public app.
+- Archived and draft records are always excluded. Rows hidden by a table's row scope
+  (`private_filters`) are excluded on every reach — base scans, link extraction, and
+  non-self-scoped traversals alike. (Row scopes don't apply when the app owner is an admin.)
+- **Dev loop**: `lotics app dev` forwards query RPCs to the **deployed** manifest. Editing
+  `lotics.queries` locally does nothing until you `lotics app deploy`.
+
+### Results
+
+A result is `{ rows, columns, source_fields_by_table_id }` (`+ total` for a count request).
+`columns` is the statically computed output schema — `{ name, type, nullable?,
+source_table_id?, source_field_key? }` per column. Rows are plain objects keyed by output
+column name; decode cells with the SDK readers (`row.*`, `readSelect`, `readMembers`,
+`readLinks`, `readFiles` — see [data_fetching.md](./data_fetching.md)).
+
+Delivery-layer enrichment (applied to the response, per request):
+
+- **`files` cells** — each entry gains a presigned `url` + `thumbnail_url` (24 h TTL) and
+  `size` (bytes) + `created_at`, resolved from the file object at read. Presigning is
+  server-bounded (§10). Public apps hand out direct presigned URLs — anonymous-fetchable,
+  time-boxed. (App workflow-execute responses presign returned files the same way, so their
+  URLs also work for anonymous public-app viewers — see [files.md](./files.md).)
+- **`select_member` cells** — bare member-id arrays become `{ id, name, email? }[]` (`email`
+  only for authenticated members of the app's own org).
+- **`select` cells** — bare option-key arrays become `{ key, label }[]` (colors ride in
+  `useFieldOptions`, not the cell — see [members_and_options.md](./members_and_options.md)).
+- **`number` columns** arrive as JS numbers (Postgres `numeric` strings are coerced; a
+  high-precision decimal that would lose digits stays a string). **`date`/`datetime`** columns
+  arrive as canonical wall-clock strings (`YYYY-MM-DD` / `YYYY-MM-DDTHH:mm`).
+
+### System columns
+
+Every row-level query carries auto-injected addressing columns alongside your output columns:
+`__source_record_id`, `__source_table_id`, `__source_locked` (decode with `readLocked`),
+`__created_at`, `__updated_at`, and per-projection `__src_field_<output>` metadata. You never
+declare these; output names starting with `__source_` / `__src_field_`, or equal to
+`__created_at` / `__updated_at`, are **reserved** and rejected. A `group` collapses rows and
+drops addressing (grouped results can't be written through or matched by `record_id`); a `join`
+keeps the **left** side's addressing.
+
+---
+
+## 2. The AST node reference
+
+Eleven node kinds. Every node except `from_table` wraps one or more child nodes; each subtree
+compiles to a derived `SELECT`. All structural errors below fail at **deploy** (the output
+schema + compile passes run there); only data-dependent errors fail at run time.
+
+### `from_table` — the only leaf
+
+```jsonc
+{ "kind": "from_table", "table_id": "tbl_orders",
+  "filter": { /* TableRecordFilters, §6 */ },
+  "search": "{{params.q}}",          // optional free-text search, §7
+  "sort":   [{ "field_key": "created", "order": "desc" }],
+  "limit":  50 }
+```
+
+Scans one table. Output = one column per field on the table (named by field key, typed per §5)
+plus the system columns. `filter`, `search` (AND-ed with `filter`), `sort`, and `limit` apply
+inside the scan — this is the **source layer**, where the richest operator support and all
+indexes live (§10). `sort` entries are `{ field_key, order: "asc"|"desc", blank_position?:
+"top"|"bottom" }` (blanks default to bottom). Unknown filter/sort field keys fail deploy.
+
+### `project` — choose and compute columns
+
+```jsonc
+{ "kind": "project", "from": { … },
+  "columns": [
+    "status",                                           // passthrough shorthand
+    { "output": "code", "source": "order_code" },       // rename
+    { "output": "is_paid", "type": "boolean",
+      "source": { "isNotEmpty": "paid_at" } },          // computed (needs output + type)
+    { "output": "id", "source": { "record_id": true } } // the row's own id
+  ] }
+```
+
+- A bare string is a passthrough: output name = the field key, type = the field's type,
+  source addressing preserved (write-through eligible via `writable_target`).
+- A computed source (any typed object except `record_id`) must declare `output` **and**
+  `type`, is always nullable, and is never writable.
+- Output names must be unique and non-reserved.
+- A passthrough may declare a `type` **override** — realized as a *real, guarded SQL cast*
+  (§4), never a relabel. An uncastable combination is rejected at deploy.
+- **Project only what you render.** A bare `from_table` ships every column — including `files`
+  cells with storage keys — to the client (over-exposure + the presign ceiling at scale).
+
+### `filter` — predicate over derived columns
+
+```jsonc
+{ "kind": "filter", "from": { …any node… }, "predicate": { /* TableRecordFilters */ } }
+```
+
+Filters the child's **output columns** (field_keys are output column names here). Column types
+come from the child's output schema, so type-shaped operators (record-link containment, array
+emptiness, timezone-aware date points) behave exactly like the source layer. The derived layer
+supports the full §5 operator matrix **except**: `traversal` nodes, `locked`, and
+`current_member` conditions are rejected — push those down into `from_table.filter`.
+`record_id` works on any row-level derived query (rejected over a `group`, which has no row
+identity). When a `filter` directly wraps a `union` of `project(from_table)` arms and every
+condition targets bare passthrough columns, the engine pushes the predicate into each arm's
+source filter automatically (making it index-servable); otherwise it evaluates post-union.
+
+### `join` — combine two row sets
+
+```jsonc
+{ "kind": "join", "type": "inner",              // "inner" | "left"
+  "left": { … }, "right": { … },
+  "on": { "left_column": "customer_id", "right_column": "id" } }
+```
+
+Single **equality** predicate on one output column per side — no multi-column ON, no
+inequality/range joins. The two ON columns must share a SQL value category (text/number/…);
+mismatches are rejected at deploy (cast one side with a projection type override). Column-name
+collisions between the sides are rejected — `project`-rename first. A `left` join makes every
+right-side column nullable. Addressing (write-through, `record_id` filtering) follows the
+**left** side only.
+
+### `union` — stack row sets
+
+```jsonc
+{ "kind": "union", "sources": [ { … }, { … } ] }   // 2+ sources
+```
+
+`UNION ALL` — duplicates are preserved, never deduped. Sources must align **positionally** by
+column name *and* type (column j of every source must have the same name and type). Use
+`project` with `{ "literal": null }` fills (typed by the column's declared `type`) to align
+heterogeneous tables. Source addressing survives per column only when every arm agrees on the
+source table/field; per-row `__src_field_*` metadata still tracks which field each row's cell
+came from.
+
+### `group` — aggregate
+
+```jsonc
+{ "kind": "group", "from": { … },
+  "by": [ "status",
+          { "bucket": { "source": "created", "granularity": "month", "output": "period" } } ],
+  "aggregates": [
+    { "output": "orders", "type": "number", "operation": "count" },
+    { "output": "revenue", "type": "number", "operation": "sum", "input_column": "total" } ] }
+```
+
+Full semantics in §8. `by` may be empty (a single-row aggregate); `aggregates` needs ≥ 1 entry.
+Aggregate operation × input-column type is validated at deploy. Grouping collapses rows —
+addressing is dropped.
+
+### `window` — aggregate without collapsing
+
+```jsonc
+{ "kind": "window", "from": { … },
+  "partition_by": ["customer_id"],
+  "order_by": [{ "field_key": "created", "order": "asc" }],
+  "frame": { "type": "rows", "following": 0 },     // optional
+  "aggregates": [{ "output": "running_total", "type": "number",
+                   "operation": "sum", "input_column": "total" }] }
+```
+
+Appends aggregate columns to every input row (input columns pass through). Only the
+**OVER-legal** operation subset is accepted (§8). Frame is `rows`-type only:
+`preceding`/`following` omitted = unbounded, `0` = current row, `N` = N rows. Omitting `frame`
+uses the SQL default — with `order_by` that is a *running* frame (partition start → current
+row, ties included); without `order_by`, the whole partition. Output names must not collide
+with input columns.
+
+### `sort` / `limit` — order and page a derived set
+
+```jsonc
+{ "kind": "sort",  "from": { … }, "by": [{ "field_key": "revenue", "order": "desc" }] }
+{ "kind": "limit", "from": { … }, "n": 20, "offset": 40 }
+```
+
+`sort.by` references output columns. `limit.n` is a positive int; `offset` optional. These are
+the same nodes the runtime refinement wraps around your query (§9) — bake a `limit` into the
+AST **only** for a fixed top-N; a baked-in limit caps the *total* a paginated browse can reach.
+
+### `unpivot` — static fan-out (columns → rows)
+
+```jsonc
+{ "kind": "unpivot", "from": { "kind": "from_table", "table_id": "tbl_shipments" },
+  "passthrough": [{ "output": "shipment_id", "type": "text", "source": { "record_id": true } }],
+  "row_columns": [
+    { "output": "charge_type",   "type": "text" },
+    { "output": "charge_amount", "type": "number" } ],
+  "rows": [
+    { "charge_type": { "literal": "freight" },  "charge_amount": "freight_fee" },
+    { "charge_type": { "literal": "handling" }, "charge_amount": "handling_fee" },
+    { "charge_type": { "literal": "customs" },  "charge_amount": "customs_fee" } ] }
+```
+
+Fans each source row into N output rows — one per `rows[]` entry — replicating `passthrough`
+columns across the fan. The shape for "one record holds K parallel fields that are really K
+child rows" (then `group` by `charge_type` for a per-type breakdown). Each `rows[i]` must
+provide a source for exactly the `row_columns` outputs; types are declared once at the top.
+The fan is **static** — declared in the AST. For fanning over an *array-valued cell's
+contents*, use `unnest`.
+
+### `unnest` — dynamic fan-out (one row per array element)
+
+```jsonc
+{ "kind": "unnest", "from": { "kind": "from_table", "table_id": "tbl_orders" },
+  "source": "tags",            // an array-valued column: select / select_member /
+  "output": "tag_key",         //   select_record_link / files (incl. such lookups)
+  "display_output": "tag_name",// links ONLY: the element's cached display text
+  "keep_empty": false }        // true → element-less rows kept with NULL element
+```
+
+One output row per **element** of an array-valued cell. Input columns (and addressing) pass
+through unchanged; `output` is a new **text** column holding each element's identity by the
+source column's type — select → option key, member → member id, link → **link record id**,
+files → file id. `display_output` is valid only over a `select_record_link` source. Rows whose
+cell is empty produce no rows unless `keep_empty: true` (then one row with NULL element
+columns). Malformed / non-array cells are treated as empty, never abort the query. Element
+columns are read-only. This is the per-element view of the record-link graph — the composition
+primitive of §8's link-identity patterns.
+
+**Limitation:** unnesting a **lookup** column only fans the *first linked record's* value —
+lookup extraction unwraps the first element before the fan (§5). To reach all values across a
+multi-link, unnest the *link column itself* and join to the target table (§8).
+
+---
+
+## 3. QuerySource — typed value expressions
+
+A `QuerySource` appears in `project.columns[].source`, `unpivot.passthrough[].source`, and
+`unpivot.rows[][key]`:
+
+| Variant | Meaning | Output type |
+| --- | --- | --- |
+| `"field_key"` (bare string) | Passthrough of an input column | the column's type |
+| `{ "literal": v }` | Constant (`string \| number \| boolean \| null`) | inferred (`null` takes the column's declared type) |
+| `{ "eq": [a, b] }` / `{ "neq": [a, b] }` | Null-safe equality (`IS [NOT] DISTINCT FROM` — `null eq null` is `true`) | boolean |
+| `{ "isEmpty": s }` / `{ "isNotEmpty": s }` | Emptiness test — over an array-valued column: empty at NULL / JSON null / `[]`; otherwise NULL-or-blank-text | boolean |
+| `{ "coalesce": [s, …] }` | First non-null | declared |
+| `{ "concat": [s, …] }` | Text concatenation (NULLs render empty) | text |
+| `{ "record_id": true }` | The row's **own** record id — requires a direct `from_table` parent; always text, non-null, never writable | text |
+| `{ "link": { "source": "customer", "field": "Company name" } }` | A field on the **first** linked record of a `select_record_link` field (correlated per-row subquery) | the target field's type |
+| `{ "expression": "…" }` | jexpr escape hatch (below) | declared |
+
+### Link extraction — the fine print
+
+`{ link: { source, field } }` requires a direct `from_table` parent, and `source` must be a
+`select_record_link` field on it. `field` names a field on the **link target table** —
+resolved **by display name first, then by key**. The target row is pinned to the declared
+table, the workspace, live (non-archived, non-draft) rows, and the target table's row scope —
+a scoped-out or stale link extracts as NULL.
+
+**Warning:** only the **first** link in the cell is followed. Multi-link analytics go through
+`unnest` + join (§8). And because `field` resolves by name first, renaming a field on the
+target table can silently re-point (or break) the extraction — prefer field **keys** when the
+target's names are volatile. Each extraction is a correlated subquery evaluated per output
+row — cheap on a filtered detail read, expensive over thousands of rows.
+
+### The expression escape hatch
+
+`{ "expression": "…" }` compiles a small jexpr subset to SQL. Column references are
+`input.<column>` (user output columns only — system columns are not reachable; use
+`{ record_id: true }` for identity). The **entire** supported surface:
+
+- **Functions**: `concat`, `coalesce`, `round`, `floor`, `ceil`/`ceiling`, `abs`, `lower`/
+  `toLowerCase`, `upper`/`toUpperCase`, `length`, `trim`, `isNull`/`isNil`, `isNotNull`.
+  (`round`/`floor`/`ceil`/`abs` are 1-arg; `round` rounds to an integer.)
+- **Operators**: `+ - * / %`, `== === != !==`, `< > <= >=`, `&& ||`, `??` (→ `COALESCE`),
+  unary `- + !`, and the ternary `cond ? a : b`.
+- **Not supported** (rejected at deploy): indexing `[…]`, nested access (`input.a.b`), list/map
+  literals, arrow functions, method calls, any other function. Project the raw columns and
+  compute client-side instead.
+
+```jsonc
+{ "output": "unit_price", "type": "number",
+  "source": { "expression": "input.qty > 0 ? round(input.total / input.qty) : 0" } }
+```
+
+Prefer the typed variants where one exists — expressions are strings and get less structural
+validation (though they still compile-check at deploy).
+
+---
+
+## 4. Column types & type overrides
+
+Query columns carry one of ten static types: `text`, `number`, `boolean`, `date`, `datetime`,
+`select`, `select_member`, `select_record_link`, `files`, `json`. Four are **array-valued**
+(`select`, `select_member`, `select_record_link`, `files`) — their cells are JSON arrays and a
+cleared cell persists as `[]`; this drives the one emptiness contract (§8) and `unnest`
+eligibility.
+
+A passthrough projection may declare a different `type` than the source column. The override is
+a **real SQL cast**, guarded so malformed values become NULL instead of aborting the query:
+
+| From → To | Behavior |
+| --- | --- |
+| same SQL category (`date` ↔ `datetime`, `select` ↔ `json`, …) | reinterpretation, no cast |
+| `text` → `number` / `boolean` / `date` / `datetime` | guarded cast; a non-conforming value → NULL |
+| `json` → any scalar | via the JSON scalar text, guarded the same way |
+| scalar → `text` / `json` | plain cast |
+| array-valued (`select`/`member`/`link`/`files`) ↔ scalar | **impossible — rejected at deploy** |
+
+The guarded-NULL rule means a query never aborts because one row holds `"n/a"` in a text column
+you cast to number — that row's cell is NULL. Use overrides to align UNION arms or to make a
+text-stored code join a numeric column; don't use them to paper over dirty data you could fix.
+
+---
+
+## 5. Per-field-type support matrix
+
+How each **table field type** behaves in a query. "Source layer" = `from_table.filter`;
+"derived layer" = `filter` nodes above projections **and** the runtime `filter` (§9) — the two
+derived surfaces share one implementation.
+
+| Field type | Column type | Source-layer operators | Derived-layer differences | Sort / group / aggregate notes |
+| --- | --- | --- | --- | --- |
+| text | `text` | `equals`, `not_equals`, `contains`, `does_not_contain`, `starts_with`, `ends_with`, `is_empty`, `is_not_empty`, `is_any_of`, `is_none_of` | same set | Sort is lexicographic in the database's default collation — no locale control. Text comparisons normalize both sides (trim + case-insensitive). |
+| number | `number` | `equals`, `not_equals`, `greater_than`, `less_than`, `greater_than_or_equal_to`, `less_than_or_equal_to`, `is_empty`, `is_not_empty` | same set | Full numeric aggregate set (§8). |
+| date / datetime | `date` / `datetime` (datetime when the field's format includes time) | `on`, `before`, `after`, `on_or_before`, `on_or_after`, `between`, `time_of_day`, `is_empty`, `is_not_empty` — values are `DateTimePoint`s (below) | same set | Day-level filters on datetime values expand to the full-day window. Sortable; bucketable in `group.by` (§8); `earliest`/`latest`/`min`/`max`/`date_range` aggregate. |
+| boolean | `boolean` | `equals` (value `true`/`false`; `false` matches NULL/missing) | same | `checked`/`unchecked`/`percent_*` aggregate (`unchecked` counts false **or** empty). |
+| select (single & multi) | `select` | `has_any_of`, `has_none_of`, `has_all_of`, `is_empty`, `is_not_empty` — values are **option keys** (`opt_*`), never labels | same | Cells are arrays even for single-selects. Sorting a select column in a query orders by raw JSON, **not** configured option order. `unnest` fans option keys. |
+| select_member | `select_member` | select ops + `is_current_member`, `is_not_current_member` (field-scoped, no value) | same — `is_current_member` **works at the runtime layer** too | `unnest` fans member ids. Anonymous public request: current-member binds the app owner (§1). |
+| select_record_link | `select_record_link` | membership by linked-record **id**: `has_any_of`, `has_none_of`, `has_all_of`; text over the cached **display**: `contains`, `not_contains`, `starts_with`, `ends_with`; `is_empty`, `is_not_empty` | same — id-membership works at the runtime layer (converged `[{id}]` containment) | Sorting orders by raw JSON, not display text — project the display (link extraction / `display_output`) and sort that. `unnest` fans link ids (+ display). |
+| files | `files` | `has_filename`, `has_mime_type` (substring), `has_file_count` (exact count), `is_empty`, `is_not_empty` | same | Presign-enriched at delivery (§1); `unnest` fans file ids. Only presence-counting aggregates. |
+| formula | its declared output type (`number`/`text`/`boolean`/`date`/`datetime`; `json` until inferred) | filtered by the output type's operators; `#ERROR:` cells are guarded — they count as empty and never match value operators | same | Extracted as a real scalar, so numeric formulas feed `sum`/`avg`/sorts. A **datetime-output** formula matches day-level date filters (full-day expansion). |
+| rollup | number-returning ops → `number`; `earliest`/`latest`/`date_range` → `date`/`datetime` per the aggregated field's format | number or date operators per output type; text operators route as text | same | Datetime-format rollups match day-level date filters. |
+| lookup | the looked-up field's type | operators of the looked-up type, evaluated with ANY-element semantics over the linked values (a row matches if *any* linked value matches) | array-typed lookups follow their column type's rules | **Projection returns the first element only.** Emptiness on a files-lookup checks the inner file arrays (a linked record with zero files counts empty). For all values across links: unnest the link column + join (§8). |
+| autonumber | `text` | text operators — filter by the visible composed string (`"ORD-0042"`) | same | Lexical sort matches numeric order (constant prefix + padding). |
+| button | `json` | **not filterable** — buttons are not data | — | Project/ignore; only presence-counting aggregates. |
+
+**Field-less conditions** (no `field_key`):
+
+| `type` | Operators | Where |
+| --- | --- | --- |
+| `locked` | `is_locked`, `is_not_locked` | source layer only |
+| `current_member` | `in_any_group` (value: group ids — gates by the *viewer's* group membership) | source layer only |
+| `record_id` | `is_any_of`, `is_none_of` (value: record ids) | source, derived, **and** runtime layers; rejected over a `group` |
+
+**Warning (silent no-op):** a condition whose operator has no translation for the field's type
+at the source layer — e.g. the date-*range* operators (`overlaps`, `within`, `starts_before`,
+`duration_*`) — contributes **no constraint** rather than erroring. The same applies to a
+condition whose value is `null`/absent. At the *derived* layer, unsupported operators fail
+loudly instead. Positive list operators with an **empty list** (`is_any_of: []`,
+`has_any_of: []`) match **nothing** at the derived layer, but are a silent no-op (no
+constraint — like a null value) at the source layer; negative ones (`is_none_of: []`,
+`has_none_of: []`) constrain nothing at either layer.
+
+### DateTimePoint
+
+Date operator values are `DateTimePoint`s, resolved server-side in the **field's timezone**
+(so "today" on a +14 h-zone field uses that zone's calendar day):
+
+```jsonc
+{ "type": "exact",    "date": "2026-03-01", "time": null }        // or "time": "14:30"
+{ "type": "relative", "offset": -7, "unit": "days" }               // units: minutes…years
+{ "type": "period",   "period": "month", "boundary": "start", "offset": 0 }
+```
+
+`between` takes `{ start, end }` of points (either side may be null → open-ended);
+`time_of_day` takes `{ start_time, end_time }` (`"HH:mm"`). A date-only `between` end bound is
+inclusive of the whole day.
+
+---
+
+## 6. Filters in depth
+
+`from_table.filter`, the `filter` node's `predicate`, and the runtime `filter` all share one
+tree shape — `TableRecordFilters`:
+
+```jsonc
+// condition        — one predicate
+{ "node_type": "condition", "field_key": "status", "operator": "has_any_of", "value": ["opt_open"] }
+// group            — AND/OR of children (conditions, traversals, nested groups)
+{ "node_type": "group", "logic": "and", "children": [ … ] }
+// traversal        — a predicate on a record reachable through link hops
+{ "node_type": "traversal", "path": ["customer"], 
+  "condition": { "node_type": "condition", "field_key": "owner", "operator": "is_current_member" } }
+```
+
+A condition's `type` (`"text"`, `"number"`, `"date"`, …) is derived from the live field —
+include it for date/formula conditions (it routes value semantics); the operator must belong to
+the field's set (§5). An **empty group is a no-op** (match-all) — the foundation of param
+pruning below.
+
+### Traversals
+
+A traversal filters the current table by a condition on a **linked** record: `path` is a chain
+of `select_record_link` field keys (max **3 hops**), `condition` evaluates on the final table.
+**ANY semantics** — a row matches if at least one reachable record satisfies the condition.
+Negation-shaped inner operators (`has_none_of`, `not_equals`, `is_none_of`,
+`is_not_current_member`, …) evaluate as *no reachable record matches the positive form* — not
+"any record matches the negation".
+
+Traversals are **source-layer only** (rejected on derived columns — push them into
+`from_table.filter`). Two access classes:
+
+- **Self-scoped** — inner operator `is_current_member` / `is_not_current_member`: tests only
+  the viewer's own membership on the linked row, leaks nothing, and is exempt from the linked
+  table's row scope. This is the primitive for "my child rows" self-service queries — scope to
+  a parent the viewer can't otherwise list.
+- **Everything else** — the traversal reads linked-row data through row selection, so the
+  linked tables are access-gated like any projected reach, and each hop honors the linked
+  table's row scope.
+
+### Params, `{{params.x}}` tokens, and optional-param pruning
+
+Tokens interpolate in **value positions**. A string that *is* exactly one token is replaced by
+the param's typed value (an array param yields an array); a token embedded in a larger string
+interpolates as text. Declared-but-unreferenced params are fine; referenced-but-undeclared
+tokens fail deploy.
+
+**Composable optional filters (one query, many scopes).** Expose several independent filter
+axes from ONE named query — don't shard into a query-per-combination. Mark each scoping param
+`required: false`; the server **prunes every filter condition (or traversal) whose
+`{{params.x}}` the caller didn't pass** — then collapses emptied groups — so an unset axis
+stops constraining instead of erroring. No-op for all-required queries.
+
+```jsonc
+"search": {
+  "ast": { "kind": "project", "from": { "kind": "from_table", "table_id": "tbl_items", "filter": {
+    "node_type": "group", "logic": "and", "children": [
+      { "node_type": "condition", "field_key": "status", "operator": "has_any_of", "value": ["{{params.status}}"] },
+      // keyword over two fields — the whole OR-group prunes when `keyword` is absent
+      { "node_type": "group", "logic": "or", "children": [
+        { "node_type": "condition", "field_key": "title", "operator": "contains", "value": "{{params.keyword}}" },
+        { "node_type": "condition", "field_key": "notes", "operator": "contains", "value": "{{params.keyword}}" } ] },
+      // date range — each bound is its OWN single-param condition, so an open-ended range prunes one side
+      { "node_type": "condition", "field_key": "created", "operator": "on_or_after",
+        "value": { "type": "exact", "date": "{{params.from}}", "time": null } },
+      { "node_type": "condition", "field_key": "created", "operator": "on_or_before",
+        "value": { "type": "exact", "date": "{{params.to}}", "time": null } } ] }, "columns": [ /* … */ ] },
+  "params": {
+    "status":  { "type": "select", "options": [ /* … */ ], "required": false },
+    "keyword": { "type": "text", "required": false },
+    "from":    { "type": "date", "required": false },
+    "to":      { "type": "date", "required": false } }
+}
+```
+
+`useQuery("search", { keyword })` filters by keyword only; `{}` returns everything. Pruning is
+per-*condition*: a group whose children all prune collapses away; a condition mixing a provided
+and an un-provided param prunes whole (all its tokens must be provided to survive). A
+`from_table.search` whose tokens aren't all provided also prunes to match-all — so a
+"show all until you type" search box works with a `required: false` search param. **Dates:**
+there is no `date_range` interpolation shortcut — embed a `date` param in a hand-built
+exact `DateTimePoint` as above, one condition per bound so each prunes independently. Keep a
+scope that must *always* apply `required` (a missing required param 400s).
+
+### Fetching one record by id
+
+Use the field-less `record_id` condition — typically as a **runtime** filter so one detail
+query serves any id:
+
+```ts
+useQuery("orderDetail", {}, { filter: {
+  node_type: "condition", type: "record_id", operator: "is_any_of", value: [id] } });
+```
+
+A link `has_any_of [id]` matches a *related* record; `record_id` matches the row's **own** id —
+the only way, since a record has no field holding its own id. Prefer a link/join when an actual
+relationship exists; reach for `record_id` when your starting point is a bare id (a drill row).
+Rejected over a grouped query (no row identity).
+
+---
+
+## 7. Free-text search
+
+`from_table.search` runs over the record's maintained **search document** — a per-record text
+index that is:
+
+- **diacritics- and case-insensitive** (`"da nang"` matches `"Đà Nẵng"`),
+- **trigram-indexed** (scales to large tables — unlike `contains`, which scans),
+- **near-total field coverage** — indexes text, number, date (ISO plus `MM/dd/yyyy` and
+  `dd/MM/yyyy` forms), select option labels, member names, link display text, and
+  formula/rollup/lookup values; boolean and files cells are not indexed,
+- multi-term: the query splits on whitespace (max 10 terms), all terms must match (AND).
+
+It AND-s with `filter` (search *within* a scope) and is templatable
+(`"search": "{{params.q}}"`). An empty or whitespace-only term matches everything; an
+unresolved optional token prunes to match-all (§6).
+
+**Search-as-you-type uses `search`, never a `contains` OR-group.** Per-field `contains` is
+accent-*sensitive* and unindexed — a zero-match keystroke forces a full-partition scan that
+hangs the picker. Reserve an OR-group of `contains` for when you must bound exactly *which*
+fields match. Gate the fetch on a non-empty term client-side (`enabled`), or first paint dumps
+the table.
+
+---
+
+## 8. Shaping: group, buckets, window, fan-out
+
+### The 20 aggregate operations
+
+`group` and `window` share one operation vocabulary. `count` is `COUNT(*)` (no `input_column`);
+everything else requires an `input_column` whose type must be compatible — checked at deploy:
+
+| Operation | Valid input column types | Result | Notes |
+| --- | --- | --- | --- |
+| `count` | — (counts rows) | number | non-null; 0 for empty groups |
+| `sum`, `avg`, `median`, `range` | number | number | `range` = max − min; `median` = continuous percentile |
+| `min`, `max` | number, text, date, datetime | input type (number/text) or date | text is lexicographic; on dates ≡ earliest/latest |
+| `earliest`, `latest` | date, datetime | date/datetime | |
+| `date_range` | date, datetime | number | span in **days** (fractional) |
+| `filled`, `empty` | any except boolean | number | presence counts — see the emptiness contract |
+| `percent_filled`, `percent_empty` | any except boolean | number | **fraction 0–1**, not 0–100; NULL for an empty group |
+| `unique`, `percent_unique` | text, number, date/datetime, select, select_member, select_record_link, files, json¹ | number | distinct **present** values; array cells compare as whole arrays |
+| `checked`, `unchecked`, `percent_checked`, `percent_unchecked` | boolean | number | `unchecked` counts false **or** empty |
+
+¹ opaque `json` columns support only the presence-counting six (`empty`/`filled`/`unique` and
+their `percent_*` forms).
+
+**The one emptiness contract.** `filled`/`empty`/`unique`/`percent_*` use the same definition
+of "present" as the filter layer's `is_empty` and the `isEmpty` source: array-valued cells are
+empty at NULL / JSON `null` / `[]`; text at NULL or blank (whitespace-only); opaque json at
+NULL / JSON `null`; other scalars at SQL NULL. A cleared multi-select or a whitespace-only text
+cell counts **empty** everywhere — filters and aggregates never disagree.
+
+### Date-bucket group keys
+
+`group.by` accepts, alongside plain column names:
+
+```jsonc
+{ "bucket": { "source": "created", "granularity": "month", "output": "period" } }
+```
+
+- `source` must be a `date` or `datetime` **column** of the input (deploy-checked).
+- `granularity`: `day` | `week` | `month` | `quarter` | `year`. **Weeks are ISO — Monday
+  start.**
+- Buckets are computed on the stored **wall-clock** value in the field's timezone (a 23:30
+  record buckets into its local month), matching how date filters compare.
+- The output is a new **`date`** column holding the **bucket start** — sortable, filterable,
+  and re-aggregatable downstream like any date column. A NULL source date yields a NULL bucket
+  (its rows group together).
+
+```jsonc
+{ "kind": "group",
+  "from": { "kind": "from_table", "table_id": "tbl_orders" },
+  "by": [ { "bucket": { "source": "created", "granularity": "week", "output": "week" } }, "status" ],
+  "aggregates": [ { "output": "n", "type": "number", "operation": "count" } ] }
+```
+
+Sort by the bucket column for a time series; filter it with date operators for a rolling
+window. **Always bucket server-side** — shipping raw rows to bucket in JS burns the row cap and
+the timeout for nothing.
+
+### Window functions — the OVER-legal subset
+
+Only operations that compile to a single legal SQL window call are accepted in `window`:
+**`count`, `sum`, `avg`, `min`, `max`, `earliest`, `latest`, `filled`, `checked`,
+`unchecked`.** The rest cannot take an OVER clause (`median` is an ordered-set aggregate;
+`unique`/`percent_unique` need DISTINCT; `range`/`empty`/`date_range`/`percent_*` compose
+multiple calls) — rejected at deploy.
+
+**There are no ranking or navigation functions** — no `row_number`, `rank`, `dense_rank`,
+`lag`, `lead`, `first_value`. **Top-N per group** is emulated with a running count over a
+frame:
+
+```jsonc
+{ "kind": "filter",
+  "from": { "kind": "window",
+    "from": { "kind": "from_table", "table_id": "tbl_orders" },
+    "partition_by": ["customer_id"],
+    "order_by": [{ "field_key": "total", "order": "desc" }],
+    "frame": { "type": "rows", "following": 0 },        // partition start → current row
+    "aggregates": [{ "output": "rank", "type": "number", "operation": "count" }] },
+  "predicate": { "node_type": "condition", "field_key": "rank",
+                 "operator": "less_than_or_equal_to", "value": 3 } }
+```
+
+`count` over a `ROWS … CURRENT ROW` frame is a row position (`row_number`-like; ties are
+ordered arbitrarily unless the `order_by` is total — add a tiebreaker key for determinism).
+
+### unpivot vs unnest
+
+- **`unpivot`** — *static* fan: N parallel **fields** on one record become N rows. The fan is
+  written in the AST.
+- **`unnest`** — *dynamic* fan: the **elements of one array cell** become rows. The fan is the
+  data.
+
+They compose: unpivot a record's three link fields into rows, then unnest each.
+
+### No pivot
+
+There is **no pivot/crosstab node** — you cannot turn row values into columns server-side.
+Group by the two dimensions (`by: [bucket, "status"]`) and pivot client-side over the compact
+grouped result (cheap — it's already aggregated), or `unpivot` a wide record into long form
+first. For a fixed, small set of columns, N filtered aggregate queries also work.
+
+---
+
+## 9. Runtime refinement — filter / sort / limit / offset / count
+
+Each query request carries optional refinement the server wraps **around** the deployed
+template as derived nodes, in this order: `filter` (narrow) → `sort` (order) → `limit`+`offset`
+(page):
+
+- **`filter`** — a `TableRecordFilters` tree over the query's **output columns** (§5 derived
+  layer; `record_id` allowed). A `field_key` that isn't a projected output column → 400. This
+  is the exposure invariant: a caller can refine what the query already exposes, never widen
+  it. Record-link membership (`has_any_of` by id) **works** here; so does `is_current_member`
+  on a member column. Traversals / `locked` / `current_member` do not — bake those into the
+  template.
+- **`sort`** — `[{ field_key, order, blank_position? }]` over output columns.
+- **`limit` / `offset`** — offset pagination. `limit` is clamped to the 10,000-row cap (§10).
+- **`count: true`** — returns `{ total }` only: a single-row COUNT over the *filtered* set,
+  ignoring sort/limit/offset. Drives "Page 1 of N".
+
+The SDK hooks map onto this directly (`dist/src/hooks.d.ts` for exact signatures): `useQuery`
+sends `limit: pageSize, offset: 0` (a cap, not pagination) plus `opts.sort`/`opts.filter`;
+`useInfiniteQuery` pages by `offset = page × pageSize`; `usePaginatedQuery` owns the page
+cursor and issues the page query plus a `count` keyed on `(alias, params, filter)` —
+independent of page and sort, so paging and re-sorting never recount, while changing
+`(params, filter)` resets to page 0 and recounts.
+
+Build `filter` from UI column-filters with `columnFilterToConditions` (`@lotics/ui`); prefer
+`useFieldOptions` for a select filter's option set.
+
+**Warning (transport gaps):** the embedded product host and the `lotics app dev` forwarder pass
+`sort`/`filter`/`count` through. The **standalone public transport** (`<slug>.lotics.app`)
+currently forwards only `alias`/`params`/`limit`/`offset` — runtime `sort`/`filter` are
+silently ignored there and `count` never resolves (`usePaginatedQuery.total` stays
+`undefined`). A standalone app must bake ordering/scoping into the template (or params) rather
+than rely on runtime refinement.
+
+**Pagination semantics:** offset-only — a deep page costs the server the full skipped prefix
+(page 400 of a 25-row pager scans ~10,000 rows before returning 25), and pages can shift under
+concurrent writes (a row inserted before your offset repeats or skips a row across pages).
+There is no cursor/keyset pagination. Keep paginated browses filtered and sorted by a stable
+key, and don't build UX that walks thousands of pages.
+
+---
+
+## 10. Limits & the efficiency playbook
+
+### Hard limits
+
+| Limit | Value | On violation |
+| --- | --- | --- |
+| Rows per response | **10,000** (caller `limit` is clamped; the cap is the default) | silent truncation at the cap — paginate |
+| Statement timeout | **15 s** per query execution | 400: `query timed out after 15s — narrow the filter or simplify the query` |
+| Concurrent query executions | server-configured bulkhead (bounded slots + bounded queue wait) | **503**: `The app is handling too many requests right now. Please retry in a moment.` — a distinct busy-retry outcome; back off and retry |
+| Signed file URLs per response | server-configured, default **2,000 file entries** | 400 naming the alias, the count, and the ceiling — project files columns only where rendered, narrow, or paginate |
+| Traversal depth | 3 hops | **silent match-nothing** — a longer path compiles to `FALSE` (deploys green, returns zero rows) |
+| Param schema depth | 8 | deploy reject |
+
+Any other execution failure returns a generic `query execution failed` (the real error — which
+may embed SQL — is server-logged only). Deploy-time and validation errors are always specific.
+
+### Index reality, in plain terms
+
+Records live in one big partitioned store; a `from_table` scan narrows to the table's partition
+slice, and within it:
+
+- **GIN-served (fast at any size):** *positive* exact-membership filters at the **source
+  layer** — `select`/`select_member`/`select_record_link` `has_any_of` / `has_all_of`, and
+  `is_current_member`. These compile to containment the JSONB GIN index serves.
+- **Trigram-served:** `from_table.search` (§7).
+- **Partition scan (linear in table size):** everything else — text `contains`/`equals`,
+  number and date range predicates, negations (`has_none_of`, `is_none_of`, `not_*`),
+  emptiness, files predicates. Fine on thousands of rows; on very large tables these dominate
+  latency and are the usual timeout cause.
+
+**Filter shape drives latency.** Lead with a GIN-served membership filter or `search` where you
+can; let the scan-shaped predicates refine the already-narrowed set. Derived-layer filters run
+over the subquery result (no index), so **filter at the source layer whenever the field exists
+there** — the runtime filter is for caller-driven refinement, not for the main cut. (The engine
+pushes eligible filter-over-union predicates down automatically, but don't rely on that for
+other shapes.)
+
+### The authoring rules
+
+1. **Filter at the source.** Push every static predicate into `from_table.filter`.
+2. **Prefer `search`** for any free-text box; `contains` OR-groups only to bound the fields.
+3. **Aggregate and bucket server-side.** A dashboard reads grouped rows, never raw rows it
+   reduces in JS — raw-row shipping burns the 10k cap, the timeout, and bandwidth at once.
+4. **Project narrow.** Every un-rendered column is wasted bytes; every un-rendered `files`
+   column risks the presign ceiling and over-exposes storage metadata.
+5. **Files columns only where rendered.** A list view projects no files; the detail query does.
+6. **Avoid deep offsets.** Filter first so the browsable set is small; sort by a stable key.
+7. **Don't bake a `limit` into a browsable query** — it caps the total; let `pageSize` drive.
+8. **Parameterize lookups.** A code/id lookup is a `{{params.x}}` filter (or a `record_id`
+   runtime filter) returning one row — never load-all-then-find in JS.
+9. **Expect and handle the three runtime outcomes**: a 400 with a message (surface it), the
+   timeout 400 (narrow/simplify), and the 503 busy (retry after a moment).
+
+---
+
+## 11. Combining tables — the patterns
+
+Four tools combine tables: **join** (row sets on a shared value), **union** (stack), **link
+extraction** (one field off the first link), and **unnest + join** (the link graph,
+per-element). Choosing:
+
+- One display field from a single-link relation → **link extraction** (or better, a
+  materialized **lookup field** on the table, which is filterable/sortable at the source).
+- Rows relate through a shared business key (an order code column both tables carry) →
+  **join** on the key columns directly.
+- Anything per-element over a multi-link (aggregates across links, per-tag counts, join through
+  link identity) → **unnest + `{ record_id: true }` + join**.
+- A per-parent aggregate you need *often* and *filterable at the source* → consider a
+  materialized **rollup field** on the parent table instead of a live query — the platform
+  keeps it updated, and it filters/sorts with source-layer support. The query-side aggregate
+  is for shapes a rollup can't express or ad-hoc analytics.
+
+### Link-identity join (decorate rows with linked-record data)
+
+Orders link customers; you want each order with the customer's region — all links resolvable,
+not just the first field:
+
+```jsonc
+{ "kind": "join", "type": "left",
+  "left": { "kind": "unnest",
+    "from": { "kind": "project", "from": { "kind": "from_table", "table_id": "tbl_orders" },
+              "columns": ["order_code", "total", "customer"] },
+    "source": "customer", "output": "customer_id", "keep_empty": true },
+  "right": { "kind": "project", "from": { "kind": "from_table", "table_id": "tbl_customers" },
+             "columns": [ { "output": "cust_rid", "source": { "record_id": true } },
+                          { "output": "region", "source": "region" } ] },
+  "on": { "left_column": "customer_id", "right_column": "cust_rid" } }
+```
+
+`unnest` turns the link cell into a text `customer_id` per link; the right side projects the
+customer's own id via `{ record_id: true }`; the scalar-equality join matches them. Both
+columns are text — the ON type check passes. `keep_empty: true` keeps customer-less orders
+(LEFT-join semantics end to end).
+
+### Child-aggregate-by-parent (including many-to-many)
+
+Sum of order totals per customer, when *orders* hold the (possibly multi) link:
+
+```jsonc
+{ "kind": "group",
+  "from": { "kind": "unnest",
+    "from": { "kind": "project", "from": { "kind": "from_table", "table_id": "tbl_orders" },
+              "columns": ["total", "customer"] },
+    "source": "customer", "output": "customer_id", "display_output": "customer_name" },
+  "by": ["customer_id", "customer_name"],
+  "aggregates": [
+    { "output": "orders", "type": "number", "operation": "count" },
+    { "output": "revenue", "type": "number", "operation": "sum", "input_column": "total" } ] }
+```
+
+Works unchanged for many-to-many: an order linked to two customers contributes a row to each
+group (by design — each parent sees its own child). Group by the display column too so the
+result is directly renderable.
+
+### Per-tag counts
+
+```jsonc
+{ "kind": "group",
+  "from": { "kind": "unnest",
+    "from": { "kind": "project", "from": { "kind": "from_table", "table_id": "tbl_items" },
+              "columns": ["tags"] },
+    "source": "tags", "output": "tag" },
+  "by": ["tag"],
+  "aggregates": [{ "output": "n", "type": "number", "operation": "count" }] }
+```
+
+Multi-select cells fan one row per option key; grouping counts each tag's frequency. (Resolve
+keys to labels/colors with `useFieldOptions`.)
+
+### One row per file (a document register)
+
+```jsonc
+{ "kind": "unnest",
+  "from": { "kind": "project", "from": { "kind": "from_table", "table_id": "tbl_contracts" },
+            "columns": ["contract_code", "attachments"] },
+  "source": "attachments", "output": "file_id" }
+```
+
+Each file becomes a row carrying its parent's columns — but note the fanned `file_id` is a bare
+text id; the presign enrichment rides the original `files` **cell**, which this query still
+projects (so each fanned row repeats the full cell). For a lean register, keep the `files`
+column projected only in the query that renders the previews, and mind the presign ceiling.
+
+### All values of a multi-link lookup
+
+A lookup projection (and unnesting the lookup column) yields only the **first** linked record's
+value (§5). To read the looked-up field across *all* links: unnest the **link column**, join to
+the target on `record_id`, and project the field from the target side — the link-identity join
+above, with `region` replaced by whatever the lookup pointed at.
+
+---
+
+## 12. Current limitations
+
+Consolidated from the sections above — these describe present engine behavior:
+
+- **No pivot/crosstab node.** Row-values-to-columns happens client-side over grouped results
+  (§8).
+- **No ranking or navigation window functions** (`row_number`, `rank`, `lag`, `lead`, …).
+  Top-N per group = the count-over-frame emulation (§8). Window ops are the 10-item OVER-legal
+  subset.
+- **Offset-only pagination.** Deep pages cost the full skipped prefix; pages can shift under
+  concurrent writes (§9).
+- **No collation control.** Text ORDER BY uses the database default collation —
+  locale-specific alphabetical order (e.g. accented-letter ordering) is not configurable.
+- **Select / member / link columns sort by raw JSON** in queries — not by configured option
+  order or display text. Sort a projected text form instead.
+- **Lookup projection returns the first element**; unnesting a lookup column fans only the
+  first linked record's value. All-values access goes through unnest-the-link + join (§11).
+- **Link extraction follows the first link only**, resolves the target field by display name
+  before key, and costs a correlated subquery per row (§3).
+- **Join is single-column equality** with SQL-category-matched types; addressing follows the
+  left side (§2).
+- **Text / number / date range predicates are unindexed within the partition** — the usual
+  cause of slow queries and timeouts on large tables; positive membership filters and `search`
+  are the indexed paths (§10).
+- **Traversals, `locked`, and `current_member` conditions are source-layer only** — not
+  available in derived or runtime filters (§6).
+- **The standalone public transport drops runtime `sort`/`filter`/`count`** — refinement is
+  silently ignored and paginated totals never resolve there; bake ordering/scoping into the
+  template for standalone apps (§9).
+- **Unsupported operators at the source layer are silent no-ops** (notably the date-range
+  operator family) — the condition contributes no constraint rather than erroring (§5).
+- **The expression allowlist is small and flat** — no indexing, nested access, or functions
+  beyond the §3 list; compute anything richer client-side from projected columns.
+- **`from_table` is the only leaf** — a query reads tables; there is no way to query a view,
+  another query, or an external source.