@xano/sdk 1.0.0

package/dist/xdo-CxDr2Q1C.d.ts

@@ -0,0 +1,1371 @@
+/**
+ * GENERATED by `npm run codegen:query-filters` — do not edit.
+ *
+ * `qf.*` — the filters a **db-query expression** resolves. They compile into the
+ * SQL statement the database runs, which is why they are a different registry
+ * from `fl.*` (the runtime value pipeline) and why a name from one does not
+ * resolve in the other.
+ *
+ * Reach them from a query's own expression surfaces — `eval`, `sort`, `where`:
+ *
+ * ```ts
+ * s.db.query({
+ *   table: chunk,
+ *   eval: [{ name: "embedding", as: "distance", filters: [qf.vector_cos_distance(inp("q"))] }],
+ *   sort: [{ sortBy: "distance", dir: "asc" }],   // nearest first
+ * })
+ * ```
+ *
+ * Each factory returns the same `{ name, arg }` step the raw form builds, so the
+ * emitted bytes are identical — what changes is that the name, the argument
+ * COUNT and (where the engine enumerates it) the argument's accepted spellings
+ * are checked where you write them instead of at request time.
+ *
+ * Signatures come from the engine's filter/aggregate classes, which enforce an
+ * exact argument count. Where a class and the YAML catalog disagree the class
+ * wins: the per-part timestamp extractors (`qf.epochms_month`, …) take a
+ * timezone the catalog does not mention, and `qf.round`'s precision is required.
+ */
+
+/** A bare JS literal a query filter argument accepts in place of a {@link Value}. */
+type Scalar = string | number | boolean;
+/**
+ * One step of a query-expression pipeline — structurally the `DbEvalFilter` an
+ * `eval`/`sort`/`where` takes. The phantom name parameter keeps the emitted
+ * step traceable to the factory that built it.
+ */
+interface QueryFilter<N extends string = string> {
+    readonly name: N;
+    readonly arg?: Value[];
+}
+/** Every name `qf` offers. */
+declare const QUERY_FILTER_NAMES: readonly string[];
+/**
+ * The subset that are AGGREGATES — computed by the database over a grouped
+ * result, so they belong in an aggregate query's `eval`/`group` and nowhere
+ * else.
+ */
+declare const QUERY_AGGREGATE_NAMES: readonly string[];
+/**
+ * The TypeScript type each name's declared result reads as — what an aggregate
+ * `eval`/`group` alias types to when this is its last step. A `json`
+ * result is absent (not statically known).
+ */
+interface QueryFilterResults {
+    add: number;
+    array_length: number;
+    at_timezone: number;
+    avg: number;
+    between_filter: boolean;
+    ceil: number;
+    concat: string;
+    count: number;
+    count_distinct: number;
+    covers: boolean;
+    distance: number;
+    div: number;
+    epochms_add_day: number;
+    epochms_add_hour: number;
+    epochms_add_minute: number;
+    epochms_add_month: number;
+    epochms_add_sec: number;
+    epochms_add_year: number;
+    epochms_day: number;
+    epochms_dow: number;
+    epochms_doy: number;
+    epochms_epoch_day: number;
+    epochms_epoch_hour: number;
+    epochms_epoch_minute: number;
+    epochms_epoch_sec: number;
+    epochms_hour: number;
+    epochms_minute: number;
+    epochms_month: number;
+    epochms_sub_day: number;
+    epochms_sub_hour: number;
+    epochms_sub_minute: number;
+    epochms_sub_month: number;
+    epochms_sub_sec: number;
+    epochms_sub_year: number;
+    epochms_week: number;
+    epochms_year: number;
+    floor: number;
+    length: number;
+    lower: string;
+    max: number;
+    max_timestamp: number;
+    median: number;
+    min: number;
+    min_timestamp: number;
+    mul: number;
+    round: number;
+    search_rank: number;
+    sub: number;
+    substr: string;
+    sum: number;
+    time: number;
+    to_decimal: number;
+    to_int: number;
+    to_text: string;
+    to_timestamp: number;
+    unaccent: string;
+    upper: string;
+    vector_cos_distance: number;
+    vector_cos_similarity: number;
+    vector_hamming_distance: number;
+    vector_inner_product: number;
+    vector_jaccard_distance: number;
+    vector_l1_distance: number;
+    vector_l2_distance: number;
+    vector_negative_inner_product: number;
+    within: boolean;
+}
+/** The engine's declared shape for each name, for the manifest and the docs. */
+declare const QUERY_FILTER_SPECS: Readonly<Record<string, {
+    kind: string;
+    args: {
+        name: string;
+        type: string;
+        enum?: readonly string[];
+    }[];
+    arity: number;
+    result?: string;
+    entry?: readonly string[];
+}>>;
+declare const qf: {
+    readonly add: (value: Scalar | Value) => QueryFilter<"add">;
+    readonly array_length: () => QueryFilter<"array_length">;
+    readonly at_timezone: (value: Scalar | Value) => QueryFilter<"at_timezone">;
+    readonly avg: () => QueryFilter<"avg">;
+    readonly between_filter: (left: Scalar | Value, right: Scalar | Value) => QueryFilter<"between_filter">;
+    readonly ceil: () => QueryFilter<"ceil">;
+    readonly coalesce: (value: Scalar | Value) => QueryFilter<"coalesce">;
+    readonly concat: (value: Scalar | Value) => QueryFilter<"concat">;
+    readonly count: () => QueryFilter<"count">;
+    readonly count_distinct: () => QueryFilter<"count_distinct">;
+    readonly covers: (point: Scalar | Value) => QueryFilter<"covers">;
+    readonly distance: (point: Scalar | Value) => QueryFilter<"distance">;
+    readonly div: (value: Scalar | Value) => QueryFilter<"div">;
+    readonly epochms_add_day: (amount: Scalar | Value) => QueryFilter<"epochms_add_day">;
+    readonly epochms_add_hour: (amount: Scalar | Value) => QueryFilter<"epochms_add_hour">;
+    readonly epochms_add_minute: (amount: Scalar | Value) => QueryFilter<"epochms_add_minute">;
+    readonly epochms_add_month: (amount: Scalar | Value) => QueryFilter<"epochms_add_month">;
+    readonly epochms_add_sec: (amount: Scalar | Value) => QueryFilter<"epochms_add_sec">;
+    readonly epochms_add_year: (amount: Scalar | Value) => QueryFilter<"epochms_add_year">;
+    readonly epochms_day: (timezone: Scalar | Value) => QueryFilter<"epochms_day">;
+    readonly epochms_dow: (timezone: Scalar | Value) => QueryFilter<"epochms_dow">;
+    readonly epochms_doy: (timezone: Scalar | Value) => QueryFilter<"epochms_doy">;
+    readonly epochms_epoch_day: () => QueryFilter<"epochms_epoch_day">;
+    readonly epochms_epoch_hour: () => QueryFilter<"epochms_epoch_hour">;
+    readonly epochms_epoch_minute: () => QueryFilter<"epochms_epoch_minute">;
+    readonly epochms_epoch_sec: () => QueryFilter<"epochms_epoch_sec">;
+    readonly epochms_hour: (timezone: Scalar | Value) => QueryFilter<"epochms_hour">;
+    readonly epochms_minute: (timezone: Scalar | Value) => QueryFilter<"epochms_minute">;
+    readonly epochms_month: (timezone: Scalar | Value) => QueryFilter<"epochms_month">;
+    readonly epochms_sub_day: (amount: Scalar | Value) => QueryFilter<"epochms_sub_day">;
+    readonly epochms_sub_hour: (amount: Scalar | Value) => QueryFilter<"epochms_sub_hour">;
+    readonly epochms_sub_minute: (amount: Scalar | Value) => QueryFilter<"epochms_sub_minute">;
+    readonly epochms_sub_month: (amount: Scalar | Value) => QueryFilter<"epochms_sub_month">;
+    readonly epochms_sub_sec: (amount: Scalar | Value) => QueryFilter<"epochms_sub_sec">;
+    readonly epochms_sub_year: (amount: Scalar | Value) => QueryFilter<"epochms_sub_year">;
+    readonly epochms_week: (timezone: Scalar | Value) => QueryFilter<"epochms_week">;
+    readonly epochms_year: (timezone: Scalar | Value) => QueryFilter<"epochms_year">;
+    readonly floor: () => QueryFilter<"floor">;
+    readonly length: () => QueryFilter<"length">;
+    readonly lower: () => QueryFilter<"lower">;
+    readonly max: () => QueryFilter<"max">;
+    readonly max_timestamp: () => QueryFilter<"max_timestamp">;
+    readonly median: () => QueryFilter<"median">;
+    readonly min: () => QueryFilter<"min">;
+    readonly min_timestamp: () => QueryFilter<"min_timestamp">;
+    readonly mul: (value: Scalar | Value) => QueryFilter<"mul">;
+    readonly round: (precision: Scalar | Value) => QueryFilter<"round">;
+    readonly search_rank: (q: Scalar | Value) => QueryFilter<"search_rank">;
+    readonly sub: (value: Scalar | Value) => QueryFilter<"sub">;
+    readonly substr: (start: Scalar | Value, length: Scalar | Value) => QueryFilter<"substr">;
+    readonly sum: () => QueryFilter<"sum">;
+    readonly time: (option: "century" | "day" | "decade" | "dow" | "doy" | "epoch" | "hour" | "isodow" | "isoyear" | "microseconds" | "millennium" | "milliseconds" | "minute" | "month" | "quarter" | "second" | "timezone" | "timezone_hour" | "timezone_minute" | "week" | "year" | Value) => QueryFilter<"time">;
+    readonly to_decimal: () => QueryFilter<"to_decimal">;
+    readonly to_distinct_list: () => QueryFilter<"to_distinct_list">;
+    readonly to_distinct_list_asc: () => QueryFilter<"to_distinct_list_asc">;
+    readonly to_distinct_list_desc: () => QueryFilter<"to_distinct_list_desc">;
+    readonly to_int: () => QueryFilter<"to_int">;
+    readonly to_list: () => QueryFilter<"to_list">;
+    readonly to_list_asc: () => QueryFilter<"to_list_asc">;
+    readonly to_list_desc: () => QueryFilter<"to_list_desc">;
+    readonly to_text: () => QueryFilter<"to_text">;
+    readonly to_timestamp: () => QueryFilter<"to_timestamp">;
+    readonly unaccent: () => QueryFilter<"unaccent">;
+    readonly upper: () => QueryFilter<"upper">;
+    readonly vector_cos_distance: (vector: Scalar | Value) => QueryFilter<"vector_cos_distance">;
+    readonly vector_cos_similarity: (vector: Scalar | Value) => QueryFilter<"vector_cos_similarity">;
+    readonly vector_hamming_distance: (vector: Scalar | Value) => QueryFilter<"vector_hamming_distance">;
+    readonly vector_inner_product: (vector: Scalar | Value) => QueryFilter<"vector_inner_product">;
+    readonly vector_jaccard_distance: (vector: Scalar | Value) => QueryFilter<"vector_jaccard_distance">;
+    readonly vector_l1_distance: (vector: Scalar | Value) => QueryFilter<"vector_l1_distance">;
+    readonly vector_l2_distance: (vector: Scalar | Value) => QueryFilter<"vector_l2_distance">;
+    readonly vector_negative_inner_product: (vector: Scalar | Value) => QueryFilter<"vector_negative_inner_product">;
+    readonly within: (point: Scalar | Value, radius: Scalar | Value) => QueryFilter<"within">;
+};
+
+/**
+ * The shared tagged-value primitive. 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 Xano SDK 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 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;
+};
+/**
+ * An `auth(path)` read, carrying its path at the type level only (phantom
+ * `__auth`) so `InferResponse` types it from a query's auth table row.
+ */
+type AuthValue<Path extends string = string> = Value & {
+    readonly __auth: Path;
+};
+/**
+ * A {@link Value} whose tag has no object-literal form, so `obj()` refuses it
+ * as a member — at the type level through this phantom `__notObjMember` carrier
+ * (never present at runtime), and at runtime by the tag. Bind it with
+ * `s.set_var` first and `ref()` the variable.
+ */
+type NotObjMember<Tag extends string> = Value & {
+    readonly __notObjMember: Tag;
+};
+/**
+ * A `caught(path)` read, carrying its path at the type level only (phantom
+ * `__caught`) so `InferResponse` types it: `code`, `message` and `name` are
+ * strings, `result` is whatever payload was attached.
+ */
+type CaughtValue<Path extends string = string> = NotObjMember<"trycatch"> & {
+    readonly __caught: Path;
+};
+/** What `caught(path)` reads, at the type level. */
+type CaughtShape<Path extends string> = Path extends "code" | "message" | "name" ? string : Path extends "" ? {
+    code: string;
+    message: string;
+    name: string;
+    result: unknown;
+} : unknown;
+/**
+ * A {@link Value} that carries, at the type level only, the input it reads
+ * (`inp("email")` → `InpValue<"email">`), so `InferResponse` types it from the
+ * def's declared `input` instead of `unknown`. Phantom, like `__ref`.
+ */
+type InpValue<Name extends string = string> = Value & {
+    readonly __inp: 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. 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").
+ * `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. 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).": 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 NotJson ? NotPlainJson : T extends readonly (infer E)[] ? readonly RejectValues<E>[] : T extends object ? {
+    [K in keyof T]: RejectValues<T[K]>;
+} : T;
+/**
+ * JS values `JSON.stringify` cannot carry faithfully: a function or symbol
+ * vanishes (or reads `null` in a list), a bigint throws, a `Date` becomes a
+ * string and a `Map`/`Set` becomes `{}`. Each is refused at the type level
+ * here and at runtime by {@link assertPlainJson}.
+ */
+type NotJson = ((...args: never[]) => unknown) | bigint | symbol | Date | RegExp | ReadonlyMap<unknown, unknown> | ReadonlySet<unknown> | WeakMap<object, unknown> | WeakSet<object> | Promise<unknown>;
+/** `c.obj([…])` — a list handed to the record constructor. Printed verbatim, like {@link TaggedValueNotAllowed}. */
+type ListNotAllowed = {
+    "❌ c.obj takes a { key: value } record — a list is c.array([ … ]).": never;
+};
+/** `c.obj`'s top-level rejection of a list; a record (or anything else) passes. */
+type RejectList<T> = T extends readonly unknown[] ? ListNotAllowed : unknown;
+/** The error branch for a {@link NotJson} member — printed verbatim, like {@link TaggedValueNotAllowed}. */
+type NotPlainJson = {
+    "❌ c.obj/c.array take plain JSON only — no functions, Dates, Maps/Sets, class instances, bigint or symbol values. Convert first: a Date to date.toISOString(), a Map to Object.fromEntries(map).": never;
+};
+/**
+ * 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.
+ *
+ * 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";
+/**
+ * A constant {@link Value} that also remembers the JavaScript type it resolves
+ * to at runtime.
+ *
+ * Phantom and optional, so a `ConstValue<T>` IS a `Value` everywhere one is
+ * expected and a plain `Value` is still assignable back — nothing about the
+ * encoding changes, and no existing call site moves. What it buys is one thing:
+ * `s.set_var("n", c.int(1))` can brand its binding, so a `ref("n")` in the
+ * response resolves to `number` instead of bottoming out at `unknown`.
+ *
+ * Deliberately NOT carried by every constructor. `c.blank()` is the editor's
+ * unconfigured value box and `c.expression()` is unparsed source — neither has a
+ * type anything here could honestly claim, so both stay bare and keep the
+ * `unknown` floor.
+ */
+type ConstValue<T> = Value & {
+    readonly __const?: T;
+};
+/** 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<const S extends string | null>(s: S): ConstValue<S>;
+    /**
+     * Integer constant → `tag:"const:int"`, value stringified (e.g. `"123"`).
+     *
+     * Pass a **string** or `bigint` for an integer outside JavaScript's safe
+     * range: `c.int("9223372036854775807")` is exact, where the number literal
+     * for it silently rounds. The engine's integers are signed 64-bit and it
+     * clamps a value past that range with no error, so the export warns on one
+     * (`value.int-out-of-range`); the string form still stores the digits as
+     * written, which a pulled workspace relies on.
+     *
+     * 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.
+     */
+    int(n: number | bigint | string): ConstValue<number>;
+    /**
+     * 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): ConstValue<number>;
+    /**
+     * 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<const B extends boolean>(b: B): ConstValue<B>;
+    /**
+     * 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`.
+     *
+     * ⚠ 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): ConstValue<null>;
+    /**
+     * 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. 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. The equivalent `text("now") |to_epoch_ms`
+     * chain evaluates 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)))`.
+     *
+     * Inside an `obj()` the tag is flattened into an expression string, where the
+     * identifier `now` alone is the STRING "now" — so `obj()` writes the
+     * `now|to_epochms` coercion that restores this tag's meaning. A `c.now()` used
+     * as a FILTER ARGUMENT there is refused: the coercion cannot be written in
+     * that position. Hoist it with `s.set_var` and `ref()` it.
+     */
+    now(): ConstValue<number>;
+    /**
+     * 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`.
+     *
+     * 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. 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.
+     * `export()` warns `value.obj-zero-based-numeric-keys` on the def that carries one.
+     */
+    obj<const T>(o?: (T & RejectValues<T> & RejectList<T>) | null): ConstValue<T>;
+    /**
+     * 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.
+     */
+    array<const T extends readonly unknown[]>(a: T & RejectValues<T>): ConstValue<T>;
+    /**
+     * 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.** Xano SDK 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.
+     *
+     * 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 — 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.
+ *
+ * `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()";
+/**
+ * Reference a function/endpoint **input**: `{tag:"input", value}`. See {@link ref} for the full picker.
+ * `inp("")` is the whole input object (`$input`).
+ */
+declare function inp<const Name extends string>(name: Name, opts?: SafeIsRefOnly): InpValue<Name>;
+/**
+ * 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. Outside a
+ * `db.*` statement's where/sort/eval (a condition, a `set_var`, a response) the
+ * engine reads it as the column's NAME, so export refuses it there.
+ */
+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<const P extends string = "">(path?: P, opts?: SafeIsRefOnly): AuthValue<P>;
+/**
+ * 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): NotObjMember<"response">;
+/**
+ * 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<const P extends CaughtField | "" = "">(path?: P, opts?: SafeIsRefOnly): CaughtValue<P>;
+/**
+ * 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.
+ */
+declare function toolset(path: ToolsetPath, opts?: SafeIsRefOnly): NotObjMember<"toolset">;
+/**
+ * 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: a **public** endpoint has no caller identity, so `auth("id")`
+ * does not resolve there — the
+ * request FAILS with a 403 rather than degrading to one shared 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). */
+    /**
+     * The request's headers, keyed Title-Cased whatever the client sent — a
+     * client's `x-sync-secret` is read as `X-Sync-Secret`, so read that spelling.
+     * `s.api.call` sends header names the same way.
+     */
+    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): NotObjMember<"output">;
+/**
+ * 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>;
+/**
+ * One chain member {@link withFilters} takes: an `fl.*` filter, or a `qf.*`
+ * step for an operand a db query compiles to SQL — `where: expr(col("at"), ">",
+ * withFilters(c.now(), qf.epochms_sub_day(7)))`. A `qf` step carries no
+ * `disabled`, and a zero-argument one no `arg`; it is appended as it came, the
+ * bytes a query's `eval` stores for the same step.
+ */
+type ChainFilter = FilterXdo | QueryFilter;
+/**
+ * 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.
+ * A db-query operand also takes `qf.*` steps (see {@link ChainFilter}).
+ */
+declare function withFilters<V extends Value, const Fs extends readonly (ChainFilter | ChainFilter[])[]>(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[];
+}
+
+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 default for isolated runs. Any other value names a datasource
+     * the engine **clones** before the test runs; `"live"` warns at encode time to
+     * prevent cloning large production databases, but in ephemeral test environments
+     * `datasource: "live"` is safe and allows running tests against `table({ seed })` rows.
+     */
+    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 — 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 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", "const:encoded", "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. 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. 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;
+    /** `null` on the one input the platform stores a null default for: an MCP trigger's `auth`. */
+    default: string | null;
+    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;
+    };
+};
+
+export { setting as $, type AuthValue as A, auth as B, type CacheXdo as C, c as D, type ExprGroup as E, type FieldXdo as F, caught as G, type HistoryXdo as H, type InpValue as I, col as J, env as K, type ListBoundsXdo as L, type MethodXdo as M, type NotObjMember as N, expect as O, type PersistedFunctionRow as P, QUERY_AGGREGATE_NAMES as Q, type RefValue as R, type StackItemXdo as S, TAGS as T, filter as U, type Value as V, inp as W, out as X, qf as Y, ref as Z, resp as _, type CaughtField as a, sys as a0, test as a1, toolset as a2, withFilters as a3, type CaughtShape as a4, type CaughtValue as b, type ConditionalContext as c, type ConditionalElifContext as d, type ConstValue as e, type ExprNode as f, type ExprOperand as g, type ExprStatement as h, type FilterXdo as i, type FilteredValue as j, type FunctionXdo as k, type InputXdo as l, QUERY_FILTER_NAMES as m, QUERY_FILTER_SPECS as n, type QueryFilter as o, type QueryFilterResults as p, type RegexValue as q, type ResultItemXdo as r, type StatementInputXdo as s, TEST_EXPECT_TYPES as t, type Tag as u, type TaggedValue as v, type TestDef as w, type TestExpect as x, type TestExpectType as y, type TestXdo as z };