@xanots/sdk 0.0.1

package/llms.txt

@@ -0,0 +1,483 @@
+# xanots v0.0.1
+
+> TypeScript SDK that compiles a typed Xano workspace into the importable packageExport JSON bundle.
+
+Author a Xano workspace in TypeScript: build typed objects, register them on a
+`new Xano()` instance, and call `.export()` to get one importable bundle. Compile
+with `xanots export ./xano/index.js`.
+
+Coverage: object kinds 24/30, 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; see `coverage.objectKinds.unmodeled` in `manifest.json`.
+
+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
+below — open the one whose condition matches the task, and skip the rest. For
+exhaustive per-entry detail in NEITHER — a statement's full field schema with engine
+defaults, a filter's complete argument list, the engine `storedName` mapping — do a
+TARGETED lookup in the shipped `manifest.json` (grep or `jq` the one entry you need;
+it is ~55k tokens, so never read it whole). Its top-level keys are `name`, `version`, `description`, `coverage`, `values`, `objectKinds`, `fieldTypes`, `statements`, `filters`, `cli`, `cliGlobalFlags`. `statements` and `filters` are ARRAYS, not maps — SELECT, do not index:
+  jq '.statements[] | select(.sPath=="db.get")' manifest.json
+  jq '.filters[]    | select(.name=="json_decode")' manifest.json
+Select a statement on `sPath` (the `s.*` path you write), NOT `surface` (the XanoScript term): 24 of 214 differ — `var`→`set_var`, `break`→`foreach_break`, `foreach.remove`→`foreach_remove`, and every `expect.*`.
+
+## Topic files
+
+Each line is a condition on the task. Open the files whose condition matches and
+skip the rest — paths are relative to this file (`node_modules/@xanots/sdk/` once
+installed), so they resolve with a plain file read and always match the version you
+have. `llms-full.txt` is this file and every one below concatenated — for a reader
+that wants one fetch, not for an agent that can open the two files it needs.
+
+- [Object kinds](llms/object-kinds.md): Read when you need the full catalog of authorable primitives — which factory builds each, which register method takes it, and which payload key it lands under. Read it too when a `register*` call will not typecheck because the array was built by `.flatMap()`/`.concat()` across modules.
+- [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.
+- [Agent and MCP def shapes](llms/kinds-agent-mcp.md): Read when the workspace defines an `agent()` or an `mcpServer()`.
+- [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.
+- [Auth, cross-object calls, and microservices](llms/statements-calls.md): Read when the stack authenticates, calls another object (`s.function.run`, `s.api.request`, `s.tool.call`), 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.
+- [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, each surface binds a different set of identifiers, and the hazards are not guessable.
+- [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. None of the retired names are authorable for new code.
+- [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.
+
+## Quickstart
+
+Authoring is **declarative def-objects** passed to factories — there is no
+callback/chaining builder.
+
+```ts
+import { workspace, apiGroup, query, table, input, f, ref, inp, auth, s } from "@xanots/sdk";
+
+const users = table({
+  name: "users",
+  auth: true, // backs authentication
+  // `id` (int PK) + `created_at` (epochms) are auto-injected — don't declare them.
+  schema: {
+    email: f.email({ required: true }),
+    name: f.text(),
+  },
+  // Indexes: { type, fields: [{ name, op? }] }. `"unique"` is shorthand for `"btree|unique"`.
+  // A DOTTED name indexes a key inside a column (`xdo.email`); only the part before the
+  // first dot is checked against the schema.
+  index: [{ type: "unique", fields: [{ name: "email" }] }],
+});
+
+const posts = table({
+  name: "posts",
+  schema: {
+    author: f.tableRef(users), // foreign key → users (NOT `ref`)
+    body: f.text({ required: true }),
+  },
+});
+
+const api = apiGroup({ name: "blog", canonical: "blog" }); // canonical → the URL token
+
+const createPost = query({
+  name: "create_post", verb: "POST", apiGroup: api, auth: users, // the auth table
+  input: { body: input.text({ required: true }) },
+  stack: [
+    s.db.add({ table: posts, row: { author: auth("id"), body: inp("body") }, as: "post" }),
+  ],
+  response: ref("post"),
+});
+
+const listPosts = query({
+  name: "list_posts", verb: "GET", apiGroup: api,
+  stack: [s.db.query({ table: posts, sort: [{ sortBy: "created_at", dir: "desc" }], as: "rows" })],
+  response: ref("rows"),
+});
+
+export default workspace("my-blog")
+  .registerTables([users, posts])
+  .registerApiGroups([api])
+  .registerQueries([createPost, listPosts]);
+```
+
+Compile: `xanots export ./index.ts --out bundle.json` (or `writeBundle(app, path)`
+from `@xanots/sdk/node` in code). The default export must be the `Xano` registry. The entry must be an
+ES module (XanoTS defs are ESM-only): set `"type": "module"` in the nearest
+package.json or name the entry `.mts`. `npm init -y` writes `"type": "commonjs"`,
+which fails with a "must be ES modules" error until you switch it to module.
+
+Set `canonical` on every `apiGroup`. The engine mints the URL token server-side, so
+without one a group's client paths are unresolvable until a lock exists: the bundle
+exports fine and `xanots paths` / `getPath()` then fail on the very queries it just
+built. An explicit `canonical` resolves them from the source alone.
+
+Build warnings: `export()` prints the shapes that deploy clean and then do the wrong
+thing (a `bulk.update` zero-filling omitted columns, an `ignoreEmpty` on an empty
+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.
+
+Identity: object guids derive from `(type, name)`, so renames change identity.
+`xanots export <entry> --lock` freezes every guid + api-group/toolset canonical in a lock
+file written BESIDE THE ENTRY FILE — `xano/xano.lock` for the standard scaffold, NOT the
+project root — which you commit (auto-read once present; CI guard `--frozen-lock` fails
+instead of changing the lock). Fix-up subcommands:
+`xanots lock rename <kind> <old> <new>` (kind = payloadKey or table/api_group),
+`xanots lock prune <entry-file> [keys…] --yes` — finding orphans RUNS the entry's module scope
+(env assertions included); `--no-verify --yes <kind:name>…` prunes named keys with no evaluation
+and no orphan check,
+`xanots lock adopt <live-bundle.json> [--yes]` — all accept `--lock=<path>`.
+Programmatic use: call `seedLockOverrides(readLockFile(path))` BEFORE importing
+any def module — references bake guids at import time, so late seeding is a
+silent no-op (`resetLockOverrides` exists for tests).
+Development workflow: opt in EARLY — run `xanots export ./xano/index.ts --lock` once and COMMIT
+`xano.lock` beside the entry file; every later export then keeps identities
+stable across renames and environments. To rename an object: rename in code,
+export (stderr prints the exact fix-up), run `xanots lock rename <kind> <old>
+<new>`, export again — the original guid is emitted under the new name, so the
+engine renames in place instead of delete+create. Taking over an existing
+workspace: `xanots lock adopt <its-packageExport.json>` first, then export.
+
+## Deploy
+
+`xanots init` → `xanots deploy` → URL. Each `deploy` runs the same compile
+pipeline as `export` (honoring `xano.lock`), then imports the result into a live
+environment and prints its URL.
+⚠ Every deploy is a FULL REPLACE: it clears that environment's workspace — objects
+AND records — before importing. The blast radius is a disposable environment, not a
+production workspace, but confirm with the user before the first run.
+
+**Two destinations, and the choice changes more than the target.**
+
+- `--dest ephemeral` (DEFAULT) — a NAMED, workspace-scoped, auto-expiring tenant
+  (~1h; `--expires-hours` 1–72 at create time). The active one is tracked in
+  `./.xano/ephemeral.json`, so deploying again REFRESHES it and the URL is unchanged;
+  if it expired or was swept, a fresh one is created and the new URL is called out.
+  `--static` puts the frontend ON THE EPHEMERAL, so backend and frontend share one
+  disposable environment.
+  ⚠ Only the BACKEND URL survives a refresh: the replace clears static hosting too,
+  so `--static` publishes a NEW host every run and the previous URL stops serving.
+- `--dest sandbox` — your single throwaway tenant, no expiry. `--static` puts the
+  frontend on your OWN (parent) workspace instead, because the sandbox tenant does
+  not serve static hosting.
+- `xanots release` promotes to your INSTANCE workspace and MERGES, not replaces:
+  adds/updates what you define, deletes nothing, writes no rows. Destruction is
+  opt-in per flag, previewed + confirmed, and can drop a table WITH its rows.
+  NOT flag-gated: removing a column from a schema destroys that column's data
+  (previewed against live). `--prune` deletes only what `xano.lock` records this
+  project released, and refuses without a lock.
+
+Nothing from a DEPLOY is written back into `xano.lock` (an ephemeral/sandbox is a
+separate workspace, so its identities must not pollute yours). The one write-back is
+`release --replace`, which mints fresh identities in the workspace the lock describes:
+it re-pins the lock from the rebuilt workspace, because otherwise the next release
+matches nothing and duplicates every object. Deploying an ENTRY
+FILE still updates the local lock via the shared compile step, exactly as `export`
+does — only when a lock exists or `--lock` is passed.
+
+**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 validate` 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
+URLs and publishable keys only, never secrets. Secrets go in backend env, read
+server-side via `env(name)`.
+
+**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.
+
+## Gotchas
+
+Non-obvious authoring rules:
+
+- **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.
+- **`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.
+- **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`
+  `expr(...)`; writes (`db.add`/`db.edit`/`db.add_or_edit`) take a `row`/`data`.
+  `db.get_by_id` is the exception to the field-match rule — it is the dedicated
+  get-by-primary-key statement and takes `{ table, id }`, NOT `fieldValue`.
+  Signatures: `llms/statements-data.md`.
+- **Single-field only — no composite match.** These ops match exactly ONE field;
+  there is no two-field form (the engine's by-field lookup takes a single
+  predicate). For a `(a, b)` existence/fetch — e.g. dedupe a `(habit, date)`
+  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.
+- **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".
+- **Same-name siblings collide.** Object guids derive from `(type, name)` and
+  ignore a query's `verb`, so a `GET` and `POST` both named `posts` clash;
+  `export()` throws on the collision — give them DISTINCT names (`posts` and
+  `posts/create`; the verb still carries the semantics). A distinct explicit
+  `guid` on each clears that throw but is NOT a lasting fix: a lock entry is
+  keyed by `(type, name)` too and cannot hold two guids, so `export --lock`
+  refuses the pair — and a committed lock is the recommended workflow.
+  `export()` warns on a same-name pair even unlocked. An explicit `guid` 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 (which a frontend can import query
+  defs from to use `getPath()`/`InferInput` with no Node built-ins in the bundle).
+  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.
+- **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 — **~289 kB minified (~57 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 ~1 kB. So the cost is paid by importing ANY def at all, and reducing what a
+  def does will not reduce it.
+  Fix: `xanots paths <entry> --emit xano/routes.gen.ts` (`routes` 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.
+- **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, 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. A bare
+  `c.text("^[^@\s]+@...$")` is an invalid pattern that matches *nothing* for every
+  input, so a precondition on it silently rejects all values (valid ones included).
+  `c.regex("^[^@\s]+@[^@\s]+\.[^@\s]+$", "i")` wraps + escapes it for you (accepts a
+  JS `RegExp` too: `c.regex(/^…$/i)`), and `withFilters` throws on a bare `c.text`
+  pattern pointing here — from ANY position in the chain, so a normalizer in front
+  (`withFilters(c.text("^hi"), fl.trim(), fl.regex_test(...))`) is refused too; nothing
+  upstream adds the delimiters. `s.expect.to_match`'s `value` is the same PATTERN slot,
+  refused the same way; a `ref`/`inp` pattern is passed through untouched, either place.
+  Better still, prefer 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.
+- **Event-driven objects fire on an EPHEMERAL, not in the sandbox.** A `task`
+  (scheduled), an `mcpServer`, and every trigger — `tableTrigger` included — run normally
+  on an ephemeral env, which is `deploy`'s DEFAULT destination. So test an event-driven
+  design (screen-on-insert, cron cleanup, MCP tool call) by deploying it and letting it
+  run.
+  ⚠ Under `--dest sandbox` they import cleanly but their stacks NEVER execute, and there
+  is no way to fire one manually — an insert on a bound table does not run its
+  `tableTrigger`, and the design silently does nothing. Only synchronously-invoked objects
+  (queries, functions, and the agents an endpoint calls with `s.ai.agent.run`) run there.
+  If you must stay on the sandbox, verify the logic out of band: factor the body into a
+  `defineFunction` (or a callable `query`) and invoke it directly — a `tableTrigger` that
+  screens a row on insert should delegate to a function a `query` can also call via
+  `s.function.run`, and you assert against that.
+- **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
+
+Reachable through the `s` namespace: `s.<path>({...})`. Declarative statements
+take one typed args object (field names match the engine); every surface's field
+signature is in `llms/statements-catalog.md`. Specials (`[special]`) are
+hand-authored: control flow is below, and the rest are in the `llms/statements-*`
+topic files this doc's navigation names.
+Wrap an `input`-routed `value` field in `ignored(...)` to store it but SKIP it at
+  runtime — the engine records `<name>:ignore` and the parameter falls back to its
+  default. Not the same as an empty value, and not the same as omitting the field
+  (which stores no entry at all). Mostly seen on a pulled workspace. A field written
+  into `context` instead (the `s.math.*`/`s.text.append` mutation family) has no slot
+  for the flag and THROWS rather than dropping it.
+Fields marked `value` take a `Value` (`c.*`/`ref`/`inp`); `comparison` takes an
+`expr(...)`. A `→ as: <type>` suffix names what the statement's `as:` output var
+holds (curated, not exhaustive — absence means read the `[output]` flag and prose).
+
+### Specials — authored signatures
+
+Control flow & blocks (each nests a sub-stack; block specials name it `body`):
+
+- `s.set_var(name, value)` · `s.update_var(name, value)` · `s.return(value)` · `s.comment(text)` — positional.
+- **Every** statement takes `disabled?`/`description?` — annotations on the stack item, not args: `disabled: true` is Xano's "disable step" (kept in the stack, skipped at runtime), `description` the note beside it. Inline on object-arg factories; a trailing object on the positional ones (`s.set_var("x", v, { disabled: true })`).
+- **Statements with an `as`** also take `asFilters?` — `fl.*` filters on the RESULT as it binds, in order, same slot as `disabled`: `s.set_var("x", v, { asFilters: [fl.trim(), fl.lower()] })`. Saves a follow-up `set_var`. Throws without an `as`. The bound variable is RETYPED by the chain (`db.query` + `[fl.count()]` → `number`); filters whose result the engine declares as `any` (`get`, `set`, `json_decode`, …) fold to `unknown`.
+- `s.conditional({ when, then, elif?, else? })` — if/elif/else. `when` is a condition (`expr`/`cmp`/`and`/`or`); `elif` is an ordered `[{ when, then }]` (each an else-if branch); `then`/`else` are `Statement[]`.
+- `s.for({ as, count, body })` — **count-bounded** loop (`as` is the index), NOT from/to.
+- `s.foreach({ as, list, body })` — iterate `list`; `as` is the current item.
+- `s.while({ when, body })` — `when` is a condition (`expr`/`cmp`/`and`/`or`).
+- `s.switch({ on, cases: [{ when, body, break? }], default? })` — multi-way branch on a subject `Value` `on`; each `case`'s `when` is a literal `Value` matched against `on` (NOT a comparison — use `s.conditional` for `<`/`>`/ranges). ⚠ **Omitting `break: true` FALLS THROUGH** — the matched case also runs every LATER case body. Type-checks clean; only `export --strict` catches it.
+- `s.try_catch({ try, catch?, finally? })` — three `Statement[]` blocks.
+- `s.group(body)` / `s.util.post_process(body)` — take a `Statement[]` **positionally**.
+- `s.foreach_break()` / `s.foreach_continue()` / `s.foreach_remove()` — nullary loop control.
+- `s.expect.to_throw({ body, exception? })` — `body` is the statements expected to raise.