@lotics/app-sdk 0.102.0 → 0.102.1

package/docs/queries.md

@@ -234,7 +234,7 @@ supports the full §5 operator matrix **except**: `traversal` nodes, `locked`, a
 `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.
+source filter automatically, where it runs once per record; otherwise it evaluates post-union.
 
 ### `join` — combine two row sets
 
@@ -545,9 +545,9 @@ Negation-shaped inner operators (`has_none_of`, `not_equals`, `is_none_of`,
 
 Traversals are **source-layer only** (rejected on derived columns — push them into
 `from_table.filter`). Each hop reaches the linked rows by primary key from the ids in the link
-cell. Under an OR beside column conditions a traversal runs once per row and takes the column
-conditions off their indexes with it; give it a `union` arm of its own when the other arms must
-stay index-served. Two access classes:
+cell. Under an OR beside column conditions a traversal runs once per row and takes a membership
+condition off its index with it; give it a `union` arm of its own when the other arms must keep
+theirs. 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
@@ -871,7 +871,7 @@ ordering and scoping into the template or its params.
 Any other execution failure returns a generic `query execution failed` (the real error — which
 may embed SQL — is server-logged only). Bind-time and validation errors are always specific.
 
-### Index reality, in plain terms
+### What a query reads, in plain terms
 
 Records are stored partitioned by workspace, so a query reads only its own workspace's slice; a
 `from_table` narrows that slice to the table's rows, and within them:
@@ -879,39 +879,18 @@ Records are stored partitioned by workspace, so a query reads only its own works
 - **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).
-- **B-tree-served (automatic for bound queries):** text `equals`, number and date
-  comparisons (exact and range), `from_table.sort` fields, and a one-key `sort` node over a
-  number or date field the rows pass unchanged — for fields referenced in a **bound named
-  query's template**. The platform provisions a partial expression index per referenced
-  field automatically: built online whenever `set_app_query` or `set_app_queries` binds a query, re-synced daily,
-  capped at 8 per table (fields past the cap fall back to the scan tier, with a server WARN).
-  A `{{params.…}}` value hole doesn't change this — the field key is static in the template,
-  so it still gets its index. Index-seek speed at any table size once provisioned.
-- **Table scan (linear in table size):** everything else — text `contains`, negations
-  (`has_none_of`, `is_none_of`, `not_*`), emptiness, files predicates, and predicates/sorts on
-  fields that appear **only** in the runtime `filter`/`sort` options rather than the bound
-  template. Fine on thousands of rows; on very large tables these dominate latency and are the
-  usual timeout cause.
-
-**Filter shape drives latency.** Equality/range/sort predicates in the bound template are
-index-served; lead with those or a GIN-served membership filter / `search`, and let 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 (a runtime-only field gets no
-managed index). (The engine pushes eligible filter-over-union predicates down automatically,
-but don't rely on that for other shapes.)
-
-**A sorted page reads in its sort index — declare the order it is read in.** A page sorted by one
-column that passes a number or date field unchanged (a bare `project` source with no `type`
-override, an `unpivot` passthrough, or a row column that reads the same field in every row) reads
-the table in that field's sort index and stops at the page, instead of reading every row and
-sorting. Over a `union`, each arm is paged this way on its own and the arms are merged, so a
-register over several tables or `unpivot` sides is fast at any size — don't hand-split it into
-per-table queries you merge client-side. The index exists when a bound template sorts that field
-in the same direction and blank position: give the query its default order as a top-level `sort`,
-and a page the app sorts the same way is served. A text column, a computed, literal or cast column,
-a sort on more than one key, and a cursor (`keyset`) page sort every row.
+- **Trigram-served:** `from_table.search` (§7), within the one table.
+- **Every row of the table:** everything else — text equality and `contains`, number and date
+  comparisons, sorts, negations, emptiness, files predicates. Fine on thousands of rows; the cost
+  grows with the table, and 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`, which
+narrow the table before its rows are read, and let the other conditions refine that set.
+Derived-layer filters run over the subquery result, after any `unpivot` fan-out, 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 moves eligible filter-over-union predicates into
+each arm's source automatically, but don't rely on that for other shapes.)
 
 **An aggregate arm you cannot filter costs its whole table, every execution.** A `join` whose right
 side is a `group` over entire tables, keyed on a value the LEFT side supplies at run time, has no

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lotics/app-sdk",
-  "version": "0.102.0",
+  "version": "0.102.1",
   "description": "The SDK a Lotics custom-code app reads and writes through \u2014 typed hooks over the host bridge, cell readers, mount() and AppRouter",
   "type": "module",
   "exports": {