@xanots/sdk 0.0.1

package/dist/response-CVAE2kMj.d.ts

@@ -0,0 +1,1915 @@
+/**
+ * The shared tagged-value primitive (KTD-2). Every place a function references
+ * data — input bindings, statement context, response — uses this `{value, tag,
+ * filters}` shape. Built and tested once here, reused everywhere.
+ */
+
+/** A XanoTS authored value is just the stored tagged-value shape. */
+type Value = TaggedValue;
+/**
+ * A {@link Value} that also carries, **at the type level only**, the name of the
+ * stack variable it references (`ref("user")` → `RefValue<"user">`). The `__ref`
+ * carrier is phantom — never present at runtime — and required (not optional) so
+ * `InferResponse`'s trace (U5) matches only real refs, never a plain `Value`.
+ * Because it is a subtype of `Value`, every existing `ref(...)` use — filter
+ * args, `db.query` `where`, response fields — keeps type-checking unchanged.
+ */
+type RefValue<Name extends string = string> = Value & {
+    readonly __ref: Name;
+};
+/**
+ * A {@link Value} that has had a filter chain attached (`withFilters(...)`).
+ * The `__filtered` carrier is phantom (type-only). A filter can reshape the
+ * value arbitrarily at runtime — turn an object into a scalar, add or drop keys
+ * — with no static signal, so `InferResponse` treats a filtered response value
+ * as `unknown` (the honest floor, matching how the Xano engine degrades a
+ * filtered result to `json`). Overriding via `responseShape` remains available.
+ */
+type FilteredValue<Base = unknown, Chain extends readonly unknown[] = readonly unknown[]> = Value & {
+    readonly __filtered: true;
+    /** Phantom: the value the chain was applied to, so its type can be folded. */
+    readonly __base?: Base;
+    /** Phantom: the flattened filter chain, in application order. */
+    readonly __chain?: Chain;
+};
+/**
+ * A {@link Value} built by {@link c.regex} — a PCRE pattern the engine can
+ * actually run, delimiter-wrapped (`/…/flags`).
+ *
+ * The `__regex` carrier is phantom (type-only). It exists so a helper that takes
+ * a pattern can SAY so in its signature (`function match(p: RegexValue)`) and so
+ * an editor's hover distinguishes a pattern from the text beside it.
+ *
+ * It is deliberately NOT used to restrict `s.expect.to_match` or the `fl.regex_*`
+ * pattern slot, which is what issue #213 proposed. A nominal restriction there
+ * would have to reject `Value`, and `inp()`, `env()`, `auth()` and `sys.*` all
+ * return exactly `Value` — the same type `c.text` does — so it would reject every
+ * DYNAMIC pattern along with the broken constant ones. The enforcement is instead
+ * a build-time refusal that inspects the value it was actually given
+ * ({@link assertRegexPattern}), which fires on the bare constant and stays silent
+ * on a reference it cannot see through.
+ */
+type RegexValue = Value & {
+    readonly __regex: true;
+};
+/** Flatten one level of `withFilters`'s spread-or-array argument list. */
+type FlattenFilters<Fs extends readonly unknown[]> = Fs extends readonly [
+    infer Head,
+    ...infer Tail
+] ? Head extends readonly unknown[] ? [...Head, ...FlattenFilters<Tail>] : [Head, ...FlattenFilters<Tail>] : [];
+/**
+ * A {@link Value} produced by {@link col} (or a filter chain built from one). The
+ * `__col` carrier is phantom (type-only). It exists so a `col()` reference can be
+ * *statically rejected* where it would silently fail at runtime: inside a
+ * `db.edit`/`db.add` `row`, `{tag:"col"}` does not resolve to the row's stored
+ * value — it evaluates to `null`, so a following `fl.add(1)` computes `null + 1`
+ * and the engine aborts ("Numbers are required for mathematical operations",
+ * issue #32). `col()` is only meaningful in a `db.query` `where`/view expression.
+ */
+type ColValue = Value & {
+    readonly __col: true;
+};
+/**
+ * The error branch surfaced when a tagged {@link Value} is nested inside a
+ * `c.obj`/`c.array` literal (issue #42). The long message is the *property key*
+ * so TypeScript prints it verbatim in the "property … is missing" diagnostic; a
+ * `Value` has no such key, so intersecting it here makes the offending position
+ * fail to type-check. The runtime guard ({@link assertPlainJson}) carries the
+ * same guidance for JS/`any`-typed callers the type can't reach.
+ */
+type TaggedValueNotAllowed = {
+    "❌ c.obj/c.array take plain JSON only — a tagged value (inp/ref/auth/col/c.*) can't be nested. For a computed object response use a record of values: `response: { key: value }` (not c.obj). See issue #42.": never;
+};
+/**
+ * Recursively reject any nested {@link Value} in a plain-JSON literal `T`. A
+ * member assignable to `Value` maps to {@link TaggedValueNotAllowed}; plain JSON
+ * (primitives, arrays, objects) passes through unchanged. Used intersected with
+ * a naked `T` (`o: T & RejectValues<T>`) so `T` stays inferrable while the
+ * rejection rides along. Structural `extends Value` detection — not a `JsonLiteral`
+ * constraint — so it survives a future `TaggedValue` interface→alias refactor.
+ */
+type RejectValues<T> = T extends Value ? TaggedValueNotAllowed : T extends readonly (infer E)[] ? readonly RejectValues<E>[] : T extends object ? {
+    [K in keyof T]: RejectValues<T[K]>;
+} : T;
+/**
+ * Tags {@link c.blank} can spell — the constant tags with no exact blank form of
+ * their own.
+ *
+ * Derived by exclusion from {@link TAGS} rather than listed, so a constant tag
+ * added to the catalog is blank-spellable without a second edit here. The two
+ * carve-outs are the tags that already round-trip a blank exactly: `const` via
+ * `c.text("")`, and `const:obj` via `c.obj(null)`.
+ *
+ * Reference tags are excluded by construction: a blank `var`/`input`/`col` is an
+ * unbound reference, not an empty value, and the two want different fixes.
+ */
+type BlankTag = Exclude<Extract<Tag, `const${string}`>, "const" | "const:obj">;
+/**
+ * Tags {@link c.null} can spell — the two the engine stores a `"null"` value
+ * under. `const:null` is the plain one; `const:obj` is the object-typed null a
+ * `db.*` statement's `@meta` slot carries (issue #151).
+ *
+ * Listed rather than derived: a `"null"` value under any OTHER constant tag is
+ * unobserved, and inventing spellings for it would offer an authoring form for
+ * bytes no engine writes.
+ */
+type NullTag = "const:null" | "const:obj";
+/** Constant constructors. Values always serialize as strings (per fixture). */
+declare const c: {
+    /**
+     * Plain string constant → `tag:"const"`.
+     *
+     * `null` is accepted alongside a string because the engine stores both: 47
+     * values in the sweep are a bare `const` holding `null` rather than `""`,
+     * mostly ignored statement-input entries the engine never reads. They are
+     * distinct bytes — `normalize` keeps them apart, unlike the `const:obj` blanks
+     * it does canonicalize — so a pull has to be able to spell the null form, and
+     * `c.text(null)` did not type-check.
+     *
+     * Write `c.text("")` for an empty string. The null form is here so a pulled
+     * workspace round-trips, not to be authored.
+     */
+    text(s: string | null): Value;
+    /**
+     * Integer constant → `tag:"const:int"`, value stringified (e.g. `"123"`).
+     *
+     * Pass a **string** or `bigint` for an integer outside JavaScript's safe
+     * range. The engine stores integers as strings and has no such limit, so
+     * `c.int("18446744073709551615")` — 2^64 − 1, what a bitwise NOT returns —
+     * is exact, where the number literal for it silently rounds to `…616`.
+     *
+     * A `number` that is not an integer, or is past `Number.MAX_SAFE_INTEGER`,
+     * **throws**: by the time such a literal reaches here its precision is already
+     * gone, so encoding it would write a value the caller did not type. The throw
+     * names the string form. (issue #153)
+     */
+    int(n: number | bigint | string): Value;
+    /**
+     * Decimal constant → `tag:"const:decimal"`.
+     *
+     * Pass a **string** to preserve a stored spelling a number literal cannot
+     * reproduce — `c.decimal("10.00")` keeps its trailing zeros, where
+     * `c.decimal(10)` writes `"10"`. The engine stores decimals as strings either
+     * way, so this is exactness rather than a workaround; prefer the number form
+     * whenever it reproduces the value you want.
+     */
+    decimal(n: number | string): Value;
+    /**
+     * The editor's **unconfigured value box** — a value cell added and never
+     * filled in, stored as `{value: "", tag}`.
+     *
+     * This is not a zero, an empty string, or an empty collection. The engine
+     * reads `""` and `"0"` differently, so `c.blank("const:int")` and `c.int(0)`
+     * are different stored values and the SDK will not canonicalize one into the
+     * other. It exists because 13 real values in the survey corpus are in this
+     * state and had no authoring form, so a pull emitted them as annotated
+     * literals with a warning attached — describing a workspace that was fine.
+     *
+     * Constant tags only. A blank `var` or `input` is an unbound REFERENCE, which
+     * is a different defect with a different fix, and is deliberately not
+     * spellable here. `const` and `const:obj` are excluded too: they already have
+     * exact blank forms in `c.text("")` and `c.obj(null)`, and a second spelling
+     * for the same bytes is how two constructors start disagreeing.
+     */
+    blank(tag: BlankTag): Value;
+    /** Boolean constant → `"true"`/`"false"` with `tag:"const:bool"`. */
+    bool(b: boolean): Value;
+    /**
+     * Null constant → value `"null"` (per engine fixture).
+     *
+     * Bare `c.null()` is the plain `const:null`. Pass a tag for the **object-typed
+     * null** the engine writes into a `db.*` statement's `@meta` slot —
+     * `c.null("const:obj")` → `{tag:"const:obj", value:"null"}`, 16 of them across
+     * eight ordinary queries in the survey corpus, which had no spelling and came
+     * back as `rawValue` (issue #151).
+     *
+     * ⚠ Not the same bytes as `c.obj(null)`, which is the BLANK object
+     * (`value: ""`). Both evaluate to null — the engine JSON-decodes the stored
+     * string and `""` and `"null"` both decode to it — but they are two stored
+     * spellings, and the SDK writes back the one it was given rather than
+     * re-pointing a pulled workspace at the other.
+     */
+    null(tag?: NullTag): Value;
+    /**
+     * Build a **regex pattern value** for the pattern-piped regex filters
+     * (`fl.regex_test`/`regex_match`/`regex_replace`/…). Xano runs PHP `preg_*`, so
+     * the pattern MUST be delimiter-wrapped — a bare `c.text("^…$")` is an invalid
+     * PCRE and the filter then matches *nothing* for every input, so a precondition
+     * built on it silently rejects all values (issue #128). This wraps the raw
+     * pattern in `/…/`, escapes any interior `/`, and appends `flags`, so the result
+     * is always valid; `withFilters` rejects a bare `c.text` pattern and points here.
+     *
+     * Pass a JS `RegExp` (source + flags used directly, minus JS-only `g`/`y`/`d`):
+     * `c.regex(/^[^@\s]+@[^@\s]+\.[^@\s]+$/i)`, or a raw body + optional PCRE flags:
+     * `c.regex("^[^@\\s]+@[^@\\s]+\\.[^@\\s]+$", "i")`. The pattern is the piped
+     * value; the filter's `subject` arg is the text tested against it.
+     */
+    regex(pattern: string | RegExp, flags?: string): RegexValue;
+    /**
+     * Current time as an **epoch-milliseconds** value — the engine's native
+     * `const:epochms` constant. Xano has no `$now` *setting*, so this lives on
+     * `c.*` (a current-time literal) rather than {@link sys} (which emits
+     * `setting("$…")` and would reference a dead `$now` var).
+     *
+     * Emits `{tag:"const:epochms", value:"now"}` — an UNFILTERED value, valid
+     * inline as a `where`/`cmp` operand. It previously emitted the equivalent
+     * `text("now") |to_epoch_ms` chain; both evaluate to the same epoch-ms number
+     * on a live engine, and both persist verbatim, but the native tag is what the
+     * editor writes and needs no filter to get there. Chain math onto it as usual:
+     * `withFilters(c.now(), fl.epochms_add_ms(c.int(-maxAgeMs)))`. (issues #120,
+     * #145)
+     */
+    now(): Value;
+    /**
+     * Object constant → JSON-string value with `tag:"const:obj"`. Takes **plain
+     * JSON literals only**: nesting a tagged value (`inp`/`ref`/`auth`/`c.*`) is a
+     * compile error and throws at runtime — it would serialize as internal
+     * representation the engine can't decode. For a computed/multi-key object
+     * response use a record of values (`response: { key: value }`), not `c.obj`.
+     * See issue #42.
+     *
+     * Called with no argument it is the **empty object**, `{}` — the same default
+     * the editor gives a new object variable, and the only empty form current
+     * editors write.
+     *
+     * Called with an explicit `null` it is the **blank** form (stored `value: ""`),
+     * which the engine evaluates to `null` rather than `{}` — it JSON-decodes the
+     * stored string, and decoding `""` yields null. That is a real difference in
+     * what the statement sees, so the two are separate spellings rather than one
+     * "empty object": `c.obj()` is `{}`, `c.obj(null)` is null.
+     *
+     * ⚠ **Prefer `c.obj()`.** The blank form is legacy — no current editor path
+     * writes it — and it exists here so a pulled workspace round-trips to the
+     * same bytes instead of being quietly re-pointed at `{}`.
+     *
+     * A **populated** object is stored the way the editor stores one: an empty
+     * `{}` base carrying one `set` filter per key (issue #248). It is NOT a
+     * populated JSON string — that form fails the request at runtime, see
+     * {@link objSetFilters}.
+     *
+     * ⚠ **Zero-based numeric keys come back as a LIST**, not an object:
+     * `c.obj({ "0": "a" })` evaluates to `["a"]`. That is the engine's data model
+     * — a numeric key IS an index there, and the same object decoded from JSON
+     * anywhere else behaves identically — not something this encoding introduces.
+     * A non-zero-based numeric key (`{ "2": … }`) survives as a key. Live-verified.
+     */
+    obj<const T>(o?: (T & RejectValues<T>) | null): Value;
+    /**
+     * Array constant → JSON-string value with `tag:"const:array"`. Takes **plain
+     * JSON literals only** — like {@link obj}, a nested tagged value is a compile
+     * error and throws at runtime. See issue #42.
+     */
+    array<const T extends readonly unknown[]>(a: T & RejectValues<T>): Value;
+    /**
+     * A **Xano Expression Engine** expression, passed through verbatim →
+     * `tag:"const:expr2"`. The string IS the expression, exactly as it would be
+     * typed into the expression editor:
+     *
+     *   c.expression('"Hello, " ~ $input.name')
+     *   c.expression("$var.price * $var.qty")
+     *   c.expression("{ id: $var.user.id, tier: $var.plan }")
+     *
+     * ⚠️ **THE STRING IS NOT VALIDATED.** XanoTS does not parse it, does not
+     * type-check it, and cannot tell a working expression from a typo — the whole
+     * string is handed to the engine as-is. Nothing here participates in
+     * `InferResponse`, so a var referenced inside it is invisible to the type
+     * system, and a rename that updates every typed `ref()` will NOT update this.
+     * A malformed expression surfaces at RUNTIME, and one that is merely wrong
+     * (`$var.tota1`) surfaces as a wrong answer, not an error. Play at your own
+     * risk until validation exists.
+     *
+     * Prefer the typed surfaces whenever they cover the case: `ref`/`inp`/`col`
+     * for references, `withFilters(..., fl.*)` for transforms, {@link obj} for a
+     * dynamic object (it BUILDS a checked expression for you). Reach for this only
+     * for expression-engine syntax the typed surfaces cannot express — string
+     * concatenation with `~`, inline arithmetic, conditionals.
+     *
+     * NOT the `expr()` condition builder. `expr(col("id"), "=", inp("id"))` builds
+     * a comparison for a `where`; this builds a VALUE from raw expression source.
+     */
+    expression(source: string): Value;
+    /**
+     * The **older** expression form → `tag:"const:expr"`, kept because real
+     * workspaces still hold values stored that way and codegen has to bring them
+     * back as something readable. New code wants {@link expression}, which is what
+     * the expression editor writes today.
+     *
+     * ⚠️ Unvalidated passthrough, exactly like {@link expression} — see the
+     * warning there. This one additionally uses the older syntax generation, so an
+     * expression copied out of the current editor may not mean the same thing
+     * here.
+     */
+    expressionLegacy(source: string): Value;
+};
+/** Options for {@link ref}. */
+interface RefOptions {
+    /**
+     * Null-safe nested access (opt-in). A dotted `ref("owner.user_id")` normally
+     * compiles to the raw var path `$owner.user_id`, which the engine resolves in
+     * a single lookup — so when the base var `owner` is null (e.g. a `db.get` that
+     * matched no row), it raises a runtime `ERROR_FATAL` "Unable to locate var"
+     * (HTTP 500) instead of yielding null (issue #47).
+     *
+     * With `safe: true` the path compiles through the `get` filter
+     * (`$owner|get:"user_id"`), which walks the remaining path and resolves to
+     * null when the base is null — so an ownership/existence guard evaluates to
+     * `false` cleanly rather than throwing. Has no effect on a plain, dot-free name
+     * (a bare var already resolves to null without error).
+     */
+    safe?: boolean;
+}
+/**
+ * Reference a **stack variable** — the `as:` output of an earlier statement:
+ * `{tag:"var", value}`. e.g. `dbGet({ ..., as: "user" })` then `ref("user")`.
+ *
+ * Pass `{ safe: true }` to make a *nested* path null-safe: `ref("owner.user_id",
+ * { safe: true })` resolves to null instead of 500ing when the base `owner` is
+ * null (issue #47) — the intent-revealing opt-in for drilling into a `db.get`
+ * result that may not exist.
+ *
+ * Picking a reference helper (these are easy to mix up):
+ * - {@link ref} — a stack variable (`as:` output). **Not** a foreign key — that's
+ *   the field constructor `f.tableRef`.
+ * - {@link inp} — an endpoint/function `input`.
+ * - {@link col} — a table column (in a `db.query` `where`/view comparison).
+ * - {@link auth} — the authenticated caller (`auth("id")`).
+ * - `c.*` — a literal constant (`c.int(1)`, `c.text("x")`).
+ */
+declare function ref<const Name extends string>(name: Name, opts?: RefOptions): RefValue<Name>;
+/**
+ * The second parameter every non-`ref` reference creator declares, so that
+ * passing `{ safe: true }` to one is a COMPILE error whose expected type is the
+ * explanation (issue #80).
+ *
+ * `safe` was silently dropped before this: the creators took one parameter, so
+ * JavaScript discarded the extra argument and TypeScript never saw it. An
+ * author who wrote `inp("owner.id", { safe: true })` believed they had a
+ * null-safe drill and still got a 500 on a null base.
+ */
+type SafeIsRefOnly = "`safe` is only valid on ref() — see issue #80";
+/** Reference a function/endpoint **input**: `{tag:"input", value}`. See {@link ref} for the full picker. */
+declare function inp(name: string, opts?: SafeIsRefOnly): Value;
+/**
+ * Reference a table **column**: `{tag:"col", value}` (used in `db.query` `where` +
+ * table views). See {@link ref} for the full picker. The return is branded
+ * {@link ColValue} so it is a *compile error* to pass `col()` into a `db.edit`/
+ * `db.add` `row` — where it would resolve to `null` at runtime (issue #32).
+ */
+declare function col(name: string, opts?: SafeIsRefOnly): ColValue;
+/**
+ * Reference the authenticated identity (`{tag:"auth", value}`). Pass a path to
+ * drill into the auth record — `auth("id")` is the authenticated row id
+ * (Xano's `$auth.id`); bare `auth()` is the whole record. Use it to bind the
+ * caller into a row write on an authenticated endpoint (one whose `auth` names
+ * an auth table), e.g.
+ * `s.db.add({ table: post, row: { author_id: auth("id") } })`.
+ */
+declare function auth(path?: string, opts?: SafeIsRefOnly): Value;
+/**
+ * Reference the RESPONSE of the object under test (`{tag:"response", value}`) —
+ * the subject nearly every unit-test assertion is written against.
+ *
+ * Bare `resp()` is the whole response (stored as the literal `"response"`, which
+ * is what the editor writes); a path drills into it, `resp("id")` →
+ * `"response.id"`. A segment that is not a bare identifier takes the engine's
+ * bracket escape, so `resp("user-data")` → `response["user-data"]`.
+ *
+ * Meaningful only inside a `tests` entry's `expect` list. It is NOT a stack
+ * variable: a running stack has no response yet, which is why `ref` cannot
+ * spell this and why the engine gives it its own tag.
+ */
+declare function resp(path?: string, opts?: SafeIsRefOnly): Value;
+/**
+ * The four fields the engine binds in a `s.try_catch` catch arm. Read straight
+ * off the engine's own catch-variable map, which sets exactly these.
+ */
+type CaughtField = "code" | "message" | "name" | "result";
+/**
+ * Read the caught error inside a {@link s.try_catch} **catch** arm
+ * (`{tag:"trycatch", value}` — XanoScript's `$trycatch.*`).
+ *
+ * Only valid inside the catch arm; the engine binds these for that scope alone
+ * and they read empty anywhere else. The four fields are all the engine sets:
+ * - `name` — the error name/type (for a thrown error statement, its message)
+ * - `message` — the human-readable message (`"Throw Error Statement"` for a throw)
+ * - `code` — the mapped HTTP-ish error code
+ * - `result` — the error payload, when one was attached
+ *
+ * e.g. `s.try_catch({ try: [...], catch: [s.debug_log(caught("message"))] })`.
+ * Bare `caught()` is the whole error record.
+ */
+declare function caught(path?: CaughtField | "", opts?: SafeIsRefOnly): Value;
+/**
+ * The toolset-scoped bindings, as the engine sets them.
+ *
+ * Both statements that populate the namespace write exactly two members —
+ * `token` (the calling URL's token, null when the call carried none) and
+ * `params` (the URL's parameters, an empty object when there were none). A
+ * dotted `params.<key>` reads one parameter: the lookup walks the stored map,
+ * so a path into `params` resolves the same way `ref("a.b")` does.
+ *
+ * Closed at the root deliberately — a name outside it resolves to empty rather
+ * than raising, so a typo would read as a silent null at runtime.
+ */
+type ToolsetPath = "token" | "params" | `params.${string}`;
+/**
+ * Read a **toolset-scoped binding** inside an agent/MCP tool
+ * (`{tag:"toolset", value}`) — the token and URL parameters the toolset was
+ * called with, alongside {@link ref}/{@link inp}/{@link env}/{@link auth}.
+ *
+ * - `toolset("token")` — the token on the calling URL, null when absent.
+ * - `toolset("params")` — the URL parameters as an object.
+ * - `toolset("params.tenant")` — one parameter out of that object.
+ *
+ * Only bound while a tool runs under its toolset; anywhere else it reads empty
+ * (issue #152).
+ */
+declare function toolset(path: ToolsetPath, opts?: SafeIsRefOnly): Value;
+/**
+ * Read a **workspace environment variable** — the ones set via `workspaceConfig({ env })`
+ * or the workspace dashboard, e.g. `env("STRIPE_KEY")` → `$env.STRIPE_KEY`.
+ *
+ * Under the hood a workspace env var is a `{tag:"setting", value:"NAME"}` (the plain,
+ * non-`$` name) — `$env.NAME` in XanoScript is sugar for that setting. This is the SAME
+ * tag the built-in request/system vars use; those just carry a `$`-prefixed name
+ * (`$env.$remote_ip`). So `env("remote_ip")` reads a *user* var literally named
+ * `remote_ip` (usually unset → null), NOT the caller IP — use {@link sys} (`sys.remoteIp()`)
+ * or {@link setting} with the exact `$`-prefixed name for the built-ins.
+ *
+ * (`$env.NAME` is a setting, not the raw `tag:"env"` form — which does not resolve
+ * workspace vars — so this reads them as settings, matching the platform.)
+ */
+declare function env(name: string, opts?: SafeIsRefOnly): Value;
+/**
+ * Reference a workspace setting by raw name (`{tag:"setting", value}`). The built-in
+ * request/system variables are settings with a **`$`-prefixed** name — `setting("$remote_ip")`,
+ * `setting("$datasource")`, etc. Prefer the typed {@link sys} accessors, which spell the
+ * names for you and avoid the `$`-prefix footgun; drop to `setting()` only for a name `sys`
+ * doesn't cover.
+ */
+declare function setting(name: string, opts?: SafeIsRefOnly): Value;
+/**
+ * Built-in **system / request-context variables**. In XanoScript these are written
+ * `$env.$remote_ip`, `$env.$datasource`, … — note the second `$`: they are *settings*
+ * (`{tag:"setting", value:"$remote_ip"}`), distinct from the user-defined env vars that
+ * {@link env} reaches. Reaching for `env("remote_ip")` silently reads the wrong thing;
+ * these accessors emit the correct `setting("$…")` form so you never type the `$` prefix.
+ *
+ * The one that matters most: on a **public** endpoint `auth("id")` is null (every caller
+ * collapses into one bucket), so key a rate limit off {@link sys.remoteIp} instead —
+ * `withFilters(c.text("rl:apply:"), fl.concat(sys.remoteIp()))`.
+ *
+ * Mirrors the full workspace "environment" panel; every accessor returns a {@link Value}.
+ */
+declare const sys: {
+    /** Client IP address (`$remote_ip`, text). Best public-endpoint rate-limit key. */
+    remoteIp: () => Value;
+    /** HTTP method of the request — `GET`, `POST`, … (`$request_method`, text). */
+    requestMethod: () => Value;
+    /** Full request URI/path (`$request_uri`, text). */
+    requestUri: () => Value;
+    /** Raw query-string portion of the URL (`$request_querystring`, text). */
+    requestQueryString: () => Value;
+    /** Request headers as an object/map (`$http_headers`, object). */
+    httpHeaders: () => Value;
+    /** The caller's `Authorization` bearer token, if present (`$request_auth_token`, text). */
+    requestAuthToken: () => Value;
+    /** API base URL for the request (`$api_baseurl`, text). */
+    apiBaseUrl: () => Value;
+    /** Active data source name — e.g. `live` or a branch source (`$datasource`, text). */
+    datasource: () => Value;
+    /** Active branch name (`$branch`, text). */
+    branch: () => Value;
+    /** Tenant identifier for multi-tenant instances (`$tenant`, text). */
+    tenant: () => Value;
+    /** Current release number (`$release`, int). */
+    release: () => Value;
+    /** Platform identifier (`$platform`, int). */
+    platform: () => Value;
+    /** `true` when the request is running under the debugger (`$debugger`, bool). */
+    isDebugger: () => Value;
+};
+/**
+ * Reference a column of the **parent statement's output row** (`{tag:"output",
+ * value}`) — the `$output.<col>` reference an addon input binds to. Only
+ * meaningful inside an addon spec's `input` map (see `s.db.query`'s `addon`
+ * arg), where the engine resolves it against each row the parent query returns,
+ * e.g. `addon: [{ addon: transactions, as: "items._txns",
+ * input: { user_id: out("id") } }]`.
+ */
+declare function out(name: string, opts?: SafeIsRefOnly): Value;
+/**
+ * Build a `mvp_filter` chain entry: `{name, disabled:false, arg}`.
+ *
+ * Generic in the name so a literal call carries it at the type level
+ * (`filter("upper")` is a `FilterXdo<"upper">`), which is what lets a chain's
+ * result type be folded. A `string` name — the escape-hatch spelling, and what a
+ * decoded workspace passes — widens to `FilterXdo<string>` and folds to
+ * `unknown`, exactly as before.
+ */
+declare function filter<const N extends string>(name: N, ...args: (Value | undefined)[]): FilterXdo<N>;
+/**
+ * Attach a filter chain to a value, returning a new value. Pass filters spread
+ * (the canonical form, `withFilters(v, fl.trim(), fl.lower())`); the array form
+ * (`withFilters(v, [fl.trim(), fl.lower()])`) is also accepted — both are flattened.
+ */
+declare function withFilters<V extends Value, const Fs extends readonly (FilterXdo | FilterXdo[])[]>(value: V, ...filters: Fs): FilteredValue<V, FlattenFilters<Fs>> & (V extends ColValue ? {
+    readonly __col: true;
+} : unknown);
+
+/**
+ * Unit-test ASSERTIONS — the `expect[]` list on a saved `test`.
+ *
+ * ## Not to be confused with `s.expect.*`
+ *
+ * Xano overloads the word, and so does this SDK, because both surfaces are
+ * really called `expect` in the product:
+ *
+ * - `expect.*` (this module) builds a `{type, vars[]}` **assertion record**
+ *   stored on a `tests` entry of a query/function/middleware. It is data, not a
+ *   step, and it only ever appears inside `tests: [{ expect: [...] }]`.
+ * - `s.expect.*` builds an assertion **statement** that runs inside a
+ *   `workflowTest()` stack. It is a stack item like any other.
+ *
+ * They are not interchangeable and the type system enforces it: these return
+ * {@link TestExpect}, those return `Statement`.
+ *
+ * ## The subject comes first
+ *
+ * Every matcher takes its subject as the first argument — almost always
+ * {@link resp}. Argument ORDER is the assertion's meaning:
+ * `expect.to_contain(resp("tags"), c.text("new"))` asserts the response's tags
+ * contain `"new"`, not the reverse.
+ */
+
+/** The stored matcher names, in the engine's own order. */
+declare const TEST_EXPECT_TYPES: readonly ["to_be_defined", "to_be_empty", "to_be_false", "to_be_greater_than", "to_be_in_the_future", "to_be_in_the_past", "to_be_less_than", "to_be_null", "to_be_true", "to_be_within", "to_contain", "to_end_with", "to_equal", "to_match", "to_not_be_defined", "to_not_be_null", "to_not_equal", "to_start_with", "to_throw"];
+/** One of the 19 stored matcher names. */
+type TestExpectType = (typeof TEST_EXPECT_TYPES)[number];
+/** A stored assertion — `{type, vars[]}`, the `mvp_test_expect` shape. */
+interface TestExpect {
+    type: TestExpectType;
+    vars: Value[];
+}
+/**
+ * Unit-test assertions, for the `expect` list of a `tests` entry.
+ *
+ * See the module header for why this is NOT `s.expect.*`.
+ *
+ * ```ts
+ * query({
+ *   name: "score",
+ *   verb: "POST",
+ *   input: { score: input.int() },
+ *   tests: [
+ *     {
+ *       name: "adds one",
+ *       input: { score: c.int(1) },
+ *       expect: [expect.to_equal(resp(), c.int(2))],
+ *     },
+ *   ],
+ *   stack: [s.set_var("x1", c.expression("$input.score + 1"))],
+ *   response: ref("x1"),
+ * });
+ * ```
+ */
+declare const expect: {
+    /** The subject is set (not undefined). */
+    readonly to_be_defined: (subject: Value) => TestExpect;
+    /** The subject is undefined. */
+    readonly to_not_be_defined: (subject: Value) => TestExpect;
+    /** The subject is empty — `""`, `[]`, `{}`, `0`, or null. */
+    readonly to_be_empty: (subject: Value) => TestExpect;
+    /** The subject is `null`. */
+    readonly to_be_null: (subject: Value) => TestExpect;
+    /** The subject is not `null`. */
+    readonly to_not_be_null: (subject: Value) => TestExpect;
+    /** The subject is boolean true. */
+    readonly to_be_true: (subject: Value) => TestExpect;
+    /** The subject is boolean false. */
+    readonly to_be_false: (subject: Value) => TestExpect;
+    /** The subject is a timestamp later than now. */
+    readonly to_be_in_the_future: (subject: Value) => TestExpect;
+    /** The subject is a timestamp earlier than now. */
+    readonly to_be_in_the_past: (subject: Value) => TestExpect;
+    /** `subject === value`. */
+    readonly to_equal: (subject: Value, value: Value) => TestExpect;
+    /** `subject !== value`. */
+    readonly to_not_equal: (subject: Value, value: Value) => TestExpect;
+    /** `subject > value`, both read as numbers. */
+    readonly to_be_greater_than: (subject: Value, value: Value) => TestExpect;
+    /** `subject < value`, both read as numbers. */
+    readonly to_be_less_than: (subject: Value, value: Value) => TestExpect;
+    /** A list subject contains the item; a text subject contains the substring. */
+    readonly to_contain: (subject: Value, item: Value) => TestExpect;
+    /** The subject, as text, starts with `prefix`. */
+    readonly to_start_with: (subject: Value, prefix: Value) => TestExpect;
+    /** The subject, as text, ends with `suffix`. */
+    readonly to_end_with: (subject: Value, suffix: Value) => TestExpect;
+    /**
+     * The subject matches a regular expression. `pattern` is a PCRE pattern
+     * INCLUDING its delimiters — build it with `c.regex(...)` rather than by hand;
+     * a bare `"^a"` is not a runnable pattern and the engine's match silently
+     * fails rather than erroring.
+     */
+    readonly to_match: (subject: Value, pattern: Value) => TestExpect;
+    /**
+     * `min < subject < max`, both bounds EXCLUSIVE and all three read as numbers.
+     * A subject equal to either bound fails.
+     */
+    readonly to_be_within: (subject: Value, min: Value, max: Value) => TestExpect;
+    /**
+     * The run raised an error. Pass `exception` to require that text to appear in
+     * the error message (a case-insensitive substring, not an exact match);
+     * omit it to accept ANY error.
+     *
+     * Unlike every other matcher this one takes no subject: the thing under
+     * assertion is the run's failure, and the engine stores the response slot as
+     * a fixed first var. That is what the editor writes, and it is preserved so
+     * an authored test and a pulled one are the same bytes.
+     */
+    readonly to_throw: (exception?: Value) => TestExpect;
+};
+
+/**
+ * The lean statement-input entry — `{name, tag, value, filters}` — shared by
+ * every call site that emits the *lean* input form (no rich
+ * `ignore`/`expand`/`children`):
+ *
+ * - addon `input[]` bindings ({@link ../statements/special/addon-encode.ts}),
+ * - the lean db family (`db.add_or_edit` / the bulk ops in
+ *   {@link ../statements/special/db.ts}),
+ * - lean spec-driven statements ({@link ../statements/schema-dsl/interpret.ts}).
+ *
+ * One builder so the shape lives in exactly one place. (JSON key order is not
+ * significant to the engine parser, which reads by field name.)
+ */
+
+/** A lean input binding — `{name, tag, value, filters}`, no `ignore/expand/children`. */
+interface LeanInput {
+    name: string;
+    tag: string;
+    value: string;
+    filters: unknown[];
+}
+
+/**
+ * A saved UNIT TEST — one entry of the `test[]` a query, function, or
+ * middleware carries. This is the thing the Xano UI calls a unit test: a named
+ * set of inputs, run against the object it hangs off, with assertions on the
+ * response.
+ *
+ * ## Not `workflowTest()`
+ *
+ * A {@link ../kinds/workflow-test.js WorkflowTestDef} is a standalone top-level
+ * object with its own stack that calls other objects. A unit test is a PROPERTY
+ * of one object and has no stack of its own — the object under test is the
+ * stack. The two never interact.
+ *
+ * ## Mocks live on the statements, not here
+ *
+ * A test can substitute a value for any statement in the object's stack, so the
+ * step returns the mock instead of doing its work. That is authored on the
+ * STATEMENT (`s.*(…, { mock: { "<test name>": … } })`) and keyed by this test's
+ * name; see {@link ./test-mocks.js}.
+ */
+
+interface TestDef {
+    /**
+     * The test's display name, unique within the object. It is also the key a
+     * statement's `mock` map uses to name this test, which is why a duplicate is
+     * refused rather than merged.
+     */
+    name: string;
+    /**
+     * Explicit stored `id` (this test's identity). Defaults to one derived from
+     * the owning object and the test name; set it to keep identity across a
+     * rename. A pulled test always carries the id Xano minted for it.
+     */
+    id?: string;
+    description?: string;
+    /**
+     * Datasource to run against. `""` (the default) means an EMPTY datasource —
+     * the recommended setting. Any other value names a datasource the engine
+     * **clones** before the test runs; `"live"` warns at encode time.
+     */
+    datasource?: string;
+    /**
+     * The inputs to call the object with, by input name — the same tagged values
+     * used everywhere else (`c.*`, `ref`, …), not plain JS scalars.
+     */
+    input?: Record<string, Value>;
+    /**
+     * The assertions, built with the top-level `expect.*` helpers — NOT
+     * `s.expect.*`, which builds workflow-test statements. See
+     * {@link ../values/expect.js}.
+     */
+    expect?: TestExpect[];
+    /**
+     * An auth token to run the test as an authenticated caller.
+     *
+     * Accepted so an authored test can supply one, but note that a pull does NOT
+     * bring it back: a token is an expiring credential rather than authored
+     * configuration, so `codegen` reports a stored one as a deliberate omission
+     * instead of writing it into a committed tree.
+     */
+    token?: string;
+}
+/** The stored `mvp_test` shape. */
+interface TestXdo {
+    datasource: string;
+    description: string;
+    expect: TestExpect[];
+    id: string;
+    input: LeanInput[];
+    name: string;
+    /**
+     * Always emitted, blank when unset. The stored schema marks it optional, but a
+     * live round trip shows the engine persists `""` regardless — omitting it read
+     * as a failed round trip on every test.
+     */
+    token: string;
+}
+/**
+ * Declare a saved unit test. Sugar for a plain object literal — use it for the
+ * inferred type and the doc hover; `tests: [{ … }]` is equally valid.
+ */
+declare function test(def: TestDef): TestDef;
+
+/**
+ * TypeScript mirror of Xano's stored `mvp_function` JSON contract (the
+ * importable `xdo` subset, flattened per KTD-1 — no `xdo` wrapper).
+ *
+ * Field shapes are taken from the real Xano engine's persisted function shape.
+ *
+ * The SDK emits only authored fields. Server/auto-generated keys (`id`,
+ * `created_at`, `_xsid`, `@guid`, `@index`, `guid`, `_draft`, `stack_id`, …)
+ * are generated by the engine on import and are NEVER emitted here; the test
+ * normalizer (U6) strips them from the fixture before comparison.
+ */
+/**
+ * Xano tagged-value tags (verified against the Xano engine). The runtime
+ * `TAGS` tuple is the single source of truth; the `Tag` type is derived from it
+ * so the manifest can enumerate the tag catalog without drifting from the type.
+ */
+
+declare const TAGS: readonly ["const", "const:int", "const:decimal", "const:bool", "const:array", "const:obj", "const:null", "const:epochms", "const:expr", "const:expr2", "var", "input", "auth", "env", "setting", "col", "output", "response", "trycatch", "toolset"];
+type Tag = (typeof TAGS)[number];
+/**
+ * A filter in a `mvp_filter` chain: `{name, disabled, arg}`.
+ *
+ * `N` is a **phantom** carrier for the filter's name, set by the `fl.*` factories
+ * (`fl.upper()` is a `FilterXdo<"upper">`) and never present at runtime — `name`
+ * already holds it. It exists so a chain's RESULT type can be folded statically:
+ * knowing a chain is `["trim", "upper"]` rather than `string[]` is what lets
+ * `withFilters`/`asFilters` report `string` instead of `unknown`.
+ *
+ * It defaults to `string`, so every existing `FilterXdo` position — stored
+ * envelopes, decoder output, the `filter()` escape hatch — keeps working
+ * unchanged and simply folds to `unknown`, the honest floor for a chain whose
+ * names are not statically known.
+ */
+interface FilterXdo<N extends string = string> {
+    name: string;
+    /**
+     * Whether the engine skips this filter. OPTIONAL because the engine stores it
+     * both ways: `filter()` and every `fl.*` constructor write it, but a filter
+     * persisted by an older editor may carry no `disabled` key at all.
+     *
+     * Required here until now, which made a pulled workspace fail its own
+     * type-check: codegen emits a stored filter verbatim when no `fl.*` form
+     * reproduces it, and a verbatim emit of a filter stored without the key does
+     * not have it (issue #134). Writing `disabled: false` in would have been the
+     * other repair, and it is the wrong one — it ADDS a key the engine did not
+     * store, so the re-encode would no longer match the stored bytes and the value
+     * would degrade further rather than round-trip.
+     *
+     * Read it as `filter.disabled ?? false`.
+     */
+    disabled?: boolean;
+    arg: TaggedValue[];
+    /** Phantom: the filter's name at the type level. Never present at runtime. */
+    readonly __filter?: N;
+}
+/** The core tagged value: `{value, tag, filters}`. Values serialize as strings. */
+interface TaggedValue {
+    value: string;
+    tag: Tag;
+    filters: FilterXdo[];
+}
+/**
+ * An input/column "method" (e.g. `trim`, or `min:8`). `arg` holds the filter's
+ * literal arguments as scalars (`["8"]`); the persisted corpus is numeric/string
+ * inconsistent on them (`[8]` vs `["10"]`), the same artifact class as
+ * `const:int` tagged values — the normalizer coerces both to strings.
+ */
+interface MethodXdo {
+    name: string;
+    disabled: boolean;
+    arg: Array<string | number>;
+}
+/**
+ * A field-bearing entry — the shape shared by function/query inputs and table
+ * columns (KTD-6). In the persisted form the two are byte-identical: both use
+ * `customize:{}`, numeric `market_item` ids, an `_xsid` placeholder, and a
+ * present `description`. (The older parser generation emitted `customize:""` /
+ * string ids for inputs; the live `mvp_query`/`mvp_dbo` rows show they converge.)
+ */
+/**
+ * A field's array length bounds, as PERSISTED.
+ *
+ * Both members are `json`-typed in the engine rather than numeric — the editor
+ * declares them that way and every consumer reads them through a coercion
+ * (`+list.max`) — so a set bound arrives as `5` or as `"5"`, and an UNSET one as
+ * whichever empty the editor serialized: `""` on 8,814 fields in the sweep, `{}`
+ * on two. All four spellings are real bytes, so the type admits them rather than
+ * asserting a tidiness the engine does not have.
+ */
+type ListBoundsXdo = {
+    min?: string | number | Record<string, never>;
+    max?: string | number | Record<string, never>;
+};
+interface FieldXdo {
+    name: string;
+    type: string;
+    _xsid: string;
+    description?: string;
+    nullable: boolean;
+    /**
+     * Absent for types that persist no default (`uuid`) — the engine drops the
+     * key rather than storing it empty, and the two are different stored bytes.
+     */
+    default?: string;
+    merge: boolean;
+    hidden: unknown[];
+    override: unknown[];
+    customize: string | Record<string, unknown>;
+    required: boolean;
+    values: unknown[];
+    mode: string;
+    format: string;
+    sensitive: boolean;
+    list: ListBoundsXdo;
+    vector: {
+        size: number;
+    };
+    access: string;
+    style: {
+        type: string;
+    };
+    children: unknown[];
+    methods: MethodXdo[];
+    market_item: {
+        id: string | number;
+        version: string | number;
+        guid: string;
+    };
+    is_settings_registry: boolean;
+}
+/**
+ * A single function/query input (`input[]` entry). Shares the persisted field
+ * shape with table columns ({@link FieldXdo}) — `customize:{}`, numeric
+ * `market_item` ids, `_xsid` present.
+ */
+interface InputXdo {
+    name: string;
+    type: string;
+    _xsid: string;
+    description: string;
+    nullable: boolean;
+    default: string;
+    merge: boolean;
+    hidden: unknown[];
+    override: unknown[];
+    customize: string | Record<string, unknown>;
+    required: boolean;
+    values: unknown[];
+    mode: string;
+    format: string;
+    sensitive: boolean;
+    list: ListBoundsXdo;
+    vector: {
+        size: number;
+    };
+    access: string;
+    style: {
+        type: string;
+    };
+    children: unknown[];
+    methods: MethodXdo[];
+    market_item: {
+        id: string | number;
+        version: string | number;
+        guid: string;
+    };
+    is_settings_registry: boolean;
+}
+/** A response item (`result[]` entry). The persisted form always carries `_xsid` and `disabled`. */
+interface ResultItemXdo {
+    filters: FilterXdo[];
+    name: string;
+    tag: Tag;
+    value: string;
+    _xsid: string;
+    disabled: boolean;
+}
+/**
+ * A stack statement (`run[]` entry). The persisted form is a **uniform** 12-key
+ * envelope, identical across every statement type (confirmed against live
+ * `mvp_query`/`mvp_tool`): every member is always present, with empty defaults.
+ * `context` varies per statement (set_var carries a TaggedValue; conditional
+ * carries nested runs — see below).
+ */
+interface StackItemXdo {
+    as: string;
+    name: string;
+    _xsid: string;
+    addon: unknown[];
+    input: unknown[];
+    mocks: unknown;
+    output: unknown;
+    context: unknown;
+    runtime: unknown;
+    disabled: boolean;
+    description: string;
+    settings_registry: unknown[] | null;
+}
+/**
+ * A statement `input[]` argument binding — a named tagged value, distinct from
+ * the rich `InputXdo` field shape. Lean form is `{name,value,tag,filters}`;
+ * "full" statements (api_request, db ops, file ops) add `ignore/expand/children`.
+ */
+interface StatementInputXdo {
+    name: string;
+    value: string;
+    tag: Tag;
+    filters: FilterXdo[];
+    ignore?: boolean;
+    expand?: boolean;
+    children?: unknown[];
+}
+/** A single binary comparison operand inside a conditional expression. */
+interface ExprOperand {
+    operand: string;
+    tag: Tag;
+    filters: FilterXdo[];
+    ignore_empty?: boolean;
+}
+/** One `statement`-type entry in a conditional's `expr.expression[]`. */
+interface ExprStatement {
+    type: "statement";
+    or: boolean;
+    group: {
+        expression: unknown[];
+    };
+    statement: {
+        op: string;
+        left: ExprOperand;
+        right: ExprOperand;
+    };
+}
+/** A `{type:"group"}` entry — a nested AND/OR subtree of expression nodes. */
+interface ExprGroup {
+    type: "group";
+    or: boolean;
+    group: {
+        expression: ExprNode[];
+    };
+}
+/** One node in an expression tree: a comparison statement or a nested group. */
+type ExprNode = ExprStatement | ExprGroup;
+/** `context` for a `mvp:conditional` statement. */
+interface ConditionalContext {
+    expr: {
+        expression: ExprNode[];
+    };
+    if: {
+        run: StackItemXdo[];
+    };
+    /**
+     * The elif stack — a `run[]` of `mvp:conditional_elif` statements, each its own
+     * `{ expr, if:{run} }` branch (mirrors how `mvp:switch` stacks `switch_case`).
+     * The engine always persists this key, `{run:[]}` when there are no elif
+     * branches (verified against a live conditional capture).
+     */
+    elif: {
+        run: StackItemXdo[];
+    };
+    else: {
+        run: StackItemXdo[];
+    };
+}
+/** `context` for a `mvp:conditional_elif` statement — one leaf branch of a conditional's elif stack. */
+interface ConditionalElifContext {
+    expr: {
+        expression: ExprNode[];
+    };
+    if: {
+        run: StackItemXdo[];
+    };
+}
+interface CacheXdo {
+    active: boolean;
+    ttl: number;
+    input: boolean;
+    auth: boolean;
+    datasource: boolean;
+    ip: boolean;
+    headers: unknown[];
+    env: unknown[];
+}
+interface HistoryXdo {
+    inherit: boolean;
+    enabled: boolean;
+    limit: number;
+}
+interface MiddlewareXdo {
+    pre_customize: boolean;
+    post_customize: boolean;
+    pre: unknown[];
+    post: unknown[];
+}
+/** The flattened authored function envelope the SDK emits. */
+interface FunctionXdo {
+    name: string;
+    description: string;
+    docs: string;
+    workspace: {
+        id: number;
+    };
+    branch: {
+        id: number;
+    };
+    cache: CacheXdo;
+    history: HistoryXdo;
+    middleware: MiddlewareXdo;
+    tag: unknown[];
+    input: InputXdo[];
+    result: ResultItemXdo[];
+    run: StackItemXdo[];
+    test: TestXdo[];
+    market_item: {
+        id: number;
+        version: number;
+        guid: string;
+    };
+    shared_workspace: {
+        is_shared: boolean;
+    };
+}
+/**
+ * The persisted row: authored envelope plus the server columns the engine
+ * adds on import. Used ONLY by the test normalizer — the SDK never emits these.
+ */
+type PersistedFunctionRow = FunctionXdo & {
+    id: number;
+    created_at: string;
+    updated_at: string;
+    deleted_at?: string;
+    guid: string;
+    _draft?: boolean;
+    _xsid?: string;
+    market_item?: {
+        id: number;
+        version: number;
+        guid: string;
+    };
+};
+
+/**
+ * A statement's per-test MOCK — the value a step returns instead of doing its
+ * work, when one specific test runs.
+ *
+ * Authored keyed by TEST NAME, which is what the Xano editor shows and what
+ * XanoScript spells. The stored form is keyed by test ID; the rewrite happens
+ * at kind-encode time, the only place that knows both the stack and the test
+ * list (see `../kinds/test-mocks.js`).
+ *
+ * A mock applies ONLY while its test runs. It has no effect on a normal
+ * request, so mocking a step does not change what the deployed endpoint does.
+ */
+
+/**
+ * One mock: a value, or a value plus `enabled`.
+ *
+ * The bare form means enabled. The object form exists so a mock can be kept
+ * around switched off — the editor stores a disabled mock rather than deleting
+ * it, and dropping it on encode would lose an authored artefact.
+ */
+type MockEntry = Value | {
+    value: Value;
+    enabled?: boolean;
+};
+/** A statement's mocks, keyed by the name of the test each applies to. */
+type MockMap = Record<string, MockEntry>;
+/** The stored `mvp_test_mock` shape. */
+interface MockXdo {
+    value: string;
+    tag: string;
+    filters: unknown[];
+    enabled: boolean;
+}
+
+/**
+ * Statement model, base envelope encoder, and registry (U5 — the KTD-4
+ * extensibility seam).
+ *
+ * The real stored statement shape (from the golden fixture's `run[0]`) is lean:
+ * `{name, as?, context, input}`. The base encoder fills the common envelope
+ * (`input: []` default) so each concrete statement factory only declares its
+ * `name`, optional `as`, and `context`. The registry maps statement name →
+ * factory so the eventual ~500-statement catalog plugs in here.
+ */
+
+/**
+ * The type-level contract linking a branded db statement (the **producer** —
+ * `db.get`/`db.query`/`db.add`/`db.edit`/`db.patch`/`db.add_or_edit`/`db.has`/
+ * `db.bulk.patch`/`db.bulk.delete`, each returning `Statement & AsShapeBrand<…>`)
+ * to `InferResponse`'s single-variable trace (the **consumer** — `TraceVar`,
+ * which destructures this shape). Both `__as` (the stack variable the statement
+ * binds) and `__shape` (the row shape it produces) are phantom carriers — never
+ * present at runtime. Naming the contract here keeps producer and consumer
+ * compiler-linked, so any further branded statement joins the trace by extending
+ * this type with zero edits to the trace logic.
+ */
+type AsShapeBrand<As extends string, Shape> = {
+    readonly __as: As;
+    readonly __shape: Shape;
+};
+/**
+ * The two envelope members every stack item carries, whatever it does.
+ *
+ * They are editor affordances rather than statement arguments — `disabled` is
+ * how a step is commented out (it stays in the stack; the run engine skips it),
+ * and `description` is the note shown on the step. `encodeStatement` writes both
+ * for every statement, so every factory accepts them: the generated ones as two
+ * more optional fields on their argument object, the positional specials as a
+ * trailing options argument.
+ *
+ * Both are elided at their defaults on both sides of a round trip, so setting one
+ * to `false`/`""` is the same bytes as omitting it.
+ */
+interface StatementAnnotations {
+    /** Leave the step in the stack but skip it at runtime — Xano's "disable step". */
+    disabled?: boolean;
+    /** Free-text note on the step, shown in the editor beside it. */
+    description?: string;
+    /**
+     * Per-test MOCKS — what this step returns instead of running, keyed by the
+     * name of the test the mock applies to.
+     *
+     * `{ "happy path": c.int(1) }` makes the step return `1` while the test named
+     * "happy path" runs, and changes nothing about a normal request. Wrap an
+     * entry as `{ value, enabled: false }` to keep a mock switched off.
+     *
+     * Every name must match a test declared on the object this statement belongs
+     * to; an unmatched name throws at encode time, because the engine silently
+     * ignores a mock whose key is not a real test id.
+     */
+    mock?: MockMap;
+}
+/**
+ * {@link StatementAnnotations} plus the result-filter option, for the statements
+ * that bind an `as` variable.
+ *
+ * Split from the annotations rather than folded into them so `asFilters` is only
+ * offered where there is a binding to attach it to: a statement that returns
+ * nothing (`precondition`, `switch`, `while`, …) should not surface the option
+ * in autocomplete at all. The runtime guard in {@link assertBindsAs} still
+ * backs this up for callers that reach past the types.
+ */
+interface StatementOptions extends StatementAnnotations {
+    /**
+     * Filters piped onto the result before it is bound — the editor's
+     * `return as token | upper`.
+     *
+     * Authored from the same `fl.*` catalog as value filters and applied in
+     * order, so `asFilters: [fl.trim(), fl.upper()]` trims and then upper-cases.
+     *
+     * The bound variable is RETYPED by the chain: `InferResponse` folds each
+     * filter's declared result, so a `db.query` bound through `[fl.count()]` is a
+     * `number`. Filters the engine declares as returning `any` (`get`, `set`,
+     * `json_decode`, …) fold to `unknown` — see `values/filter-result.ts`.
+     */
+    asFilters?: FilterXdo[];
+}
+/**
+ * Apply {@link StatementOptions} to a built statement.
+ *
+ * Only members that were actually authored are copied, so a factory's own
+ * `description` (a few statements route one) is not clobbered by an absent key.
+ *
+ * `asFilters` merges into the `output` envelope rather than replacing it: a db
+ * statement's column selection (`output.items`) and its result filters live in
+ * the same block, and dropping one to write the other would silently discard
+ * whichever the factory set first.
+ */
+declare function annotate<T extends Statement>(stmt: T, a?: StatementOptions): T;
+/** What a statement factory returns before base-envelope encoding. */
+interface Statement {
+    name: string;
+    as?: string;
+    context: unknown;
+    input?: unknown[];
+    /** `output` envelope. Lean (`{filters:[]}`) or rich (`{customize,filters,items}`) forms are both accepted and normalized to the full rich form. */
+    output?: unknown;
+    /** Statement description (defaults to `""`). */
+    description?: string;
+    /** Settings-registry bindings (defaults to `null`). */
+    settings_registry?: unknown[] | null;
+    /** Attached addons (defaults to `[]`). */
+    addon?: unknown[];
+    /** Async/runtime block (e.g. `mvp:call_agent`'s `{ mode }`); defaults to `null`. */
+    runtime?: unknown;
+    /**
+     * Encoded per-test mocks, keyed by test NAME until the owning kind rewrites
+     * the keys to test ids. Authored via the `mock` option, not set directly.
+     */
+    mocks?: Record<string, MockXdo> | unknown;
+    /** Whether the statement is disabled in the stack (defaults to `false`). */
+    disabled?: boolean;
+}
+/**
+ * Return a statement sequence from a helper **without losing the tuple**
+ * (issue #11).
+ *
+ * `InferResponse` traces the `as` binding a `response` names by walking the
+ * stack's TUPLE type. Spreading anything typed `Statement[]` widens the whole
+ * array, and every binding — including ones declared *after* the spread —
+ * becomes invisible, so the response silently resolves to
+ * {@link StackTupleWidened}. A helper that emits more than one statement has to
+ * return an array, so any shared helper triggers it:
+ *
+ * ```ts
+ * // ✗ widens: every `as` in the calling stack stops being traceable
+ * function assertOk(v: string): Statement[] { return [s.lambda({…}), s.precondition({…})]; }
+ *
+ * // ✓ tuple survives the spread
+ * function assertOk(v: string) { return statements(s.lambda({…}), s.precondition({…})); }
+ * ```
+ *
+ * Type-level only — the returned array is the arguments verbatim, so there is no
+ * encoder involvement and no cost.
+ *
+ * **Fixed arity only.** A helper that builds its array in a loop cannot be a
+ * tuple; declare `responseShape` on the calling def instead.
+ */
+declare function statements<const T extends readonly Statement[]>(...items: T): T;
+/** True when a statement name has a registered factory. */
+declare function isRegisteredStatement(name: string): boolean;
+/** Look up a registered factory, throwing a clear error when absent. */
+declare function getStatementFactory(name: string): (...args: any[]) => Statement;
+/**
+ * Encode a statement into the stored `StackItemXdo`, filling the **full**
+ * persisted envelope. Every stored statement carries the same 12 keys
+ * regardless of type (confirmed against live `mvp_query`/`mvp_tool`), so the
+ * envelope is uniform here rather than per-statement: empty members are emitted
+ * with their canonical defaults so the output is 1:1 with the engine's
+ * persisted form. `_xsid` is engine-generated on import; we emit `""` (the
+ * stored placeholder) so the key is present for comparison.
+ */
+declare function encodeStatement(stmt: Statement): StackItemXdo;
+
+/**
+ * Shared field encoder (KTD-6). Function inputs and table columns are nearly
+ * the same stored shape; this encoder fills the common defaults and is
+ * parameterized by a `FieldContext` for the three spots where they differ:
+ * `customize` (`""` vs `{}`), `market_item` id types (string vs numeric), and
+ * whether `description` is emitted.
+ */
+
+/** Field visibility — the engine's `access` enum. */
+type FieldAccess = "public" | "private" | "internal";
+/** Valid `format` values for text fields (per the engine's text-field schema). */
+type TextFormat = "" | "plaintext" | "yaml" | "html" | "xml" | "markdown";
+/** Field cardinality — `"single"` (scalar) or `"list"` (array column). */
+type FieldStyleType = "single" | "list";
+interface FieldOptions {
+    required?: boolean;
+    nullable?: boolean;
+    /**
+     * Default value. Authored as a `string`, `number`, or `boolean` for
+     * ergonomics (`default: 0`, `default: false`); the engine stores it as a
+     * string, so it's coerced at encode time (`0` → `"0"`, `false` → `"false"`).
+     *
+     * On a **table column** the default must stay within the Basic Multilingual
+     * Plane: a 4-byte character (codepoint > U+FFFF — emoji, CJK-extension glyphs)
+     * is mangled into an invalid UTF-8 sequence by the engine's default pipeline
+     * and is rejected at export/encode time rather than 500ing at deploy with
+     * Postgres `22021` (issue #45). BMP characters (accents, `€`, most CJK) store
+     * fine. A *function/endpoint input* default binds at runtime and has no limit.
+     */
+    default?: string | number | boolean;
+    /**
+     * Persist **no `default` key at all** for this field, rather than the empty
+     * `default: ""` every other field carries.
+     *
+     * Set on a table's `uuid` PRIMARY KEY, which is the one column the engine
+     * stores this way — its value is engine-generated, so there is nothing for a
+     * default to mean, and absent vs empty are different stored bytes. Applied
+     * automatically by `idType: "uuid"`; you rarely set it by hand.
+     *
+     * NOT a property of `uuid` in general: an ordinary (non-key) `uuid` column
+     * does carry `default: ""`. Mutually exclusive with {@link default}.
+     */
+    noDefault?: boolean;
+    description?: string;
+    /**
+     * Methods/filters applied at bind time. Each entry is either a bare name
+     * (`"trim"`), a colon-form string with args (`"min:8"` → `{name:"min",
+     * arg:["8"]}`), or an explicit `{ name, arg }` object.
+     */
+    methods?: MethodSpec[];
+    /** Enum values (for `type:"enum"` fields), e.g. `["draft","live"]`. */
+    values?: Array<string | number>;
+    mode?: string;
+    /** Text-field display format (text fields only; the engine drops it elsewhere). */
+    format?: TextFormat;
+    sensitive?: boolean;
+    /**
+     * Merge the referenced object's fields into this one rather than nesting them.
+     *
+     * **Leave this unset** unless reproducing a pulled field. It defaults to `false`,
+     * which is what every field this SDK authors from scratch wants; it is here so a
+     * pulled workspace's field can be recovered as a readable `f.*` call instead of
+     * degrading to `rawField()`. Paired with {@link hidden} in the wild — 584 fields
+     * across the sweep carry `merge: true` with a `hidden` list beside it.
+     */
+    merge?: boolean;
+    /**
+     * Names to hide from this field's expansion (e.g. `["created_at"]`).
+     *
+     * **Leave this unset** unless reproducing a pulled field; it defaults to `[]`.
+     * Each entry is resolved as a name and removed from the expanded shape, so an
+     * entry naming nothing hides nothing — a stored `[""]` is a real spelling that
+     * appears in the wild and round-trips verbatim here rather than being guessed at.
+     */
+    hidden?: readonly string[];
+    /** Field visibility in API output. Defaults to `"public"`. */
+    access?: FieldAccess;
+    style?: {
+        type: FieldStyleType;
+    };
+    /**
+     * Length bounds for an array field. Both members are `json`-typed in the
+     * engine, not numeric — the editor declares them as `json` and every consumer
+     * reads them through a numeric coercion (`+list.max`) — so a bound can arrive
+     * as `5` or as `"5"` and neither spelling is wrong.
+     *
+     * That is also why "unset" has no single spelling: an empty `json` control
+     * serializes to `""` on 8,814 fields in the sweep and to `{}` on two. Codegen
+     * elides the block whenever every member is blank in either form (see
+     * `hasNoListBounds`), so only a bound that is actually SET reaches this type.
+     */
+    list?: {
+        min?: string | number;
+        max?: string | number;
+    };
+    vector?: {
+        size: number;
+    };
+    /**
+     * Array/list field — stored as `style:{type:"list"}` (e.g. `int[]`, `object[]`).
+     * Ignored when an explicit `style` is given.
+     */
+    array?: boolean;
+    /** Nested fields for `type:"obj"` columns; each is itself a named, typed field. */
+    children?: NestedField[];
+    /**
+     * Per-column overrides applied to this field's EXPANSION, keyed by the
+     * expanded column's name. Meaningful on a merged field — an
+     * {@link input.dbLink} — where the engine expands a table's columns into
+     * request inputs and consults this map for each one.
+     *
+     * **Leave this unset** unless reproducing a pulled field; it defaults to `{}`.
+     * Xano's own CRUD scaffold writes it, so it is the common shape in a pulled
+     * workspace, not an edge case.
+     */
+    customize?: Readonly<Record<string, FieldCustomization>>;
+}
+/**
+ * One expanded column's override inside a merged field's {@link
+ * FieldOptions.customize} map.
+ *
+ * Every member restates what the column already declares, so an omitted member
+ * is not "inherit" — it is the stored default (`hidden:false`, `required:false`,
+ * `default:""`, no methods). Author the ones you mean to change and accept the
+ * rest, which is what the editor writes.
+ */
+interface FieldCustomization {
+    /** Drop this column from the expansion entirely. */
+    hidden?: boolean;
+    /** Whether the expanded input is required. */
+    required?: boolean;
+    /** Default for the expanded input; stored as a string (`0` → `"0"`). */
+    default?: string | number | boolean;
+    /** Methods/filters appended to the column's own, in the same spellings as {@link FieldOptions.methods}. */
+    methods?: readonly MethodSpec[];
+    /** Overrides for an object column's OWN children, keyed by child name. */
+    customize?: Readonly<Record<string, FieldCustomization>>;
+}
+/** A nested field inside an object column's `children` — a named, typed `FieldOptions`. */
+interface NestedField extends FieldOptions {
+    name: string;
+    type: string;
+}
+/**
+ * A field method/filter: a bare name (`"trim"`), a colon-form string carrying
+ * args (`"min:8"`, `"min:8:foo"` — first segment is the name, the rest are
+ * args), or an explicit `{ name, arg }` object.
+ */
+type MethodSpec = string | {
+    name: string;
+    arg?: Array<string | number>;
+};
+/**
+ * A type-narrowed {@link MethodSpec} for a field constructor: a bare method name
+ * from the field type's valid set `N` (`"trim"`), the colon-form carrying args
+ * (`"min:8"`), or the explicit `{ name, arg }` object — which stays a universal
+ * escape hatch for any name the per-type union doesn't enumerate. The per-type
+ * `N` unions live in `fields/generated/field-methods.generated.ts`.
+ */
+type MethodArg<N extends string> = N | `${N}:${string}` | {
+    name: string;
+    arg?: Array<string | number>;
+};
+/**
+ * An options type `T` with its `methods` array widened to `readonly`. Field/input
+ * constructors capture their options via a `const` type parameter so literal
+ * flags (`required`/`nullable`/`array`) survive for `InferInput`; `const` also
+ * makes any inline `methods: [...]` a readonly tuple, so a constructor's options
+ * constraint must accept readonly arrays. The runtime cast back to `FieldOptions`
+ * is safe — the encoder only ever reads (`.map`) the methods.
+ */
+type ReadonlyMethods<T, N extends string> = Omit<T, "methods"> & {
+    methods?: readonly MethodArg<N>[];
+};
+
+/**
+ * Value-type algebra for the typed descriptor layer (U1/U2).
+ *
+ * Input and column constructors (`input.*`, `f.*`) return a runtime descriptor
+ * of exactly `{ type, options }`. This module adds a **phantom brand** to those
+ * return types that carries, at the TYPE LEVEL only, the field's value type `V`
+ * and the literal options object `O` the caller passed. The brand props are
+ * optional and never assigned at runtime, so the emitted object is unchanged and
+ * every branded descriptor stays structurally assignable to the un-branded
+ * `FieldDescriptor` / `InputDescriptor` — existing consumers are unaffected.
+ *
+ * `InferInput` (see `../inputs/infer.ts`) reads these brands to turn a query's
+ * declared `input` map into the request-payload TS type. The same algebra powers
+ * nested-object inference, since object `children` are built from `f.*`.
+ */
+/**
+ * Opaque runtime value of a file input/column. The request payload carries a
+ * resource reference (path/metadata), not the raw bytes — model it structurally
+ * rather than as `unknown` so a consumer at least sees an object shape.
+ */
+interface XanoFileRef {
+    /** Vault path, e.g. `/vault/<…>/<name>`. Join it to your base URL — see {@link import("./file-url.js").fileUrl}. */
+    path?: string;
+    name?: string;
+    type?: string;
+    size?: number;
+    /** Storage visibility as stored on the column (`"public"` / `"private"`). */
+    access?: string;
+    /** Type-specific metadata — e.g. `{ width, height }` on an image. */
+    meta?: unknown;
+    /**
+     * ⚠ The engine's own absolute URL, which on a tenant-scoped environment omits
+     * the `/tenant/<name>` segment and 404s. Do NOT read it directly: pass the
+     * file to `fileUrl(file, baseUrl)`, which joins the correct `path` to the base
+     * URL your client already has (issue #31).
+     */
+    url?: string;
+}
+/**
+ * Opaque runtime value of a raw file **upload** (`input.file()`).
+ *
+ * Distinct from {@link XanoFileRef}, and the distinction matters: this is the
+ * bytes as they arrive on the request (multipart, base64, or a fetched URI). It
+ * is not yet stored anywhere and cannot be written to a file column. Pass it to
+ * a `s.storage.create_*` statement (`create_image`, `create_attachment`, …) to
+ * store it and get back the {@link XanoFileRef} a column holds.
+ */
+interface XanoFileUpload {
+    readonly __fileUpload?: never;
+}
+/**
+ * Marker value of a database-link input (`input.dbLink()`).
+ *
+ * Opaque on purpose: a dblink input does not bind a value of its own. The engine
+ * EXPANDS it into one input per column of the linked table, so a table with
+ * three columns turns one dblink entry into three request inputs. Read those by
+ * their own column names — `inp("email")`, not `inp("user__")`.
+ */
+interface XanoDbLink {
+    readonly __dbLink?: never;
+}
+/** Opaque runtime value of a geo input/column (a GeoJSON-shaped object). */
+/** One `{ lng, lat }` position, as the engine both accepts and returns. */
+interface XanoGeoPosition {
+    lng: number;
+    lat: number;
+}
+/**
+ * The value of an `f.geo.*` column: `{ type, data }`.
+ *
+ * Named for what it is rather than for GeoJSON, which this is NOT — the
+ * previous `XanoGeoJson` declared `{ type, coordinates }`, a shape the engine
+ * neither accepts nor returns (issue #208).
+ *
+ * The same shape works in BOTH directions, verified live: seeding
+ * `{ type: "point", data: { lng: 1, lat: 2 } }` reads back byte-identical, and
+ * a polygon seeded as `{ type: "poly", data: [{ lng, lat }, …] }` reads back
+ * with its ring closed for you. `type` is the engine's own abbreviation
+ * (`"point"`, `"poly"`, …), not the GeoJSON keyword, and `data` nests by
+ * geometry: an object for a point, an array of positions for a polygon.
+ *
+ * Raw WKT text (`c.text("POINT(1 2)")`) is also accepted wherever a value is
+ * taken — it is just not the typed path, because a read never returns one.
+ */
+interface XanoGeoValue {
+    type: string;
+    data: XanoGeoPosition | XanoGeoPosition[] | XanoGeoPosition[][];
+}
+/**
+ * Phantom brand intersected onto a descriptor's return type. `V` is the field's
+ * base value type; `O` is the literal options object captured via a `const` type
+ * parameter at the call site. Both props are optional and never present at
+ * runtime.
+ */
+interface TypeBrand<V, O> {
+    readonly __value?: V;
+    readonly __opts?: O;
+}
+/** The base value type carried by a branded descriptor `D` (before array/nullable). */
+type BrandValue<D> = D extends TypeBrand<infer V, unknown> ? V : unknown;
+/** The literal options object captured on a branded descriptor `D`. */
+type BrandOpts<D> = D extends TypeBrand<unknown, infer O> ? O : object;
+type ApplyArray<T, O> = O extends {
+    array: true;
+} ? T[] : T;
+type ApplyNullable<T, O> = O extends {
+    nullable: true;
+} ? T | null : T;
+/**
+ * The full value type of a single branded descriptor `D`: its base value with
+ * `array` and `nullable` applied. (Optionality of the *key* is a map-level
+ * concern handled by {@link FromFieldMap}.)
+ */
+type ValueOf<D> = ApplyNullable<ApplyArray<BrandValue<D>, BrandOpts<D>>, BrandOpts<D>>;
+/** Keys whose descriptor options declare `required: true`. */
+type RequiredKeys<M> = {
+    [K in keyof M]: BrandOpts<M[K]> extends {
+        required: true;
+    } ? K : never;
+}[keyof M];
+/** Keys without `required: true` — optional in the produced payload type. */
+type OptionalKeys<M> = Exclude<keyof M, RequiredKeys<M>>;
+/**
+ * Turn a named map of branded descriptors into an object type: required inputs
+ * become required keys, everything else becomes an optional (`?`) key. Used both
+ * for a query's top-level `input` map and for nested `object` children.
+ */
+type FromFieldMap<M> = Prettify<{
+    [K in RequiredKeys<M>]: ValueOf<M[K]>;
+} & {
+    [K in OptionalKeys<M>]?: ValueOf<M[K]>;
+}>;
+/**
+ * Turn a named map of branded descriptors into a **row** type — the read shape
+ * of a table. Unlike {@link FromFieldMap} (a request payload, where `required`
+ * gates key optionality), every declared column is present on a returned row, so
+ * all keys are required here; `nullable`/`array` still apply via {@link ValueOf}.
+ * Powers `InferRow<typeof table>` (see `../kinds/table.ts`).
+ */
+type RowFromFieldMap<M> = Prettify<{
+    [K in keyof M]: ValueOf<M[K]>;
+}>;
+/** Flatten an intersection into a single object literal for readable hovers. */
+type Prettify<T> = {
+    [K in keyof T]: T[K];
+} & {};
+
+declare const REFERENCEABLE_KINDS: Set<string>;
+/**
+ * A reference to another workspace object: its def handle, or a bare name.
+ *
+ * A def may carry an explicit `guid` (its Xano identity). When present it's used
+ * verbatim; otherwise the guid is derived from `name`. Pass def handles (which
+ * carry the `guid`) rather than bare names when an object sets an explicit guid,
+ * so the reference and the target agree on the *same* guid.
+ */
+type ObjectRef = string | {
+    name: string;
+    guid?: string;
+};
+/**
+ * The guid for a `(type, name)` pair. A seeded `xano.lock` override wins (the
+ * lock freezes identity across renames — see lock/store.ts); otherwise the
+ * deterministic 32-char hex derivation. Every reference and every emitted
+ * target flows through here, so a lock override propagates everywhere by
+ * construction — including guids embedded inside strings at authoring time.
+ */
+declare function deriveGuid(type: string, name: string): string;
+/** Resolve a reference target (def handle or name) to the referenced object's guid. */
+declare function resolveRef(type: string, target: ObjectRef): string;
+
+/**
+ * AUTO-GENERATED by scripts/codegen-field-methods.ts — DO NOT EDIT BY HAND.
+ *
+ * Per-field-type method-name unions, distilled from the engine's column-create
+ * API schema (the per-type field-schema definitions). Each
+ * `f.<type>` / `input.<type>` constructor types its `methods` against the
+ * matching union so only names valid for that field type are accepted (the
+ * explicit `{ name, arg }` form remains a universal escape hatch).
+ *
+ * Regenerate with `npm run codegen:methods` (`-- --refresh` to re-distill upstream).
+ */
+/** Per-field-type method metadata (method name → colon-form arg type; `bool` = flag, no arg). */
+declare const FIELD_METHODS: Readonly<Record<string, Readonly<Record<string, string>>>>;
+/** Field methods valid on `decimal` fields. */
+type DecimalMethod = "max" | "min";
+/** Field methods valid on `email` fields. */
+type EmailMethod = "lower" | "trim";
+/** Field methods valid on `int` fields. */
+type IntMethod = "max" | "min";
+/** Field methods valid on `password` fields. */
+type PasswordMethod = "max" | "min" | "minAlpha" | "minDigit" | "minLowerAlpha" | "minSymbol" | "minUpperAlpha" | "salt";
+/** Field methods valid on `tableRef` fields. */
+type TableRefMethod = "max" | "min";
+/** Field methods valid on `text` fields. */
+type TextMethod = "alphaOk" | "digitOk" | "lower" | "max" | "min" | "ok" | "pattern" | "startsWith" | "trim" | "upper";
+/** Field methods valid on `vector` fields. */
+type VectorMethod = "max" | "min";
+
+/**
+ * Rich field-type catalog (`f.*`). A typed, validated authoring surface over the
+ * shared field encoder. Each constructor returns a {@link FieldDescriptor}
+ * (`{ type, options }`) carrying the **stored** type string — the engine's
+ * author-facing names differ from what it persists, so this layer applies the
+ * authoritative mapping (the engine's stored-type map):
+ *
+ *   object → obj · timestamp → epochms · image → blob_img ·
+ *   video → blob_video · audio → blob_audio · attachment → blob
+ *
+ * Every other type (text/int/decimal/bool/uuid/date/email/password/json/enum/
+ * vector/geo_*) is stored under its own name. Columns and inputs both consume
+ * descriptors; the per-context differences (`customize`, `market_item`,
+ * `description`) are still applied by {@link encodeField}.
+ */
+
+/** A typed field, ready to attach to a column/input name. */
+interface FieldDescriptor {
+    /** The **stored** type string (post-mapping), e.g. `blob_img`, `epochms`. */
+    type: string;
+    options: FieldOptions;
+}
+/** A named map of fields — used for table schemas and object children. */
+type FieldMap = Record<string, FieldDescriptor>;
+/** Options accepted by every catalog constructor (no `values`/`children`/`vector` — those are positional). */
+type FieldOpts = Omit<FieldOptions, "values" | "children" | "vector">;
+/**
+ * {@link FieldOpts} with `methods` narrowed to the field type's valid method set
+ * `N` (see {@link MethodArg}). Types with no engine-declared methods use
+ * `MethodOpts<never>`, leaving only the `{ name, arg }` escape hatch.
+ */
+type MethodOpts<N extends string> = Omit<FieldOpts, "methods"> & {
+    methods?: MethodArg<N>[];
+};
+/** {@link MethodOpts} made safe to capture under a `const` type parameter (see {@link ReadonlyMethods}). */
+type ConstMethodOpts<N extends string> = ReadonlyMethods<MethodOpts<N>, N>;
+/** Convert a named field map into the encoder's `NestedField[]` form. */
+declare function toNestedFields(map: FieldMap): NestedField[];
+/**
+ * The stored scalar type of a `tableRef` FK, derived from its `type` option: a
+ * `uuid`-keyed reference stores a `string`, everything else (the default `int`)
+ * stores a `number`. Keeps `InferRow` honest — a FK column is the referenced
+ * table's PK value, never the loose `string | number`.
+ */
+type TableRefValue<O> = "uuid" extends (O extends {
+    type: infer T;
+} ? T : never) ? string : number;
+/** The rich field-type catalog. */
+declare const f: {
+    readonly text: <const O extends ConstMethodOpts<TextMethod> = Record<string, never>>(options?: O) => FieldDescriptor & TypeBrand<string, O>;
+    readonly int: <const O extends ConstMethodOpts<IntMethod> = Record<string, never>>(options?: O) => FieldDescriptor & TypeBrand<number, O>;
+    readonly decimal: <const O extends ConstMethodOpts<DecimalMethod> = Record<string, never>>(options?: O) => FieldDescriptor & TypeBrand<number, O>;
+    readonly bool: <const O extends ConstMethodOpts<never> = Record<string, never>>(options?: O) => FieldDescriptor & TypeBrand<boolean, O>;
+    readonly uuid: <const O extends ConstMethodOpts<never> = Record<string, never>>(options?: O) => FieldDescriptor & TypeBrand<string, O>;
+    readonly date: <const O extends ConstMethodOpts<never> = Record<string, never>>(options?: O) => FieldDescriptor & TypeBrand<string, O>;
+    readonly email: <const O extends ConstMethodOpts<EmailMethod> = Record<string, never>>(options?: O) => FieldDescriptor & TypeBrand<string, O>;
+    /** Password field; defaults to `access:"internal"` (the engine's stored default). */
+    readonly password: <const O extends ConstMethodOpts<PasswordMethod> = Record<string, never>>(options?: O) => FieldDescriptor & TypeBrand<string, O>;
+    /**
+     * JSON column. Accepts an optional nested `children` schema — the structure the
+     * editor shows when a `json` field is expanded, and what a pulled workspace
+     * carries.
+     *
+     * `children` is spelled as an ARRAY of named, typed fields rather than the
+     * `FieldMap` {@link FieldCatalog.object} takes positionally. The two are not
+     * interchangeable: an object column's children are the column's own schema,
+     * while a json column's are a description of the shape stored inside it, which
+     * the engine persists in the order given. That order is part of the stored
+     * bytes, and a map does not preserve it.
+     *
+     * Without this there is no way to author a structured JSON column at all
+     * (issue #135).
+     */
+    readonly json: <const O extends ConstMethodOpts<never> & {
+        children?: readonly NestedField[];
+    } = Record<string, never>>(options?: O) => FieldDescriptor & TypeBrand<unknown, O>;
+    /** Epoch-millisecond timestamp (authored as `timestamp`). */
+    readonly timestamp: <const O extends ConstMethodOpts<never> = Record<string, never>>(options?: O) => FieldDescriptor & TypeBrand<number, O>;
+    /** Image file resource (stored `blob_img`). */
+    readonly image: <const O extends ConstMethodOpts<never> = Record<string, never>>(options?: O) => FieldDescriptor & TypeBrand<XanoFileRef, O>;
+    /** Video file resource (stored `blob_video`). */
+    readonly video: <const O extends ConstMethodOpts<never> = Record<string, never>>(options?: O) => FieldDescriptor & TypeBrand<XanoFileRef, O>;
+    /** Audio file resource (stored `blob_audio`). */
+    readonly audio: <const O extends ConstMethodOpts<never> = Record<string, never>>(options?: O) => FieldDescriptor & TypeBrand<XanoFileRef, O>;
+    /** Generic file attachment (stored `blob`). */
+    readonly attachment: <const O extends ConstMethodOpts<never> = Record<string, never>>(options?: O) => FieldDescriptor & TypeBrand<XanoFileRef, O>;
+    readonly geo: {
+        readonly point: <const O extends ConstMethodOpts<never> = Record<string, never>>(options?: O) => FieldDescriptor & TypeBrand<XanoGeoValue, O>;
+        readonly multipoint: <const O extends ConstMethodOpts<never> = Record<string, never>>(options?: O) => FieldDescriptor & TypeBrand<XanoGeoValue, O>;
+        readonly linestring: <const O extends ConstMethodOpts<never> = Record<string, never>>(options?: O) => FieldDescriptor & TypeBrand<XanoGeoValue, O>;
+        readonly multilinestring: <const O extends ConstMethodOpts<never> = Record<string, never>>(options?: O) => FieldDescriptor & TypeBrand<XanoGeoValue, O>;
+        readonly polygon: <const O extends ConstMethodOpts<never> = Record<string, never>>(options?: O) => FieldDescriptor & TypeBrand<XanoGeoValue, O>;
+        readonly multipolygon: <const O extends ConstMethodOpts<never> = Record<string, never>>(options?: O) => FieldDescriptor & TypeBrand<XanoGeoValue, O>;
+    };
+    /**
+     * Enum field. `values` may be empty — that is an enum column added in the
+     * editor and not yet given its options, which the engine stores and which
+     * appears in the survey corpus. Refusing it made the SDK stricter than the
+     * engine and cost a real table its readable form.
+     *
+     * An empty `values` brands the column `never` — an enum permitting nothing can
+     * hold nothing. Note what that becomes downstream: `InferRow` surfaces the
+     * column as `undefined`, not `never`, so a read-time narrow written against
+     * `never` (`if (row.e === "x")`) is dead differently than it looks.
+     */
+    readonly enum: <const V extends ReadonlyArray<string | number>, const O extends ConstMethodOpts<never> = Record<string, never>>(values: V, options?: O) => FieldDescriptor & TypeBrand<V[number], O>;
+    /** Vector field; `size` (>= 1) is the embedding dimensionality. */
+    readonly vector: <const O extends ConstMethodOpts<VectorMethod> = Record<string, never>>(size: number, options?: O) => FieldDescriptor & TypeBrand<number[], O>;
+    /** Nested object field (stored `obj`); `children` is a named field map. */
+    readonly object: <const C extends FieldMap, const O extends ConstMethodOpts<never> = Record<string, never>>(children: C, options?: O) => FieldDescriptor & TypeBrand<FromFieldMap<C>, O>;
+    /**
+     * Table-reference (foreign-key) field — the column holds the referenced
+     * table's primary key. The engine persists the link as a trailing `@` method
+     * carrying the target table's id (`{name:"@", arg:["dbo=<guid>"]}`); on import
+     * it parses that back into the column's `tableref_id`. The reference resolves to the
+     * table's deterministic guid via the shared cross-object resolver, so it
+     * agrees with the target table's payload `guid` with no shared registry.
+     *
+     * Defaults to an `int` column (matching an `int` primary key); pass
+     * `{ type: "uuid" }` to reference a uuid-keyed table. A reference column may
+     * only be `int` or `uuid` — the two valid primary-key types.
+     *
+     * @param table The referenced table (a `table()` def handle or its bare name).
+     *   For a **self-reference** (e.g. `tweets.reply_to → tweets`), the table's
+     *   `const` binding isn't assigned yet inside its own initializer — using the
+     *   handle throws a "used before declaration" error. Pass the **bare name**
+     *   instead: `f.tableRef("tweets", { type: "int" })`. Identity guids derive
+     *   from `(type, name)`, so the name form resolves to the same guid.
+     *
+     * Byte-verified whole-object against a persisted table readback
+     * (`test/fixtures/tables/ex_field_table_ref.json`, asserted in
+     * `test/conformance/kinds-corpus.test.ts`): the `@` method carries
+     * `disabled:false`, sits last in `methods`, and its `dbo=` arg is the target
+     * table's payload guid.
+     *
+     * The engine asserts the referenced table's primary-key type matches
+     * (int↔int, uuid↔uuid). When the target is passed as a **def handle** its
+     * `idType` is in hand, so a mismatch throws here instead of surfacing as an
+     * import failure. The bare-name form (self-references) carries no schema —
+     * there is nothing to check against, and it is not guessed at.
+     */
+    readonly tableRef: <const O extends ConstMethodOpts<TableRefMethod> & {
+        type?: "int" | "uuid";
+    } = Record<string, never>>(table: ObjectRef, options?: O) => FieldDescriptor & TypeBrand<TableRefValue<O>, O>;
+};
+
+/**
+ * `obj({...})` — a **dynamic** object value: an object literal whose members can
+ * be live references (`inp`/`ref`/`auth`/`col`) or constants. This is the
+ * missing sibling of `c.obj` (issue #42): `c.obj` takes plain JSON only and
+ * rejects nested tagged values, so it can't express `{ id: inp("id") }`.
+ *
+ * Xano stores a dynamic object as a single value with `tag: "const:expr2"` whose
+ * `value` is the object rendered as a **XanoScript expression string** (verified
+ * against the Xano engine's stored inline-value format). So `obj`
+ * serializes each member to its XanoScript form (`$input.x`, `$var.x`, `$auth`,
+ * `$db.col`, quoted strings, numbers) and wraps them in `{ … }`.
+ *
+ * Why `const:expr2` and not a structured `const:obj`: the Xano runtime value
+ * evaluator resolves `const:obj` by JSON-decoding its value — it
+ * treats the value as a *static JSON string*, so dynamic members (`$input.x`)
+ * would never resolve. Only `const:expr2` is run through the expression parser
+ * (it normalizes to `const:expr` and evaluates), so it is the sole
+ * representation that resolves live references inside an object literal. That
+ * choice is therefore runtime-verified, not a preference.
+ *
+ * The rendered string form (spacing/escaping) is now golden-verified: the
+ * `call_agent` object-args fixture in the conformance corpus pins the exact
+ * `const:expr` string this encoder emits for `obj({ question: inp(...) })`.
+ *
+ * **Supported members:** `inp()`, `ref()`, `auth()`, `col()`, `env()` /
+ * `setting()` / `sys.*`, `c.now()`, `c.text/int/decimal/bool/null`, nested
+ * `obj`-style records, and arrays of those — each optionally carrying a
+ * **filter chain**, which renders as the expression language's own postfix pipe
+ * (`$var.row|get:"address.city"`).
+ *
+ * The filter chain used to throw, and the rejection was wrong (#222). It
+ * collided constantly, because `db.get` binds `null` on a miss — the SDK's own
+ * headline gotcha — so almost every object built from a `db.get` result needs a
+ * null-safe drill, which compiles through the `get` filter. One team counted
+ * twenty pure-plumbing `s.set_var` statements written to work around it.
+ *
+ * The representation was never the obstacle: the engine's own parser stores
+ * `{ …, goals: [$q.goal_1, …]|filter:$$ != null, … }` as ONE `const:expr2`
+ * string, so a per-member chain is exactly what it carries. Nothing had to
+ * change in the engine; the SDK was guessing that it could not.
+ *
+ * **On evidence.** The value of an `expr2` is an expression string the engine
+ * parses — it is NOT XanoScript, and nothing validates its contents ahead of a
+ * live run. So what backs this is the engine's own parser fixtures (paired
+ * source → stored JSON), which show the exact string its tooling produces. A
+ * rendering outside that set is not "probably fine"; it is unverified. Keep the
+ * emitted grammar to shapes a fixture demonstrates.
+ *
+ * What still throws: a filter argument carrying its OWN chain (a trailing `|`
+ * binds to the whole value, so it cannot be written without changing meaning),
+ * a **disabled** filter (an expression string has nowhere to record that), and
+ * the remaining exotic tags (`output`/`response`/`toolset`/`reg`). Build those
+ * in a prior stack step and reference them with `ref`.
+ */
+
+/**
+ * A member of an {@link obj} literal — a {@link Value}, a raw scalar literal
+ * (`string`/`number`/`boolean`, coerced to the matching constant), a nested
+ * record, or an array. Raw scalars let `obj({ max_age_days: 3 })` and
+ * `obj({ greeting: "hi" })` *just work* without wrapping each in `c.int`/`c.text`.
+ */
+type ObjMember = Value | string | number | boolean | ObjInput | ObjMember[];
+/** The record shape {@link obj} accepts: keys → members. */
+interface ObjInput {
+    [key: string]: ObjMember;
+}
+/**
+ * A {@link Value} that also carries, **at the type level only**, the member
+ * record it was built from (`obj({ id: ref("u.id") })` → `ObjValue<{ id:
+ * RefValue<"u.id"> }>`). The `__obj` carrier is phantom — never present at
+ * runtime — and exists so `InferResponse` can recurse into the members and
+ * resolve each one the way it resolves a top-level response key (issue #118).
+ *
+ * Before this, `obj()` returned a bare `Value`: the members were erased at the
+ * signature, so the resolver saw no `__ref` to trace and every member landed on
+ * the `unknown` floor. `{ user: obj({ id: ref("u.id") }) }` derived `{ user:
+ * unknown }` while the identical refs written as object-literal keys derived
+ * `{ id: number | null }` — and the mismatch only surfaced downstream, as
+ * `unknown` flowing into a caller that had asked for a type.
+ *
+ * Because it is a subtype of `Value`, every existing `obj(...)` use — a request
+ * body, an agent's `args`, a statement field — keeps type-checking unchanged.
+ */
+type ObjValue<T extends ObjInput = ObjInput> = Value & {
+    readonly __obj: T;
+};
+/**
+ * Build a dynamic object {@link Value} from a record of members. Members may be
+ * references (`inp`/`ref`/`auth`/`col`), constants (`c.*`), nested records, or
+ * arrays. Emits `tag:"const:expr2"` — the engine's dynamic-object representation.
+ *
+ * ```ts
+ * obj({ id: inp("id"), name: c.text("Bob"), tags: [c.text("a"), ref("t")] })
+ * // → { value: '{ id: $input.id, name: "Bob", tags: ["a", $var.t] }', tag: "const:expr2", filters: [] }
+ * ```
+ *
+ * The member record is preserved on the return type as {@link ObjValue}, so a
+ * response built with `obj()` traces through `InferResponse` exactly as the same
+ * members written as object-literal keys would (issue #118). A dynamically-built
+ * `ObjInput` has no literal to read and degrades to unknown-valued members.
+ */
+declare function obj<T extends ObjInput>(fields: T): ObjValue<T>;
+
+/**
+ * Response → `result[]` mapping, shared by every response-bearing kind
+ * (function, query, tool, middleware, and the response-bearing triggers).
+ * Extracted from the MVP's compile.ts so kinds beyond function can reuse it.
+ */
+
+/**
+ * A member of a record response — a {@link Value}, or a nested plain object
+ * literal which is auto-wrapped via {@link obj} (so `response: { user: { id:
+ * ref(x) } }` just works instead of failing tsc against `TaggedValue`; #133).
+ */
+type ResponseMember = Value | ObjInput;
+/** A single `Value` response, or a record of named result items. */
+type ResponseDef = Value | Record<string, ResponseMember>;
+/** Map a response into `result[]`: one unnamed item for a single value, or
+ * one named item per key for a record. A record member that is a nested plain
+ * object is auto-wrapped via {@link obj} (a dynamic `const:expr2` value). */
+declare function encodeResponse(response: ResponseDef | undefined): ResultItemXdo[];
+
+export { type RowFromFieldMap as $, type MethodOpts as A, type BrandOpts as B, type CacheXdo as C, type DecimalMethod as D, type EmailMethod as E, type FunctionXdo as F, type MethodSpec as G, type HistoryXdo as H, type InputXdo as I, type MethodXdo as J, type MockEntry as K, type ListBoundsXdo as L, type MethodArg as M, type MockMap as N, type MockXdo as O, type ObjInput as P, type ObjMember as Q, REFERENCEABLE_KINDS as R, type ObjValue as S, type ObjectRef as T, type PasswordMethod as U, type Value as V, type PersistedFunctionRow as W, type RefValue as X, type RegexValue as Y, type ResponseDef as Z, type ResultItemXdo as _, FIELD_METHODS as a, type StackItemXdo as a0, type Statement as a1, type StatementAnnotations as a2, type StatementInputXdo as a3, type StatementOptions as a4, TAGS as a5, TEST_EXPECT_TYPES as a6, type TableRefMethod as a7, type Tag as a8, type TaggedValue as a9, setting as aA, statements as aB, sys as aC, test as aD, toolset as aE, withFilters as aF, type FieldOptions as aG, type Prettify as aH, type ReadonlyMethods as aI, type XanoFileUpload as aJ, type XanoDbLink as aK, type ConstMethodOpts as aL, type AsShapeBrand as aM, type TestDef as aa, type TestExpect as ab, type TestExpectType as ac, type TestXdo as ad, type TextFormat as ae, type TextMethod as af, type TypeBrand as ag, type ValueOf as ah, type VectorMethod as ai, type XanoFileRef as aj, type XanoGeoPosition as ak, type XanoGeoValue as al, annotate as am, auth as an, c as ao, caught as ap, col as aq, env as ar, expect as as, f as at, filter as au, inp as av, obj as aw, out as ax, ref as ay, resp as az, encodeStatement as b, type BrandValue as c, deriveGuid as d, encodeResponse as e, type CaughtField as f, getStatementFactory as g, type ConditionalContext as h, isRegisteredStatement as i, type ConditionalElifContext as j, type ExprGroup as k, type ExprNode as l, type ExprOperand as m, type ExprStatement as n, type FieldAccess as o, type FieldDescriptor as p, type FieldMap as q, resolveRef as r, type FieldOpts as s, toNestedFields as t, type FieldStyleType as u, type FieldXdo as v, type FilterXdo as w, type FilteredValue as x, type FromFieldMap as y, type IntMethod as z };