@xanots/sdk 0.0.12 → 0.0.14

package/llms-full.txt

@@ -1,4 +1,4 @@
-# xanots v0.0.12
+# xanots v0.0.14
 
 > TypeScript SDK that compiles a typed Xano workspace into the importable packageExport JSON bundle.
 
@@ -15,11 +15,11 @@ TAGGED value — `ref("x")` a stack variable, `inp("x")` an input, `auth("id")`
 caller, `c.*` a constant — resolved at request time; JS operators over them do not
 compute (see Gotchas). Requests share no memory — state persists in tables or redis.
 
-Coverage: object kinds 25/31, statement surfaces 214/214, filters 226 (226 typed).
+Authorable: statement surfaces 214/214, filters 226 (226 typed).
 Not authorable here: branch, market_item, realtime_channel, run.job, run.service, tablemap — these cannot be authored and do not survive a pull; reasons in `coverage.objectKinds.unmodeled`.
 
 This file is the whole always-read surface: the mental model, the deploy contract,
-every gotcha, and control flow. Per-surface detail lives in the topic files listed
+every cross-cutting gotcha, and control flow. Per-surface detail lives in the topic files listed
 below — open the one whose condition matches the task, skip the rest. For
 exhaustive per-entry detail in NEITHER — a statement's field schema with engine
 defaults, a filter's full argument list, the `storedName` mapping — do a TARGETED
@@ -37,23 +37,25 @@ Paths are relative to this file (`node_modules/@xanots/sdk/` once installed), so
 plain file read resolves them at the version you have.
 `llms-full.txt` is everything concatenated — one fetch for a reader that cannot open files.
 
-- [Object kinds](llms/object-kinds.md): Read when deciding WHAT to build — every authorable primitive (tables, endpoints, functions, tasks, agents, MCP, realtime, microservices, …), what each is, and which factory + register method build it. Read it too when a `register*` call will not typecheck because the array was built by `.flatMap()`/`.concat()` across modules.
+- [Object kinds](llms/object-kinds.md): Read when deciding WHAT to build — every authorable primitive, what each is, and which factory + register method builds it. Also when `register*` will not typecheck an array built by `.flatMap()`/`.concat()`.
 - [Core def shapes](llms/kinds-core.md): Read when authoring a function, query, api group, task, workflow test, middleware, or tool — and for the `response` and `expr` shapes every one of them uses.
-- [Saved unit tests, assertions, and mocks](llms/tests.md): Read when authoring a `workflowTest()` stack, when a query/function/middleware carries `tests`, when a statement should mock a value, or when running a deployed environment's tests.
+- [Consuming defs from a client](llms/client.md): Read when a frontend imports a def (`getPath()`/`InferResponse`) or calls the deployed backend — what the import costs, `window.XANO_HOST`, local dev, file URLs, and a Node spot-check.
+- [Error index](llms/errors.md): Read when a request, test, build, or pull fails with a message you did not write — the string, its cause, and where the fix is.
+- [Saved unit tests, assertions, and mocks](llms/tests.md): Read when authoring a `workflowTest()` stack, when a query/function/middleware carries `tests`, when a statement needs a `mock`, or when running a deployed environment's tests.
 - [Agent and MCP def shapes](llms/kinds-agent-mcp.md): Read when the workspace defines an `agent()` or an `mcpServer()`.
-- [Knowledge def shape](llms/kinds-knowledge.md): Read when the workspace defines a `knowledge()` item — the markdown its AI agents read.
+- [Knowledge def shape](llms/kinds-knowledge.md): Read when the workspace defines a `knowledge()` item for its AI agents.
 - [Realtime def shapes](llms/kinds-realtime.md): Read when the workspace defines a `realtimeServer()`, `realtimeChannel()`, or `realtimeMessage()` handler.
 - [Triggers](llms/triggers.md): Read when authoring any trigger. A trigger's `stack` is a callback rather than the plain array every other kind takes, so the shape does not carry over.
 - [Array and database statements](llms/statements-data.md): Read when the stack reads or writes rows (`s.db.*`), or transforms an array in place (`s.array.map`, `s.array.union`).
-- [Statement runtime behavior](llms/statements-runtime.md): Read when you need to know what a statement's `as:` output actually holds, or why a bound variable is not the shape you expected.
+- [Statement runtime behavior](llms/statements-runtime.md): Read when you need to know what a statement's `as:` output holds, or why a bound variable is not the shape expected.
 - [Auth, cross-object calls, and microservices](llms/statements-calls.md): Read when the stack authenticates (the signup/login/token recipe is here), calls another object (`s.function.run`, `s.api.request`, `s.tool.call`), sends email (`s.util.send_email`), or reaches a microservice.
 - [Value catalog](llms/values.md): Read when you need a literal, a reference, or a tag you have not used before — `c.*`, `ref`, `inp`, `auth`, `col`, and what each one encodes to.
-- [Column and input types](llms/fields.md): Read when declaring a table column (`f.*`) or a function/query input (`input.*`) — a type's options and accessor methods, and the `s.precondition` error/status contract that rides the same catalog.
+- [Column and input types](llms/fields.md): Read when declaring a table column (`f.*`) or a function/query input (`input.*`) — a type's options and methods, and the `s.precondition` error/status contract. Also `table({ seed })` rows and `use_xdo`.
 - [Filter catalog](llms/filters.md): Read when piping a value through `fl.*` — the full catalog with each filter's argument types.
-- [Lambda bodies (JavaScript)](llms/lambda.md): Read when writing a JavaScript body, or weighing whether to reach for one at all — `lam.fn`, `fl.lambda`, `fl.reduce`, `s.lambda`. Lambda workers are a bounded shared resource, and each surface binds a different set of identifiers.
+- [Lambda bodies (JavaScript)](llms/lambda.md): Read when writing a JavaScript body, or weighing whether to reach for one at all — `lam.fn`, `fl.lambda`, `fl.reduce`, `s.lambda`; each surface binds a different set of identifiers.
 - [Lock file](llms/lock.md): Read when a `xano.lock` exists or should — renaming/pruning/importing identities, seeding the lock programmatically, or asking which commands write it.
-- [Legacy paradigms and retired statements](llms/legacy.md): Read when the code was PULLED from an existing Xano instance rather than authored here — how a codegen'd tree reads and the three shapes in it that must not be "fixed", plus a `raw({ name: "mvp:…" })` statement, a `realtimeTrigger()`, or any name the catalogs do not list.
-- [Statement catalog](llms/statements-catalog.md): Read for the field signature of a specific statement — every surface, grouped by `s.*` namespace. Look here after the control-flow core in the router does not cover what you need.
+- [Legacy paradigms and retired statements](llms/legacy.md): Read when the code was PULLED from an existing Xano instance — how a codegen'd tree reads, the shapes in it that must not be "fixed", and any `raw({ name: "mvp:…" })`, `realtimeTrigger()`, or name the catalogs do not list.
+- [Statement catalog](llms/statements-catalog.md): Read for the field signature of a specific statement — every surface, grouped by `s.*` namespace.
 
 ## Quickstart
 
@@ -125,6 +127,8 @@ operand, a `ref()` nothing binds). Each has a legitimate use, so each only warns
 but nothing fails on a message no one reads, so in CI and in unattended agent builds
 pass `--strict` (`emitBundle(app, { strict: true })` / `app.export({ strict: true })`):
 every warning becomes a hard failure. Same bundle bytes either way.
+Before calling the work done: `npm run typecheck`, `xanots export <entry> --strict`,
+`xanots deploy <entry>`, then `xanots test run-all` against what deployed.
 
 Identity: object guids derive from `(type, name)` — a query's from `(api group,
 verb, name)` — so renames change identity.
@@ -170,90 +174,89 @@ production workspace, but confirm with the user before the first run.
 
 **Frontend wiring.** `--static <dir>` injects the DEPLOYED env's backend URL as
 `window.XANO_HOST` into EVERY html document in the build, before the app bundle runs,
-so the frontend needs no rebuild to target an env. Every document, not just the root:
-a prerendered build serves a different one per route, and a route without the global
-renders fine while every call goes to the wrong origin. Read it at runtime with a build-time
-fallback:
-  const HOST = (typeof window !== 'undefined' && window.XANO_HOST) || import.meta.env.VITE_XANO_HOST;
-In LOCAL DEV there is no injected global, so the fallback is what answers: set
-`VITE_XANO_HOST` in a `.env.local` beside `.env.example` at the PROJECT ROOT. The
-scaffold's vite config sets `envDir` there (its `root` is `frontend/`, and Vite
-resolves `.env` files against `root`) — without it the var reads as undefined, the
-host falls back to '', and every call 404s off the dev server.
-⚠ It is INJECTED in bracket form — `window["XANO_HOST"]="…"` — so verifying a deploy
-by grepping `window.XANO_HOST` matches nothing and reads as a failed inject. Grep the
-bare `XANO_HOST` token.
-⚠ `xanots preflight` ignores the deploy login and reads `XANO_VALIDATE_INSTANCE` /
-`XANO_VALIDATE_TOKEN` (+ optional `XANO_VALIDATE_WORKSPACE_ID`) from the environment.
-**Displaying a stored file.** A file column comes back as `{ path, name, type, size,
-meta, access, url }`. ⚠ Do NOT use its `url`: on a tenant-scoped environment that field
-addresses the instance host WITHOUT the `/tenant/<name>` segment and 404s, silently —
-as a broken `<img>`, with every API assertion still passing. Build the URL from `path`
-instead: `fileUrl(row.avatar, HOST)` (exported from `@xanots/sdk`) returns `null` for
-an absent file and is correct on an ephemeral and an instance workspace alike.
-⚠ A static host serves these files verbatim, so everything injected is PUBLIC — base
+so the frontend needs no rebuild to target an env. How to read it, local dev, verifying
+the inject, and displaying a stored file: `llms/client.md`.
+⚠ A static host serves its files verbatim, so everything injected is PUBLIC — base
 URLs and publishable keys only, never secrets. Secrets go in backend env, read
 server-side via `env(name)`.
+⚠ `xanots preflight` ignores the deploy login and reads `XANO_VALIDATE_INSTANCE` /
+`XANO_VALIDATE_TOKEN` (+ optional `XANO_VALIDATE_WORKSPACE_ID`) from the environment.
 
 **Full CLI surface:** `xanots <command> --help` lists every command, flag, and
 default; the shipped `manifest.json` carries the same in its `cli` array. This doc
 does not duplicate it — it covers what you must know to AUTHOR a workspace.
-**Recommended style:** reach statements through the `s` namespace
-(`s.db.add`, `s.math.add`, …) — one discoverable, tab-completable surface. The
-flat factory aliases (`dbAdd`, `dbQuery`, `setVar`, `mathAdd`, …) are exported
-and identical in output; prefer `s.*` in new code so examples stay consistent.
+**Style:** reach statements through the `s` namespace (`s.db.add`, `s.math.add`, …).
+The flat aliases (`dbAdd`, `setVar`, …) are identical in output; prefer `s.*`.
 
 ## Gotchas
 
 Non-obvious authoring rules:
 
+### Values and references
+
 - **No callback builder.** Flat def-objects + `register*`, not
   `workspace(w => w.table(...))`. `workspace(name)` returns a named `new Xano()`;
   tables are `table({ schema: { col: f.text() } })`.
-- **Foreign key is `f.tableRef(table)`, not `ref`.** `ref(name)` references a
-  stack variable (a value); `f.tableRef` is the column constructor.
 - **Reference-helper picker:** `ref` = stack var (`as:` output), `inp` = input,
   `col` = table column (in `db.query` `where`), `auth("id")` = the caller,
   `c.*` = a constant. Pick by what you're pointing at.
+- **Foreign key is `f.tableRef(table)`, not `ref`.** `ref(name)` references a
+  stack variable (a value); `f.tableRef` is the column constructor.
 - **Tagged values are DATA — a JS template literal cannot compose them.** `${ref(...)}`
   (or `"a" + ref(...)`) stringifies the tag object at BUILD time: ``c.text(`Hi ${ref("u.name")}`)``
   type-checks and encodes the literal text `Hi [object Object]`, served verbatim.
   `export()` warns; `--strict` fails. Compose at RUNTIME:
   `withFilters(c.text("Hi "), fl.concat(ref("u.name")))`, an `obj({...})`/record member,
   or `c.expression('"Hi, " ~ $var.u.name')`.
-- **`s.api.call` / `s.task.call` / `s.trigger.call` / `s.workflow_test.call` are
-  WORKFLOW-TEST ONLY.** Outside a `workflowTest({...})` stack the engine cannot reach
-  the target, so one in a query/function/task deploys clean and then answers the first
-  real request with `ERROR_FATAL: <Type> does not exist: <type>:<n>` — and not per
-  host kind, the same call fails identically from a function a query runs.
-  `export()` refuses them. `s.function.call`, `s.tool.call`, `s.middleware.call` and
-  `s.addon.call` run anywhere, as does `s.function.run` (the ordinary function
-  invocation). To share logic between endpoints, put it in a `defineFunction` and
-  `s.function.run` it from both.
-- **`expect.*` is a unit-test assertion; `s.expect.*` is a workflow-test statement.**
-  A statement's `mock` is keyed by TEST NAME; an undeclared name throws. See `llms/tests.md`.
-- **Drilling into a maybe-null `db.get` result 500s — use `ref(path, { safe: true })`.**
-  `db.get` binds `null` on a no-match, but a nested `ref("owner.user_id")` resolves
-  `$owner.user_id` in one lookup and raises a runtime "Unable to locate var" (HTTP 500)
-  when `owner` is null — so an ownership/existence guard throws instead of failing
-  cleanly. Either guard existence first (`expr(ref("owner"), "!=", c.null())`,
-  or a `db.has`/`db.query`-count precondition), or drill with the null-safe opt-in:
-  `expr(ref("owner.user_id", { safe: true }), "=", auth("id"))` compiles through the
-  `get` filter and yields `null` (guard reads `false`) rather than 500ing.
-  Works inside `obj({...})` too — no per-member `s.set_var` hoist needed.
-  ⚠ EXPRESSION and `obj()` operands ONLY — never a `db.*` match argument. `null`
-  is not a legal `fieldValue`/`id`, so a chained get (fetch the child row, then
-  fetch its parent to check the owner) fails with HTTP 400 `Missing param:
-  field_value` one statement BEFORE the guard — the same net effect as the 500,
-  with an internal-sounding status the caller should never see. Only an id
-  matching no row reaches it, so it deploys clean. In the chained case guarding
-  existence first is MANDATORY, not a stylistic alternative: precondition on
-  `expr(ref("ticket"), "!=", c.null())`, then drill WITHOUT `safe` (the base is
-  known non-null by then). `export()` warns on a safe ref in that position.
-  ⚠ That is for a base that EXISTS and may be null. If the base binds nothing at all
-  (a typo), `{ safe: true }` turns the 500 into a silent `null` and buries the bug —
-  `export()` warns on a `ref()` whose base segment no `as` in that stack binds, with a
-  did-you-mean; fix the name instead.
+- **Declare inputs with `input.<type>()`, read them with `inp("name")`.** `inp()`
+  resolves ONLY against this def's own `input` block — a value produced earlier in
+  the stack is `ref("var.field")`, not `inp("field")`. An undeclared name fails at
+  runtime with `Unable to locate input` (`export()` warns).
+- **`get_input`/`get_raw_input` read the whole payload**, not one named input
+  (args are `{ as?, encoding?, excludeMiddleware? }` — no `name`). For a single
+  input use `inp("name")`.
+- **To match every row, omit `where` — never pass a constant.** `where: c.bool(true)` is
+  not "no filter": a bare scalar literal states no condition and the engine reads the
+  resulting `context.search` as garbage, so it throws. An absent `where` is how "every
+  row" is spelled. A raw `Value` `where` stays the escape hatch for a clause built
+  elsewhere — `inp("clause")`, `ref("built_where")`, or `c.text("id > 0")`.
+
+### Tables and columns
+
+- **System columns are auto-injected.** `id` + `created_at` are prepended to
+  every table (`system: true` by default); declaring them by hand is redundant.
+  `id` is an `int` PK by default; pass `idType: "uuid"` on the table for a uuid key.
+  Both are valid targets wherever a column name is accepted — `db.query` `sort`/
+  `output`, a `db.get`/`edit`/`del` `fieldName`, etc. (the column-name type is
+  `keyof schema | "id" | "created_at"`), and both appear in `InferRow<typeof table>`.
+- **A column named `run` is reserved.** The table deploys and reads back fine, then
+  EVERY `s.db.add` into it 400s — at any column type, with or without a value — and
+  the error names the column while complaining about the VALUE. Use `run_id`. Exact,
+  case-sensitive, one name: `Run`/`runs`/`run_id` are fine. `--strict` fails on it.
+- **Self-referencing tables** need the bare-name form: inside `tweets`'s own
+  schema, write `f.tableRef("tweets", { type: "int" })` — the `const tweets`
+  handle isn't assigned yet, so the handle form throws "used before declaration".
+- **Seed a table's starting rows with `table({ seed })`.** Rows typed against the
+  schema, inline (`seed: [{ name: "…" }]`) or from a file (`seedFile("./seed.json",
+  import.meta.url)`). Only `deploy` ships them, and a re-deploy re-seeds cleanly. Never
+  put secrets in `seed`. Row shape, `id` pinning, and the file rules: `llms/fields.md`.
+- **`f.password()` defaults to `access: "internal"`, so `db.get` does NOT return it.**
+  A login stack that reads `ref("u.password")` after a plain `db.get` fails at runtime
+  with `Unable to locate var: u.password` — the column is simply absent from the row.
+  Name it in the read's `output` to pull it: `s.db.get({ table: users, fieldName: "email",
+  fieldValue: inp("email"), output: ["id", "email", "password"], as: "u" })`, then
+  `s.security.check_password`. `output` OVERRIDES column visibility — it is the only way to
+  read an `internal` column, and `export()` warns when a stack reads one a `db.get` did not
+  return.
+- **Don't take a password through `input.password` on login — it double-hashes.**
+  An `f.password()` column hashes on write, and `input.password` *also* hashes the
+  submission on bind, so `s.security.check_password` compares two different hashes
+  and a correct password always fails (`ok:false` on a found row). Take the submitted
+  password as `input.text()` on both signup and login and pass the plaintext straight
+  to `check_password` (which does the comparison hash itself). `export()` warns.
+
+### Reading and writing rows
+
 - **DB reads are field-match, not `where`-expr.** `db.get`/`db.edit`/`db.del`/
   `db.has`/`db.patch` match one field: `{ fieldName, fieldValue }` (`fieldName`
   defaults to the PK `id`). Only `db.query` takes a `where`/`additionalWhere`
@@ -267,44 +270,73 @@ Non-obvious authoring rules:
   check-in — use `db.query({ where: [expr(col("habit"), "=", ...), expr(col("date"), "=", ...)], as })`
   (a `where` array is ANDed) and branch on the result, rather than pushing the
   check to the client.
-- **A column named `run` is reserved.** The table deploys and reads back fine, then
-  EVERY `s.db.add` into it 400s — at any column type, with or without a value — and
-  the error names the column while complaining about the VALUE. Use `run_id`. Exact,
-  case-sensitive, one name: `Run`/`runs`/`run_id` are fine. `--strict` fails on it.
-- **System columns are auto-injected.** `id` + `created_at` are prepended to
-  every table (`system: true` by default); declaring them by hand is redundant.
-  `id` is an `int` PK by default; pass `idType: "uuid"` on the table for a uuid key.
-  Both are valid targets wherever a column name is accepted — `db.query` `sort`/
-  `output`, a `db.get`/`edit`/`del` `fieldName`, etc. (the column-name type is
-  `keyof schema | "id" | "created_at"`), and both appear in `InferRow<typeof table>`.
-- **Seed a table's starting rows with `table({ seed })`.** `seed` takes rows
-  typed against the table's schema as a WRITE shape (a column without
-  `required: true`, and the system columns, may be omitted; `null` needs
-  `nullable: true`) — inline (`seed: [{ name: "…" }]`), a FILE
-  (`seed: seedFile("./seed.json", import.meta.url)`; path resolves against the DECLARING
-  file), or a thunk (`seed: () => import("./seed.json")`, async ok, `.default` unwrapped).
-  Inline rows are TYPED against the schema at compile time; a `seedFile`/thunk seed is
-  NOT — the JSON is opaque to the typechecker, and the `xanots export`/`deploy` CLI
-  validates it instead, naming the row index, the offending column, and the known
-  columns. ⚠ Prefer `seedFile` for a file: a thunk's `import()` sits in
-  YOUR module, so a bundler emits the JSON as a served chunk. NEITHER is a secrecy
-  boundary — a bundler that inlines the asset ships them either way. Never put secrets
-  in `seed`. `deploy --static` REFUSES a build carrying internal/sensitive seed values;
-  `--allow-seed-in-static` overrides for deliberately public demo credentials.
-  Deploy is a full replace, so re-deploying re-seeds
-  cleanly (no duplication). Omit `id` and rows auto-number `1..N` (int PK) or take
-  a stable derived uuid (uuid PK); supplying `id` pins it (engine preserves it,
-  resets an int sequence past the max). All-or-nothing — mixing explicit and
-  omitted `id` throws. A `system:false` PK is the author's to supply. Pinning is
-  `seed`-only — `s.db.bulk.add` DROPS `id` unless `allowIdField: true`.
-- **`use_xdo` storage mode.** Workspace setting (`registerWorkspace({ use_xdo })`,
-  default `false`) controlling whether fields are stored as JSON under the `xdo`
-  column (`true`, adds a `gin(xdo)` index) or as real columns (`false`, no gin).
-  Tables inherit it; override per-table with `table({ useXdo })`. Resolved at
-  `export()`, so the workspace and tables can be registered in any order.
-- **Self-referencing tables** need the bare-name form: inside `tweets`'s own
-  schema, write `f.tableRef("tweets", { type: "int" })` — the `const tweets`
-  handle isn't assigned yet, so the handle form throws "used before declaration".
+- **Drilling into a maybe-null `db.get` result 500s — use `ref(path, { safe: true })`.**
+  `db.get` binds `null` on a no-match, but a nested `ref("owner.user_id")` raises a runtime
+  "Unable to locate var" (HTTP 500) when `owner` is null — an ownership guard throws instead
+  of failing cleanly. Two correct shapes:
+  - Guard existence first — `s.precondition({ expr: expr(ref("owner"), "!=", c.null()),
+    error_type: "notfound", error: c.text("Not found.") })` — then drill WITHOUT `safe`.
+  - Or drill null-safe inside an EXPRESSION or `obj()` operand:
+    `expr(ref("owner.user_id", { safe: true }), "=", auth("id"))` yields `null` (the guard
+    reads `false`) instead of 500ing. Works inside `obj({...})` too — no `s.set_var` hoist needed.
+  ⚠ EXPRESSION and `obj()` operands ONLY — never a `db.*` match argument. `null` is not a
+  legal `fieldValue`/`id`, so a chained get (fetch the child row, then its parent to check
+  the owner) fails with HTTP 400 `Missing param: field_value` one statement BEFORE the guard.
+  There guarding existence first is MANDATORY. `export()` warns on a safe ref in that position.
+  ⚠ That is for a base that EXISTS and may be null. If the base binds nothing at all (a typo),
+  `{ safe: true }` buries the bug as a silent `null` — `export()` warns with a did-you-mean;
+  fix the name instead.
+
+### Stacks and calls
+
+- **Block specials nest a `body`, not a `stack`.** `s.for`/`s.foreach`/
+  `s.while`/`s.switch`/`s.try_catch`/`s.db.transaction`/`s.expect.to_throw`
+  take their sub-stack as `body` (`try`/`catch`/`finally` for `try_catch`);
+  `s.group(body)` and `s.util.post_process(body)` take it **positionally**.
+  `s.for` is **count-bounded** (`{ as, count: <Value>, body }`), not from/to. See the
+  authored signatures in `llms/statements-data.md`.
+- **`s.api.call` / `s.task.call` / `s.trigger.call` / `s.workflow_test.call` are
+  WORKFLOW-TEST ONLY.** Outside a `workflowTest({...})` stack the engine cannot reach
+  the target, so one in a query/function/task deploys clean and then answers the first
+  real request with `ERROR_FATAL: <Type> does not exist: <type>:<n>` — and not per
+  host kind, the same call fails identically from a function a query runs.
+  `export()` refuses them. `s.function.call`, `s.tool.call`, `s.middleware.call` and
+  `s.addon.call` run anywhere, as does `s.function.run` (the ordinary function
+  invocation). To share logic between endpoints, put it in a `defineFunction` and
+  `s.function.run` it from both.
+- **`expect.*` is a unit-test assertion; `s.expect.*` is a workflow-test statement.**
+  A statement's `mock` is keyed by TEST NAME; an undeclared name throws. See `llms/tests.md`.
+- **A helper returning `Statement[]` widens the stack and kills `InferResponse`.**
+  Spreading `...requireX()` where the helper is typed `Statement[]` drops the stack's TUPLE
+  type, so EVERY `ref()`/`as` in that stack — even ones after the spread — resolves to
+  `unknown` and the response types as `StackTupleWidened`. Nothing fails at the helper; it
+  surfaces where the response is consumed, often a frontend typecheck. Fix: return
+  `statements(s.a(...), s.b(...))` — its tuple survives the spread. A helper that builds
+  its array in a LOOP cannot be a tuple; declare `responseShape` on the query there.
+- **Build regex-filter patterns with `c.regex(body, flags?)`, never `c.text`.**
+  The regex filters (`regex_test`/`regex_match`/`regex_replace`/…) are PHP `preg_*`: the
+  piped value is the PATTERN and must be delimiter-wrapped, and the ARGUMENT is the subject.
+  Correct: `withFilters(c.regex(/^[a-z-]+$/i), fl.regex_test(inp("slug")))`.
+  - A bare `c.text("^…$")` is an invalid pattern that matches *nothing* for every input,
+    so a precondition on it silently rejects all values. `c.regex(body, "i")` wraps +
+    escapes it for you (a JS `RegExp` too: `c.regex(/^…$/i)`).
+  - Reversed — subject piped, pattern in the argument — reads correctly, type-checks, and
+    answers false for EVERY input, so an `if (matches) reject` guard admits what it refuses.
+  - Build time refuses both: `withFilters` throws on a bare `c.text` pattern from ANY position
+    in the chain (a normalizer in front of the regex filter is refused too; nothing upstream
+    adds the delimiters) and on a pattern found in the subject slot; `s.expect.to_match` is the
+    same PATTERN slot, refused both ways; a `ref`/`inp` pattern is passed through untouched.
+    `export()` warns on a reversed pair in stored bytes.
+  - Better still: a native typed input (`input.email`) over hand-rolled validation.
+- **An `auth()`-keyed limiter collapses on any host with no caller identity — at every**
+  **tier.** `s.redis.ratelimit({ key: withFilters(c.text("rl:"), fl.concat(auth("id"))) })`
+  is the per-user form, but `auth()` is `null` on a public query, a task, or a function,
+  and every caller then shares one bucket. Attaching it once at
+  `apiGroup({ middleware })` or the workspace tier is the tempting DRY move and inherits
+  the same collapse onto every member endpoint. Export warns, naming the tier.
+
+### Identity, build, and deploy
+
 - **Same-name siblings collide — queries excepted: their identity carries group + verb.**
   Guids derive from `(type, name)`, so two functions (or tables, toolsets, …) sharing
   a name derive ONE guid and `export()` throws — give them DISTINCT names. A QUERY
@@ -315,137 +347,34 @@ Non-obvious authoring rules:
   is NOT a lasting fix: a lock entry cannot hold two guids, so `export --lock`
   refuses the pair (`export()` warns even unlocked); it is for pinning identity
   across a rename, not for sharing a name.
-- **`export()` vs `emitBundle()` vs `writeBundle()`:** `writeBundle(app, path)`
-  writes it to disk; `export()` returns the bundle object;
-  `emitBundle()` returns the pretty JSON string. All three run the SAME build-time
-  checks, INCLUDING seed validation of a literal `seed: [...]` array (row shape,
-  unknown column, coercion, enum membership, the all-or-nothing `id` rule). A
-  DEFERRED seed — a thunk (`() => import("./seed.json")`) or `seedFile()` — needs an
-  await or the filesystem, so it is materialised and checked only by the
-  `xanots export`/`deploy` CLI path. Seed rows are never emitted into the bundle
-  either way; only `deploy` ships them. The `node:fs` writers
-  (`writeBundle`/`writeArtifact`) and lock-file I/O import from `@xanots/sdk/node`,
-  NOT the browser-safe `@xanots/sdk` entry (a frontend imports defs from it for
-  `getPath()`/`InferInput`).
-  The compiler machinery (per-kind `encode*`, the registries, the bundle serializer,
-  the lock model) is on `@xanots/sdk/internal` and is never needed to author.
-  READING a bundle back is `@xanots/sdk/bundle` — a statement walker (`2.if.0` paths),
-  a structural hash, `mvp:*` catalog, `tableRefOf`.
-- **Client bundle size / tree-shaking.** `@xanots/sdk` is `sideEffects: false` and pulls
-  no Node built-ins, so a bundler drops unused SDK exports. But importing a **def** for its
-  `getPath()`/`verb`/`getUrl()`/`getChannel()` also pulls whatever its `stack` references:
-  the `s.*`/`c.*` factory CALLS run at module load to BUILD it. Types are free.
-  ⚠ A FLOOR — **~267 kB minified (~65 kB gzipped)** for the FIRST def; splitting modules
-  never removes it. The floor is the RUNTIME, not the def: a second def, or a much richer
-  one, adds ~2 kB — so reducing what a def does will not reduce it.
-  Fix: `xanots routes <entry> --emit xano/routes.gen.ts` (`paths` is an accepted alias) — verbs, paths, and sockets as
-  plain data importing NOTHING, still compile-checked: `routePath("blog/{slug}", { slug })`,
-  `channelPath("rooms/{room_id}", { room_id })`, `socketUrl("chat", baseUrl)` (tenant base
-  URLs lifted to `wss://h/ws/<tenant>:<canonical>`). A rename is a type error, not a 404.
+- **`export()` vs `emitBundle()` vs `writeBundle()`:** `export()` returns the bundle object,
+  `emitBundle()` the pretty JSON string, `writeBundle(app, path)` writes it to disk. All
+  three run the SAME build-time checks, INCLUDING seed validation of a literal `seed: [...]`
+  array (row shape, unknown column, coercion, enum membership, the all-or-nothing `id`
+  rule). A DEFERRED seed — a thunk (`() => import("./seed.json")`) or `seedFile()` — is
+  checked only by the `xanots export`/`deploy` CLI path. Seed rows are never emitted into
+  the bundle either way; only `deploy` ships them.
+  - Entry points: the `node:fs` writers (`writeBundle`/`writeArtifact`) and lock-file I/O
+    import from `@xanots/sdk/node`, NOT the browser-safe `@xanots/sdk` entry (a frontend
+    imports defs from it for `getPath()`/`InferInput`). `@xanots/sdk/internal` is the
+    compiler machinery, never needed to author. READING a bundle back is `@xanots/sdk/bundle`
+    — a statement walker (`2.if.0` paths), a structural hash, `mvp:*` catalog, `tableRefOf`.
 - **Intra-workspace imports use `.js` specifiers** (`../tables/links.js`), not
   extensionless — the defs compile under `moduleResolution: bundler`. Add the `.js`.
-- **Verifying a def outside a bundler.** Inside a bundler (Vite/webpack) importing a
-  query def to read `getPath()`/`verb` works directly. To spot-check from Node, run a REAL
-  file with `tsx <file.ts>` **from inside the project root** — not `tsx -e "import …"`
-  (its CJS-preparse mis-resolves the package `exports` map → ERR_PACKAGE_PATH_NOT_EXPORTED),
-  and not bare `node file.ts` (chokes on the `.js`-specifier intra-workspace imports the
-  xanots CLI's own loader resolves). Running from outside the project root also breaks
-  the `@xanots/sdk` specifier resolution.
-- **A helper returning `Statement[]` widens the stack and kills `InferResponse`.**
-  Factoring a repeated guard into `function requireX(): Statement[]` and spreading it
-  (`...requireX("d")`) drops the stack's TUPLE type, so EVERY `ref()`/`as` in that stack —
-  including ones declared after the spread — resolves to `unknown` and the query's
-  response types as `StackTupleWidened`. Nothing fails at the helper: the error surfaces
-  wherever the response is consumed, often a frontend package's typecheck. Fix: return
-  `statements(s.a(...), s.b(...))` — a const-generic identity export whose tuple survives
-  the spread. A helper that builds its array in a LOOP cannot be a tuple; declare
-  `responseShape` on the query there. See `llms/statements-runtime.md`.
-- **Block specials nest a `body`, not a `stack`.** `s.for`/`s.foreach`/
-  `s.while`/`s.switch`/`s.try_catch`/`s.db.transaction`/`s.expect.to_throw`
-  take their sub-stack as `body` (`try`/`catch`/`finally` for `try_catch`);
-  `s.group(body)` and `s.util.post_process(body)` take it **positionally**.
-  `s.for` is **count-bounded** (`{ as, count: <Value>, body }`), not from/to. See the
-  authored signatures in `llms/statements-data.md`.
-- **MCP servers & agents are distinct root kinds** that both persist under the
-  `toolset` payload key (so a same-name pair collides). `mcpServer({...})` exposes
-  tools over MCP (auth is per-tool — no server-level gate); `agent({...})` carries a
-  typed `llm` block — and so may an `mcpServer`, since the two are ONE stored
-  object distinguished by `type`. Their `tools` take a `tool()` handle (or name), resolved to the
-  tool's guid like the call family; a raw numeric `id` is an escape hatch.
-- **`task.schedule` is an array** of `{ startsOn, freq?, repeatEnabled?, endsOn?, endsEnabled? }`
-  (`ScheduleDef[]`), not a single `{ type, value }`. `freq` is seconds; `startsOn`/
-  `endsOn` are timestamp strings validated at encode time — `"2026-01-01T00:00:00Z"`, or
-  the space-separated `"2026-01-01 00:00:00+0000"` a pulled workspace carries. Never
-  epoch numbers, and never zoneless: the engine stores the string verbatim without
-  checking it, so one it cannot parse deploys clean and the task then never fires.
-- **`get_input`/`get_raw_input` read the whole payload**, not one named input
-  (args are `{ as?, encoding?, excludeMiddleware? }` — no `name`). For a single
-  input use `inp("name")`.
-- **`f.password()` defaults to `access: "internal"`, so `db.get` does NOT return it.**
-  A login stack that reads `ref("u.password")` after a plain `db.get` fails at runtime
-  with `Unable to locate var: u.password` — the column is simply absent from the row.
-  Name it in the read's `output` to pull it: `s.db.get({ table: users, fieldName: "email",
-  fieldValue: inp("email"), output: ["id", "email", "password"], as: "u" })`, then
-  `s.security.check_password`. `output` OVERRIDES column visibility — it is the only way to
-  read an `internal` column, and `export()` warns when a stack reads one a `db.get` did not
-  return.
-- **Build regex-filter patterns with `c.regex(body, flags?)`, never `c.text`.**
-  The regex filters (`regex_test`/`regex_match`/`regex_replace`/…) are pattern-piped
-  PHP `preg_*`: the piped value is the PATTERN and must be delimiter-wrapped, and the
-  ARGUMENT is the subject. A bare `c.text("^…$")` is an invalid pattern that matches
-  *nothing* for every input, so a precondition on it silently rejects all values.
-  `c.regex(body, "i")` wraps + escapes it for you (a JS `RegExp` too: `c.regex(/^…$/i)`).
-  Reversed — subject piped, pattern in the argument — reads correctly, type-checks, and
-  answers false for EVERY input, so an `if (matches) reject` guard admits what it
-  refuses. `withFilters` throws on a bare `c.text` pattern from ANY position in
-  the chain (a normalizer in front of the regex filter is refused too; nothing upstream
-  adds the delimiters) and on a pattern found in the subject slot; `s.expect.to_match`
-  is the same PATTERN slot, refused both ways; a `ref`/`inp` pattern is passed through untouched.
-  `export()` warns on a reversed pair in stored bytes. Better still:
-  a native typed input (`input.email`) over hand-rolled validation.
-- **Compose a rule set as SIBLINGS, not a folded chain.** `and(...rules)` takes any
-  number of terms and encodes flat; `rules.reduce((acc, r) => and(acc, r))` nests one
-  container per rule, which costs quadratic bytes (512 terms: 394 KiB flat, 21 MiB
-  folded) and is refused past 128 levels. Mixed joins: `and(or(...anyOf), ...allOf)`.
-- **Declare inputs with `input.<type>()`, read them with `inp("name")`.** `inp()`
-  resolves ONLY against this def's own `input` block — a value produced earlier in
-  the stack is `ref("var.field")`, not `inp("field")`. An undeclared name fails at
-  runtime with `Unable to locate input` (`export()` warns).
-- **Don't take a password through `input.password` on login — it double-hashes.**
-  An `f.password()` column hashes on write, and `input.password` *also* hashes the
-  submission on bind, so `s.security.check_password` compares two different hashes
-  and a correct password always fails (`ok:false` on a found row). Take the submitted
-  password as `input.text()` on both signup and login and pass the plaintext straight
-  to `check_password` (which does the comparison hash itself).
 - **Agents authenticate with env vars — never `xanots login`.** `login` blocks on a
-  browser consent no agent can complete. Set `$XANO_INSTANCE_URL` + `$XANO_WORKSPACE_ID`
-  + `$XANO_META_TOKEN` and run `deploy`/`release` directly: no disk, no rotation, so it
-  survives repeated runs. It outranks every other credential (`--config` and
-  `$XANO_REFRESH_TOKEN` included, each named on stderr when displaced), and setting SOME
-  of the three is a hard error — a misspelled secret must not fall through to whatever
-  credential the runner has. As a file that triple is `{ "type": "token",
-  "instance_base_url": …, "workspace_id": <n>, "meta_api_token": … }`. The older
-  `$XANO_REFRESH_TOKEN` + `$XANO_CLIENT_ID` pair still works but ROTATES: single-use.
+  browser consent no agent can complete. Set all three of `$XANO_INSTANCE_URL`,
+  `$XANO_WORKSPACE_ID`, `$XANO_META_TOKEN` and run `deploy`/`release` directly: no disk, no
+  rotation, so it survives repeated runs.
+  - The triple outranks every other credential (`--config` and `$XANO_REFRESH_TOKEN` included,
+    each named on stderr when displaced). Setting SOME of the three is a hard error, so a
+    misspelled secret cannot fall through to whatever credential the runner has.
+  - As a file: `{ "type": "token", "instance_base_url": …, "workspace_id": <n>,
+    "meta_api_token": … }`. The older `$XANO_REFRESH_TOKEN` + `$XANO_CLIENT_ID` pair still
+    works but ROTATES: single-use.
 - **Event-driven objects fire on an EPHEMERAL.** A `task` (scheduled), an `mcpServer`,
   and every trigger — `tableTrigger` included — run normally on an ephemeral env, which
   is where `deploy` sends them. So test an event-driven design (screen-on-insert, cron
   cleanup, MCP tool call) by deploying it and letting it run.
-- **Zero-based numeric keys make `c.obj` a LIST.** `c.obj({ "0": "a" })` evaluates to
-  `["a"]`: a numeric key IS an index in the engine's data model, so keys that are exactly
-  `0..n-1` come back as a list with HTTP 200 and no error. Write `c.array([...])` when you
-  want the list, or prefix the keys (`"k0"`) when you want an object. A non-zero-based
-  numeric key (`{ "2": … }`) survives as a key. Export warns.
-- **To match every row, omit `where` — never pass a constant.** `where: c.bool(true)` is
-  not "no filter": a bare scalar literal states no condition and the engine reads the
-  resulting `context.search` as garbage, so it throws. An absent `where` is how "every
-  row" is spelled. A raw `Value` `where` stays the escape hatch for a clause built
-  elsewhere — `inp("clause")`, `ref("built_where")`, or `c.text("id > 0")`.
-- **An `auth()`-keyed limiter collapses on any host with no caller identity — at every**
-  **tier.** `s.redis.ratelimit({ key: withFilters(c.text("rl:"), fl.concat(auth("id"))) })`
-  is the per-user form, but `auth()` is `null` on a public query, a task, or a function,
-  and every caller then shares one bucket. Attaching it once at
-  `apiGroup({ middleware })` or the workspace tier is the tempting DRY move and inherits
-  the same collapse onto every member endpoint. Export warns, naming the tier.
 
 ## Statements
 
@@ -483,7 +412,7 @@ Control flow & blocks (each nests a sub-stack; block specials name it `body`):
 
 # Object kinds
 
-> Read when deciding WHAT to build — every authorable primitive (tables, endpoints, functions, tasks, agents, MCP, realtime, microservices, …), what each is, and which factory + register method build it. Read it too when a `register*` call will not typecheck because the array was built by `.flatMap()`/`.concat()` across modules.
+> Read when deciding WHAT to build — every authorable primitive, what each is, and which factory + register method builds it. Also when `register*` will not typecheck an array built by `.flatMap()`/`.concat()`.
 
 Author with the factory, register on the Xano instance, lands under the payload key. Each line ends with a one-liner on what the primitive is.
 
@@ -504,7 +433,7 @@ Author with the factory, register on the Xano instance, lands under the payload
 - mcp_server: `mcpServer` → `Xano.registerMcpServers` → payload `toolset` — An MCP server exposing a set of tools to external MCP clients.
 - agent: `agent` → `Xano.registerAgents` → payload `toolset` — An AI agent: an LLM configuration plus the tools it can call. Invoke it from any stack (query/function/task/tool/trigger) with `s.ai.agent.run` — no public endpoint; the result is a rich envelope whose completion text is at `.result`.
 - task: `task` → `Xano.registerTasks` → payload `task` — A scheduled background job (cron/interval) that runs a stack on a timer.
-- workflow_test: `workflowTest` → `Xano.registerWorkflowTests` → payload `workflow_test` — An end-to-end test: a named stack with NO input and NO response that invokes other objects (`s.function.call`, `s.task.call`, `s.api.call`) and asserts on what they bind with `s.expect.*`. `datasource` defaults to `""` (an EMPTY datasource, recommended); naming one makes the engine CLONE that datasource before every run, so pointing a test at production-sized data can be slow enough to fail the run — `"live"` warns at compile time.
+- workflow_test: `workflowTest` → `Xano.registerWorkflowTests` → payload `workflow_test` — An end-to-end test: a named stack with NO input and NO response that invokes other objects (`s.function.call`, `s.task.call`, `s.api.call`) and asserts on what they bind with `s.expect.*`. `datasource` defaults to `""` (an EMPTY datasource, recommended); naming one is the clone trap described in `llms/kinds-core.md`.
 - middleware: `middleware` → `Xano.registerMiddleware` → payload `middleware` — A reusable pre/post stack attached to a query/function/task/tool/API group to run before or after its own logic.
 - addon: `addon` → `Xano.registerAddons` → payload `addon` — A reusable read fragment that enriches a query result by joining related table data.
 - realtime_server: `realtimeServer` → `Xano.registerRealtimeServers` → payload `realtime_server` — A realtime (websocket) server: the canonical-addressed container that owns realtime channels. Off until `enabled: true`. Returns a handle with `getUrl(baseUrl)`/`getPath()` for the client's socket URL (`wss://<host>/ws/<canonical>`).
@@ -529,8 +458,18 @@ to survive a rename).
   - `verb`: `"GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "HEAD"` (required), UPPERCASE. Anything else — most often a lowercase `"post"` — makes `query()` THROW, because Xano does NOT reject it: it stores the verb as NULL, a null verb serves as GET, and the endpoint then answers on the wrong method while the one you meant 404s `Unable to locate request.`
   - `apiGroup`: an `apiGroup()` def handle (or its name) — binds by guid, stable across syncs. Raw numeric `apiGroupId?` is the escape hatch and wins if both given.
   - `auth`: `false` (no auth) or an auth-table id; `responseType`: `"standard" | "stream"` (default `standard`) — any other spelling THROWS, since Xano stores an unrecognized one as NULL and a null buffers as `standard`, so a misspelled stream quietly does not stream.
-  - `name` is the endpoint PATH within the group. A `{param}` segment is a URL PATH PARAM bound to the input of the same name, and segments chain: `name: "blog/{slug}/review/{review_id}"` + `input: { slug: input.text(), review_id: input.int() }`. Read it with `inp("slug")` like any other input. Every `{param}` MUST have a matching input or `query()` THROWS — Xano treats an unbound marker as inert route text, so the endpoint would answer on the path and see nothing. A `{param}` need NOT be a whole segment (`"blog/post-{slug}"` routes fine), but its type must fit one segment (no object/list/json/file/geo/vector); there are no wildcards or patterns. `required: true` is NOT demanded (the engine's editor leaves path inputs unmarked). The CONVERSE is warned, not enforced: an input a `GET`/`DELETE`/`HEAD` looks ONE ROW up by (`s.db.get`/`get_by_id`/`has`/by-field edit/patch/delete) belongs in the path — `export()` warns `query.path-segment-candidate`. It still serves `?blog_id=1`, but the route is not addressable and `getPath()` types STATIC, so a caller cannot pass the value positionally. A segment is any value naming WHICH resource is wanted, not just an id (`"shop/{country}"`). An input that NARROWS A LIST (`s.db.query`) stays a query-string param. Inputs absent from the path are ordinary query-string/body params. Name charset is ONLY `A-Za-z0-9_-/{}`, max 200: a `.` (`"export.zip"`) is NOT rejected by Xano — it stores an EMPTY name that deploys clean then 404s forever, so `query()` THROWS. Use `"export_zip"` and set the extension in the response headers.
-  - **Client recipe:** `q.getPath({ params: { slug: "hello" } })` → `/api:<canonical>/blog/hello` — never interpolate by hand. `getPath` percent-encodes each value (so `?`/`#`/spaces stay in their segment) and throws on what encoding cannot contain: a `/`, and a value that IS `.`/`..` (a URL parser drops those before routing — `%2e` counts — addressing a different endpoint). The keys are typed from the literal `name`, so a typo is a compile error. The HANDLE's `q.toSearchParams(input)` drops path params for a GET; the free `query.toSearchParams(input)` has no view of the route and keeps every key.
+  - `name` is the endpoint PATH within the group.
+    - A `{param}` segment is a URL PATH PARAM bound to the input of the same name, and segments chain: `name: "blog/{slug}/review/{review_id}"` + `input: { slug: input.text(), review_id: input.int() }`. Read it with `inp("slug")` like any other input.
+    - Every `{param}` MUST have a matching input or `query()` THROWS — Xano treats an unbound marker as inert route text, so the endpoint would answer on the path and see nothing.
+    - A `{param}` need NOT be a whole segment (`"blog/post-{slug}"` routes fine), but its type must fit one segment (no object/list/json/file/geo/vector); there are no wildcards or patterns. `required: true` is NOT demanded (the engine's editor leaves path inputs unmarked).
+    - The CONVERSE is warned, not enforced: an input a `GET`/`DELETE`/`HEAD` looks ONE ROW up by (`s.db.get`/`get_by_id`/`has`/by-field edit/patch/delete) belongs in the path — `export()` warns `query.path-segment-candidate`. It still serves `?blog_id=1`, but the route is not addressable and `getPath()` types STATIC, so a caller cannot pass the value positionally. A segment is any value naming WHICH resource is wanted, not just an id (`"shop/{country}"`). An input that NARROWS A LIST (`s.db.query`) stays a query-string param.
+    - Inputs absent from the path are ordinary query-string/body params.
+    - Name charset is ONLY `A-Za-z0-9_-/{}`, max 200: a `.` (`"export.zip"`) is NOT rejected by Xano — it stores an EMPTY name that deploys clean then 404s forever, so `query()` THROWS. Use `"export_zip"` and set the extension in the response headers.
+  - **Client recipe:** `q.getPath({ params: { slug: "hello" } })` → `/api:<canonical>/blog/hello` — never interpolate by hand.
+    - `getPath` percent-encodes each value (so `?`/`#`/spaces stay in their segment) and throws on what encoding cannot contain: a `/`, and a value that IS `.`/`..` (a URL parser drops those before routing — `%2e` counts — addressing a different endpoint).
+    - The keys are typed from the literal `name`, so a typo is a compile error.
+    - The HANDLE's `q.toSearchParams(input)` drops path params for a GET; the free `query.toSearchParams(input)` has no view of the route and keeps every key.
+  - What importing a def costs a browser bundle, the `routes.gen.ts` alternative, and how to spot-check a def from Node: `llms/client.md`.
 - `apiGroup({ name, guid?, canonical?, description?, docs?, swagger?, apiGroupEnabled?, documentation?, cors? })` — a query container; register it and bind queries to it via their `apiGroup`.
   - `cors?`: `{ mode?, allowOrigins?: string[], allowHeaders?: string[], allowCredentials?, maxAge?, allowMethods?: { get?, post?, put?, patch?, delete?, head? } }`.
     - `mode?`: `"default"` (the default) | `"custom"` | `"disabled"`, lowercase — a fourth value THROWS at export (`apiGroup()` itself does not check), because Xano neither rejects nor blanks it: it DROPS THE WHOLE API GROUP on import, so the deploy succeeds and every query in the group 404s. ⚠ Every OTHER field applies only under `"custom"`: `"default"` serves a FIXED permissive policy (any origin, `allow-headers: *`, `allow-credentials: true`, `max-age: 86400`) and ignores the block, so setting `maxAge`/`allowCredentials`/`allowHeaders` alone changes nothing. `"disabled"` sends no CORS headers at all, so every browser call fails.
@@ -582,11 +521,94 @@ surface — `s.conditional`/`s.while` `when` (incl. each `elif` branch), and
   `ambiguous-condition`.
 - A **filtered** operand (`withFilters(...)`) works inline in any condition/`where` (conditional,
   while, `db.query`/addon, …) — e.g. `cmp(withFilters(col("title"), fl.trim()), "=", inp("q"))`.
+- **Compose a rule set as SIBLINGS, not a folded chain.** `and(...rules)` takes any
+  number of terms and encodes flat; `rules.reduce((acc, r) => and(acc, r))` nests one
+  container per rule, which costs quadratic bytes (512 terms: 394 KiB flat, 21 MiB
+  folded) and is refused past 128 levels. Mixed joins: `and(or(...anyOf), ...allOf)`.
 - e.g. `db.query({ table: posts, where: expr(col("author"), "=", auth("id")), as: "rows" })`.
 
+# Consuming defs from a client
+
+> Read when a frontend imports a def (`getPath()`/`InferResponse`) or calls the deployed backend — what the import costs, `window.XANO_HOST`, local dev, file URLs, and a Node spot-check.
+
+Importing a def into a browser bundle or a Node script — for `getPath()`, `getUrl()`, `verb`, or `InferResponse` — runs its factory calls; these are the costs and the checks.
+
+- **Client bundle size / tree-shaking.** `@xanots/sdk` is `sideEffects: false` and pulls
+  no Node built-ins, so a bundler drops unused SDK exports. But importing a **def** for its
+  `getPath()`/`verb`/`getUrl()`/`getChannel()` also pulls whatever its `stack` references:
+  the `s.*`/`c.*` factory CALLS run at module load to BUILD it. Types are free.
+  ⚠ A FLOOR — **~267 kB minified (~65 kB gzipped)** for the FIRST def; splitting modules
+  never removes it. The floor is the RUNTIME, not the def: a second or much richer def
+  adds ~2 kB, so trimming a def does not shrink it.
+  Fix: `xanots routes <entry> --emit xano/routes.gen.ts` (`paths` is an accepted alias) — verbs, paths, and sockets as
+  plain data importing NOTHING, still compile-checked: `routePath("GET blog/{slug}", { slug })`
+  `channelPath("rooms/{room_id}", { room_id })`, `socketUrl("chat", baseUrl)` (tenant base
+  URLs lifted to `wss://h/ws/<tenant>:<canonical>`). A rename is a type error, not a 404.
+- **Verifying a def outside a bundler.** Inside a bundler (Vite/webpack) importing a
+  query def to read `getPath()`/`verb` works directly. To spot-check from Node, run a REAL
+  file with `tsx <file.ts>` **from inside the project root** — not `tsx -e "import …"`
+  (its CJS-preparse mis-resolves the package `exports` map → ERR_PACKAGE_PATH_NOT_EXPORTED),
+  and not bare `node file.ts` (chokes on the `.js`-specifier intra-workspace imports the
+  xanots CLI's own loader resolves). Running from outside the project root also breaks
+  the `@xanots/sdk` specifier resolution.
+
+**Reading the injected backend URL.** `xanots deploy <entry> --static <dir>` writes the deployed env's URL
+into every html document: a prerendered build serves a different one per
+route, and a route without the global renders fine while every call goes to the wrong
+origin. Read it at runtime with a build-time fallback:
+  const HOST = (typeof window !== 'undefined' && window.XANO_HOST) || import.meta.env.VITE_XANO_HOST;
+In LOCAL DEV there is no injected global, so the fallback is what answers: set
+`VITE_XANO_HOST` in a `.env.local` beside `.env.example` at the PROJECT ROOT. The
+scaffold's vite config sets `envDir` there (its `root` is `frontend/`, and Vite
+resolves `.env` files against `root`) — without it the var reads as undefined, the
+host falls back to '', and every call 404s off the dev server.
+⚠ It is INJECTED in bracket form — `window["XANO_HOST"]="…"` — so verifying a deploy
+by grepping `window.XANO_HOST` matches nothing and reads as a failed inject. Grep the
+bare `XANO_HOST` token.
+**Displaying a stored file.** A file column comes back as `{ path, name, type, size,
+meta, access, url }`. ⚠ Do NOT use its `url`: on a tenant-scoped environment that field
+addresses the instance host WITHOUT the `/tenant/<name>` segment and 404s, silently —
+as a broken `<img>`, with every API assertion still passing. Build the URL from `path`
+instead: `fileUrl(row.avatar, HOST)` returns `null` for
+an absent file and is correct on an ephemeral and an instance workspace alike.
+
+# Error index
+
+> Read when a request, test, build, or pull fails with a message you did not write — the string, its cause, and where the fix is.
+
+### Request-time (deployed) failures
+
+- `Unable to locate input: <name>` — `inp()` names an undeclared input, or an attached middleware reads its own `input` (never bound). Declare it; a stack value is `ref("var.field")`; middleware reads the body with `s.util.get_all_input`. `llms.txt`; `llms/kinds-core.md`.
+- `Unable to locate var: <a.b>` (HTTP 500) — a dotted `ref` into a null base (a `db.get` miss), or a column absent from the row (`f.password` is `internal`). Guard existence first, or use the null-safe `safe` option; name the column in `output`. `llms.txt`.
+- `Missing var entry: <name>` inside `s.expect.to_throw` — the body runs in an isolated var stack; bind what it needs inside the body. `llms/tests.md`.
+- `Missing param: field_value` (HTTP 400) — a `db.*` match argument resolved to `null` (a safe ref, a nullable foreign key). Guard existence before the lookup; an optional FK stores `0` and is read with field-match `db.get`. `llms.txt`; `llms/fields.md`.
+- `Value is less than the minimum value of 1` (HTTP 400) — `db.get_by_id` given `0`; use field-match `db.get`. `llms/statements-data.md`.
+- `Invalid op: <op>` — a `cmp` operator (`in`, `like`, …) in a RUNTIME condition, which takes the `expr` set only; write `or(expr(...), expr(...))`. `llms/kinds-core.md`.
+- `Unsupported param format` / `Unsupported parameter reference` — an aggregate or `eval` `name` that is not a bare column, or a bare `eval` name for a joined column. `llms/statements-data.md`.
+- `ParseError: Invalid value for param` (HTTP 400) — `contains`/`@>`/`overlaps` on a text column (use `includes`), or a joined column qualified without `tableAlias`. `llms/statements-data.md`.
+- `ERROR_FATAL: <Type> does not exist: <type>:<n>` — `s.api.call`/`s.task.call`/`s.trigger.call`/`s.workflow_test.call` outside a workflow test; share logic via `defineFunction` + `s.function.run`. `llms.txt`.
+- `ERROR_FATAL "Unable to decode."` — a populated JSON string where the engine expects `c.obj`'s form; write `c.obj({...})` or `obj({...})`. `llms/values.md`.
+- `Precondition failed.` in place of your message — `error` was a bare string; pass `c.text("…")`. `llms/fields.md`.
+- `Param: token - Text filter requires an integer, float, string or boolean value` — `s.api.call` `auth.token` given a tagged `Value`; it must be a bare string. `llms/statements-calls.md`.
+- Every `s.db.add` into one table 400s naming a column while complaining about its VALUE — the column is named `run`. `llms.txt`.
+- HTTP 200 with an EMPTY body where `0` was expected — a bare `returnType: "count"` of zero; wrap it as `{ count: ref("n") }`. `llms/statements-data.md`.
+- A lambda returns error TEXT with HTTP 200 (`Could not resolve "node:crypto"`, an undefined-binding message) — the body threw; use the preloaded globals, the surface's bindings, and `capture`. `llms/lambda.md`.
+- `Unable to locate request.` (404) on an endpoint that deployed — a lowercase verb, a `.` in the name, or a CORS `mode` typo that dropped the whole API group. `llms/kinds-core.md`.
+- A browser call fails on a missing `access-control-allow-origin` while deploy looks fine — CORS `mode: "custom"` with `"*"` or an unmatched origin. `llms/kinds-core.md`.
+- A websocket is closed right after the handshake — a refused `connect` gate: an empty/falsy return, a crash, or a gating trigger with no `response`. `llms/triggers.md`.
+- `to_throw failed - response is ok` around an auth-refused call — `ERROR_CODE_ACCESS_DENIED` carries no message; the auth gate is not reachable from a workflow test. `llms/tests.md`.
+- Output reads `Hi [object Object]` — a tagged value inside a JS template literal; compose at runtime with `withFilters` + `fl.concat`. `llms.txt`.
+
+### Build-time and tooling failures
+
+- `must be ES modules` — package.json says `"type": "commonjs"`; set `"type": "module"`. `llms.txt` Quickstart.
+- A response types as `StackTupleWidened` — a `Statement[]` helper was spread into the stack; return `statements(...)`. `llms.txt`; `llms/statements-runtime.md`.
+- `ERR_PACKAGE_PATH_NOT_EXPORTED` — `tsx -e "import …"`, or running from outside the project root; run a real file with `tsx <file.ts>` from the root. `llms/client.md`.
+- `Missing statement: mvp:placeholder` on import — an unconfigured slot in a pulled tree; replace it with the statement it stands in for. `llms/legacy.md`.
+
 # Saved unit tests, assertions, and mocks
 
-> Read when authoring a `workflowTest()` stack, when a query/function/middleware carries `tests`, when a statement should mock a value, or when running a deployed environment's tests.
+> Read when authoring a `workflowTest()` stack, when a query/function/middleware carries `tests`, when a statement needs a `mock`, or when running a deployed environment's tests.
 
 Named input sets run against one object, with assertions on its response — the tests the Xano editor shows. NOT `workflowTest()`, which is a standalone object with its own stack that calls other objects.
 
@@ -626,9 +648,9 @@ A statement returns a value instead of doing its work, for one named test.
 
 The run is isolated in ways that make a correct test fail for reasons the failure message does not name.
 
-- The run uses an EMPTY datasource, so **no `table({ seed })` rows exist while it runs** and every `db` read misses. A test that buys seeded row 1 fails with its own precondition message, which reads as a wrong id rather than an empty database. Create what the test needs INSIDE the test — typically a `defineFunction` fixture the stack calls first.
+- The run uses an EMPTY datasource, so **no `table({ seed })` rows exist while it runs** (same as a unit test, above): a read of seeded row 1 fails with its own precondition message, not an empty-database error. Build fixtures INSIDE the test.
 - `s.api.call` does NOT raise when the endpoint answers with an error. It BINDS the error envelope (`{code, message}`) to its `as` and carries on, so a later `s.expect.to_be_defined({ expr: ref("r.field") })` reports the ASSERTION while the real failure was the call, four statements up. Assert on the envelope — `s.expect.to_contain({ expr: ref("r.code"), value: c.text("ERROR_CODE_INPUT_ERROR") })` — when a call may fail. `s.function.run` raises instead; the two disagree.
-- `s.expect.to_throw({ body, exception? })` runs `body` in an ISOLATED var stack, so a variable bound EARLIER in the test is not visible inside it — bind what the body needs inside the body. `exception` is a `Value` whose text the raised message must CONTAIN (`c.text("already exists")`, not a bare string); omit it to accept any error.
+- `s.expect.to_throw({ body, exception? })` runs `body` in an ISOLATED var stack, so a variable bound EARLIER in the test is not visible inside it — bind what the body needs inside the body. An outer one raises `Missing var entry: <name>` there, which the test reports as `to_throw` not matching (`export()` warns). `exception` is a `Value` whose text the raised message must CONTAIN (`c.text("already exists")`, not a bare string); omit it to accept any error.
 - `s.expect.to_throw` catches such a call only when the error carries a MESSAGE. `ERROR_CODE_ACCESS_DENIED` arrives with an empty one, so `to_throw` around an auth-refused call reports `to_throw failed - response is ok` — which reads as a broken auth gate on a gate that works.
 - An endpoint's `auth` gate is NOT enforced on `s.api.call`. A `query({ auth: users })` runs anyway and fails only where its stack dereferences `auth(...)`. A stack that never touches `auth(...)` runs unauthenticated and passes.
 - Neither `auth.token` nor an `Authorization` entry in `headers` authenticates the call — a token that answers 200 over real HTTP is refused here. To cover auth-gated logic, move the body into a `defineFunction` taking the user id and `s.function.call` that; the gate itself is not reachable from a workflow test.
@@ -656,10 +678,11 @@ The run is isolated in ways that make a correct test fail for reasons the failur
   - `output?`: `{ schema: Record<string, input.*>, enabled? }` — structured-output schema. `schema` is a named-field record authored with the `input.*` catalog, exactly like a `defineFunction`/`query` `input:` map (the stored `structuredOutputsSchema` is the same wire shape as function inputs). e.g. `output: { schema: { priority: input.enum(["low","high"]), summary: input.text() } }`. When you pass the agent *handle* to `s.ai.agent.run({ agent })`, `.result` is typed straight from this schema — no `resultShape` witness needed (the shape is declared once). `resultShape` remains only to override that, or to type an agent referenced by bare name.
   - **Run + read recipe (`s.ai.agent.run`):** bind the run to a var (`s.ai.agent.run({ agent, args, as: "run" })`) — it produces a rich envelope, and the completion is at **`.result`**. Read one structured field with a dotted ref (`response: ref("run.result.priority")`) or the whole completion (`ref("run.result")`, typed from `output.schema`); persist it in a later step the same way (`s.set_var({ name, value: ref("run.result.summary") })`). `args` is a plain object of run inputs (`{ topic: inp("topic") }` — raw literals are fine, e.g. `{ max_steps: 3 }`) surfaced to the agent as `{{ $args.topic }}`. Tool-call / per-step data (when tools ran) rides `.toolCalls` / `.steps` on the same envelope — both optional, absent or empty when no tools executed.
   - **Marketplace:** for chat history, use `@xanots/chatbot`; for vector RAG, use `@xanots/vector` (`tools: [vector.searchTool]`). Find add-ons with `xanots marketplace search <q>`.
+- Both kinds persist under the `toolset` payload key, so a same-name `agent` + `mcpServer` pair derives ONE guid and `export()` throws — give them distinct names.
 
 # Knowledge def shape
 
-> Read when the workspace defines a `knowledge()` item — the markdown its AI agents read.
+> Read when the workspace defines a `knowledge()` item for its AI agents.
 
 - `knowledge({ name, description?, type?, mode?, enabled?, body, refs?, guid?, tags? })` — markdown the workspace's AI agents read before they act. Takes `registerKnowledge`.
   - `body` (REQUIRED): `knowledgeFile("./runbook.md", import.meta.url)` — a path to a real markdown FILE. There is no inline-string form. The path resolves relative to the MODULE THAT DECLARES the item, not the process working directory and not the workspace entry; `import.meta.url` is required and is what makes that true.
@@ -700,11 +723,11 @@ The run is isolated in ways that make a correct test fail for reasons the failur
     - `deliverTo?`: `"channel"` (default) | `"sender"` | `"others"` | `"explicit"`. ⚠ `"explicit"` still delivers to NOBODY — nothing selects recipients from inside a handler, and `s.realtime.publish` (which originates an event INTO a channel) is not a substitute.
     - Only `"channel"`/`"others"` fan out AND are written to the `conversation` transcript — a `"sender"` response is invisible to every future joiner.
   - **Both input surfaces read as ordinary inputs:** `inp("body")` for a payload field, `inp("room_id")` for the channel's `{room_id}`. No session lookup, no frame parsing.
-    - A path param is bound ONCE at join and read from the connection thereafter, never from the frame — a sender cannot claim a room it did not join. The same values reach a channel `join`/`leave` trigger's stack.
+    - A path param is bound ONCE at join and read from the connection thereafter, never from the frame — a sender cannot claim a room it did not join.
   - `s.realtime.get_session({ as })` — the CALLER's realtime session for the current frame. FLAT shape:
     - `authenticated` bool · `client_id` text (the AUTHED ROW ID as text, `""` anonymous) · `dbo_id` int (the auth TABLE's id — NOT the user's row id; `0` anonymous — to look the caller up use `client_id`. `dbo_id` is an int in the same position and typechecks, so a gate that keys on it finds no user and refuses EVERYONE) · `socket_id` int (transport id) · `channel` text (resolved path, `""` in a server trigger) · `params` object (bound path params, `{}` when none — `ref("session.params.room_id")`) · `extras` object · `opened_at` decimal.
     - Works in a realtime MESSAGE stack and in CHANNEL and SERVER trigger stacks; off that path it degrades to an anonymous session.
-    - For a path param prefer `inp("room_id")`. Reach for the session when you need the CONNECTION (identity/extras) — "who is this sender" on an anonymous-client channel.
+    - For a path param prefer `inp("room_id")` in a MESSAGE; a lifecycle TRIGGER has only the session. Reach for the session when you need the CONNECTION (identity/extras) — "who is this sender" on an anonymous-client channel.
     - ⚠ THREE UNRELATED THINGS ARE CALLED A CLIENT ID: `session.client_id` (app-facing identity), `session.socket_id` (transport), and a frame's `options.client_id` (the at_least_once CURSOR handle). Conflating the first and last breaks at_least_once for anonymous clients.
   - `s.realtime.publish({ server, channel, data, message?, authTable?, authId? })` — the PUSH direction: originate a server-authored event onto a channel from ANY stack, no client frame first.
     - `server` is the handle or its NAME (resolved by name, not guid); `channel` is the FILLED-IN path (`channel.getChannel({ room_id: 42 })`), never the template — a constant still carrying `{param}` THROWS at author time, and a constant `server`/`channel` naming nothing this workspace registers WARNS at export.
@@ -739,7 +762,7 @@ The run is isolated in ways that make a correct test fail for reasons the failur
   - **Conversation frames — the transcript hydrates the client, so DO NOT build a hydration endpoint.**
     - On a `conversation` channel the replay is PUSHED automatically at join, unasked: `conversation_start` (`payload.count`) → the last `limit` messages, each a normal `action: "message"` frame carrying its ORIGINAL `type` and `payload` plus `conversation: true` and the original `ts` → `conversation_end`.
     - So the client needs NO fetch, no `GET /messages`, and no table read to paint the initial view. Render `message` frames identically either way; the backfill paints itself.
-    - ⚠ `{ enabled: true }` ALONE IS A NO-OP: `limit` defaults to 0, and 0 means RETAIN NONE (not retain everything), so the transcript is never written and never replayed, with no error. ALWAYS PASS `limit`.
+    - ⚠ `{ enabled: true }` alone is a no-op: `limit` defaults to 0 and 0 means RETAIN NONE (see `conversation` above) — always pass `limit`.
     - The POST-HANDLER broadcast payload IS the stored transcript row — a handler must broadcast everything the UI needs to render a past message (author name, id, `created_at`). Nothing else is replayed.
     - Only `deliverTo` `"channel"`/`"others"` are RECORDED, so a `"sender"` response is invisible to every future joiner by construction.
     - The transcript is a capped ring (`limit`, `ttl`), not storage. Persist to a table only for durability, search, or reads BEYOND that window — never merely to hydrate a joiner.
@@ -772,8 +795,20 @@ realtimeChannelTrigger, mcpServerTrigger, agentTrigger, workspaceTrigger,
 errorTrigger}({ name, guid?, description?, active?, tags?, ... })`.
 
 - `tableTrigger({ name, table?, datasources?, actions?: {insert?,update?,delete?,truncate?}, stack })` — database/table trigger. `t.new` / `t.old` are the row **after** / **before** the change; `t.action` (`insert|update|delete|truncate`), `t.datasource`. Bind `table` to a `table()` handle and `t.new("col")` / `t.old("col")` are typed to that row (misspelled column = compile error). Nullability follows the enabled actions: insert → `old` is null, delete → `new` is null, update → both, truncate → neither. Config-only (no response).
-- `realtimeServerTrigger({ name, realtimeServer, actions?: {connect?,disconnect?}, stack?, response?, responseShape? })` — realtime SERVER lifecycle (a client connecting to / disconnecting from the server, not a message). Inputs: `t.action` (`connect|disconnect`), `t.realtime_server`, `t.client`. Bind `realtimeServer` to a `realtimeServer()` handle (or its name). `connect` GATES the connection — a denial sends an `error` and CLOSES the socket with code 4401 before it is ever ready, so it is a real front door, not an observer; same return shape as a channel `join` (`{ allowed: c.bool(true) }` or any truthy value admits, EMPTY/FALSY DENIES — INCLUDING a gating trigger with NO `response`, which returns nothing and so refuses every client). A CRASH DENIES too — the transport seeds a deny and keeps it on a throw. Both failure modes lock the door, so plan for a self-inflicted LOCKOUT (an unguarded drill into a null `db.get` raises → everyone refused), not a breach. Gating is OPT-IN: a server with no `connect` trigger accepts every connection. `disconnect` is OBSERVATIONAL (return ignored, throws swallowed — cleanup must always complete). Both are SERVER-scoped, so `s.realtime.get_session` works but carries no channel path and no bound params.
-- `realtimeChannelTrigger({ name, channel, actions?: {join?,leave?,deliver?}, stack?, response?, responseShape? })` — realtime CHANNEL lifecycle. Inputs: `t.action` (`join|leave|deliver`), `t.channel`, `t.client`. Bind `channel` to a `realtimeChannel()` handle — a bare path is NOT accepted (it is unique only within its server). The three actions have DIFFERENT postures, and the posture decides what the stack should return: `join` GATES the join (it runs BEFORE the client becomes a member, so a denial means it never sees a fan-out) — return `{ allowed: c.bool(true) }` (optional `reason` reaches the client) or any truthy value to admit, and an EMPTY OR FALSY RETURN DENIES, so a stack that just falls through — or a gating trigger with NO `response` — refuses everyone, and a CRASH DENIES too. That is the inverse of a normal message (a crashing message still delivers) and of `deliver` below (a gate that fails OPEN). `join`/`leave` bind the channel's typed path params as INPUTS, so `inp("room_id")` resolves and the gate decides per room; a SERVER connect/disconnect has no channel, the one place a path param cannot be read; `leave` is OBSERVATIONAL (return ignored, throws swallowed); `deliver` GATES delivery PER RECIPIENT — the per-viewer redaction tool and the most expensive action here (a stack per recipient per message), and it needs `delivery.perRecipient` on the channel to run at all — BOTH HALVES are required, so a `deliver` trigger on a channel without the flag NEVER RUNS and every subscriber receives the UNREDACTED payload (no error, no log line); `export()` warns on each half alone. **`deliver`'s RETURN VALUES DO NOT READ LIKE A FILTER:** ONLY an explicit NULL drops the message for that recipient; an OBJECT replaces that recipient's payload; ANYTHING ELSE — INCLUDING `false`, `0`, `""` — DELIVERS IT UNCHANGED, as does a crash. So `return false` from a yes/no redaction check SENDS the message it was written to suppress — return null instead. The delivered payload arrives NESTED, so read `inp("payload").<field>`, and `t.client` is the SENDER while `s.realtime.get_session` describes the RECIPIENT this run is for.
+- `realtimeServerTrigger({ name, realtimeServer, actions?: {connect?,disconnect?}, stack?, response?, responseShape? })` — realtime SERVER lifecycle (a client connecting to / disconnecting from the server, not a message). Inputs: `t.action` (`connect|disconnect`), `t.realtime_server`, `t.client`. Bind `realtimeServer` to a `realtimeServer()` handle (or its name).
+  - `connect` GATES the connection — a denial sends an `error` and CLOSES the socket with code 4401 before it is ever ready, so it is a real front door, not an observer; same return shape as a channel `join` below (EMPTY/FALSY DENIES — INCLUDING a gating trigger with NO `response`, which returns nothing and so refuses every client).
+  - A CRASH DENIES too — a gate that cannot answer must not admit. Both failure modes lock the door, so plan for a self-inflicted LOCKOUT (an unguarded drill into a null `db.get` raises → everyone refused), not a breach.
+  - Gating is OPT-IN: a server with no `connect` trigger accepts every connection.
+  - `disconnect` is OBSERVATIONAL (return ignored, throws swallowed — cleanup must always complete).
+  - Both are SERVER-scoped, so `s.realtime.get_session` works but carries no channel path and no bound params.
+- `realtimeChannelTrigger({ name, channel, actions?: {join?,leave?,deliver?}, stack?, response?, responseShape? })` — realtime CHANNEL lifecycle. Inputs: `t.action` (`join|leave|deliver`), `t.channel`, `t.payload`, `t.client`. Bind `channel` to a `realtimeChannel()` handle — a bare path is NOT accepted (it is unique only within its server). The three actions have DIFFERENT postures, and the posture decides what the stack should return:
+  - `join` GATES the join (it runs BEFORE the client becomes a member, so a denial means it never sees a fan-out) — return `{ allowed: c.bool(true) }` (optional `reason` reaches the client) or any truthy value to admit, and an EMPTY OR FALSY RETURN DENIES, so a stack that just falls through — or a gating trigger with NO `response` — refuses everyone, and a CRASH DENIES too. ONCE the object carries an `allowed` key admission needs STRICTLY `true` — a computed `1`/`"yes"` there DENIES. That is the inverse of a crashing message, which still delivers, and of `deliver` below.
+  - A lifecycle trigger's inputs are PINNED to those four, so a channel PATH PARAM is NOT among them — `inp("room_id")` RAISES, which crashes the gate and so REFUSES every client; take the param from `s.realtime.get_session` (`ref("session.params.room_id")`).
+  - A gate establishes NO auth, so `ref("auth.id")` reads 0 even when authenticated — identity is `t.client("permissions.dbo_id")` or the session. A SERVER connect/disconnect has no channel, so no params at all.
+  - `leave` is OBSERVATIONAL (return ignored, throws swallowed).
+  - `deliver` GATES delivery PER RECIPIENT — the per-viewer redaction tool and the most expensive action here (a stack per recipient per message), and it needs `delivery.perRecipient` on the channel to run at all — BOTH HALVES are required, so a `deliver` trigger on a channel without the flag NEVER RUNS and every subscriber receives the UNREDACTED payload (no error, no log line); `export()` warns on each half alone.
+  - **`deliver`'s RETURN VALUES DO NOT READ LIKE A FILTER:** ONLY an explicit NULL drops the message for that recipient; an OBJECT replaces that recipient's payload; ANYTHING ELSE — INCLUDING `false`, `0`, `""` — DELIVERS IT UNCHANGED, as does a crash. So `return false` from a yes/no redaction check SENDS the message it was written to suppress — return null instead.
+  - The delivered payload arrives NESTED, so read `t.payload("<field>")`, and `t.client` is the SENDER while `s.realtime.get_session` describes the RECIPIENT this run is for.
 - `mcpServerTrigger({ name, mcpServer, stack?, response?, responseShape? })` / `agentTrigger({ name, agent, stack?, response?, responseShape? })` — toolset connection. Bind with the `mcpServer()`/`agent()` def handle (or its name) — it resolves to the toolset guid at export. Raw numeric `objId` is the escape hatch, rarely right: ids are assigned at import, so a handle passed to `objId` is a type error, and binding nothing deploys a trigger that never fires. Inputs: `t.toolset` (`t.toolset("name")`), `t.tools`. Response-bearing; the default stack copies `toolset`/`tools` into vars and returns them.
 - `workspaceTrigger({ name, actions?: {branch_live?,branch_merge?,branch_new?}, stack? })` — branch lifecycle. Inputs: `t.to_branch`, `t.from_branch`, `t.action`. Config-only.
 - `errorTrigger({ name, stack? })` — error-signature trigger. Inputs: `t.event` (`new|regression|fixed`), `t.id`, `t.signature`, `t.error` (`t.error("code")`/`t.error("message")`), `t.caller`, `t.statement`, `t.actor`, `t.count`, `t.first_seen`, `t.last_seen`, `t.fixed_at`. Config-only.
@@ -846,7 +881,7 @@ primary key `id`):
 
 # Statement runtime behavior
 
-> Read when you need to know what a statement's `as:` output actually holds, or why a bound variable is not the shape you expected.
+> Read when you need to know what a statement's `as:` output holds, or why a bound variable is not the shape expected.
 
 Runtime behavior (what the `as:` output holds, and misses):
 
@@ -884,12 +919,27 @@ Runtime behavior (what the `as:` output holds, and misses):
   - Attaching a typed `addon({ table, output })` handle merges its alias (the last `as` segment) onto the row in `InferResponse`: `{cols}` for `single`, `{cols}[]` for `list`, `number` for `count`, `boolean` for `exists`, and for `aggregate` an array keyed by the `group`/`eval` aliases (`unknown` values; `unknown` when neither is declared).
   - An attachment-level `output` narrows an object/array graft further. A bare-NAME reference grafts `unknown` — narrow it at the call site.
   - ⚠ An alias that shadows an existing column on the queried table throws at build time; rename with a `_` prefix.
-- **Middleware attachment** runs a reusable `middleware({...})` before/after a host's own stack. Attach with the host's `middleware: { pre, post }` field on `query`/`function`/`task`/`tool`/`apiGroup` (NOT triggers): each phase is an ordered list of middleware refs (def handle or name), or `{ middleware, active: false }` to keep an entry disabled. Providing a phase **overrides** it (sets the stored `pre_customize`/`post_customize` flag); omitting a phase **inherits** the parent tier's chain — the engine resolves Query → API Group → Workspace at request time (override, not merge; the API-Group tier applies to queries — functions/tasks/tools have no API-group binding and inherit straight from the workspace). Prefer a def handle over a bare name when the middleware pins an explicit `guid`. `pre: middleware.clear()` (an empty list) overrides with nothing — stop inheriting. Workspace-level defaults are the terminal tier: `workspaceConfig({ middleware: { query: { pre }, function, task, tool } })` emits the flat `{host}_{phase}` map (no `_customize` flags) — setting it replaces the whole workspace map, so unlisted hosts are cleared; omit the field to leave existing workspace middleware untouched. Distinct from `s.middleware.call` (inline invoke).
-- **Middleware request context.** A `pre` middleware runs **after** auth resolution, so `auth()` is available inside the middleware when the host is authenticated (its `auth` names an auth table); on a public host `auth()` is `null`. This matters for the canonical use — a rate limit keyed by `auth("id")`: on an authenticated endpoint the bucket is per-user, but attach the same middleware to a public endpoint and every anonymous caller keys under the same `null` id (one shared bucket), silently. To catch that, `export()` **warns** (never blocks) when a middleware whose stack references `auth()` is directly attached to a host where `auth()` may be null — a `query` with no auth table, a `task` (scheduled, never authenticated), or a `function`/`tool` (whose auth is caller-dependent). An authenticated query (its own `auth` table set) is skipped. The check is direct-attachment only; a middleware reaching a public query via API-group/workspace tier inheritance is not caught.
-- **Rate-limit recipe (the canonical middleware).** Per-user rate limiting is the most common middleware. Author it with `s.redis.ratelimit` and a **composite key** built via the filter chain — `"prefix" + auth("id")` does not exist, you build the key: `middleware({ name: "write_rl", exceptionPolicy: "rethrow", stack: [ s.redis.ratelimit({ key: withFilters(c.text("rl:write:"), fl.concat(auth("id"))), max: c.int(10), ttl: c.int(30), error: c.text("Too fast.") }) ] })`. `exceptionPolicy` defaults to `"rethrow"`, which is what makes a tripped limit abort with HTTP 429; `"silent"` would let the over-limit request through. Attach it with `middleware: { pre: [writeRl] }` on an **authenticated** host (its `auth` set) so `auth("id")` keys per-user; on a public host `auth("id")` is null and every caller shares one bucket (`export()` warns — see request context above). **Shared-bucket rule:** co-attaching one middleware object to N hosts means all N share the *same* key ⇒ *one* counter — `max: 10` is a global per-user budget across them, not 10-per-host. Vary the key (fold in the host/action name) for an independent limit per host.
+- **Middleware attachment** runs a reusable `middleware({...})` before/after a host's own stack. Distinct from `s.middleware.call` (inline invoke).
+  - Attach with the host's `middleware: { pre, post }` field on `query`/`function`/`task`/`tool`/`apiGroup` (NOT triggers): each phase is an ordered list of middleware refs (def handle or name), or `{ middleware, active: false }` to keep an entry disabled.
+  - Providing a phase **overrides** it (sets the stored `pre_customize`/`post_customize` flag); omitting a phase **inherits** the parent tier's chain — the engine resolves Query → API Group → Workspace at request time (override, not merge; the API-Group tier applies to queries — functions/tasks/tools have no API-group binding and inherit straight from the workspace).
+  - Prefer a def handle over a bare name when the middleware pins an explicit `guid`.
+  - `pre: middleware.clear()` (an empty list) overrides with nothing — stop inheriting.
+  - Workspace-level defaults are the terminal tier: `workspaceConfig({ middleware: { query: { pre }, function, task, tool } })` emits the flat `{host}_{phase}` map (no `_customize` flags) — setting it replaces the whole workspace map, so unlisted hosts are cleared; omit the field to leave existing workspace middleware untouched.
+- **Middleware request context.** A `pre` middleware runs **after** auth resolution, so `auth()` is available inside the middleware when the host is authenticated (its `auth` names an auth table); on a public host `auth()` is `null`.
+  - This matters for the canonical use — a rate limit keyed by `auth("id")`: on an authenticated endpoint the bucket is per-user, but attach the same middleware to a public endpoint and every anonymous caller keys under the same `null` id (one shared bucket), silently.
+  - To catch that, `export()` **warns** (never blocks) when a middleware whose stack references `auth()` is directly attached to a host where `auth()` may be null — a `query` with no auth table, a `task` (scheduled, never authenticated), or a `function`/`tool` (whose auth is caller-dependent). An authenticated query (its own `auth` table set) is skipped.
+  - The check is direct-attachment only; a middleware reaching a public query via API-group/workspace tier inheritance is not caught.
+- **Rate-limit recipe (the canonical middleware).** Per-user rate limiting is the most common middleware. Author it with `s.redis.ratelimit` and a **composite key** built via the filter chain — `"prefix" + auth("id")` does not exist, you build the key: `middleware({ name: "write_rl", exceptionPolicy: "rethrow", stack: [ s.redis.ratelimit({ key: withFilters(c.text("rl:write:"), fl.concat(auth("id"))), max: c.int(10), ttl: c.int(30), error: c.text("Too fast.") }) ] })`.
+  - `exceptionPolicy` defaults to `"rethrow"`, which is what makes a tripped limit abort with HTTP 429; `"silent"` would let the over-limit request through.
+  - Attach it with `middleware: { pre: [writeRl] }` on an **authenticated** host (its `auth` set) so `auth("id")` keys per-user; on a public host `auth("id")` is null and every caller shares one bucket (`export()` warns — see request context above).
+  - **Shared-bucket rule:** co-attaching one middleware object to N hosts means all N share the *same* key ⇒ *one* counter — `max: 10` is a global per-user budget across them, not 10-per-host. Vary the key (fold in the host/action name) for an independent limit per host.
 - **Middleware `exceptionPolicy`** governs what a **throw** in the middleware stack does to the request (XanoTS passes the value through; the Xano engine interprets it). `"rethrow"` is the **default** — the throw aborts the request and surfaces the authored `error`/status (a tripped `s.redis.ratelimit` → HTTP 429); the `post` chain still runs. `"silent"` swallows the throw, so a guard set to it is **not enforced** — advisory middleware only. `"critical"` is `"rethrow"` plus skipping the `post` chain. The only difference between `rethrow` and `critical` is whether `post` runs — no status or logging change.
 
-- **Request history** controls per-object execution capture (the request/task/trigger debugger). Authored as a single scalar `history` field on any primitive: `false` off, `true` on at the default capture depth, a number = capture depth (how many statement executions are recorded per history record — NOT record retention), `"all"` unlimited. **Omit `history` to inherit** — the engine resolves object → container → workspace at request time (a query inherits from its API group, a tool from its toolset envelope, everything else straight from the workspace). Any authored value stops inheriting for that object. Per-kind defaults (when inheriting): query/task/tool capture ON, function/trigger/middleware OFF; default depth 100. Container tiers are authorable too — `apiGroup({ history })` sets the `query_*` default its queries inherit, and an agent/mcp_server/toolset `history` sets the `tool_*` default its tools inherit. Workspace-level defaults are the terminal tier: `workspaceConfig({ history: { query, function, task, tool, trigger, middleware } })` emits the flat `{objType}_enabled`/`{objType}_limit` map (no inherit flag) — setting it is wholesale (unlisted types fall back to their engine default), so declare every default you want to keep; omit the field to leave existing workspace history untouched.
+- **Request history** controls per-object execution capture (the request/task/trigger debugger). Authored as a single scalar `history` field on any primitive: `false` off, `true` on at the default capture depth, a number = capture depth (how many statement executions are recorded per history record — NOT record retention), `"all"` unlimited.
+  - **Omit `history` to inherit** — the engine resolves object → container → workspace at request time (a query inherits from its API group, a tool from its toolset envelope, everything else straight from the workspace). Any authored value stops inheriting for that object.
+  - Per-kind defaults (when inheriting): query/task/tool capture ON, function/trigger/middleware OFF; default depth 100.
+  - Container tiers are authorable too — `apiGroup({ history })` sets the `query_*` default its queries inherit, and an agent/mcp_server/toolset `history` sets the `tool_*` default its tools inherit.
+  - Workspace-level defaults are the terminal tier: `workspaceConfig({ history: { query, function, task, tool, trigger, middleware } })` emits the flat `{objType}_enabled`/`{objType}_limit` map (no inherit flag) — setting it is wholesale (unlisted types fall back to their engine default), so declare every default you want to keep; omit the field to leave existing workspace history untouched.
 
 - **Workspace environment variables** set a tenant's env vars through the workspace object: `workspaceConfig({ env: { STRIPE_KEY: process.env.STRIPE_KEY!, APP_BASE_URL: "https://…" } })`. Author them as a name→value MAP. Read a var back with `env("NAME")` (→ `$env.NAME`), which compiles to tag "setting" with the plain name. Values are SECRETS: prefer sourcing from `process.env` over committing literals, and don't commit a compiled bundle with real values. `deploy` REPLACES the tenant's env with the declared map; `release` (merge) is ADD-ONLY — it creates missing keys but does NOT update or remove existing ones, so changing a value in code and releasing leaves the live value unchanged. Omit `env` to leave existing env untouched. The separate `settings` field is a plain object.
 
@@ -908,8 +958,20 @@ Auth & calls:
 - `s.security.create_guid({ as? })` — bind a fresh GUID string. Takes nothing else.
 - `s.function.run({ fn, input?, as?, runtime? })` / `s.function.call({ fn, input?, as? })` — run another function; `input` is keyed by the target's input names.
   - `runtime?` runs it in the BACKGROUND: `{ mode: "async-shared" }` or `{ mode: "async-dedicated", cpu?, memory?, timeout?, maxRetry? }` (resources read at dedicated only). An async call DOES NOT return the result — it dispatches and continues, so `as` binds nothing; collect with `s.await({ ids })`. Omit for a normal call. Same block on `s.ai.agent.run`.
-- `s.api.call({ api, input?, headers?, auth?, as? })` — invoke an endpoint. `api` takes the `query()` def HANDLE (or a `{ name, guid }` pair) — a bare name is refused, because a query's identity is composed from its api group, verb, and name. `headers` REPLACES the request headers the callee sees and takes the same shapes as `s.api.request`'s — a `{ "Name": value }` record (values may be tagged), a `string[]` of `"Name: value"` lines, or one `Value`. `auth` is `{ token, ignoreExpiration? }`: `token` must be a BARE STRING — a tagged `Value` deploys clean and then fails the run with `Param: token - Text filter requires an integer, float, string or boolean value`, since the engine stores that slot as plain text and never evaluates it. Neither slot authenticates the call today; see `llms/tests.md` for what a workflow-test run actually sees. WORKFLOW-TEST ONLY (see Gotchas in `llms.txt`) — elsewhere it deploys clean and 500s the first real request.
-- `s.api.request({ url, method?, params?, headers?, timeout?, follow_location?, verify_host?, verify_peer?, ca_certificate?, certificate?, certificate_pass?, private_key?, private_key_pass?, description?, output?, as? })` — external HTTP request (`mvp:api_request`). Ergonomic types, each also accepting a dynamic `Value`: `method` suggests the 7 verbs (GET/POST/PUT/DELETE/HEAD/OPTIONS/PATCH), `params` a plain JSON object **or** a FLAT record whose values are tagged `Value`s (`{ count: ref("count") }`, each lifted via a `set` filter — the same record-of-values shape `response: { key: value }` takes); a tagged value NESTED inside an object or array THROWS at encode, so wrap a structured body in `obj({...})`, which encodes any depth as one `const:expr2` (→ query string for GET/HEAD/OPTIONS, body otherwise), `headers` a `{ "Name": value }` record whose values may be tagged (`{ "x-api-key": env("KEY") }`, each pair joined to a `"Name: value"` line) **or** a `string[]` of full header lines — prefer a header over a `?key=` query param for a credential — a URL travels into access logs, proxies and `Referer`. ⚠ Neither spelling is envelope-safe: the `as` envelope's `request` half mirrors `url`, `params` AND `headers`, so never return it raw from a credentialed request — read `response.result`. A NAME outside the header-token charset is refused, and a LITERAL value carrying a newline is refused; a value may hold `:` and spaces (`Bearer a: b` is a valid value). A TAGGED value cannot be checked at build time, so strip CRLF from caller-controlled input before this slot. Literal pairs lead the emitted array and computed ones follow, so the wire order is not the record's key order, `timeout` a `number` in seconds (1–86400), and `follow_location`/`verify_host`/`verify_peer` booleans. `description` (Settings tab) and `output` filters (Output tab) ride the envelope. SSL cert interdependencies (certificate↔private_key, ca_certificate→verify_peer) are checked at build time when statically provable, else by the engine at runtime. The `as` result is typed as the `{request, response}` envelope (`response.status: number`, `response.result: unknown`), so `InferResponse` resolves a `ref` to it. Same typed result on `webflow.request` and `microservice.request`.
+- `s.api.call({ api, input?, headers?, auth?, as? })` — invoke an endpoint. WORKFLOW-TEST ONLY (see Gotchas in `llms.txt`).
+  - `api` takes the `query()` def HANDLE (or a `{ name, guid }` pair) — a bare name is refused, because a query's identity is composed from its api group, verb, and name.
+  - `headers` REPLACES the request headers the callee sees and takes the same shapes as `s.api.request`'s — a `{ "Name": value }` record (values may be tagged), a `string[]` of `"Name: value"` lines, or one `Value`.
+  - `auth` is `{ token, ignoreExpiration? }`: `token` must be a BARE STRING — a tagged `Value` deploys clean and then fails the run with `Param: token - Text filter requires an integer, float, string or boolean value`, since the engine stores that slot as plain text and never evaluates it.
+  - Neither slot authenticates the call today; see `llms/tests.md` for what a workflow-test run actually sees.
+- `s.api.request({ url, method?, params?, headers?, timeout?, follow_location?, verify_host?, verify_peer?, ca_certificate?, certificate?, certificate_pass?, private_key?, private_key_pass?, description?, output?, as? })` — external HTTP request (`mvp:api_request`). Ergonomic types, each also accepting a dynamic `Value`:
+  - `method` suggests the 7 verbs (GET/POST/PUT/DELETE/HEAD/OPTIONS/PATCH).
+  - `params` a plain JSON object **or** a FLAT record whose values are tagged `Value`s (`{ count: ref("count") }`, each lifted via a `set` filter — the same record-of-values shape `response: { key: value }` takes); a tagged value NESTED inside an object or array THROWS at encode, so wrap a structured body in `obj({...})`, which encodes any depth as one `const:expr2` (→ query string for GET/HEAD/OPTIONS, body otherwise).
+  - `headers` a `{ "Name": value }` record whose values may be tagged (`{ "x-api-key": env("KEY") }`, each pair joined to a `"Name: value"` line) **or** a `string[]` of full header lines — prefer a header over a `?key=` query param for a credential — a URL travels into access logs, proxies and `Referer`.
+  - ⚠ Neither spelling is envelope-safe: the `as` envelope's `request` half mirrors `url`, `params` AND `headers`, so never return it raw from a credentialed request — read `response.result`.
+  - A NAME outside the header-token charset is refused, and a LITERAL value carrying a newline is refused; a value may hold `:` and spaces (`Bearer a: b` is a valid value). A TAGGED value cannot be checked at build time, so strip CRLF from caller-controlled input before this slot. Literal pairs lead the emitted array and computed ones follow, so the wire order is not the record's key order.
+  - `timeout` a `number` in seconds (1–86400), and `follow_location`/`verify_host`/`verify_peer` booleans.
+  - `description` (Settings tab) and `output` filters (Output tab) ride the envelope. SSL cert interdependencies (certificate↔private_key, ca_certificate→verify_peer) are checked at build time when statically provable, else by the engine at runtime.
+  - The `as` result is typed as the `{request, response}` envelope (`response.status: number`, `response.result: unknown`), so `InferResponse` resolves a `ref` to it. Same typed result on `webflow.request` and `microservice.request`.
 - `s.stream.from_request({ url, method?, …tls, as? })` — streaming external HTTP request (`mvp:streaming_api_request`); same typed field surface as `s.api.request` (no description/output envelope). `url` is REQUIRED — it shares `api.request`'s engine declaration, which has no default.
 - `s.util.send_email({ to, subject, message, from?, cc?, bcc?, reply_to?, service_provider?, api_key?, scheduled_at?, as? })` — send email from the stack. `service_provider` is `"xano"` (the built-in mailer — needs NO `api_key` and no configuration, and does not require a verified sender) or `"resend"` (pass the key as `api_key: env("RESEND_API_KEY")`). Prefer this over hand-rolling `s.api.request` against a mail provider.
 - `s.webflow.request({ path, method?, …tls, as? })` — Webflow API request (`mvp:connect_webflow_api_request`); like `s.api.request` but addressed by `path` (host is engine-supplied), and `path` is REQUIRED — the engine rejects an empty one. No `headers`: the engine builds its own from the workspace's Webflow connection and ignores an authored value.
@@ -920,9 +982,18 @@ Auth & calls:
 
 Microservices (the `microservice()` def and the statement that calls it):
 
-- `microservice({ name, kind, … })` — two mutually exclusive shapes via `kind`: `builtin` declares containers (image/ports/resources/env/command/args) plus optional `ingresses`, and `helm` points at a chart and its `values` — passing both throws. EARLY SURFACE, expected to change — every export of a workspace declaring one prints a notice saying so. `configs`/`volumes` are typed and `@deprecated` but NOT deployable: the engine rejects an import carrying either, so `export()` fails the build rather than letting the deploy fatal. Put a value the workload reads in a container's `env`, and storage in a container's own `volumes` (`emptyDir`/`persistent`/`config`). Container names are free-form — they need not match the microservice name, which is what a stack addresses.
+- `microservice({ name, kind, … })` — two mutually exclusive shapes via `kind`: `builtin` declares containers (image/ports/resources/env/command/args) plus optional `ingresses`, and `helm` points at a chart and its `values` — passing both throws.
+  - EARLY SURFACE, expected to change — every export of a workspace declaring one prints a notice saying so.
+  - `configs`/`volumes` are typed and `@deprecated` but NOT deployable: the engine rejects an import carrying either, so `export()` fails the build rather than letting the deploy fatal.
+  - Put a value the workload reads in a container's `env`, and storage in a container's own `volumes` (`emptyDir`/`persistent`/`config`).
+  - Container names are free-form — they need not match the microservice name, which is what a stack addresses.
 - SECRETS RIDE ALONG — `chart.values` and `registryAuth.dockerconfigjson` are carried into the bundle, and into a pulled tree, verbatim (they must be, or a pulled microservice could not be redeployed). Both are stored strings with NO deploy-time indirection: `process.env.X` in the def resolves at EXPORT and writes the literal into the bundle, so it is not a way to keep the credential out. Either leave `registryAuth` unset (public image, or a credential attached outside this workspace) or treat the bundle and any pulled tree as secret material — keep them out of git, or rotate after. Export prints a notice per microservice carrying either field; `--strict` does not promote it. For a secret a STACK reads, the mapped surface is `workspaceConfig({ env })` + `env("NAME")`.
-- `s.microservice.request({ host, path, port?, method?, params?, headers?, timeout?, follow_location?, as? })` — in-cluster microservice call (`mvp:microservice_request`); no TLS fields. ONLY `host`+`path` required; the rest default to the engine's values (`GET`/`{}`/`[]`/`10`/`true`), always emitted. Pass the `microservice()` DEF as `host` — it binds by NAME (how the engine resolves it), so a rename fixes every call site and the port is checked before deploy. `port?` folds into `host` as `"name:port"`: a def exposing ONE `servicePort` resolves automatically, SEVERAL requires it. A raw `"name:port"` string works, unvalidated, and is the only way to reach an instance-level microservice. `tenantDeploy: "manual"` on the def imports the row without starting the workload.
+- `s.microservice.request({ host, path, port?, method?, params?, headers?, timeout?, follow_location?, as? })` — in-cluster microservice call (`mvp:microservice_request`); no TLS fields.
+  - ONLY `host`+`path` required; the rest default to the engine's values (`GET`/`{}`/`[]`/`10`/`true`), always emitted.
+  - Pass the `microservice()` DEF as `host` — it binds by NAME (how the engine resolves it), so a rename fixes every call site and the port is checked before deploy.
+  - `port?` folds into `host` as `"name:port"`: a def exposing ONE `servicePort` resolves automatically, SEVERAL requires it.
+  - A raw `"name:port"` string works, unvalidated, and is the only way to reach an instance-level microservice.
+  - `tenantDeploy: "manual"` on the def imports the row without starting the workload.
 - `s.workflow_test.call({ workflowTest, datasource?, as? })` — run another workflow test from inside one, which is the only place it runs (see Gotchas in `llms.txt`). The odd one out: NO `input` (a workflow test takes none), and it carries `datasource?` instead — same clone caveat as the kind's own field.
 
 # Value catalog
@@ -935,11 +1006,11 @@ Microservices (the `microservice()` def and the statement that calls it):
 - `c.blank(tag: "const:<type>") => Value` — The editor's UNCONFIGURED value box (stored value ""), emitted by codegen for a pulled workspace — do not author it. NOT a zero or an empty collection: the engine reads "" and "0" differently, so c.blank("const:int") ≠ c.int(0) and neither canonicalizes into the other. Constant tags except const/const:obj, whose blanks are c.text("")/c.obj(null).
 - `c.bool(b: boolean) => Value` — Boolean constant → tag "const:bool".
 - `c.null(tag?: "const:null" | "const:obj") => Value` — Null constant, stored value "null". Bare c.null() is tag "const:null". c.null("const:obj") is the OBJECT-TYPED null the engine writes into a db.* statement's @meta slot — different stored bytes from c.obj(null), which is the blank object (value ""), though both evaluate to null. Codegen emits whichever spelling the workspace stored; do not swap one for the other.
-- `c.obj(o?: Json | null) => Value` — Object constant → tag "const:obj". A populated one stores an empty {} carrying one `set` filter per key — the editor's form, and the only populated form the engine reads back (a populated JSON string arrives truncated and fails the request with ERROR_FATAL "Unable to decode."). ⚠ a ZERO-BASED numeric key is an INDEX in the engine's data model, so c.obj({"0":"a"}) evaluates to the list ["a"] (a non-zero-based one like {"2":…} survives as a key) — that is the platform, not this encoding. No argument = the empty object {} — use this one. Explicit null = the legacy blank form the engine evaluates to null, NOT {}; it exists only so a pulled workspace round-trips, do not author it. Plain JSON literals only — a nested tagged value (inp/ref/auth/c.*) is rejected; for a computed object response use a record of values, not c.obj.
+- `c.obj(o?: Json | null) => Value` — Object constant → tag "const:obj". A populated one stores an empty {} carrying one `set` filter per key — the editor's form, and the only populated form the engine reads back (a populated JSON string arrives truncated and fails the request with ERROR_FATAL "Unable to decode."). ⚠ a ZERO-BASED numeric key is an INDEX in the engine's data model, so c.obj({"0":"a"}) evaluates to the list ["a"] (a non-zero-based one like {"2":…} survives as a key) — that is the platform, not this encoding. Write c.array([...]) for a list, or prefix the keys ("k0") for an object; `export()` warns. No argument = the empty object {} — use this one. Explicit null = the legacy blank form the engine evaluates to null, NOT {}; it exists only so a pulled workspace round-trips, do not author it. Plain JSON literals only — a nested tagged value (inp/ref/auth/c.*) is rejected; for a computed object response use a record of values, not c.obj.
 - `c.array(a: Json[]) => Value` — Array constant (JSON string) → tag "const:array". Plain JSON literals only — a nested tagged value is rejected, same as c.obj.
 - `c.expression(source: string) => Value` — Xano Expression Engine source, passed through VERBATIM → tag "const:expr2". The string IS the expression: c.expression('"Hi, " ~ $input.name'), c.expression("$var.price * $var.qty"). ⚠️ NOT VALIDATED — never parsed or type-checked, invisible to InferResponse, and untouched by a rename that updates every typed ref(); a typo surfaces at runtime or as a wrong answer. Use it ONLY for syntax the typed surfaces cannot express (~ concatenation, inline arithmetic, conditionals) — prefer ref/inp/col, withFilters+fl.*, and obj() (which BUILDS a checked expression). Not the expr() condition builder.
 - `c.now() => Value` — Current time as epoch-ms — the engine-native const:epochms constant (no filter). Valid inline as a where/cmp operand. For cutoff math (cutoff = now - max_age) either compare inline or, for reuse/readability, hoist it into an s.set_var and compare against the var.
-- `obj(fields: Record<string, Value | nested>) => ObjValue<typeof fields>` — Dynamic object value → tag "const:expr2" (an object-literal expression string). The dynamic sibling of c.obj: members may be inp/ref/auth/col values, env()/setting()/sys.*, c.now(), c.* constants, nested records, or arrays — and each member may carry a FILTER CHAIN (withFilters + fl.*), which renders as the expression pipe `$var.row|get:"a.b"`. That matters most for the null-safe drill: db.get binds null on a miss, so ref(path, { safe: true }) inside an obj() is the normal shape, not a workaround — you do NOT need a preceding s.set_var to hoist it. The member record rides the return type, so InferResponse resolves each member the way it resolves a top-level response key — `response: { user: obj({ id: ref("row.id") }) }` derives `{ user: { id: Col | null } }`, and a raw nested object literal (`response: { user: { id: ref("row.id") } }`, auto-wrapped through this) derives the same. A constant record or list has two spellings that both work and render identically: bare (`{ a: 1 }`, `[]`) or `c.obj(...)`/`c.array([...])` — prefer the bare form. NEST WITH A RAW RECORD, not an inner obj() call: an inner call yields a const:expr2 value, which the expression serializer has no spelling for and THROWS. The legacy blank `c.obj(null)` is refused here (it evaluates to null, not {}) — write c.null() or c.obj(). Still rejected: a filter ARGUMENT that carries its own chain or is a c.now() (a trailing | binds to the whole value, not one argument, and c.now() needs one), a DISABLED filter (an expression string cannot record that), and the output/response/toolset/reg tags — build those in a prior step and ref() them. Use for e.g. s.ai.agent.run args.
+- `obj(fields: Record<string, Value | nested>) => ObjValue<typeof fields>` — Dynamic object value → tag "const:expr2" (an object-literal expression string). The dynamic sibling of c.obj: members may be inp/ref/auth/col values, env()/setting()/sys.*, c.now(), c.* constants, nested records, or arrays — and each member may carry a FILTER CHAIN (withFilters + fl.*), which renders as the expression pipe `$var.row|get:"a.b"`. A null-safe ref(path, { safe: true }) works inside an obj() member directly. The member record rides the return type, so InferResponse resolves each member the way it resolves a top-level response key — `response: { user: obj({ id: ref("row.id") }) }` derives `{ user: { id: Col | null } }`, and a raw nested object literal (`response: { user: { id: ref("row.id") } }`, auto-wrapped through this) derives the same. A constant record or list has two spellings that both work and render identically: bare (`{ a: 1 }`, `[]`) or `c.obj(...)`/`c.array([...])` — prefer the bare form. NEST WITH A RAW RECORD, not an inner obj() call: an inner call yields a const:expr2 value, which the expression serializer has no spelling for and THROWS. The legacy blank `c.obj(null)` is refused here (it evaluates to null, not {}) — write c.null() or c.obj(). Still rejected: a filter ARGUMENT that carries its own chain or is a c.now() (a trailing | binds to the whole value, not one argument, and c.now() needs one), a DISABLED filter (an expression string cannot record that), and the output/response/toolset/reg tags — build those in a prior step and ref() them. Use for e.g. s.ai.agent.run args.
 - `ref(name: string, opts?: { safe?: boolean }) => Value` — Reference a stack variable → tag "var". Pass { safe: true } for null-safe nested access — a dotted ref("owner.user_id", { safe: true }) compiles through the get filter so it resolves to null instead of raising "Unable to locate var" when the base is null.
 - `inp(name: string) => Value` — Reference a function/endpoint input → tag "input". Resolves ONLY against the `input` block of the def it sits in — a value produced earlier in the stack is `ref("var.field")`, not `inp("field")`. A name that is not declared here deploys clean and fails at runtime with ERROR_FATAL "Unable to locate input: <name>" on every branch that reads it; `export()` warns, and `--strict` fails the build. Sending the name in the request does NOT rescue it — an undeclared input is never bound, so the call fails identically with the value present. A dotted path drills INTO a declared input (`inp("action.amount")` needs a declared `action`).
 - `col(name: string) => Value` — Reference a table column → tag "col".
@@ -957,7 +1028,7 @@ Tags: const, const:int, const:decimal, const:bool, const:array, const:obj, const
 
 # Column and input types
 
-> Read when declaring a table column (`f.*`) or a function/query input (`input.*`) — a type's options and accessor methods, and the `s.precondition` error/status contract that rides the same catalog.
+> Read when declaring a table column (`f.*`) or a function/query input (`input.*`) — a type's options and methods, and the `s.precondition` error/status contract. Also `table({ seed })` rows and `use_xdo`.
 
 Author table columns + function/API inputs with the typed catalog: `f.<type>(opts?)`
 for columns, `input.<type>(opts?)` for inputs. Common opts: `required`, `nullable`,
@@ -1002,6 +1073,31 @@ any `SearchOp`: give the table `index: [{ type: "vector", fields: [{ name: "embe
 queries it.
 `{ array: true }` makes any `f.*` scalar a **list column** — `f.text({ array: true })`
 surfaces as `string[]` in `InferRow<typeof table>` (the column analogue of `input.list`).
+**Seed a table's starting rows with `table({ seed })`.** `seed` takes rows
+typed against the table's schema as a WRITE shape (a column without
+`required: true`, and the system columns, may be omitted; `null` needs
+`nullable: true`) — inline (`seed: [{ name: "…" }]`), a FILE
+(`seed: seedFile("./seed.json", import.meta.url)`; path resolves against the DECLARING
+file), or a thunk (`seed: () => import("./seed.json")`, async ok, `.default` unwrapped).
+Inline rows are TYPED against the schema at compile time; a `seedFile`/thunk seed is
+NOT — the JSON is opaque to the typechecker, and the `xanots export`/`deploy` CLI
+validates it instead, naming the row index, the offending column, and the known
+columns. ⚠ Prefer `seedFile` for a file: a thunk's `import()` sits in
+YOUR module, so a bundler emits the JSON as a served chunk. NEITHER is a secrecy
+boundary — a bundler that inlines the asset ships them either way. Never put secrets
+in `seed`. `deploy --static` REFUSES a build carrying internal/sensitive seed values;
+`--allow-seed-in-static` overrides for deliberately public demo credentials.
+Deploy is a full replace, so re-deploying re-seeds
+cleanly (no duplication). Omit `id` and rows auto-number `1..N` (int PK) or take
+a stable derived uuid (uuid PK); supplying `id` pins it (engine preserves it,
+resets an int sequence past the max). All-or-nothing — mixing explicit and
+omitted `id` throws. A `system:false` PK is the author's to supply. Pinning is
+`seed`-only — `s.db.bulk.add` DROPS `id` unless `allowIdField: true`.
+**`use_xdo` storage mode.** Workspace setting (`registerWorkspace({ use_xdo })`,
+default `false`) controlling whether fields are stored as JSON under the `xdo`
+column (`true`, adds a `gin(xdo)` index) or as real columns (`false`, no gin).
+Tables inherit it; override per-table with `table({ useXdo })`. Resolved at
+`export()`, so the workspace and tables can be registered in any order.
 A **column `default` must stay within the BMP** — a 4-byte character (codepoint > U+FFFF,
 e.g. an emoji) is mangled into invalid UTF-8 by the engine's default pipeline and is rejected
 at export rather than 500ing at deploy (Postgres `22021`); BMP defaults (accents, `€`, most
@@ -1110,14 +1206,10 @@ statement, and one CANNOT be synthesized in the SDK (it would compile to this sa
 database with a single `s.db.direct_query` UPDATE (`SET clicks = clicks + 1 WHERE …`),
 which the DB applies atomically. Reserve the pipeline form for low-contention counters
 where a rare lost update is acceptable.
-⚠ `direct_query` needs the table's PHYSICAL Postgres name, which the typed surface
-does NOT expose: the engine derives it from ids assigned at import — not knowable from a
-`table()` def (identity is a name + guid, not the numeric id) — and `sql_name` persists
-empty. The derived name is also NOT STABLE: a deploy is a full replace, so every table is
-created afresh and the id in its name moves each time, on the same unchanged project. So
-the safe counter drops out of the typed surface: resolve the physical name from
-`information_schema` inside the request that uses it, and never store, cache or hardcode
-one. A typed atomic path needs an engine change.
+⚠ `direct_query` needs the table's PHYSICAL Postgres name, which the typed surface does NOT
+expose and which is NOT STABLE across deploys — resolve it from `information_schema` inside
+the request that uses it, never store or hardcode one (rules under `s.db.direct_query` in
+`llms/statements-data.md`). A typed atomic path needs an engine change.
 
 - `fl.add(value: decimal): decimal`
 - `fl.append(value: <T>, path: text): <T>[]`
@@ -1257,7 +1349,7 @@ Variadic filters — they take arguments, but no declared list, so the count is
 
 # Lambda bodies (JavaScript)
 
-> Read when writing a JavaScript body, or weighing whether to reach for one at all — `lam.fn`, `fl.lambda`, `fl.reduce`, `s.lambda`. Lambda workers are a bounded shared resource, and each surface binds a different set of identifiers.
+> Read when writing a JavaScript body, or weighing whether to reach for one at all — `lam.fn`, `fl.lambda`, `fl.reduce`, `s.lambda`; each surface binds a different set of identifiers.
 
 **A lambda is an escape hatch, not a default.** The body runs outside the request's own
 runtime, and a workspace has a BOUNDED pool of lambda workers every lambda in it shares
@@ -1402,7 +1494,7 @@ object. CI: `--frozen-lock` fails instead of changing the lock.
 
 # Legacy paradigms and retired statements
 
-> Read when the code was PULLED from an existing Xano instance rather than authored here — how a codegen'd tree reads and the three shapes in it that must not be "fixed", plus a `raw({ name: "mvp:…" })` statement, a `realtimeTrigger()`, or any name the catalogs do not list.
+> Read when the code was PULLED from an existing Xano instance — how a codegen'd tree reads, the shapes in it that must not be "fixed", and any `raw({ name: "mvp:…" })`, `realtimeTrigger()`, or name the catalogs do not list.
 
 Older paradigms this SDK still supports and still emits when it decodes an existing
 workspace. **Do not author these.** They are listed by name only so you recognize them
@@ -1446,7 +1538,7 @@ var VALUES ride inline in `xano/workspace.ts`, so treat a pulled tree as secret-
 
 # Statement catalog
 
-> Read for the field signature of a specific statement — every surface, grouped by `s.*` namespace. Look here after the control-flow core in the router does not cover what you need.
+> Read for the field signature of a specific statement — every surface, grouped by `s.*` namespace.
 
 ### (top-level)