@xanots/sdk 0.0.10 → 0.0.11

package/dist/response-BQVQ24l1.d.ts

@@ -0,0 +1,844 @@
+import { V as Value, h as FilterXdo, S as StackItemXdo, k as ResultItemXdo } from './xdo-BjJj5W_E.js';
+
+/**
+ * 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`,
+ * `c.obj(…)` / `c.array([…])`, 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"`).
+ *
+ * A constant record or list has two spellings that mean the same thing here: a
+ * bare `{…}` / `[…]` and `c.obj` / `c.array`. They render to identical bytes
+ * (issue #295) — `c.array` used to throw while the bare form worked, which made
+ * the empty list an export failure.
+ *
+ * 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 XanoDbLink as $, type TextFormat as A, type BrandOpts as B, type TextMethod as C, type DecimalMethod as D, type EmailMethod as E, FIELD_METHODS as F, type TypeBrand as G, type VectorMethod as H, type IntMethod as I, type XanoGeoPosition as J, type XanoGeoValue as K, annotate as L, type MethodArg as M, f as N, type ObjInput as O, type PasswordMethod as P, obj as Q, REFERENCEABLE_KINDS as R, type Statement as S, type TableRefMethod as T, statements as U, type ValueOf as V, type FieldOptions as W, type XanoFileRef as X, type Prettify as Y, type ReadonlyMethods as Z, type XanoFileUpload as _, encodeStatement as a, type ConstMethodOpts as a0, type AsShapeBrand as a1, type BrandValue as b, type FieldAccess as c, deriveGuid as d, encodeResponse as e, type FieldDescriptor as f, getStatementFactory as g, type FieldMap as h, isRegisteredStatement as i, type FieldOpts as j, type FieldStyleType as k, type FromFieldMap as l, type MethodOpts as m, type MethodSpec as n, type MockEntry as o, type MockMap as p, type MockXdo as q, resolveRef as r, type ObjMember as s, toNestedFields as t, type ObjValue as u, type ObjectRef as v, type ResponseDef as w, type RowFromFieldMap as x, type StatementAnnotations as y, type StatementOptions as z };