@xanots/sdk 0.0.10 → 0.0.12

package/guides/authoring.md

@@ -137,6 +137,13 @@ auto-assigned `id`/`created_at`, `s.db.del` binds `null`, and `edit`/`del` **thr
   the engine reads the operand as a text literal and fails at runtime with a parse error
   naming the *other* operand, so `db.query` rejects that spelling at export instead.
 
+- **A join adds no columns to the returned row.** With or without a `bind`, a row is the
+  queried table's columns — which is what `InferResponse` types, so there is no `row.author`
+  to read. To bring a joined column back, project it with an `eval` whose `name` is the dotted
+  path: `eval: [{ name: "author.name", as: "author_name" }]` puts `author_name` on the row and
+  on the inferred type. A *bare* name there fails at runtime (it qualifies to the base table),
+  and a dotted joined column in `output` is dropped with no error.
+
 - **Paging changes the response shape.** Supplying `paging` with metadata on (the default)
   returns a **paging envelope** — `{ items, curPage, nextPage, prevPage, offset, perPage,
   itemsReceived }`, plus totals when `totals: true` — instead of a bare `Row[]`, and
@@ -194,8 +201,10 @@ auto-assigned `id`/`created_at`, `s.db.del` binds `null`, and `edit`/`del` **thr
   `lower`, and the `epochms_add_day` / `epochms_sub_month` family). The request-time timestamp
   filters do not — `epochms_transform`, `epochms_add_ms`, `epochms_add_secs`, `epochms_date`,
   `epochms_from_format` — and the engine doesn't degrade gracefully: the request dies with a
-  bare fatal naming nothing. For a relative cutoff, use the SQL-side spelling or compute it in
-  an earlier `s.set_var` and `ref()` that. `export()` warns; a bare `c.now()` is always fine.
+  bare fatal naming nothing. For a relative cutoff, use the SQL-side spelling — by raw name,
+  since `fl.*` carries no builder for that family: `filter("epochms_add_day", …)` or the raw
+  `{ name, arg }` form — or compute it in an earlier `s.set_var` and `ref()` that. `export()`
+  warns; a bare `c.now()` is always fine.
 - **A `s.switch` case without `break: true` falls through.** The engine's default is
   fallthrough, so a matched case also runs every *later* case body — and the `default` block
   too. Whatever those bodies write gets written two or three times, at HTTP 200, with `tsc`

package/guides/typed-frontend.md

@@ -94,7 +94,7 @@ on the query and every caller derives from that single source of truth:
 
 ```ts
 const getPost = query({
-  verb: "GET", apiGroup: blog, name: "get_post",
+  verb: "GET", apiGroup: blog, name: "get_post/{id}",   // one row → address it in the path
   input: { id: input.int({ required: true }) },
   stack: [s.db.query({ table: post, where: expr(col("id"), "=", inp("id")), as: "rows" })],
   // A filtered response is opaque to the static walk, so derivation is `unknown`.
@@ -157,10 +157,10 @@ also pulls whatever its `stack` builds — the `s.*`/`c.*` factory *calls* run a
 to construct the def, so they can't be tree-shaken out. Types are free (`InferInput`/
 `InferRow` erase to nothing — use `import type`). That cost is a **floor**, not a function of
 how lean the def is. Measured on a Vite lib build against the published package: one
-`apiGroup` + one empty `query`, imported for a single `getPath()`, is **289 kB minified
-(57 kB gzipped)** against 56 B for a hand-written path string. A realistic def — two
+`apiGroup` + one empty `query`, imported for a single `getPath()`, is **267 kB minified
+(65 kB gzipped)** against 56 B for a hand-written path string. A realistic def — two
 tables, a foreign key, a typed input, a `db.query` with a `where` and a sort, plus a
-second endpoint — measures 290 kB. That 1 kB spread is the point: the floor is the SDK
+second endpoint — measures 269 kB. That 2 kB spread is the point: the floor is the SDK
 runtime itself, so splitting modules or simplifying a def does not move it, and the cost
 is paid by importing any def at all.
 
@@ -172,7 +172,7 @@ xanots routes ./xano/index.ts --emit xano/routes.gen.ts
 ```
 
 The emitted file is plain data plus one interpolator and imports nothing at all — the same
-app builds to 1.3 kB, a 214x saving, with no SDK code in the output. Route names and their `{param}` keys are still checked at compile
+app builds to 1.3 kB, a ~200x saving, with no SDK code in the output. Route names and their `{param}` keys are still checked at compile
 time, so a backend rename is a compile error rather than a 404:
 
 ```ts

package/llms/filters.md

@@ -39,12 +39,13 @@ database with a single `s.db.direct_query` UPDATE (`SET clicks = clicks + 1 WHER
 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 a physical name from workspace + table ids (of the
-form `x<workspace_id>_<table_id>`, e.g. `x6_203970`), ids assigned at import — not knowable
-from a `table()` def (identity is a name + guid, not the numeric id), and `sql_name`
-persists empty. So the safe counter drops out of the typed surface: hardcode
-the physical name after inspecting the deployed table. A typed atomic path needs an
-engine change.
+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.
 
 - `fl.add(value: decimal): decimal`
 - `fl.append(value: <T>, path: text): <T>[]`
@@ -136,11 +137,11 @@ engine change.
 - `fl.prepend(value: <T>, path: text): <T>[]`
 - `fl.range(start: int, stop: int): int[]`
 - `fl.reduce(initial_value: int, code: text, timeout?: int): any[]` — `code` is a JS body run per element; the ACCUMULATOR is `$result` (there is no `$acc`) and `initial_value` is REQUIRED — omitting it would slot the code as the initial value
-- `fl.regex_match(subject: text): text[]`
-- `fl.regex_match_all(subject: text): text[]`
+- `fl.regex_match(subject: text): text[]` — piped value is the PATTERN, the arg is the subject — see `regex_test`
+- `fl.regex_match_all(subject: text): text[]` — piped value is the PATTERN, the arg is the subject — see `regex_test`
 - `fl.regex_quote(delimiter?: text): text`
-- `fl.regex_replace(replacement: text, subject: text): text`
-- `fl.regex_test(subject: text): bool`
+- `fl.regex_replace(replacement: text, subject: text): text` — piped value is the PATTERN, `subject` is the text searched — see `regex_test`. The replacement comes FIRST
+- `fl.regex_test(subject: text): bool` — piped value is the PATTERN (build it with `c.regex(...)`); the arg is the subject — the REVERSE of `contains`/`starts_with`. Swapped, it answers false for every input with no error, so write `withFilters(c.regex("^a+$"), fl.regex_test(inp("s")))` (or name the arg: `fl.regex_test({ subject: inp("s") })`). A pattern found in the subject slot is refused at build time
 - `fl.round(precision?: int): decimal`
 - `fl.rtrim(mask?: text): text`
 - `fl.secureid_decode(salt: text): int`

package/llms/kinds-core.md

@@ -13,7 +13,7 @@ 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). 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.
+  - `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.
 - `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? } }`.

package/llms/statements-data.md

@@ -12,7 +12,7 @@ primary key `id`):
 
 - `s.db.get({ table, fieldName?, fieldValue, lock?, output?, as? })` — one row by field match; `output` restricts returned columns (and overrides column visibility — it can pull `internal` columns like a password hash).
 - `s.db.get_by_id({ table, id, output?, addon?, tableAlias?, as? })` — get by primary key. Takes `id`, NOT `fieldName`/`fieldValue`; binds the row or `null` for an id that names no row. Both spellings are live in pulled workspaces.
-  - ⚠ `id` is validated `>= 1`, so the `0` sentinel an optional `f.tableRef` stores fails the request with HTTP 400 `Value is less than the minimum value of 1` — it does NOT bind `null`. The throw is not scoped to the lookup: inside a `foreach` it kills the whole request, so one unset FK loses every other row's work. Read a nullable FK with the field-match form, which binds `null` on `0` and lets the loop finish: `s.db.get({ table, fieldName: "id", fieldValue: ref("row.fk"), as })`.
+  - ⚠ `id` is validated `>= 1`, so the `0` sentinel an optional `f.tableRef` stores fails the request with HTTP 400 `Value is less than the minimum value of 1` — it does NOT bind `null`. The throw is not scoped to the lookup: inside a `foreach` it kills the whole request, so one unset FK loses every other row's work. Read a nullable FK with the field-match form, which binds `null` on `0` and lets the loop finish: `s.db.get({ table, fieldName: "id", fieldValue: ref("row.fk"), as })`. `export()` warns when the `id` is statically a `0` — the literal `c.int(0)`, an `inp()` whose declared input default is `0`, or a `ref()` to a column declared `default: 0` — and `--strict` fails the build.
 - `s.db.has({ table, fieldName?, fieldValue, as? })` — existence test.
 - `s.db.del({ table, fieldName?, fieldValue, as? })` — delete by field match.
 - `s.db.add({ table, row?, data?, output?, as? })` — insert; `row` is a partial keyed by column.
@@ -34,13 +34,14 @@ primary key `id`):
     - ⚠ `like`/`ilike` take the operand as the PATTERN, verbatim: a bare term matches only an exact whole-string equal, and the endpoint answers HTTP 200 with zero rows — nothing reports a problem, so a search box that matches nothing ships. For substring matching use `includes`/`not includes`, which wrap the operand in `%…%` themselves and match case-INSENSITIVELY. Prefer them over a hand-built `"%" + term + "%"`, which is non-empty even for an empty term and so defeats `ignoreEmpty`; `includes` composes with it. `contains`/`@>`/`overlaps` are JSON/array containment, not text — on a text column they 400 `ParseError: Invalid value for param`.
     - Compose nested boolean logic with `and(...)` / `or(...)` groups (also available on `addon()` `where`).
     - An operand may be a bare value (`col`/`inp`/`ref`/`auth`/`c.*`) OR a **filtered** value (`withFilters(...)`) inline — the engine compiles the string and arithmetic filters (`trim`, `concat`, `upper`, `lower`, …) into the SQL.
-    - ⚠ The REQUEST-TIME timestamp filters have no SQL form and kill the request with a bare fatal naming nothing: `epochms_transform`, `epochms_add_ms`, `epochms_add_secs`, `epochms_date`, `epochms_from_format`. For a relative cutoff use the SQL-side family instead (`epochms_add_day`, `epochms_sub_month`, `epochms_year`, …) or compute it in an earlier `s.set_var` and `ref()` that. `export --strict` reports it; a bare `c.now()` operand is always fine.
+    - ⚠ The REQUEST-TIME timestamp filters have no SQL form and kill the request with a bare fatal naming nothing: `epochms_transform`, `epochms_add_ms`, `epochms_add_secs`, `epochms_date`, `epochms_from_format`. For a relative cutoff use the SQL-side family instead (`epochms_add_day`, `epochms_sub_month`, `epochms_year`, …) — by raw name, since `fl.*` has no builder for them — or compute it in an earlier `s.set_var` and `ref()` that. `export --strict` reports it; a bare `c.now()` operand is always fine.
   - `bind: [{ table, as?, join?, where? }]` — joins (`context.bind[]`). `join` defaults to `"inner"`. `as` defaults to the table name; two joins to the same table need distinct aliases.
     - ⚠ In `where`/`sort`/`eval` a JOINED column takes a dotted path (`col("team_row.id")`); THIS query's own columns stay **bare** (`col("team")`). Qualifying your own by table name needs `tableAlias` (same rule as `aggregate`) — without it the engine reads the operand as text and 400s `ParseError: Invalid value for param` naming the OTHER operand, so it throws at export instead.
     - `bind: [{ table: team, as: "team_row", join: "left", where: expr(col("team"), "=", col("team_row.id")) }]`
+    - ⚠ A join does NOT put the joined table's columns on the returned row — with or without a `bind`, a row is the QUERIED table's columns, which is what `InferResponse` types. There is no `row.team_row`. To read a joined column, PROJECT it with an `eval` whose `name` is the dotted path: `eval: [{ name: "team_row.name", as: "team_name" }]` puts `team_name` on the row and on the inferred type. A bare `name` there is `Unsupported parameter reference` at runtime (it qualifies to the base table), and a dotted joined column in `output` is dropped with no error.
   - `returnType` — `"list"` (default) | `"single"` | `"count"` | `"exists"` | `"stream"` | `"aggregate"`. Drives `context.return.type` AND the `InferResponse` shape: `count`→`number`, `exists`→`boolean`, `single`→`Row|null`, `stream`→`Row[]` (pageable, no envelope), `list`→`Row[]`/envelope, `aggregate`→rows keyed by the `aggregate.group`/`eval` aliases. ⚠ A bare `count` of ZERO serializes as an EMPTY body, not `0` — a client parsing JSON gets a parse error on the one result it most needs to handle. Wrap it: `response: { count: ref("n") }`.
   - `eval: [{ name, as, filters? }]` — computed columns (`context.eval[]`). Each `as` grafts onto the row as an `unknown` key in `InferResponse`; shadowing a real column throws. Write `name` **bare** (`"embedding"`) — it is alias-qualified on emit exactly like `aggregate` (a bare eval name is `Unsupported param format` at runtime), and the statement declares the alias it used. An `as` alias is `sort`able in the SAME query.
-    - An `eval`/`sort`/`where` filter pipeline compiles to **SQL**, so it resolves a DIFFERENT registry than `fl.*` (which runs in the request): the vector family, geo `distance`/`within`/`covers`, `search_rank`, the aggregators. Exported as `QUERY_EXPRESSION_FILTERS`/`VECTOR_FILTERS`.
+    - An `eval`/`sort`/`where` filter pipeline compiles to **SQL**, so it resolves a DIFFERENT registry than `fl.*` (which runs in the request): the vector family, geo `distance`/`within`/`covers`, `search_rank`, the aggregators. ⚠ `fl.*` carries NO builder for these — reach them by raw name, `filter("epochms_add_day", …)` or the `{ name, arg }` form. The name lists are `QUERY_EXPRESSION_FILTERS`/`VECTOR_FILTERS` on `@xanots/sdk/internal`.
     - **Vector similarity search** — the ONLY way to query an `f.vector` column (no `SearchOp` does distance). `eval: [{ name: "embedding", as: "distance", filters: [{ name: "vector_cos_distance", arg: [inp("q")] }] }]` + `sort: [{ sortBy: "distance", dir: "asc" }]` ranks in the DATABASE over the column's index. Match the filter to the index `op` (`vector_cos_distance`↔`vector_cosine_ops`, `vector_l2_distance`↔`vector_l2_ops`, `vector_l1_distance`↔`vector_l1_ops`, `vector_inner_product`↔`vector_ip_ops`); `vector_cos_similarity` is the inverse, so sort it `desc`. The same filter on a `where` operand cuts off BY distance instead of by row count.
   - `aggregate: { group?, eval?, sort?, paging? }` (with `returnType:"aggregate"`) builds `context.return.aggregate`. `group`/`eval` are `{ name, as, filters? }`, an aggregator like `sum`/`count` riding `filters`. Some aggregators resolve ONLY here, not in a runtime value pipeline: `count_distinct`, `median`, `to_list`/`to_distinct_list` (each with `_asc`/`_desc`), and `vector_distance`.
     - ⚠ Write each `name` as a **bare** column (`"status"`). It is alias-qualified to `"<alias>.status"` on emit — the engine rejects an unqualified column in an aggregate with `Unsupported param format`. An already-dotted `name` (a `bind`ed/joined column) passes through.
@@ -54,6 +55,8 @@ primary key `id`):
   - `distinct` — `"auto"` (default) | `"yes"` | `"no"`, riding `context.return.<list|stream>.distinct`.
 - `s.db.truncate({ table, reset?, as? })` · `s.db.schema({ table, path, as? })`.
 - `s.db.direct_query({ sql, responseType?, args?, parser?, as? })` — `sql` is a **raw string** (not a `Value`); binds go in `args: Value[]`. `parser: "template_engine"` renders the body as a template first — how a query interpolates a column or table name a bound arg cannot carry; omit it for the default.
+  - Template placeholders are Twig over the request scope: `{{ $input.name }}` for an input, `{{ $var.name }}` for a stack variable. ⚠ A BARE `{{ name }}` renders as the empty string — HTTP 200, no error, a query that silently ran with a blank where the value belonged. A bound `?` arg carries a VALUE without the template at all.
+  - ⚠ A table's PHYSICAL name is **not stable across deploys**. A deploy is a full replace, so every table is created afresh and the id in its name moves every time — the same unchanged project redeployed three times gave one table three different names. Never store, cache, hardcode or fixture one: resolve it from `information_schema` inside the same request that uses it.
 - `s.db.external.<engine>.direct_query({ sql, connectionString, responseType?, args?, parser?, as? })` — same shape against an EXTERNAL database; `<engine>` is `postgres`/`mysql`/`mssql`/`oracle`/`snowflake`. `connectionString` is a `Value` — reach for `env(...)`, not a literal — stored as `context.connection_string_flex`. A bare string stores the older `context.connection_string` instead (an env-var name unless it looks like a URL); each form round-trips as itself.
 - `s.db.transaction({ body, as? })` — run a `Statement[]` atomically. `as` binds whatever the block returned.
 - `s.db.bulk.add({ table, items, allowIdField?, as? })` / `s.db.bulk.update` / `s.db.bulk.patch` — `items` is an array `Value`.

package/llms/values.md

@@ -12,7 +12,7 @@
 - `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. 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. Still rejected: a filter ARGUMENT carrying its own chain (a trailing | binds to the whole value, not one argument), 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"`. 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.
 - `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".

package/llms-full.txt

@@ -1,4 +1,4 @@
-# xanots v0.0.10
+# xanots v0.0.12
 
 > TypeScript SDK that compiles a typed Xano workspace into the importable packageExport JSON bundle.
 
@@ -16,25 +16,26 @@ caller, `c.*` a constant — resolved at request time; JS operators over them do
 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).
-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`.
+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
-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 ~65k 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:
+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
+lookup in the shipped `manifest.json` (a program imports it as
+`@xanots/sdk/manifest.json`, needing `with { type: "json" }` in Node ESM;
+it is ~60k 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
+⚠ `fields` is null on the 65 `declarative: false` statements (`db.get`, …): typed wrappers whose arguments are the factory's `.d.ts` signature. Null ≠ missing.
 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 a 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.
+Paths are relative to this file (`node_modules/@xanots/sdk/` once installed), so a
+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.
 - [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.
@@ -266,6 +267,10 @@ 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.
@@ -320,18 +325,19 @@ Non-obvious authoring rules:
   `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).
+  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 — **~289 kB minified (~57 kB gzipped)** for the FIRST def; splitting modules
+  ⚠ 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 ~1 kB. So the cost is paid by importing ANY def at all, and reducing what a
-  def does will not reduce it.
+  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
@@ -385,17 +391,18 @@ Non-obvious authoring rules:
   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.
+  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
@@ -522,7 +529,7 @@ 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). 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.
+  - `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.
 - `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? } }`.
@@ -785,7 +792,7 @@ primary key `id`):
 
 - `s.db.get({ table, fieldName?, fieldValue, lock?, output?, as? })` — one row by field match; `output` restricts returned columns (and overrides column visibility — it can pull `internal` columns like a password hash).
 - `s.db.get_by_id({ table, id, output?, addon?, tableAlias?, as? })` — get by primary key. Takes `id`, NOT `fieldName`/`fieldValue`; binds the row or `null` for an id that names no row. Both spellings are live in pulled workspaces.
-  - ⚠ `id` is validated `>= 1`, so the `0` sentinel an optional `f.tableRef` stores fails the request with HTTP 400 `Value is less than the minimum value of 1` — it does NOT bind `null`. The throw is not scoped to the lookup: inside a `foreach` it kills the whole request, so one unset FK loses every other row's work. Read a nullable FK with the field-match form, which binds `null` on `0` and lets the loop finish: `s.db.get({ table, fieldName: "id", fieldValue: ref("row.fk"), as })`.
+  - ⚠ `id` is validated `>= 1`, so the `0` sentinel an optional `f.tableRef` stores fails the request with HTTP 400 `Value is less than the minimum value of 1` — it does NOT bind `null`. The throw is not scoped to the lookup: inside a `foreach` it kills the whole request, so one unset FK loses every other row's work. Read a nullable FK with the field-match form, which binds `null` on `0` and lets the loop finish: `s.db.get({ table, fieldName: "id", fieldValue: ref("row.fk"), as })`. `export()` warns when the `id` is statically a `0` — the literal `c.int(0)`, an `inp()` whose declared input default is `0`, or a `ref()` to a column declared `default: 0` — and `--strict` fails the build.
 - `s.db.has({ table, fieldName?, fieldValue, as? })` — existence test.
 - `s.db.del({ table, fieldName?, fieldValue, as? })` — delete by field match.
 - `s.db.add({ table, row?, data?, output?, as? })` — insert; `row` is a partial keyed by column.
@@ -807,13 +814,14 @@ primary key `id`):
     - ⚠ `like`/`ilike` take the operand as the PATTERN, verbatim: a bare term matches only an exact whole-string equal, and the endpoint answers HTTP 200 with zero rows — nothing reports a problem, so a search box that matches nothing ships. For substring matching use `includes`/`not includes`, which wrap the operand in `%…%` themselves and match case-INSENSITIVELY. Prefer them over a hand-built `"%" + term + "%"`, which is non-empty even for an empty term and so defeats `ignoreEmpty`; `includes` composes with it. `contains`/`@>`/`overlaps` are JSON/array containment, not text — on a text column they 400 `ParseError: Invalid value for param`.
     - Compose nested boolean logic with `and(...)` / `or(...)` groups (also available on `addon()` `where`).
     - An operand may be a bare value (`col`/`inp`/`ref`/`auth`/`c.*`) OR a **filtered** value (`withFilters(...)`) inline — the engine compiles the string and arithmetic filters (`trim`, `concat`, `upper`, `lower`, …) into the SQL.
-    - ⚠ The REQUEST-TIME timestamp filters have no SQL form and kill the request with a bare fatal naming nothing: `epochms_transform`, `epochms_add_ms`, `epochms_add_secs`, `epochms_date`, `epochms_from_format`. For a relative cutoff use the SQL-side family instead (`epochms_add_day`, `epochms_sub_month`, `epochms_year`, …) or compute it in an earlier `s.set_var` and `ref()` that. `export --strict` reports it; a bare `c.now()` operand is always fine.
+    - ⚠ The REQUEST-TIME timestamp filters have no SQL form and kill the request with a bare fatal naming nothing: `epochms_transform`, `epochms_add_ms`, `epochms_add_secs`, `epochms_date`, `epochms_from_format`. For a relative cutoff use the SQL-side family instead (`epochms_add_day`, `epochms_sub_month`, `epochms_year`, …) — by raw name, since `fl.*` has no builder for them — or compute it in an earlier `s.set_var` and `ref()` that. `export --strict` reports it; a bare `c.now()` operand is always fine.
   - `bind: [{ table, as?, join?, where? }]` — joins (`context.bind[]`). `join` defaults to `"inner"`. `as` defaults to the table name; two joins to the same table need distinct aliases.
     - ⚠ In `where`/`sort`/`eval` a JOINED column takes a dotted path (`col("team_row.id")`); THIS query's own columns stay **bare** (`col("team")`). Qualifying your own by table name needs `tableAlias` (same rule as `aggregate`) — without it the engine reads the operand as text and 400s `ParseError: Invalid value for param` naming the OTHER operand, so it throws at export instead.
     - `bind: [{ table: team, as: "team_row", join: "left", where: expr(col("team"), "=", col("team_row.id")) }]`
+    - ⚠ A join does NOT put the joined table's columns on the returned row — with or without a `bind`, a row is the QUERIED table's columns, which is what `InferResponse` types. There is no `row.team_row`. To read a joined column, PROJECT it with an `eval` whose `name` is the dotted path: `eval: [{ name: "team_row.name", as: "team_name" }]` puts `team_name` on the row and on the inferred type. A bare `name` there is `Unsupported parameter reference` at runtime (it qualifies to the base table), and a dotted joined column in `output` is dropped with no error.
   - `returnType` — `"list"` (default) | `"single"` | `"count"` | `"exists"` | `"stream"` | `"aggregate"`. Drives `context.return.type` AND the `InferResponse` shape: `count`→`number`, `exists`→`boolean`, `single`→`Row|null`, `stream`→`Row[]` (pageable, no envelope), `list`→`Row[]`/envelope, `aggregate`→rows keyed by the `aggregate.group`/`eval` aliases. ⚠ A bare `count` of ZERO serializes as an EMPTY body, not `0` — a client parsing JSON gets a parse error on the one result it most needs to handle. Wrap it: `response: { count: ref("n") }`.
   - `eval: [{ name, as, filters? }]` — computed columns (`context.eval[]`). Each `as` grafts onto the row as an `unknown` key in `InferResponse`; shadowing a real column throws. Write `name` **bare** (`"embedding"`) — it is alias-qualified on emit exactly like `aggregate` (a bare eval name is `Unsupported param format` at runtime), and the statement declares the alias it used. An `as` alias is `sort`able in the SAME query.
-    - An `eval`/`sort`/`where` filter pipeline compiles to **SQL**, so it resolves a DIFFERENT registry than `fl.*` (which runs in the request): the vector family, geo `distance`/`within`/`covers`, `search_rank`, the aggregators. Exported as `QUERY_EXPRESSION_FILTERS`/`VECTOR_FILTERS`.
+    - An `eval`/`sort`/`where` filter pipeline compiles to **SQL**, so it resolves a DIFFERENT registry than `fl.*` (which runs in the request): the vector family, geo `distance`/`within`/`covers`, `search_rank`, the aggregators. ⚠ `fl.*` carries NO builder for these — reach them by raw name, `filter("epochms_add_day", …)` or the `{ name, arg }` form. The name lists are `QUERY_EXPRESSION_FILTERS`/`VECTOR_FILTERS` on `@xanots/sdk/internal`.
     - **Vector similarity search** — the ONLY way to query an `f.vector` column (no `SearchOp` does distance). `eval: [{ name: "embedding", as: "distance", filters: [{ name: "vector_cos_distance", arg: [inp("q")] }] }]` + `sort: [{ sortBy: "distance", dir: "asc" }]` ranks in the DATABASE over the column's index. Match the filter to the index `op` (`vector_cos_distance`↔`vector_cosine_ops`, `vector_l2_distance`↔`vector_l2_ops`, `vector_l1_distance`↔`vector_l1_ops`, `vector_inner_product`↔`vector_ip_ops`); `vector_cos_similarity` is the inverse, so sort it `desc`. The same filter on a `where` operand cuts off BY distance instead of by row count.
   - `aggregate: { group?, eval?, sort?, paging? }` (with `returnType:"aggregate"`) builds `context.return.aggregate`. `group`/`eval` are `{ name, as, filters? }`, an aggregator like `sum`/`count` riding `filters`. Some aggregators resolve ONLY here, not in a runtime value pipeline: `count_distinct`, `median`, `to_list`/`to_distinct_list` (each with `_asc`/`_desc`), and `vector_distance`.
     - ⚠ Write each `name` as a **bare** column (`"status"`). It is alias-qualified to `"<alias>.status"` on emit — the engine rejects an unqualified column in an aggregate with `Unsupported param format`. An already-dotted `name` (a `bind`ed/joined column) passes through.
@@ -827,6 +835,8 @@ primary key `id`):
   - `distinct` — `"auto"` (default) | `"yes"` | `"no"`, riding `context.return.<list|stream>.distinct`.
 - `s.db.truncate({ table, reset?, as? })` · `s.db.schema({ table, path, as? })`.
 - `s.db.direct_query({ sql, responseType?, args?, parser?, as? })` — `sql` is a **raw string** (not a `Value`); binds go in `args: Value[]`. `parser: "template_engine"` renders the body as a template first — how a query interpolates a column or table name a bound arg cannot carry; omit it for the default.
+  - Template placeholders are Twig over the request scope: `{{ $input.name }}` for an input, `{{ $var.name }}` for a stack variable. ⚠ A BARE `{{ name }}` renders as the empty string — HTTP 200, no error, a query that silently ran with a blank where the value belonged. A bound `?` arg carries a VALUE without the template at all.
+  - ⚠ A table's PHYSICAL name is **not stable across deploys**. A deploy is a full replace, so every table is created afresh and the id in its name moves every time — the same unchanged project redeployed three times gave one table three different names. Never store, cache, hardcode or fixture one: resolve it from `information_schema` inside the same request that uses it.
 - `s.db.external.<engine>.direct_query({ sql, connectionString, responseType?, args?, parser?, as? })` — same shape against an EXTERNAL database; `<engine>` is `postgres`/`mysql`/`mssql`/`oracle`/`snowflake`. `connectionString` is a `Value` — reach for `env(...)`, not a literal — stored as `context.connection_string_flex`. A bare string stores the older `context.connection_string` instead (an env-var name unless it looks like a URL); each form round-trips as itself.
 - `s.db.transaction({ body, as? })` — run a `Statement[]` atomically. `as` binds whatever the block returned.
 - `s.db.bulk.add({ table, items, allowIdField?, as? })` / `s.db.bulk.update` / `s.db.bulk.patch` — `items` is an array `Value`.
@@ -929,7 +939,7 @@ Microservices (the `microservice()` def and the statement that calls it):
 - `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. 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. Still rejected: a filter ARGUMENT carrying its own chain (a trailing | binds to the whole value, not one argument), 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"`. 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.
 - `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".
@@ -1101,12 +1111,13 @@ database with a single `s.db.direct_query` UPDATE (`SET clicks = clicks + 1 WHER
 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 a physical name from workspace + table ids (of the
-form `x<workspace_id>_<table_id>`, e.g. `x6_203970`), ids assigned at import — not knowable
-from a `table()` def (identity is a name + guid, not the numeric id), and `sql_name`
-persists empty. So the safe counter drops out of the typed surface: hardcode
-the physical name after inspecting the deployed table. A typed atomic path needs an
-engine change.
+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.
 
 - `fl.add(value: decimal): decimal`
 - `fl.append(value: <T>, path: text): <T>[]`
@@ -1198,11 +1209,11 @@ engine change.
 - `fl.prepend(value: <T>, path: text): <T>[]`
 - `fl.range(start: int, stop: int): int[]`
 - `fl.reduce(initial_value: int, code: text, timeout?: int): any[]` — `code` is a JS body run per element; the ACCUMULATOR is `$result` (there is no `$acc`) and `initial_value` is REQUIRED — omitting it would slot the code as the initial value
-- `fl.regex_match(subject: text): text[]`
-- `fl.regex_match_all(subject: text): text[]`
+- `fl.regex_match(subject: text): text[]` — piped value is the PATTERN, the arg is the subject — see `regex_test`
+- `fl.regex_match_all(subject: text): text[]` — piped value is the PATTERN, the arg is the subject — see `regex_test`
 - `fl.regex_quote(delimiter?: text): text`
-- `fl.regex_replace(replacement: text, subject: text): text`
-- `fl.regex_test(subject: text): bool`
+- `fl.regex_replace(replacement: text, subject: text): text` — piped value is the PATTERN, `subject` is the text searched — see `regex_test`. The replacement comes FIRST
+- `fl.regex_test(subject: text): bool` — piped value is the PATTERN (build it with `c.regex(...)`); the arg is the subject — the REVERSE of `contains`/`starts_with`. Swapped, it answers false for every input with no error, so write `withFilters(c.regex("^a+$"), fl.regex_test(inp("s")))` (or name the arg: `fl.regex_test({ subject: inp("s") })`). A pattern found in the subject slot is refused at build time
 - `fl.round(precision?: int): decimal`
 - `fl.rtrim(mask?: text): text`
 - `fl.secureid_decode(salt: text): int`

package/llms.txt

@@ -1,4 +1,4 @@
-# xanots v0.0.10
+# xanots v0.0.12
 
 > TypeScript SDK that compiles a typed Xano workspace into the importable packageExport JSON bundle.
 
@@ -16,25 +16,26 @@ caller, `c.*` a constant — resolved at request time; JS operators over them do
 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).
-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`.
+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
-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 ~65k 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:
+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
+lookup in the shipped `manifest.json` (a program imports it as
+`@xanots/sdk/manifest.json`, needing `with { type: "json" }` in Node ESM;
+it is ~60k 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
+⚠ `fields` is null on the 65 `declarative: false` statements (`db.get`, …): typed wrappers whose arguments are the factory's `.d.ts` signature. Null ≠ missing.
 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 a 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.
+Paths are relative to this file (`node_modules/@xanots/sdk/` once installed), so a
+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.
 - [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.
@@ -266,6 +267,10 @@ 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.
@@ -320,18 +325,19 @@ Non-obvious authoring rules:
   `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).
+  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 — **~289 kB minified (~57 kB gzipped)** for the FIRST def; splitting modules
+  ⚠ 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 ~1 kB. So the cost is paid by importing ANY def at all, and reducing what a
-  def does will not reduce it.
+  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
@@ -385,17 +391,18 @@ Non-obvious authoring rules:
   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.
+  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

package/manifest.json

@@ -1,6 +1,6 @@
 {
   "name": "xanots",
-  "version": "0.0.10",
+  "version": "0.0.12",
   "description": "TypeScript SDK that compiles a typed Xano workspace into the importable packageExport JSON bundle.",
   "coverage": {
     "objectKinds": {
@@ -103,7 +103,7 @@
       {
         "name": "obj",
         "signature": "(fields: Record<string, Value | nested>) => ObjValue<typeof fields>",
-        "description": "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. 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. Still rejected: a filter ARGUMENT carrying its own chain (a trailing | binds to the whole value, not one argument), 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."
+        "description": "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."
       },
       {
         "name": "ref",
@@ -9393,6 +9393,10 @@
       "flag": "--json",
       "description": "Force JSON on stdout (default: whenever stdout is not a terminal)"
     },
+    {
+      "flag": "--no-refresh",
+      "description": "Do not refresh the managed block in CLAUDE.md / AGENTS.md / the Cursor rule"
+    },
     {
       "flag": "--help, -h",
       "description": "Show help for the command and exit"