@xano/sdk 1.0.5 → 1.0.6

package/guides/codes.md

@@ -35,7 +35,7 @@ Printed as `! …` on stderr, and as `{ code, message }` in a `--json` document'
 
 | Code | Meaning |
 |---|---|
-| `agents.refresh-failed` | A managed agent file (AGENTS.md, …) could not be refreshed; the compile itself went on. |
+| `agents.refresh-failed` | A managed block (AGENTS.md, the README's Built-with footer) could not be refreshed; the compile itself went on. |
 | `agents.symlink` | … is a symlink — left it and its target untouched. |
 | `branch.deletion` | … will be permanently deleted and CANNOT be recovered: |
 | `branch.inventory-unknown` | The branch inventory could not be read, so what this wipe destroys is UNKNOWN. |
@@ -142,7 +142,9 @@ Printed as `! …` on stderr, and as `{ code, message }` in a `--json` document'
 | `module.install-failed` | … failed — the module was not added. |
 | `module.kind-unknown` | … does not declare a module kind we recognize, so it is read as an ordinary package. |
 | `module.legacy-peer-deps` | Installed with --legacy-peer-deps: …. |
-| `module.load-failed` | Could not load …/index.ts to update what the module left behind (…). |
+| `module.load-failed` | Could not load …/index.ts to … (…). |
+| `module.peer-mismatch` | The project already declares a peer a toolchain module needs, and the installed version falls outside the module's range; it was left as it is. |
+| `module.peer-not-added` | A peer a toolchain module needs could not be added as a direct dependency; the line names the command that adds it. |
 | `module.peer-unresolved` | … declares a peer range this project does not satisfy; --legacy-peer-deps did not resolve it either. |
 | `module.removed-from-marketplace` | … has been removed from the marketplace. |
 | `module.sdk-skew` | … requires `@xano/sdk` … — the module was not added. |
@@ -224,6 +226,7 @@ Printed as `! …` on stderr, and as `{ code, message }` in a `--json` document'
 | `release.seed-rows-not-decoded` | … carries seed rows for …, and a decoded tree carries no rows — they are not in …/. |
 | `release.transfer-cancelled` | Transfer cancelled — nothing was imported. |
 | `routes.cli-skew` | This CLI is another version than the project's installed SDK, so it left the route table for the installed CLI to render. |
+| `routes.module-failed` | A toolchain module could not generate its section of `routes.gen.ts`; the rest was refreshed and its previous block, if any, was kept. |
 | `routes.not-written` | The route table (`routes.gen.ts`) was not written this run; the line says why and what writes it. |
 | `routes.realtime-unresolved` | …: leaving out … — … — whose canonical URL token resolves nowhere, along with their channels. |
 | `secrets.cleartext-export` | … carries … in cleartext — written owner-only (0600); do not commit it. |
@@ -248,6 +251,7 @@ Printed as `! …` on stderr, and as `{ code, message }` in a `--json` document'
 | `static.teardown-unknown` | Could not read …'s static hosting, so this cannot say whether a frontend serves there — this replace takes down any that does. |
 | `static.unconfirmed-live` | Could not confirm the frontend is live within the wait window — the build uploaded and should come online shortly. |
 | `static.upload-failed` | The static-host upload failed — the backend deploy stands: |
+| `sync.record-failed` | The … succeeded, but its sync baseline could not be recorded in …: … |
 | `tenant.deploy-partial` | The deploy stopped partway: … release "…" declares… — answered as a NOT NULL violation, though the release makes no field required: the value converts to nul… |
 | `tenant.deploy-unconfirmed` | Compare its `deployedAt` and `deployedReleaseId` with what they were before this deploy (deployedAt …, deployedReleaseId …). |
 | `tenant.identities-unchecked` | Whether this release's names and pinned public URL slugs are free on … was not checked — …. |
@@ -309,6 +313,7 @@ Raised while a workspace compiles (`export`, `deploy`, `release`, …). A warnin
 | `field.email-default-invalid` | The `default` at … is …, which is not an email address — every insert or request that leaves the field out is refused "Invalid email format.". |
 | `field.enum-default-not-a-value` | The `default` at … is …, which is not one of the enum's values (…) — a value no request can send back. |
 | `field.input-default-invalid` | The `default` at … is …, which … — every request that leaves the input out is refused. |
+| `field.input-required-default-ignored` | The `default` at …, input "…" is …, but the input is `required: true` — the engine refuses a request that leaves a required input out ("Missing param") befor… |
 | `field.vector-not-nullable` | table "…", column "…" is a vector with `nullable: false` and no default — an empty default becomes NULL only on a nullable column, and `''` is not a vector,… |
 | `function.reserved-input-name` | function "…": the input name `…` is reserved by the engine — a call passes its arguments keyed by input name, and the engine skips a `…` key when it evaluate… |
 | `guard.role-unsatisfiable` | A guard.role on a table passed by name checks a column the table lacks, or a role its enum column cannot hold. |

package/guides/deploying.md

@@ -1243,6 +1243,58 @@ object with the same key *and* the same identity, so a lock cannot pin a guid th
 never had. If none of the lock's identities appear in the source, that is what pointing a
 project at an unrelated backend looks like, and the pull is refused unless you pass `--yes`.
 
+### Which side changed: the sync baseline
+
+When a workspace and this project differ, `workspace diff` also says **which side moved** since
+they last matched. Every command that makes them match records a baseline in `xano.lock`, under
+`synced`. A baseline is one content digest per object, kept per workspace and per branch. The
+commands that record one are `deploy --to workspace`, a verified `promote`, `pull workspace`
+and `init --from workspace`. Commit it with the rest of the lock.
+
+```bash
+xanosdk workspace diff ./xano/index.ts --json
+```
+
+```jsonc
+{
+  "matched": false,
+  "differing": ["query:GET list (apiGroup orders)", "table:order"],
+  "baseline": { "at": "2026-10-05T13:36:31.000Z", "by": "pull" },
+  "changedThere": ["query:GET list (apiGroup orders)"], // edited in Xano since the baseline
+  "changedHere": ["table:order"],                        // edited in this project since
+  "changedBoth": [],                                     // edited on both sides: a conflict
+  "unclassified": []                                     // differs, direction unknown
+}
+```
+
+- `changedThere`: pull before you deploy, or the deploy overwrites that edit.
+- `changedHere`: deploy it.
+- `changedBoth`: reconcile by hand.
+- `unclassified`: the baseline cannot tell. The object has no baseline entry, both sides
+  already differed when it was taken, or it is the workspace's own settings row, which is
+  never digested. A changed slug also shows only here, because digests leave slugs out.
+
+Additions and deletions are classified as well. The baseline keeps this project's objects apart
+from the rest of the branch, so an object the project never held (another source's, or a section
+a pull does not write into `xano/`) is never reported as deleted here; it shows up only when it
+changes in Xano. An object that is new in Xano counts as `changedThere` only when the baseline is
+**complete**: a pull, an `init --from`, a verified
+`promote` and a `--replace` record every object on the branch, and so does a merge deploy
+that read the branch first. With no baseline for the branch, `baseline` is `null` and the
+four lists are empty. A run that finds the branch exactly as recorded leaves the lock alone.
+
+A few things to know about the baseline:
+
+- It records what the branch holds after the sync, read back from the branch where the command
+  can do so, so an object stored differently from how it compiles is not reported as changed in
+  Xano. It is recorded whoever's objects landed (a `--bundle` from elsewhere, a release another
+  project cut), because it describes the branch, not ownership.
+- A baseline taken by a different SDK version under an older digest scheme is set aside
+  (`baseline: null`) and replaced by the next sync, rather than read as every object changed.
+- An SDK older than this feature drops `synced` when it rewrites `xano.lock`. Nothing breaks: the
+  next sync records a new baseline.
+- On a merge conflict in `xano.lock`, keep either side's baseline for a branch, or delete it.
+
 ### Deploying to a branch
 
 `--branch <label>` stages on a Xano branch instead of the live one, which is the safer shape

package/guides/marketplace.md

@@ -169,6 +169,23 @@ that arrived some other way is configured by this run too: a plain `npm install`
 pull request, a `git pull` that changed `package.json`. It also means nothing has to recover
 a package name out of a `file:` or tarball specifier in order to configure it.
 
+A **toolchain module** gets two more steps, and `reinstall` runs both as well. Its peers other
+than `@xano/sdk` (`zod`, say) are added as direct dependencies through the project's package
+manager: yarn never installs peers, and pnpm does not link them where `routes.gen.ts` can import
+them. Then, when the project keeps a `routes.gen.ts` beside its entry, the file is regenerated,
+so the module's section lands with the module rather than at the next `xano:routes`. Under
+`--json`, `peers` lists the specs that were added (`["zod@^4.0.0"]`, or `[]`), and `routes` says
+what happened to the file:
+
+| `routes` | Meaning |
+|---|---|
+| `written` | Regenerated. |
+| `unchanged` | Already up to date. |
+| `absent` | The project has no `routes.gen.ts` to refresh. |
+| `skipped` | It could not be regenerated here. The warning says why; run `npm run xano:routes`. |
+
+`remove` reports `routes` the same way, for the file it regenerates without the removed module.
+
 `init` takes the same names and resolves them the same way — `--marketplace auth` is
 `@xano-sdk/auth`, and an unlisted name exits 8 before anything is written — so a project can be
 scaffolded with its add-ons already installed and registered:
@@ -207,6 +224,10 @@ What happens then depends on whether the module predates the command:
 | `install` re-run over a module already in `dependencies`, or `reinstall` | Refused and **left alone**, settings included, because deleting a module you already had over a version mismatch is not a repair. Upgrade the SDK, or `marketplace remove` it. |
 | `init --marketplace` | Reported as a module that was not added and taken back off disk. The scaffold itself completes and works. |
 
+A *different* installed module that is out of range does not stop the verb. `install`, `reinstall`
+and `remove` skip it with a warning naming its range and the fix, and leave its settings and its
+`routes.gen.ts` block exactly as they were. `export`, `deploy` and `preflight` still refuse it.
+
 The point of undoing the install is that the alternative is worse: a module whose hooks were
 built against a contract this SDK does not have registers and applies **nothing**, so
 `Installed` would be followed by a project where every command that loads modules refuses it.

package/guides/module-contract.md

@@ -163,6 +163,7 @@ const plugin: ToolchainPlugin = {
   answersFromConfig: (config) => ({ ... }),
   onBundle: async (ctx) => ({ ... }),
   onPreflight: async (ctx) => ({ ... }),
+  routesManifest: (ctx) => ({ imports: [...], source: "..." }),
 };
 
 export default plugin;
@@ -175,10 +176,11 @@ guessing which would run code the manifest did not describe.
 Every hook is optional. A module that only adds a `.gitattributes` line declares
 `contributes` alone.
 
-Five hooks, and deliberately no more. This contract was designed from one example, and a
-contract designed from one example generalizes badly, so it covers exactly what that first
-module needed and stops. The second toolchain module is the one that should widen it, with a
-real second set of requirements in hand.
+Six hooks, and deliberately no more. The first five were designed from one example (a module
+that renders the workspace to a committed tree) and cover exactly what it needed. The sixth,
+`routesManifest`, was added when a second module, `@xano-sdk/zod`, brought a second real set
+of requirements: writing into a file the SDK generates rather than a tree of its own. A hook
+is added when a module needs it, not in anticipation.
 
 ## Questions
 
@@ -452,6 +454,78 @@ reason to blank.
 A project whose plugins declare no `onPreflight` never pays for the engine's rendering at all,
 so declaring the hook is what turns that fetch on.
 
+## `routesManifest`
+
+```ts
+import type { ToolchainPlugin } from "@xano/sdk/plugin";
+
+const plugin: ToolchainPlugin = {
+  kind: "toolchain",
+  routesManifest: (ctx) => ({
+    imports: [{ from: "zod", names: ["z"] }],
+    source: `export const ROUTE_SCHEMAS = ...;`,
+  }),
+};
+```
+
+Your module's section of the route manifest, `xano/routes.gen.ts`. It runs wherever that file
+is written: `xanosdk routes ./xano/index.ts --emit xano/routes.gen.ts` (the scaffold's
+`xano:routes`), `pull`, `generate`, and the refresh `marketplace install`, `reinstall` and
+`remove` make, so your block lands with your module.
+
+| `RoutesManifestContext` | What it carries |
+|---|---|
+| `inputs` | Every endpoint's, channel's and message's request inputs, under the manifest's final keys (`routes`, `channels`, `messages`), in a fixed order. |
+| `config` | Your block from the project's `package.json` `"xanosdk"` object. |
+| `sdkVersion` | The running `@xano/sdk` version. |
+
+`inputs` is a validator-neutral description (type `RouteInputs` in `@xano/sdk/plugin`, not
+the generated map of the same name): each input's name, type, `required`, `nullable`, list
+bounds, enum values, methods, and children. A database link is one `dbLink` entry carrying the
+linked table's expanded `columns`, to spread into the surrounding object; `columns` is
+`undefined` when the payload does not carry that table, which is not "no columns". Walk this
+rather than the payload: it is the same description the SDK renders its own `RouteInputs`,
+`ChannelInputs` and `MessageInputs` types from, so a validator built from it cannot disagree
+with them.
+
+**Where the section lands.** The SDK composes the file: the merged imports of every module at
+the top, then the core sections, then each module's `source` in a marked block, blocks ordered
+by package name:
+
+```ts
+// xanosdk:begin @xano-sdk/zod
+// xanosdk:version 1.0.3 - generated; edits inside this block are overwritten
+...
+// xanosdk:end @xano-sdk/zod
+```
+
+Your source is in the same file as the core sections, so it names `RouteInputs`,
+`ChannelInputs`, `MessageInputs` and `MessageName` directly, without importing them; all four
+are always emitted, as `{}` when empty. Anything you export is exported from `routes.gen.ts`.
+Your names share one scope with the core sections and every other module's, so a collision
+fails the user's typecheck rather than being renamed. A blank `source` writes no block, and its
+imports are dropped with it: that is how a config that turns the section off removes it.
+
+**Imports are declared, never written.** The core sections import nothing, which is what keeps
+the file free of the SDK runtime in a frontend bundle. Declare yours in `imports`; never put an
+`import` line in `source`. Each `from` must be a bare package name: `@xano/sdk` and its
+subpaths, a relative or absolute path, and a protocol (`node:`) are all refused, naming your
+module. Each name must be a plain identifier, with no `as` rename. A package you import must
+resolve from the user's project, so declare it in your `peerDependencies`:
+`xanosdk marketplace install` adds each peer other than `@xano/sdk` that the project does not
+already declare as a direct dependency, with your range, through the project's package manager.
+
+**Synchronous and pure.** No filesystem, network, clock or randomness: the same context must
+return the same section every time. Every writer of the file must produce the same bytes for
+the same workspace and installed modules, or `routes --emit --strict` passes or fails depending
+on which command last wrote it. A Promise, or any value that is not `{ imports?, source }`, is
+refused, and `source` must not spell a block marker (`// xanosdk:begin`, `// xanosdk:end`).
+
+**A throw is your module failing, not the manifest.** The core sections are still refreshed,
+your previous block is kept exactly as it was, and a warning names your module. On
+`routes --emit --strict` it is fatal instead, because a check that did not run must not read
+as one that passed.
+
 ## `HookResult`: `failed` is not a throw
 
 ```ts
@@ -544,6 +618,8 @@ Things worth proving about your own module:
 - Your `onBundle` writes nothing when `ctx.frozen` is true.
 - Your `onBundle` handles `ctx.entry === undefined`.
 - Your hooks never read `payload.env` values, because they are blanked.
+- `routesManifest` returns the same section for the same context, called twice, and what it
+  writes typechecks beside the core sections of a real `routes.gen.ts`.
 
 ## Publishing
 

package/guides/typed-frontend.md

@@ -238,5 +238,42 @@ const ws = new WebSocket(socketUrl("chat", XANO_HOST), token);
 ws.send(JSON.stringify({ action: "join", channel: channelPath("rooms/{room_id}", { room_id }) }));
 ```
 
+**Request types come from the same file.** It exports four types-only maps, keyed exactly
+like the runtime tables they sit beside, so a frontend types what it sends without importing a
+def at all:
+
+| Type | Keyed by | Holds |
+|---|---|---|
+| `RouteInputs` | the `ROUTES` key (`"POST listings"`, `"v1:GET vehicles"`) | the endpoint's inputs, path params included |
+| `ChannelInputs` | the `CHANNELS` key (`"rooms/{room_id}"`) | the channel's path params |
+| `MessageInputs` | `"<channel key> <message name>"` (`"rooms/{room_id} send"`) | the message's payload |
+| `MessageName` | | every `MessageInputs` key |
+
+```ts
+import { ROUTES, routePath, type RouteInputs } from "../xano/routes.gen";
+
+type NewListing = RouteInputs["POST listings"];
+
+fetch(BASE + routePath("POST listings"), {
+  method: ROUTES["POST listings"].verb,
+  headers: { "content-type": "application/json" },
+  body: JSON.stringify({ title, price } satisfies NewListing),
+});
+```
+
+Each type agrees with `InferInput<typeof def>` for the same endpoint — required and optional
+keys, `null`, enums, nested objects and lists — so code that already imports a def can keep
+using `InferInput`. The one difference is a database-link input (`input.dbLink(table)`): the
+manifest types it as the linked table's columns, which is what the server accepts, where
+`InferInput` shows an opaque marker under the link's name. Responses are not in the manifest;
+type them with `InferResponse` on an `import type` of the def.
+
+These are types, so they add nothing to a bundle. For runtime validation, install
+`@xano-sdk/zod` (`npx xanosdk marketplace install zod`): it writes `ROUTE_SCHEMAS`,
+`CHANNEL_SCHEMAS` and `MESSAGE_SCHEMAS` into the same file under the same keys
+(`ROUTE_SCHEMAS["POST listings"].parse(body)`), each checked against its type when you
+typecheck, so a schema cannot drift from the type it validates. The file then imports `zod`,
+and still never `@xano/sdk`.
+
 Add `--strict` in CI to fail when the committed manifest is out of date. A hand-typed
 `ROUTES` table is the option that gives up both the bundle saving and the rename safety.

package/llms/client.md

@@ -1,6 +1,6 @@
 # Consuming defs from a client
 
-> Read when a frontend imports a def (`getPath()`/`InferResponse`) or calls the deployed backend — what the import costs, `window.XANO_HOST`, local dev, file URLs, and a Node spot-check.
+> Read when a frontend calls the deployed backend or imports a def — request types and zod schemas without the import, its cost, `window.XANO_HOST`, local dev, file URLs, a Node spot-check.
 
 Importing a def into a browser bundle or a Node script — for `getPath()`, `getUrl()`, `verb`, or `InferResponse` — runs its factory calls; these are the costs and the checks.
 
@@ -15,6 +15,16 @@ Importing a def into a browser bundle or a Node script — for `getPath()`, `get
   plain data importing NOTHING, still compile-checked: `routePath("GET blog/{slug}", { slug })`
   `channelPath("rooms/{room_id}", { room_id })`, `socketUrl("chat", baseUrl)` (tenant base
   URLs lifted to `wss://h/ws/<tenant>:<canonical>`). A rename is a type error, not a 404.
+- **Request types without the def.** `routes.gen.ts` also exports types-only `RouteInputs`,
+  `ChannelInputs`, `MessageInputs` (and `MessageName`), keyed like `ROUTES`, `CHANNELS`, and
+  `"<channel key> <message name>"`: `type NewListing = RouteInputs["POST listings"]`. A
+  frontend types bodies, channel params and payloads from these, not `InferInput` on a def;
+  keep `InferInput` in code that already imports defs. They match `InferInput`, except a
+  `dbLink` input appears as the linked table's columns (what the server accepts). Responses
+  are not in the file: `InferResponse` on an `import type` of the def.
+  Runtime validation: `xanosdk marketplace install zod` adds `@xano-sdk/zod`, which writes
+  `ROUTE_SCHEMAS`/`CHANNEL_SCHEMAS`/`MESSAGE_SCHEMAS` into the file under the same keys, each
+  checked against its type at typecheck; the file then imports `zod`, never `@xano/sdk`.
 - **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 …"`

package/llms/filters.md

@@ -27,6 +27,10 @@ with `c.obj`/`c.array`. Any argument also takes a runtime value (`inp`, `ref`, a
 `withFilters` chain) — inside `obj()`/`expr()` an argument cannot carry its own filter
 chain, so compute it in a prior `set_var`. The arg types below name each argument's
 ENGINE type, not the JS type you may pass.
+`fl.add`/`fl.sub`/`fl.mul` keep an INT when both operands are ints (`2 × 3` is `6`, not
+`6.0`) and give a decimal only when either operand is one — the `decimal` return type
+below covers both, so an int pipeline needs no `fl.to_int()`. `fl.div` is an int only
+when it divides exactly.
 To add to a numeric column (counter, stock, balance), use `s.db.increment`
 (`llms/statements-data.md`) — one atomic UPDATE. A pipeline read-modify-write is NOT
 atomic (concurrent writers lose updates), and `col("clicks")` does NOT resolve to the

package/llms/kinds-core.md

@@ -25,7 +25,7 @@ to survive a rename).
     - `getPath` percent-encodes each value (so `?`/`#`/spaces stay in their segment) and throws on what encoding cannot contain: a `/`, and a segment that becomes `.`/`..` as sent (a URL parser drops those before routing, addressing a different endpoint).
     - The keys are typed from the literal `name`, so a typo is a compile error.
     - `q.toSearchParams(input)` drops GET path params (free `query.toSearchParams` keeps them); lists send `k[]=a&k[]=b` (`k=a&k=b` binds only `b`).
-  - Browser bundle cost, the `routes.gen.ts` alternative, and spot-checking a def from Node: `llms/client.md`.
+  - Browser bundle cost, the `routes.gen.ts` alternative (paths and request types), and spot-checking a def from Node: `llms/client.md`.
 - `apiGroup({ name, guid?, canonical?, description?, docs?, swagger?, apiGroupEnabled?, documentation?, cors?, middleware? })` — a query container; queries bind to it via their `apiGroup`. `canonical` holds only letters, digits, `_` and `-` (it is the `<canonical>` of `/api:<canonical>`); anything else THROWS at build.
   - `documentation?`: `{ require_token? }` — the gate on this group's hosted docs. `require_token: true` IS the declaration; the token lives in `xano/.secrets.json` under this group's guid, and a literal `token` FAILS the export. ⚠ ALWAYS emitted, present or not: an absent key is written as the engine default on import, so omitting the block CLEARS an existing gate (the opposite of the `workspaceConfig` rule). `swagger: true` publishes the docs; `require_token` gates them only alongside a non-empty token, so `swagger: true` with no gate makes the whole group readable by anyone with the URL — export warns once per build and `--strict` fails; `diagnostics: { allow: ["api-group.docs-public"] }` accepts it. A declared gate with NO token drops the block, so those bytes clear it: export FAILS under `swagger: true`, and with `swagger` off warns and completes.
   - `cors?`: `{ mode?, allowOrigins?: string[], allowHeaders?: string[], allowCredentials?, maxAge?, allowMethods?: { get?, post?, put?, patch?, delete?, head? } }`.

package/llms/statements-data.md

@@ -4,7 +4,7 @@
 
 Array blocks (an `if`/`transform` is applied per item):
 
-- `s.array.map({ source, as?, transform? })` — `transform` is either a per-item `Value` expression (each item maps to that value) or a **record of values** (each item maps to an object with those keys), or a list of `{ key, value }` pairs, for a key computed per item or two rows sharing one. Use `ref("$this")` for the item and `ref("$index")` for its position. These are THIS statement's own bindings, in a value expression — not the JavaScript lambda contract (see **Lambda bodies**), which binds a different set per surface and is written with `lam.fn`.
+- `s.array.map({ source, as?, transform? })` — `transform` is either a per-item `Value` expression (each item maps to that value) or a **record of values** (each item maps to an object with those keys), or a list of `{ key, value }` pairs, for a key computed per item or two rows sharing one. Use `ref("$this")` for the item and `ref("$index")` for its position. A `transform` value, filter arguments included, can read `ref("$this.<path>")` and any outer stack variable or input. These are THIS statement's own bindings, in a value expression — not the JavaScript lambda contract (see **Lambda bodies**), which binds a different set per surface and is written with `lam.fn`.
 - `s.array.union({ source, with, as?, transform? })` — set-union two arrays. `with` is REQUIRED; omitted → `Unable to locate input: `.
 
 DB reads/writes (`table` is a def handle or name; `fieldName` defaults to the
@@ -58,7 +58,8 @@ primary key `id`):
   - 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.transaction({ body })` — run a `Statement[]` atomically. It returns nothing, so it takes no `as`: read what the body binds. An `s.return` in the body ends the WHOLE stack with that value, and the writes before it commit.
+  - The body shares the enclosing stack: a variable it binds (`as: "order"` on an `s.db.add`) is still bound AFTER the transaction.
 - `s.db.bulk.add({ table, items, allowIdField?, as? })` / `s.db.bulk.update` / `s.db.bulk.patch` — `items` is an array `Value`.
   - ⚠ `bulk.add` **drops `id` on every row unless `allowIdField: true`** (silently, next sequence value instead) — the opposite of `seed`, where `id` pins. Rows referenced by a foreign key need `allowIdField: true`; literal `items` carrying `id` without it throw. `bulk.update`/`patch` keep `id` (their match key).
   - ⚠ **`bulk.update` is a whole-row REPLACE: every column an item OMITS is zeroed** (`""`/`0`/`null`), HTTP 200, no error — `{ id: 7, status: "done" }` blanks the rest of row 7. **Use `s.db.bulk.patch`** for the partial write "update these rows" means. `export()` warns on a STATIC `items` missing columns (`--strict` fails); a `ref`/`inp` `items` is uninspectable.

package/llms/toolchain.md

@@ -14,3 +14,15 @@ shipped defaults. `marketplace reinstall <pkg>` re-asks with the current setting
 defaults and re-enables a disabled one; `marketplace remove <pkg>` drops block, lines and
 dependency together — a plain `npm uninstall` leaves the block, and a package it names
 that is no longer installed fails every `--frozen-lock` run.
+
+**A module's section of `xano/routes.gen.ts`.** A module with a `routesManifest` hook (types:
+`@xano/sdk/plugin`) writes a block between `// xanosdk:begin <pkg>` and `// xanosdk:end <pkg>`
+after the core sections, on every write of the file (`routes --emit`, `xano:routes`, `pull`,
+`generate`, `marketplace install|reinstall|remove`). Edits inside the block are overwritten.
+Install also adds the module's non-SDK peers (e.g. `zod`) as direct dependencies.
+The hook is synchronous and pure: given
+the request inputs under the manifest's keys and its config, it returns `{ imports?, source }`,
+imports as bare package names (`@xano/sdk*`, relative and `node:` are refused). A module that
+fails to load or throws leaves its previous block as it was, with a warning naming it, and the
+core sections still refresh; under `routes --emit --strict` it is fatal. `@xano-sdk/zod`
+(`xanosdk marketplace install zod`) is one: it adds `ROUTE_SCHEMAS` and its siblings.

package/llms-full.txt

@@ -1,4 +1,4 @@
-# xanosdk v1.0.5
+# xanosdk v1.0.6
 
 > TypeScript SDK that compiles a typed Xano workspace into the importable packageExport JSON bundle.
 
@@ -39,7 +39,7 @@ plain file read resolves them at the version you have.
 
 - [Object kinds](llms/object-kinds.md): Read when deciding WHAT to build — every authorable primitive, what each is, and which factory + register method builds it. Also when `register*` will not typecheck an array built by `.flatMap()`/`.concat()`.
 - [Core def shapes](llms/kinds-core.md): Read when authoring a function, query, api group, task, workflow test, middleware, tool, or addon — and for the `response` and `expr` shapes every one of them uses.
-- [Consuming defs from a client](llms/client.md): Read when a frontend imports a def (`getPath()`/`InferResponse`) or calls the deployed backend — what the import costs, `window.XANO_HOST`, local dev, file URLs, and a Node spot-check.
+- [Consuming defs from a client](llms/client.md): Read when a frontend calls the deployed backend or imports a def — request types and zod schemas without the import, its cost, `window.XANO_HOST`, local dev, file URLs, a Node spot-check.
 - [Toolchain modules](llms/toolchain.md): Read when `package.json` has a `"xanosdk"` block or you run `xanosdk marketplace`.
 - [Error index](llms/errors.md): Read when a request, test, build, or pull fails with a message you did not write — the string, its cause, and where the fix is.
 - [Saved unit tests, assertions, and mocks](llms/tests.md): Read when authoring a `workflowTest()` stack, when a query/function/middleware carries `tests`, when a statement needs a `mock`, or when running a deployed environment's tests.
@@ -436,7 +436,7 @@ Non-obvious authoring rules:
   checked only by the `xanosdk export`/`deploy` CLI path. Only `deploy` ships seed rows.
   - Entry points: the `node:fs` writers (`writeBundle`/`writeArtifact`) and lock-file I/O
     import from `@xano/sdk/node`, NOT the browser-safe `@xano/sdk` entry (a frontend
-    imports defs from it for `getPath()`/`InferInput`). `@xano/sdk/internal` is the
+    imports from it; request types come from `routes.gen.ts`). `@xano/sdk/internal` is the
     compiler machinery, never needed to author. READING a bundle back is `@xano/sdk/bundle`
     — a statement walker (`2.if.0` paths), a structural hash, `mvp:*` catalog, `tableRefOf`.
 - **Intra-workspace imports use `.js` specifiers** (`../tables/links.js`), not
@@ -554,7 +554,7 @@ to survive a rename).
     - `getPath` percent-encodes each value (so `?`/`#`/spaces stay in their segment) and throws on what encoding cannot contain: a `/`, and a segment that becomes `.`/`..` as sent (a URL parser drops those before routing, addressing a different endpoint).
     - The keys are typed from the literal `name`, so a typo is a compile error.
     - `q.toSearchParams(input)` drops GET path params (free `query.toSearchParams` keeps them); lists send `k[]=a&k[]=b` (`k=a&k=b` binds only `b`).
-  - Browser bundle cost, the `routes.gen.ts` alternative, and spot-checking a def from Node: `llms/client.md`.
+  - Browser bundle cost, the `routes.gen.ts` alternative (paths and request types), and spot-checking a def from Node: `llms/client.md`.
 - `apiGroup({ name, guid?, canonical?, description?, docs?, swagger?, apiGroupEnabled?, documentation?, cors?, middleware? })` — a query container; queries bind to it via their `apiGroup`. `canonical` holds only letters, digits, `_` and `-` (it is the `<canonical>` of `/api:<canonical>`); anything else THROWS at build.
   - `documentation?`: `{ require_token? }` — the gate on this group's hosted docs. `require_token: true` IS the declaration; the token lives in `xano/.secrets.json` under this group's guid, and a literal `token` FAILS the export. ⚠ ALWAYS emitted, present or not: an absent key is written as the engine default on import, so omitting the block CLEARS an existing gate (the opposite of the `workspaceConfig` rule). `swagger: true` publishes the docs; `require_token` gates them only alongside a non-empty token, so `swagger: true` with no gate makes the whole group readable by anyone with the URL — export warns once per build and `--strict` fails; `diagnostics: { allow: ["api-group.docs-public"] }` accepts it. A declared gate with NO token drops the block, so those bytes clear it: export FAILS under `swagger: true`, and with `swagger` off warns and completes.
   - `cors?`: `{ mode?, allowOrigins?: string[], allowHeaders?: string[], allowCredentials?, maxAge?, allowMethods?: { get?, post?, put?, patch?, delete?, head? } }`.
@@ -630,7 +630,7 @@ surface — `s.conditional`/`s.while` `when` (incl. each `elif` branch), and
 
 # Consuming defs from a client
 
-> Read when a frontend imports a def (`getPath()`/`InferResponse`) or calls the deployed backend — what the import costs, `window.XANO_HOST`, local dev, file URLs, and a Node spot-check.
+> Read when a frontend calls the deployed backend or imports a def — request types and zod schemas without the import, its cost, `window.XANO_HOST`, local dev, file URLs, a Node spot-check.
 
 Importing a def into a browser bundle or a Node script — for `getPath()`, `getUrl()`, `verb`, or `InferResponse` — runs its factory calls; these are the costs and the checks.
 
@@ -645,6 +645,16 @@ Importing a def into a browser bundle or a Node script — for `getPath()`, `get
   plain data importing NOTHING, still compile-checked: `routePath("GET blog/{slug}", { slug })`
   `channelPath("rooms/{room_id}", { room_id })`, `socketUrl("chat", baseUrl)` (tenant base
   URLs lifted to `wss://h/ws/<tenant>:<canonical>`). A rename is a type error, not a 404.
+- **Request types without the def.** `routes.gen.ts` also exports types-only `RouteInputs`,
+  `ChannelInputs`, `MessageInputs` (and `MessageName`), keyed like `ROUTES`, `CHANNELS`, and
+  `"<channel key> <message name>"`: `type NewListing = RouteInputs["POST listings"]`. A
+  frontend types bodies, channel params and payloads from these, not `InferInput` on a def;
+  keep `InferInput` in code that already imports defs. They match `InferInput`, except a
+  `dbLink` input appears as the linked table's columns (what the server accepts). Responses
+  are not in the file: `InferResponse` on an `import type` of the def.
+  Runtime validation: `xanosdk marketplace install zod` adds `@xano-sdk/zod`, which writes
+  `ROUTE_SCHEMAS`/`CHANNEL_SCHEMAS`/`MESSAGE_SCHEMAS` into the file under the same keys, each
+  checked against its type at typecheck; the file then imports `zod`, never `@xano/sdk`.
 - **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 …"`
@@ -708,6 +718,18 @@ defaults and re-enables a disabled one; `marketplace remove <pkg>` drops block,
 dependency together — a plain `npm uninstall` leaves the block, and a package it names
 that is no longer installed fails every `--frozen-lock` run.
 
+**A module's section of `xano/routes.gen.ts`.** A module with a `routesManifest` hook (types:
+`@xano/sdk/plugin`) writes a block between `// xanosdk:begin <pkg>` and `// xanosdk:end <pkg>`
+after the core sections, on every write of the file (`routes --emit`, `xano:routes`, `pull`,
+`generate`, `marketplace install|reinstall|remove`). Edits inside the block are overwritten.
+Install also adds the module's non-SDK peers (e.g. `zod`) as direct dependencies.
+The hook is synchronous and pure: given
+the request inputs under the manifest's keys and its config, it returns `{ imports?, source }`,
+imports as bare package names (`@xano/sdk*`, relative and `node:` are refused). A module that
+fails to load or throws leaves its previous block as it was, with a warning naming it, and the
+core sections still refresh; under `routes --emit --strict` it is fatal. `@xano-sdk/zod`
+(`xanosdk marketplace install zod`) is one: it adds `ROUTE_SCHEMAS` and its siblings.
+
 # Error index
 
 > Read when a request, test, build, or pull fails with a message you did not write — the string, its cause, and where the fix is.
@@ -997,7 +1019,7 @@ off); a trigger's own failure reaches the error log only while it is on.
 
 Array blocks (an `if`/`transform` is applied per item):
 
-- `s.array.map({ source, as?, transform? })` — `transform` is either a per-item `Value` expression (each item maps to that value) or a **record of values** (each item maps to an object with those keys), or a list of `{ key, value }` pairs, for a key computed per item or two rows sharing one. Use `ref("$this")` for the item and `ref("$index")` for its position. These are THIS statement's own bindings, in a value expression — not the JavaScript lambda contract (see **Lambda bodies**), which binds a different set per surface and is written with `lam.fn`.
+- `s.array.map({ source, as?, transform? })` — `transform` is either a per-item `Value` expression (each item maps to that value) or a **record of values** (each item maps to an object with those keys), or a list of `{ key, value }` pairs, for a key computed per item or two rows sharing one. Use `ref("$this")` for the item and `ref("$index")` for its position. A `transform` value, filter arguments included, can read `ref("$this.<path>")` and any outer stack variable or input. These are THIS statement's own bindings, in a value expression — not the JavaScript lambda contract (see **Lambda bodies**), which binds a different set per surface and is written with `lam.fn`.
 - `s.array.union({ source, with, as?, transform? })` — set-union two arrays. `with` is REQUIRED; omitted → `Unable to locate input: `.
 
 DB reads/writes (`table` is a def handle or name; `fieldName` defaults to the
@@ -1051,7 +1073,8 @@ primary key `id`):
   - 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.transaction({ body })` — run a `Statement[]` atomically. It returns nothing, so it takes no `as`: read what the body binds. An `s.return` in the body ends the WHOLE stack with that value, and the writes before it commit.
+  - The body shares the enclosing stack: a variable it binds (`as: "order"` on an `s.db.add`) is still bound AFTER the transaction.
 - `s.db.bulk.add({ table, items, allowIdField?, as? })` / `s.db.bulk.update` / `s.db.bulk.patch` — `items` is an array `Value`.
   - ⚠ `bulk.add` **drops `id` on every row unless `allowIdField: true`** (silently, next sequence value instead) — the opposite of `seed`, where `id` pins. Rows referenced by a foreign key need `allowIdField: true`; literal `items` carrying `id` without it throw. `bulk.update`/`patch` keep `id` (their match key).
   - ⚠ **`bulk.update` is a whole-row REPLACE: every column an item OMITS is zeroed** (`""`/`0`/`null`), HTTP 200, no error — `{ id: 7, status: "done" }` blanks the rest of row 7. **Use `s.db.bulk.patch`** for the partial write "update these rows" means. `export()` warns on a STATIC `items` missing columns (`--strict` fails); a `ref`/`inp` `items` is uninspectable.
@@ -1428,6 +1451,10 @@ with `c.obj`/`c.array`. Any argument also takes a runtime value (`inp`, `ref`, a
 `withFilters` chain) — inside `obj()`/`expr()` an argument cannot carry its own filter
 chain, so compute it in a prior `set_var`. The arg types below name each argument's
 ENGINE type, not the JS type you may pass.
+`fl.add`/`fl.sub`/`fl.mul` keep an INT when both operands are ints (`2 × 3` is `6`, not
+`6.0`) and give a decimal only when either operand is one — the `decimal` return type
+below covers both, so an int pipeline needs no `fl.to_int()`. `fl.div` is an int only
+when it divides exactly.
 To add to a numeric column (counter, stock, balance), use `s.db.increment`
 (`llms/statements-data.md`) — one atomic UPDATE. A pipeline read-modify-write is NOT
 atomic (concurrent writers lose updates), and `col("clicks")` does NOT resolve to the

package/llms.txt

@@ -1,4 +1,4 @@
-# xanosdk v1.0.5
+# xanosdk v1.0.6
 
 > TypeScript SDK that compiles a typed Xano workspace into the importable packageExport JSON bundle.
 
@@ -39,7 +39,7 @@ plain file read resolves them at the version you have.
 
 - [Object kinds](llms/object-kinds.md): Read when deciding WHAT to build — every authorable primitive, what each is, and which factory + register method builds it. Also when `register*` will not typecheck an array built by `.flatMap()`/`.concat()`.
 - [Core def shapes](llms/kinds-core.md): Read when authoring a function, query, api group, task, workflow test, middleware, tool, or addon — and for the `response` and `expr` shapes every one of them uses.
-- [Consuming defs from a client](llms/client.md): Read when a frontend imports a def (`getPath()`/`InferResponse`) or calls the deployed backend — what the import costs, `window.XANO_HOST`, local dev, file URLs, and a Node spot-check.
+- [Consuming defs from a client](llms/client.md): Read when a frontend calls the deployed backend or imports a def — request types and zod schemas without the import, its cost, `window.XANO_HOST`, local dev, file URLs, a Node spot-check.
 - [Toolchain modules](llms/toolchain.md): Read when `package.json` has a `"xanosdk"` block or you run `xanosdk marketplace`.
 - [Error index](llms/errors.md): Read when a request, test, build, or pull fails with a message you did not write — the string, its cause, and where the fix is.
 - [Saved unit tests, assertions, and mocks](llms/tests.md): Read when authoring a `workflowTest()` stack, when a query/function/middleware carries `tests`, when a statement needs a `mock`, or when running a deployed environment's tests.
@@ -436,7 +436,7 @@ Non-obvious authoring rules:
   checked only by the `xanosdk export`/`deploy` CLI path. Only `deploy` ships seed rows.
   - Entry points: the `node:fs` writers (`writeBundle`/`writeArtifact`) and lock-file I/O
     import from `@xano/sdk/node`, NOT the browser-safe `@xano/sdk` entry (a frontend
-    imports defs from it for `getPath()`/`InferInput`). `@xano/sdk/internal` is the
+    imports from it; request types come from `routes.gen.ts`). `@xano/sdk/internal` is the
     compiler machinery, never needed to author. READING a bundle back is `@xano/sdk/bundle`
     — a statement walker (`2.if.0` paths), a structural hash, `mvp:*` catalog, `tableRefOf`.
 - **Intra-workspace imports use `.js` specifiers** (`../tables/links.js`), not

package/manifest.json

@@ -1,6 +1,6 @@
 {
   "name": "xanosdk",
-  "version": "1.0.5",
+  "version": "1.0.6",
   "description": "TypeScript SDK that compiles a typed Xano workspace into the importable packageExport JSON bundle.",
   "coverage": {
     "objectKinds": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xano/sdk",
-  "version": "1.0.5",
+  "version": "1.0.6",
   "description": "Xano SDK — your Xano backend as TypeScript. `xanosdk deploy` ships your typed workspace (and an optional static frontend) to a live, auto-expiring ephemeral environment and prints its URL. init → deploy → URL.",
   "keywords": [
     "xanosdk",