@xanots/sdk 0.0.1

package/dist/workspace-command-OF23DPNI.js

@@ -0,0 +1,156 @@
+import {
+  fetchWorkspaceBundle,
+  runCodegenCommand
+} from "./chunk-TRU5OHQ5.js";
+import "./chunk-26CNBZE2.js";
+import {
+  resolveOutputTarget
+} from "./chunk-XQ22GLYS.js";
+import "./chunk-QTNO2WD6.js";
+import "./chunk-ZUTSMMAG.js";
+import "./chunk-WKP4D5MO.js";
+import "./chunk-VKFQJEMW.js";
+import "./chunk-47WDWMBJ.js";
+import "./chunk-X4DVXBFY.js";
+import "./chunk-7DKX2SPN.js";
+import {
+  printMicroserviceSection,
+  readMicroservices
+} from "./chunk-NDZFBZHC.js";
+import {
+  isMachineOutput,
+  writeJson
+} from "./chunk-NUQCEOKA.js";
+import {
+  fetchOrExplain,
+  httpFailure
+} from "./chunk-3IGNIP6R.js";
+import {
+  ENV_WORKSPACE,
+  getAccessToken
+} from "./chunk-C56BC2FY.js";
+import "./chunk-7REDODS2.js";
+import "./chunk-MZUI3JNX.js";
+import "./chunk-RVB7ITKN.js";
+import "./chunk-4BXJGVZ3.js";
+import "./chunk-FJ6ZS5KB.js";
+import "./chunk-YGPIY3WT.js";
+import {
+  removedSubcommand,
+  unknownSubcommand
+} from "./chunk-IZW6MK3U.js";
+import {
+  formatFields,
+  stdoutStyle,
+  step,
+  success
+} from "./chunk-EZG76F7R.js";
+import "./chunk-3DUAGYGP.js";
+import "./chunk-YYRDLFSJ.js";
+import "./chunk-EMCAWMHC.js";
+import "./chunk-WHOJWOSV.js";
+import "./chunk-LH6Z6KFV.js";
+import "./chunk-HJPTWBLH.js";
+import "./chunk-GNPVYOPB.js";
+import "./chunk-4HT3BNZ7.js";
+
+// src/emit/workspace-command.ts
+import { writeFileSync } from "fs";
+var TIMEOUT_MS = 3e4;
+var DEFAULT_NAME = "workspace";
+async function runWorkspaceCommand(args) {
+  switch (args.subcommand) {
+    case "details":
+      return runDetails(args);
+    case "export":
+      return runExport(args);
+    case "codegen":
+      return runCodegenCommand(args, { kind: "workspace" });
+    case "deploy":
+      throw removedSubcommand("workspace", "deploy");
+    default:
+      throw unknownSubcommand("workspace", args.subcommand);
+  }
+}
+async function fetchWorkspaces(auth) {
+  const url = new URL("/api:meta/workspace", auth.instance);
+  const res = await fetchOrExplain(
+    url.href,
+    {
+      headers: { accept: "application/json", Authorization: `Bearer ${auth.access_token}` },
+      signal: AbortSignal.timeout(TIMEOUT_MS)
+    },
+    "workspace list",
+    TIMEOUT_MS
+  );
+  const text = await res.text();
+  if (!res.ok) {
+    throw new Error(httpFailure("workspace list", res, text));
+  }
+  try {
+    const parsed = JSON.parse(text);
+    return Array.isArray(parsed) ? parsed : [];
+  } catch {
+    throw new Error(`workspace list: could not parse the response as JSON:
+${text.slice(0, 200)}`);
+  }
+}
+async function runDetails(args) {
+  const auth = await getAccessToken(args);
+  const workspaceId = auth.workspaceId;
+  const all = await fetchWorkspaces(auth);
+  const match = all.find((w) => w.id === workspaceId);
+  if (!match) {
+    const known = all.filter((w) => typeof w.id === "number").map((w) => `  ${String(w.id).padStart(3)}  ${typeof w.name === "string" ? w.name : "(unnamed)"}`).join("\n");
+    const source = auth.credentialType !== "token" ? `Run \`xanots login\` again to re-pin it` : process.env[ENV_WORKSPACE] !== void 0 ? `Fix \`${ENV_WORKSPACE}\` in the environment` : `Fix \`workspace_id\` in your credential file`;
+    throw new Error(
+      `Workspace ${workspaceId} does not exist on ${new URL(auth.instance).host} (or your credential cannot see it).
+${source}.` + (known === "" ? "" : `
+
+Workspaces you can reach:
+${known}`)
+    );
+  }
+  const summary = {
+    instance: auth.instance,
+    id: workspaceId,
+    name: typeof match.name === "string" ? match.name : void 0,
+    guid: typeof match.guid === "string" ? match.guid : void 0,
+    /** Which credential this command is acting under — the only thing that selects a workspace. */
+    credential: auth.credentialType
+  };
+  const microservices = await readMicroservices(auth, auth.instance, workspaceId);
+  if (isMachineOutput(args)) {
+    writeJson({ ...summary, microservices });
+    return;
+  }
+  const s = stdoutStyle();
+  const rows = [
+    ["instance", summary.instance],
+    ["workspace", `${summary.name ?? "(unnamed)"} ${s.dim(`#${summary.id}`)}`]
+  ];
+  if (summary.guid !== void 0) rows.push(["guid", summary.guid]);
+  rows.push([
+    "source",
+    summary.credential === "token" ? "your meta API token credential" : "your sign-in (pinned at login)"
+  ]);
+  process.stdout.write(formatFields(rows) + "\n");
+  printMicroserviceSection(microservices);
+}
+async function runExport(args) {
+  const auth = await getAccessToken(args);
+  const bundle = await fetchWorkspaceBundle(auth);
+  const content = JSON.stringify(bundle, null, 2);
+  const target = resolveOutputTarget({ path: args.path, name: args.name ?? DEFAULT_NAME, ext: "json" });
+  if (target.kind === "stdout") {
+    process.stdout.write(content + "\n");
+    return;
+  }
+  writeFileSync(target.path, content + "\n", "utf8");
+  step(`Exported workspace \u2192 ${target.path}`);
+  success(`Wrote ${target.path}`);
+}
+export {
+  runWorkspaceCommand
+};
+//# sourceMappingURL=workspace-command-OF23DPNI.js.map

package/dist/workspace-export-AJMGN3CQ.js

@@ -0,0 +1,10 @@
+import {
+  exportWorkspaceBundle
+} from "./chunk-QTNO2WD6.js";
+import "./chunk-ZUTSMMAG.js";
+import "./chunk-X4DVXBFY.js";
+import "./chunk-3IGNIP6R.js";
+export {
+  exportWorkspaceBundle
+};
+//# sourceMappingURL=workspace-export-AJMGN3CQ.js.map

package/llms/fields.md

@@ -0,0 +1,104 @@
+# Column and input types
+
+> Read when declaring a table column (`f.*`) or a function/query input (`input.*`) — a type's options and accessor methods, and the `s.precondition` error/status contract that rides the same catalog.
+
+Author table columns + function/API inputs with the typed catalog: `f.<type>(opts?)`
+for columns, `input.<type>(opts?)` for inputs. Common opts: `required`, `nullable`,
+`default`, `description`.
+**`nullable` defaults PER TYPE, matching the engine's own column-creation API**: `true`
+for `f.vector`, `f.uuid`, every `f.geo.*` and every file type (`f.image`/`f.video`/
+`f.audio`/`f.attachment`), `false` for everything else (text, int, decimal, bool, email,
+enum, json, object, password, date, tableRef). Pass `nullable` explicitly to override —
+e.g. `f.geo.polygon({ nullable: false })`. This is why `f.vector(8)` deploys: the engine
+turns an empty default into SQL NULL only for a nullable column, so a non-null vector
+would reach PostgreSQL as `vector(8) not null default ''` and fail to create.
+**`f.geo.*` values are `{ type, data }`, not GeoJSON.** The same shape goes in and comes
+back: `{ type: "point", data: { lng, lat } }`, `{ type: "poly", data: [{ lng, lat }, …] }`
+— `type` is the engine's abbreviation, and a polygon ring is closed for you. Raw WKT text
+(`c.text("POINT(1 2)")`) is accepted on write too, but a read never returns one.
+`methods` is a bind-time validator/transform pipeline whose
+valid names depend on the field type (below) — pass bare names (`"trim"`), the
+colon-form with args (`"min:8"`), or `{ name, arg }` for anything not listed.
+`f.json({children})` declares the nested shape stored INSIDE a json column — an ARRAY of
+`{name, type, methods?, children?}`, order-significant, distinct from the `FieldMap` that
+`f.object` takes positionally. Omit it for an unstructured json column.
+`f.enum(values)`/`f.vector(size)`/`f.object(children)`/`f.tableRef(table)` take a
+positional payload before opts — and still accept the standard `FieldOptions` after it
+(`f.enum([])`/`input.enum([])` are accepted, because the engine stores an enum whose
+options were never filled in — that is a pulled-workspace shape, not one to author; it
+brands the column `never`, which `InferRow` surfaces at read time as `undefined` — so
+code written against `never` is dead in a way `undefined` is not.)
+(e.g. `f.tableRef(users, { required: true })` — only `min`/`max` are listed as tableRef
+methods below, but `required`/`nullable`/`description`/… apply like any field.)
+An **OPTIONAL foreign key wants a `0` sentinel, not `nullable: true`.** `f.tableRef` stores
+an `int`, and a null in it is unqueryable: `null` is never a legal `fieldValue`/`id`, so
+`s.db.get`/`edit`/`del` on that column answer HTTP 400 `Missing param: field_value` rather
+than matching nothing. Declare `f.tableRef(users, { required: true, default: 0 })` for
+"not set yet" — `s.db.get({ fieldName: "driver", fieldValue: c.int(0) })` matches no row and
+binds `null`, which is the answer the null was reaching for. `export()` warns on a literal
+`c.null()` in that slot.
+An `f.vector(size)` column is SEARCHED through `s.db.query`'s `eval` pipeline, not through
+any `SearchOp`: give the table `index: [{ type: "vector", fields: [{ name: "embedding", op:
+"vector_cosine_ops" }] }]`, then rank with a distance filter + a sort on its alias (see
+`s.db.query` → `eval`). Without that pairing the column stores and indexes but nothing
+queries it.
+`{ array: true }` makes any `f.*` scalar a **list column** — `f.text({ array: true })`
+surfaces as `string[]` in `InferRow<typeof table>` (the column analogue of `input.list`).
+A **column `default` must stay within the BMP** — a 4-byte character (codepoint > U+FFFF,
+e.g. an emoji) is mangled into invalid UTF-8 by the engine's default pipeline and is rejected
+at export rather than 500ing at deploy (Postgres `22021`); BMP defaults (accents, `€`, most
+CJK) are fine, or put the value on an `input.<type>({ default })`, applied at runtime bind.
+`input.*` mirrors `f.*` — every column type below is
+a legal input (scalars, files `input.image/video/audio/attachment`, `input.geo.*`,
+`input.vector(size)`, `input.tableRef(table)`, `input.object(children)`), plus
+`input.dbLink(table)` is the odd one: ONE entry that EXPANDS into one input per
+COLUMN of the linked table, so read them by column name (`inp("email")`), never by
+the entry's own name. `hidden: ["created_at"]` drops columns from that expansion.
+`input.list(element)` for arrays — wrap any element constructor, e.g.
+`input.list(input.text())` or `input.list(input.object({ id: f.int() }))`. Prefer the
+typed forms over `input.json()` when the shape is known.
+**Typed inputs validate/coerce on bind, before your stack runs** — so reach for the
+specific type instead of hand-rolling checks. `input.email({ required: true })` rejects a
+malformed address with a 400 (and trims; add `methods: ["lower"]` to downcase) — no
+`regex_matches` needed; `input.int`/`input.decimal`/`input.uuid`/`input.enum([...])`/`input.date`
+likewise reject or coerce bad input at the boundary. Drop to `input.text` + `s.precondition`
+only for rules no type expresses.
+⚠ `input.url` is NOT one of them — there is no engine `url` type, so it stores as `text`
+and validates NOTHING: a `javascript:`/`data:` URL type-checks, imports, and binds. It
+names intent and carries the `text` methods, nothing more. When the value gets navigated
+to, check the scheme in the stack. It is INPUT ONLY — there is no `f.url` column.
+⚠ `s.precondition`'s `error` must be a TAGGED value — `c.text("…")`, not a bare string.
+The engine falls back to the generic "Precondition failed." whenever it reads an empty or
+non-scalar message, and a bare string lands there, so the client never sees your text. The
+`error_type` → HTTP status mapping is correct either way; only the message is lost. The bare
+form stays accepted so a pulled workspace round-trips, not as a spelling to choose.
+`error_type` IS how a stack sets a response status: `badrequest`/`inputerror` → 400, `unauthorized` → 401, `accessdenied` → 403, `notfound` → 404, `toomanyrequests` → 429, `standard` → 500.
+Normalizing transforms run on bind too — put `trim`/`lower`/`upper` on the input's `methods`
+so `inp("name")` reads already-normalized; don't reroll `var $x = inp("name")|trim` in the stack.
+
+- `f.text` — methods: alphaOk, digitOk, lower, max, min, ok, pattern, startsWith, trim, upper
+- `f.int` — methods: max, min
+- `f.decimal` — methods: max, min
+- `f.bool`
+- `f.uuid`
+- `f.date`
+- `f.email` — methods: lower, trim
+- `f.password` — methods: max, min, minAlpha, minDigit, minLowerAlpha, minSymbol, minUpperAlpha, salt
+- `f.json`
+- `f.timestamp` (stored `epochms`)
+- `f.image` (stored `blob_img`)
+- `f.video` (stored `blob_video`)
+- `f.audio` (stored `blob_audio`)
+- `f.attachment` (stored `blob`)
+- `input.file` — INPUT ONLY (no `f.` form)
+- `input.dbLink` (stored `<tableGuid>_mvpschema`) — INPUT ONLY (no `f.` form)
+- `f.geo.point` (stored `geo_point`)
+- `f.geo.multipoint` (stored `geo_multipoint`)
+- `f.geo.linestring` (stored `geo_linestring`)
+- `f.geo.multilinestring` (stored `geo_multilinestring`)
+- `f.geo.polygon` (stored `geo_polygon`)
+- `f.geo.multipolygon` (stored `geo_multipolygon`)
+- `f.enum`
+- `f.vector` — methods: max, min
+- `f.object` (stored `obj`)
+- `f.tableRef` (stored `int`) — methods: max, min

package/llms/filters.md

@@ -0,0 +1,183 @@
+# Filter catalog
+
+> Read when piping a value through `fl.*` — the full catalog with each filter's argument types.
+
+Attach to a value with `withFilters(v, fl.name(...))` — the value `filters[]`
+pipeline. Filters are passed spread (canonical); the array form
+`withFilters(v, [fl.a(), fl.b()])` is also accepted. Every filter is typed:
+the ones below carry named args, and the rest take NO arguments — call them
+`fl.<name>()`, and passing an argument is a compile error.
+A typed filter's declared argument list is an EXACT count, not a floor: passing more
+than it lists THROWS, in the type and at runtime. The extra argument used to ride into
+the filter's arg list, where the engine either ignores it or fails opaquely on a live
+endpoint. `filter("name", …)` is the untyped escape for a filter the catalog
+under-declares. Seven declared filters are exceptions the engine really does take more from, so they
+stay variadic: `concat` (trailing separator), `index_by` (trailing list flag), `get` (trailing variable
+map), `array_merge` and `array_merge_recursive` (any number of arrays), `jwe_encode` and
+`jwe_decode`. To send more than a zero-argument filter's `()` accepts, use the same
+`filter("name", …)` escape. A filter with NO declared list takes nothing and is emitted
+`()` — except the variadic few listed under the catalog, which take arguments the
+catalog never declared and so are not arity-checked at all.
+A typed filter also accepts one object of NAMED arguments (`fl.add({ value: 1 })`); a key
+the filter does not declare throws rather than being dropped.
+A bare JS **scalar** — string, number or boolean — is accepted in ANY `fl.*` argument and
+wrapped as the constant you would have written by hand (`fl.get("a.b", 0)` encodes
+identically to `fl.get(c.text("a.b"), c.int(0))`). An object or array must still be built
+with `c.obj`/`c.array`. The arg types below name each argument's ENGINE type, not the JS
+type you may pass.
+Read-modify-write a column from its current value with the pipeline: to increment
+a counter you MUST `db.get` the row first, then pipe its bound value —
+`col("clicks")` does NOT resolve to the stored value inside a `db.edit` `row`
+(it is `null`, so `fl.add(1)` computes `null + 1` and the engine aborts):
+`s.db.get({ table, fieldValue, as: "current" })` then
+`s.db.edit({ table, fieldValue, row: { clicks: withFilters(ref("current.clicks"), fl.add(c.int(1))) } })`.
+⚠ This read-modify-write is NOT atomic — two concurrent writers can both read the
+same value and one increment is lost. There is no dedicated atomic-increment
+statement, and one CANNOT be synthesized in the SDK (it would compile to this same
+`get` + `edit` pair). For a **concurrency-safe** counter, do the arithmetic in the
+database with a single `s.db.direct_query` UPDATE (`SET clicks = clicks + 1 WHERE …`),
+which the DB applies atomically. Reserve the pipeline form for low-contention counters
+where a rare lost update is acceptable.
+⚠ `direct_query` needs the table's PHYSICAL Postgres name, which the typed surface
+does NOT expose: the engine derives 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.
+
+- `fl.add(value: decimal): decimal`
+- `fl.append(value: <T>, path: text): <T>[]`
+- `fl.array_diff(value: <T>[]): <T>[]`
+- `fl.array_diff_assoc(value: <T>[]): <T>[]`
+- `fl.array_fill(start: int, count: int): any[]`
+- `fl.array_fill_keys(keys: any[]): any[]`
+- `fl.array_intersect(value: <T>[]): <T>[]`
+- `fl.array_intersect_assoc(value: <T>[]): <T>[]`
+- `fl.array_merge(value: <T>[]): <T>[]`
+- `fl.array_merge_recursive(value: <T>[]): <T>[]`
+- `fl.array_push(value: <T>): <T>[]`
+- `fl.array_remove(value: <T>, path: text, strict?: bool): <T>[]`
+- `fl.array_slice(offset: int, length?: int): <T>[]`
+- `fl.array_unshift(value: <T>): <T>[]`
+- `fl.base_convert(from_base: any, to_base: any): text`
+- `fl.bitwise_and(value: int): int`
+- `fl.bitwise_or(value: int): int`
+- `fl.bitwise_xor(value: int): int`
+- `fl.concat(value: any): text`
+- `fl.contains(search: text): bool` — piped value is the subject text; the arg is the substring searched for
+- `fl.convert_encoding(to: text, from: text): text`
+- `fl.create_object(values: <T>[]): any`
+- `fl.crypto_jwe_decode(check_claims: json, key: json, key_algorithm: enum, content_algorithm: enum, timeDrift?: int): json`
+- `fl.crypto_jwe_encode(headers: json, key: json, key_algorithm: enum, content_algorithm: enum, ttl?: int): text`
+- `fl.crypto_jws_decode(check_claims: json, key: json, algorithm: enum, timeDrift?: int): json`
+- `fl.crypto_jws_encode(headers: json, key: json, algorithm: enum, ttl?: int): text`
+- `fl.csv_create(rows: text[], separator: text, enclosure: text, escape: text): text` — the header-writing counterpart to `csv_encode`: the PIPED value is the list of column names (written as the header line) and `rows` carries the data rows
+- `fl.csv_decode(separator: text, enclosure: text, escape: text): any`
+- `fl.csv_encode(separator: text, enclosure: text, escape: text): text` — writes NO header — values only, each row in THAT row's key order with no normalization across rows, so rows whose keys differ in order or count silently misalign columns. Nested cells are JSON-encoded and `false` writes empty. A piped array of SCALARS is treated as one row. Use `csv_create` for a header
+- `fl.csv_parse(separator: text, enclosure: text, escape: text): any`
+- `fl.decrypt(algorithm: enum, key: text, iv: text): text`
+- `fl.detect_encoding(encodings?: text): text`
+- `fl.div(value: decimal): decimal`
+- `fl.encrypt(algorithm: enum, key: text, iv: text): text`
+- `fl.ends_with(search: text): bool` — piped value is the subject text; the arg is the substring searched for
+- `fl.epochms_add_ms(milliseconds: int): epochms`
+- `fl.epochms_add_secs(seconds: int): epochms`
+- `fl.epochms_date(format: text, timezone?: text): text`
+- `fl.epochms_from_format(format: text, timezone?: text): text`
+- `fl.epochms_transform(format: text, timezone?: text): text` — applies a relative shift (e.g. "+1 day") to the timestamp
+- `fl.eq(value: <T>): bool`
+- `fl.every(code: text, timeout?: int): any[]` — `code` is a JS body run per element (true for all?), over `$this`/`$index`/`$parent`
+- `fl.filter(code: text, timeout?: int): any[]` — `code` is a JS body run per element (keep it? true/false), over `$this`/`$index`/`$parent`
+- `fl.filter_empty(path?: text): <T>[]` — keeps entries that are not empty ("", null, 0, "0", false, [], {})
+- `fl.filter_empty_array(path?: text): <T>[]`
+- `fl.filter_empty_object(path?: text): <T>[]`
+- `fl.filter_empty_text(path?: text): <T>[]`
+- `fl.filter_false(path?: text): <T>[]`
+- `fl.filter_null(path?: text): <T>[]`
+- `fl.filter_zero(path?: text): <T>[]`
+- `fl.find(code: text, timeout?: int): any[]` — `code` is a JS body run per element; returns the first element it accepts
+- `fl.findIndex(code: text, timeout?: int): any[]` — `code` is a JS body run per element; returns the first matching index
+- `fl.first_notempty(value: any): any` — first value that is not empty ("", null, 0, "0", false, [], {})
+- `fl.first_notnull(value: any): any`
+- `fl.fsort(path?: text, type?: "text"|"itext"|"natural"|"inatural"|"number", asc?: bool): <T>[]` — `type` is the comparator, and ONLY "number" compares numerically — "text"/"itext" are strcmp/strcasecmp, "natural"/"inatural" are the human-readable "a2 < a10" orderings. Default "itext". Anything else silently sorts as text, so a numeric sort MUST spell "number"; the path arg drills into each element
+- `fl.get(path: text, default?: json): any`
+- `fl.gt(value: <T>): bool`
+- `fl.gte(value: <T>): bool`
+- `fl.has(path: text): bool`
+- `fl.hmac_md5(key: text, raw?: bool): text`
+- `fl.hmac_sha1(key: text, raw?: bool): text`
+- `fl.hmac_sha256(key: text, raw?: bool): text`
+- `fl.hmac_sha384(key: text, raw?: bool): text`
+- `fl.hmac_sha512(key: text, raw?: bool): text`
+- `fl.icontains(search: text): bool` — case-insensitive; piped value is the subject, the arg is the substring
+- `fl.iends_with(search: text): bool` — case-insensitive; piped value is the subject, the arg is the substring
+- `fl.in(search: <T>): bool`
+- `fl.index_by(path: text): { [key: string]: <T>[] }` — a GROUP-BY: every value is an ARRAY of the items sharing that key, even when only one does, so a lookup reads `idx[key][0]`. Items whose path is missing or non-scalar are dropped
+- `fl.istarts_with(search: text): bool` — case-insensitive; piped value is the subject, the arg is the substring
+- `fl.join(separator: text): text`
+- `fl.jwe_decode(arg1: any)`
+- `fl.jwe_encode(arg1: any)`
+- `fl.lambda(code: text, timeout?: int): any` — runs a JS body once over the piped value, which it binds as `$this` (NOT `$parent`)
+- `fl.log(base: <T>): decimal`
+- `fl.lt(value: <T>): bool`
+- `fl.lte(value: <T>): bool`
+- `fl.ltrim(mask?: text): text`
+- `fl.map(code: text, timeout?: int): any[]` — `code` is a JS body run per element, over `$this`/`$index`/`$parent` — build it with `lam.fn`
+- `fl.md5(raw?: bool): text`
+- `fl.mod(value: int): int`
+- `fl.mul(value: decimal): decimal`
+- `fl.ne(value: <T>): bool`
+- `fl.num_max(value: any): decimal`
+- `fl.num_min(value: any): decimal`
+- `fl.number_format(decimals: int, decimal_separator: text, thousands_separator: text): string`
+- `fl.pick(keys: text): <T>`
+- `fl.pow(exp: <T>): decimal`
+- `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_quote(delimiter?: text): text`
+- `fl.regex_replace(replacement: text, subject: text): text`
+- `fl.regex_test(subject: text): bool`
+- `fl.round(precision?: int): decimal`
+- `fl.rtrim(mask?: text): text`
+- `fl.secureid_decode(salt: text): int`
+- `fl.secureid_encode(salt: text): text`
+- `fl.set(path: text, value: any): any`
+- `fl.set_conditional(path: text, value: any, conditional: any): any`
+- `fl.set_ifnotempty(path: text, value: any): any`
+- `fl.set_ifnotnull(path: text, value: any): any`
+- `fl.sha1(raw?: bool): text`
+- `fl.sha256(raw?: bool): text`
+- `fl.sha384(raw?: bool): text`
+- `fl.sha512(raw?: bool): text`
+- `fl.some(code: text, timeout?: int): any[]` — `code` is a JS body run per element (true for any?), over `$this`/`$index`/`$parent`
+- `fl.split(separator: text): text[]`
+- `fl.starts_with(search: text): bool` — piped value is the subject text; the arg is the substring searched for
+- `fl.string_replace(search: text, replacement: text): text`
+- `fl.strip_tags(exclude?: text): text`
+- `fl.stripos(search: text): int`
+- `fl.strpos(search: text): int`
+- `fl.sub(value: decimal): decimal`
+- `fl.substr(start: int, length: int): text`
+- `fl.to_epoch_day(timezone?: text): int`
+- `fl.to_epoch_hour(timezone?: text): int`
+- `fl.to_epoch_minute(timezone?: text): int`
+- `fl.to_epoch_ms(timezone?: text): int`
+- `fl.to_epoch_sec(timezone?: text): int`
+- `fl.to_epochms(timezone?: text): epochms`
+- `fl.transform(expression: text): any` — `expression` is Xano Expression Engine source, NOT a JS body — no `return`, and the piped value is `$0` (or `$$`), NOT `$this` (which is null here). `$var`/`$input`/`$env`/`$auth` resolve and filters pipe inside it: `$0 * 2`, `$0|sort|join:","`. Parenthesize a pipe inside an object literal — `{ s: ($0|sort|join:",") }` — or its comma is read as the key separator and later keys vanish silently. For JavaScript use `lambda`
+- `fl.trim(mask?: text): text`
+- `fl.unique(path?: text): <T>[]`
+- `fl.unpick(keys: text): <T>` — returns the object without the named keys (inverse of a pick)
+- `fl.unset(path: text): any`
+- `fl.url_addarg(key: text, value: text, encoding_rfc3986?: bool): text`
+- `fl.url_delarg(key: text): text`
+- `fl.url_getarg(key: text, default?: text): text`
+- `fl.url_hasarg(key: text): text`
+
+Zero-argument filters — call as `fl.<name>()`; an argument is a compile error: abs, acos, acosh, addslashes, array_entries, array_keys, array_pop, array_shift, array_shuffle, array_values, asin, asinh, atan, atanh, avg, base64_decode, base64_decode_urlsafe, base64_encode, base64_encode_urlsafe, bin2hex, bindec, bitwise_not, capitalize, ceil, cos, count, create_object_from_entries, decbin, dechex, decoct, deg2rad, empty, escape, even, exp, first, flatten, floor, from_utf8, hex2bin, hexdec, is_array, is_bool, is_decimal, is_int, is_object, is_text, is_uuid, json_decode, json_encode, last, list_encodings, ln, log10, lower, max, min, not, null, octdec, odd, product, querystring_parse, rad2deg, reverse, safe_array, sin, sql_alias, sql_esc, sqrt, strip_accents, strlen, sum, tan, text_escape, text_unescape, to_bool, to_decimal, to_expr, to_int, to_text, to_utf8, uid, upper, url_decode, url_decode_rfc3986, url_encode, url_encode_rfc3986, url_parse, uuid4, xml_decode, yaml_decode, yaml_encode.
+
+Variadic filters — they take arguments, but no declared list, so the count is not checked: sort, sprintf.

package/llms/kinds-agent-mcp.md

@@ -0,0 +1,11 @@
+# Agent and MCP def shapes
+
+> Read when the workspace defines an `agent()` or an `mcpServer()`.
+
+- `mcpServer({ name, guid?, description?, instructions?, docs?, enabled?, canonical?, spec?, tags?, history?, tools?, llm?, output? })` — an MCP toolset. `llm?`/`output?` are the same blocks `agent()` takes and are usually absent: an MCP server and an agent are ONE stored object distinguished by `type`, so a server that carries LLM settings can say so. Returns a handle with `getPath()`/`getUrl(baseUrl)` for the Streamable-HTTP endpoint — `getUrl` is NOT idempotent, a `baseUrl` already carrying an `/x2/mcp/<…>/stream` path (an earlier result) THROWS, so resolve ONCE from the instance base URL. Fires on an ephemeral; does NOT fire in the sandbox (see Gotchas).
+  - `tools?`: a `ToolsetToolEntry[]`. Pass the `tool()` HANDLES directly (`tools: [saveNote]`), like every other collection in the SDK; use the `{ tool, enabled?, auth? }` wrapper only when a tool needs `enabled: false` or per-tool `auth`. `auth` names an auth **table** (a `table({ auth: true })` handle or its name) — Xano's ONLY MCP auth surface (per-tool; there is no server-level gate). An entry that names no tool (no handle, no `id`) THROWS at export rather than emitting the `id: 0` null reference it used to; a deliberate raw `id: 0` warns and is carried through, so a pulled workspace still round-trips.
+- `agent({ name, guid?, description?, docs?, enabled?, canonical?, tags?, history?, llm, tools?, output? })` — an LLM orchestrator. No top-level `instructions`/`prompt`/`spec` — the prompt lives under `llm`. Invoke from a stack with `s.ai.agent.run({ agent, args })`.
+  - `llm` (REQUIRED): typed provider settings, a discriminated union on `type` (`"xano-free" | "anthropic" | "openai" | "google-genai"`). Shared fields: `systemPrompt?`, `maxSteps?` (default `5`), and `prompt?` XOR `messages?` (genuinely exclusive: both is a type error and throws — the engine stores ONE `prompt_type`, so one would be dropped); plus provider fields (`apiKey?`, `model?`, `temperature?`, `reasoningEffort?`, …). String fields accept Twig placeholders — `{{ $args.x }}` for run inputs (the `args` of `s.ai.agent.run`), `{{ $env.NAME }}` for env vars.
+  - `tools?`: same `ToolsetToolEntry[]` as `mcpServer` — bare `tool()` handles, or a `{ tool, enabled?, auth? }` wrapper when one needs `enabled`/`auth`.
+  - `output?`: `{ schema: Record<string, input.*>, enabled? }` — structured-output schema. `schema` is a named-field record authored with the `input.*` catalog, exactly like a `defineFunction`/`query` `input:` map (the stored `structuredOutputsSchema` is the same wire shape as function inputs). e.g. `output: { schema: { priority: input.enum(["low","high"]), summary: input.text() } }`. When you pass the agent *handle* to `s.ai.agent.run({ agent })`, `.result` is typed straight from this schema — no `resultShape` witness needed (the shape is declared once). `resultShape` remains only to override that, or to type an agent referenced by bare name.
+  - **Run + read recipe (`s.ai.agent.run`):** bind the run to a var (`s.ai.agent.run({ agent, args, as: "run" })`) — it produces a rich envelope, and the completion is at **`.result`**. Read one structured field with a dotted ref (`response: ref("run.result.priority")`) or the whole completion (`ref("run.result")`, typed from `output.schema`); persist it in a later step the same way (`s.set_var({ name, value: ref("run.result.summary") })`). `args` is a plain object of run inputs (`{ topic: inp("topic") }` — raw literals are fine, e.g. `{ max_steps: 3 }`) surfaced to the agent as `{{ $args.topic }}`. Tool-call / per-step data (when tools ran) rides `.toolCalls` / `.steps` on the same envelope — both optional, absent or empty when no tools executed.

package/llms/kinds-core.md

@@ -0,0 +1,68 @@
+# Core def shapes
+
+> 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.
+
+The def-object passed to each factory. `?` = optional. `input` is keyed by
+input name (`input.<type>(opts?)`); `stack` is `Statement[]` (`s.*`); `response`
+is a `ResponseDef` (see **Responses** below). Object identity is `guid?` —
+omit it and it derives from `name` (set it to survive a rename).
+
+- `defineFunction({ name, guid?, description?, docs?, workspace?, input?, stack?, response?, tests? })`
+- `query({ name, verb, apiGroup?, guid?, auth?, input?, stack?, response?, responseType?, apiEnabled?, disabled?, cache?, description?, docs?, tests?, example? })`
+  - `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.
+  - **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? } }`.
+    - `mode?`: `"default"` (the default) | `"custom"` | `"disabled"`, lowercase — a fourth value THROWS at export (`apiGroup()` itself does not check), because Xano neither rejects nor blanks it: it DROPS THE WHOLE API GROUP on import, so the deploy succeeds and every query in the group 404s. ⚠ Every OTHER field applies only under `"custom"`: `"default"` serves a FIXED permissive policy (any origin, `allow-headers: *`, `allow-credentials: true`, `max-age: 86400`) and ignores the block, so setting `maxAge`/`allowCredentials`/`allowHeaders` alone changes nothing. `"disabled"` sends no CORS headers at all, so every browser call fails.
+    - ⚠ Under `"custom"`, `allowOrigins` is matched as EXACT strings (scheme+host+port, no wildcard or subdomain expansion) and `"*"` is compared as a literal origin — it matches NOTHING. An unmatched origin gets no `access-control-*` headers at all, so the call fails in the browser on a missing `access-control-allow-origin` while export, deploy and the preflight all look fine. Name each origin, or use `mode: "default"` for any-origin. `allowMethods` gates the REAL response too: a verb left off gets no CORS headers back even though its preflight passes. Export warns on an empty origin list, a `"*"` entry, and a policy with no method enabled.
+- `defineFunction`/`query`/`apiGroup` above cover the queries+tables core; the four below are the "reach past that" primitives (tasks, workflow tests, middleware, tools). Agents and MCP servers are the same family and live in `llms/kinds-agent-mcp.md`. Same envelope conventions (`guid?`, `description?`, `docs?`, `tags?`, `history?`) unless noted.
+- `task({ name, guid?, description?, docs?, datasource?, active?, tags?, history?, schedule?, stack?, middleware? })` — a scheduled background job (function-like `stack`, no `input`/`response`).
+  - `schedule?`: a `ScheduleDef[]` (NOT a single object) — `{ startsOn, freq?, repeatEnabled?, endsOn?, endsEnabled? }`. `startsOn`/`endsOn` are **timestamp strings** validated at encode time — `"2026-01-01T00:00:00Z"`, or the space-separated `"2026-01-01 00:00:00+0000"` a pulled workspace carries — never epoch numbers, and never zoneless; `freq` is the repeat interval **in seconds** (default `86400` = daily); `endsOn` present ⇒ the schedule has an end. `endsEnabled?` defaults to that and is recovery-only — state it to reproduce a stored schedule that remembers an end date with the gate OFF. Fires on an ephemeral; does NOT fire in the sandbox (see Gotchas).
+- `workflowTest({ name, guid?, description?, docs?, datasource?, active?, tags?, stack? })` — an end-to-end test. NO `input`/`response`: `.call` something with an `as`, then assert on that var — `s.function.call({ fn, input, as: "r" })`, `s.expect.to_equal({ expr: ref("r"), value: c.int(42) })`. `s.expect.*` belongs here — it is not inert elsewhere (a failure 500s the request), so treat one in a query/function/task as a mistake to remove. `active?` defaults `true`; chain tests with `s.workflow_test.call({ workflowTest: <def handle> })`.
+  - `datasource?`: **the trap.** Default `""` is an EMPTY datasource (recommended), not "no datasource". Any non-empty name makes the engine CLONE it before EVERY run — against production-sized data, slow enough to fail the run. `"live"` warns at compile time; other names don't.
+- `middleware({ name, guid?, description?, docs?, resultStrategy?, exceptionPolicy?, tags?, history?, input?, stack?, response?, responseShape?, tests? })` — a pre/post interceptor (function-like `stack`); attach it via a host's `middleware: { pre, post }`. ⚠ `input` ENCODES but an ATTACHED middleware never has it bound — the host request binds its own inputs, so `inp()` inside pre/post fails at runtime with `Unable to locate input` and a declared default does not stand in (`export()` warns). Read the request body with `s.util.get_all_input` instead; it yields a `{ type, vars }` envelope. `s.middleware.call` is the one path that DOES bind the declared map.
+  - `resultStrategy?`: `"merge" | "replace"` (default `merge`) — how the middleware `response` folds into the host's.
+  - `exceptionPolicy?`: `"silent" | "rethrow" | "critical"` (default `"rethrow"` — a throw ABORTS the request and surfaces the authored error/status, which is what a guard wants). `"silent"` swallows the throw and lets the request through, so a guard set to it is NOT enforced — use it only for advisory middleware. `"critical"` is `"rethrow"` plus skipping the `post` chain.
+- `tool({ name, guid?, description?, instructions?, docs?, enabled?, tags?, history?, input?, stack?, response?, responseShape?, middleware? })` — a function-like operation (`input`/`stack`/`response`) that a toolset (MCP server or agent) exposes. Register it, then reference it from a toolset's `tools`.
+### Responses
+
+The `response?` field (on functions, queries, tools, middleware, and
+response-bearing triggers) maps to the stored `result[]`:
+
+- `ResponseDef = Value | Record<string, Value>`.
+- A single `Value` → one unnamed result item: `response: ref("rows")`.
+- A record → one named item per key: `response: { user: ref("u"), token: ref("t") }`.
+- Omitted → empty `result[]` (no response body).
+
+### Expressions (`expr`)
+
+`expr(left, op, right)` builds the comparison used by every condition/`where`
+surface — `s.conditional`/`s.while` `when` (incl. each `elif` branch), and
+`db.query` `where`/`additionalWhere` (and the search triggers) — one shared tree.
+
+- `op`: `=`, `!=`, `>`, `<`, `>=`, `<=` (JS aliases `==` `===` `!==` are accepted and normalized).
+- `left`/`right` are `Value`s — `col("x")` (a table column), `ref`, `inp`, `auth(...)`, or `c.*`.
+- For the full operator set (`in`/`like`/`ilike`/`between`/`contains`/`overlaps`/`@>`/`~`/`search`/…)
+  use `cmp(left, op, right, { ignoreEmpty? })`; compose nested boolean logic with `and(...)`/`or(...)`.
+- ⚠ The wider `cmp` operators are DATABASE-only (`where`, table view filter, db trigger
+  `search`). A RUNTIME condition — `s.conditional`/`elif`, `s.while`, `s.precondition`,
+  `array.*` `if` — takes the `expr` set only; the rest are refused at build time because
+  deployed they fail the request with `Invalid op: <op>` on that branch, usually a guard.
+  Spell membership out: `or(expr(x, "=", a), expr(x, "=", b))`.
+- A condition/`where` accepts a single `expr(...)`/`cmp(...)`, an `and()`/`or()` group, an array of
+  those (ANDed), or (for `where`) a raw `Value`. `s.conditional`/`s.while`/`s.switch`, `db.query`,
+  `precondition`, and the `array.*` predicates all take the same TREE shape (operators per above).
+- ⚠ `mixed(a, { or: b }, { and: c })` reproduces a container whose terms do NOT all join the
+  same way — the editor allows it, so pulled workspaces contain it. **Do not author it.** The
+  stored form does not record the grouping, and the two places it can appear disagree: a
+  branch (`s.conditional`/`s.while`/`precondition`) folds terms strictly left to right, so
+  `a OR b AND c` is `(a OR b) AND c`, while a `db.query` filter applies the engine's
+  AND-before-OR precedence and selects `a OR (b AND c)`. Write `and(or(a, b), c)` or
+  `or(a, and(b, c))` — each says one reading in every context. Pulls report these as
+  `ambiguous-condition`.
+- A **filtered** operand (`withFilters(...)`) works inline in any condition/`where` (conditional,
+  while, `db.query`/addon, …) — e.g. `cmp(withFilters(col("title"), fl.trim()), "=", inp("q"))`.
+- e.g. `db.query({ table: posts, where: expr(col("author"), "=", auth("id")), as: "rows" })`.