@vantis/data 0.0.1

package/dist/index.d.cts

@@ -0,0 +1,879 @@
+/**
+ * Schema augmentation seam.
+ *
+ * This interface is intentionally empty here. You never edit this file.
+ *
+ * The `vantis data build` command (S2) emits a project-local declaration file
+ * that extends this interface with your table shapes:
+ *
+ *   declare module '@vantis/data' {
+ *     interface Schema {
+ *       users:  { id: string; email: string };
+ *       orders: { id: string; user_id: string; total: string };
+ *     }
+ *   }
+ *
+ * TypeScript merges that declaration into this interface at compile time,
+ * making the full typed shape available throughout your project without any
+ * manual type registration. The same pattern is used by TanStack's `Register`
+ * interface (QueryClient, Router) and Hono's `Env` bindings.
+ *
+ * The Go-emitted `.vantis.d.ts` (from `vantis data build`, ADR-0048) augments this
+ * registry; the runtime client (`data.from()`, insert/upsert, embed, RPC, verbs)
+ * reads it to provide inferred row types and query results.
+ */
+interface Schema {
+}
+/**
+ * RPC registry augmentation seam (VAN-832). Empty here; `vantis data build`
+ * emits a project-local declaration extending this with each typed function:
+ *
+ *   declare module '@vantis/data' {
+ *     interface Rpc {
+ *       place_order: { Args: { qty: number }; Returns: { id: string }[] };
+ *     }
+ *   }
+ *
+ * `data.run.<name>(args)` is typed off this interface, exactly as `data.from`
+ * is typed off Schema.
+ */
+interface Rpc {
+}
+/**
+ * Verb registry augmentation seam (VAN-866, ADR-0047). Empty here;
+ * `vantis data build` emits a project-local declaration extending this with
+ * per-table typed ops + match shapes:
+ *
+ *   declare module '@vantis/data' {
+ *     interface Verbs {
+ *       orders: {
+ *         ops:   { total?: NumericVerb | SetOnInsertVerb; status?: TextVerb | SetOnInsertVerb };
+ *         match: { id: string };
+ *         guard: { id?: { eq?: string; ne?: string }; total?: { eq?: number; gt?: number } };
+ *       };
+ *     }
+ *   }
+ *
+ * `.modify(ops, match, opts?)` is typed off this interface, exactly as
+ * `data.from()` is typed off Schema and `data.run.<name>()` off Rpc.
+ */
+interface Verbs {
+}
+/**
+ * Strict insert payload seam (VAN-869, ADR-0048). Empty here;
+ * `vantis data build` emits a project-local declaration extending this with
+ * per-table insert shapes that enforce NOT-NULL-no-default columns as required:
+ *
+ *   declare module '@vantis/data' {
+ *     interface SchemaInsert {
+ *       users: { email: string; id?: string; display_name?: string | null };
+ *     }
+ *   }
+ *
+ * `.insert()` and `.upsert()` read `SchemaInsert[T]` when T is registered
+ * here, catching missing required columns at compile time. Tables absent from
+ * SchemaInsert fall back to `Partial<Schema[T]>` (permissive v0 behaviour).
+ */
+interface SchemaInsert {
+}
+/**
+ * FK embed cardinality seam (VAN-869, ADR-0048). Empty here;
+ * `vantis data build` emits a project-local declaration extending this with
+ * per-table FK cardinality entries — `'one'` for many-to-one (FK column is
+ * the referencing table's PK), `'many'` for one-to-many (all other FKs):
+ *
+ *   declare module '@vantis/data' {
+ *     interface Embeds {
+ *       posts:  { users: 'one' };   // posts.user_id FK → users (many-to-one)
+ *       users:  { posts: 'many' };  // users.id → posts (one-to-many inverse)
+ *     }
+ *   }
+ *
+ * `.embed(related)` reads `Embeds[T][Related]` to determine the result type:
+ * `'one'` → `Schema[Related]` (object), `'many'` → `Schema[Related][]` (array).
+ * Tables or relationships absent from Embeds default to the array form.
+ */
+interface Embeds {
+}
+
+/**
+ * @vantis/data — typed PostgREST error.
+ *
+ * Maps the PostgREST error body shape `{ code, message, details, hint }`.
+ * The result discriminated union returned by every query builder:
+ *   Success → { data: T; error: null; count: number|null; status: number; statusText: string }
+ *   Failure → { data: null; error: DataError; count: null; status: number; statusText: string }
+ *
+ * Security (INV-01/INV-02): the token is NEVER included in any error field.
+ * Full PostgREST error detail is returned to the tenant's own pod (server-tier —
+ * acceptable per INV-10 / ADR-0039 §4). Public-edge redaction is VAN-844.
+ */
+/**
+ * A typed error returned from the Data API.
+ *
+ * Mirrors the PostgREST error body: code (PostgreSQL error code, e.g. "42P01"),
+ * message (human-readable), and the optional details/hint fields.
+ *
+ * The `kind` field distinguishes config errors (missing env vars, browser
+ * environment) from wire errors returned by PostgREST.
+ */
+interface DataError {
+    /** Discriminator: 'postgrest' for wire errors; 'config' for SDK config errors. */
+    readonly kind: 'postgrest' | 'config';
+    /** PostgreSQL error code (e.g. "42P01", "PGRST301") — or a short config key. */
+    readonly code: string;
+    /** Human-readable error message. NEVER contains the DATA_API_TOKEN. */
+    readonly message: string;
+    /** Additional error detail from PostgreSQL or PostgREST. May be null. */
+    readonly details: string | null;
+    /** Hint from PostgreSQL or PostgREST. May be null. */
+    readonly hint: string | null;
+}
+/**
+ * Discriminated result union for every Data API query.
+ *
+ * On success: `error` is null, `data` holds the typed payload.
+ * On failure: `data` is null, `error` holds the typed DataError.
+ * `count` carries the total row count (when requested) and is null on failure.
+ * `status`/`statusText` mirror the HTTP response.
+ */
+type DataResult<T> = {
+    data: T;
+    error: null;
+    count: number | null;
+    status: number;
+    statusText: string;
+} | {
+    data: null;
+    error: DataError;
+    count: null;
+    status: number;
+    statusText: string;
+};
+
+/**
+ * @vantis/data — zero-config typed query client.
+ *
+ * Exports the ambient `data` object. Entry point: `data.from(tableName)`.
+ *
+ * Security contracts:
+ * - INV-01/INV-02: DATA_API_TOKEN is NEVER logged, NEVER included in error
+ *   messages, NEVER placed in the URL (it is an Authorization header only).
+ * - INV-11: env vars are read LAZILY on the FIRST QUERY (not at import/module
+ *   eval) so a framework build (next build) that imports server modules before
+ *   deploy-time injection does not throw.
+ * - Browser guard: if a browser global is present at query time, fail closed
+ *   with a server-only error (secondary to the `exports` browser condition stub
+ *   in browser.ts — the runtime guard is defense-in-depth).
+ * - ALL clients have explicit timeouts per CONVENTIONS.md.
+ */
+
+/** The row shape for a given table (pulled from the augmented Schema). */
+type Row<T extends keyof Schema> = Schema[T];
+/**
+ * Strict insert payload for a Schema table (VAN-869, ADR-0048).
+ *
+ * When the Go emitter (`vantis data build`) has registered the table in the
+ * `SchemaInsert` interface, this resolves to `SchemaInsert[T]` — a shape
+ * where NOT-NULL-no-default columns are required and nullable/defaulted columns
+ * are optional. Tables absent from SchemaInsert (e.g. during initial authoring
+ * before the first `vantis data build`) fall back to `Partial<Row<T>>`.
+ *
+ * Used by `.insert()`, `.upsert()`, and the `upsert` branch of `ModifyOptions`.
+ */
+type InsertPayload<T extends keyof Schema> = T extends keyof SchemaInsert ? SchemaInsert[T] : Partial<Row<T>>;
+/**
+ * Partial update payload — always `Partial<Row<T>>`.
+ *
+ * `.update()` sends only the columns to change; requiring all NOT-NULL columns
+ * would be wrong for a partial update. This is separate from InsertPayload so
+ * insert/upsert can be strict while update remains permissive.
+ */
+type UpdatePayload<T extends keyof Schema> = Partial<Row<T>>;
+/**
+ * Resolves the embed result type for a related table.
+ *
+ * Reads the `Embeds` cardinality registry populated by `vantis data build`:
+ *   - `'one'`         (FK column is the referencing table's PK) → `Schema[TRelated]` (object)
+ *   - `'many'`        (all other FKs — one-to-many inverse)     → `Schema[TRelated][]` (array)
+ *   - `'one' | 'many'` (self-FK or ambiguous)                   → `Schema[TRelated] | Schema[TRelated][]` (union)
+ *
+ * Defaults to the array form when the table or relationship is absent from
+ * `Embeds` (safe: PostgREST returns an array for unregistered embed shapes).
+ *
+ * EmbedByCardinality uses a bare type parameter `C` so TypeScript distributes
+ * over union cardinalities: `EmbedByCardinality<R, 'one' | 'many'>` resolves
+ * to `Schema[R] | Schema[R][]` rather than collapsing to the array branch
+ * (the old `Embeds[TTable][TRelated] extends 'one'` pattern was NOT
+ * distributive because the checked type was a property access, not a bare
+ * parameter — VAN-869 fix D).
+ */
+type EmbedByCardinality<R extends keyof Schema, C> = C extends 'one' ? Schema[R] : Schema[R][];
+type EmbedResult<TTable extends keyof Schema, TRelated extends keyof Schema> = TTable extends keyof Embeds ? TRelated extends keyof Embeds[TTable] ? EmbedByCardinality<TRelated, Embeds[TTable][TRelated]> : Schema[TRelated][] : Schema[TRelated][];
+/**
+ * The `ops` shape for `.modify()` on a given table — `VerbEnvelope` per
+ * modifiable (non-PK, non-uuid) column, all optional.
+ *
+ * Resolves to `never` for tables absent from the `Verbs` registry (i.e.
+ * tables with no `__vantis_modify_<t>` engine function — no PK, or all
+ * non-PK columns are non-modifiable types like uuid). Calling `.modify()`
+ * on such a table is a compile-time type error: the engine would 404 at
+ * runtime, so it must be caught by the type system instead.
+ *
+ * Populated by `vantis data build` emitting a per-project `.vantis.d.ts`
+ * that augments `interface Verbs { … }` — exactly as `Schema` is populated
+ * for `data.from()` and `Rpc` is populated for `data.run.<name>()`.
+ */
+type VerbOpsFor<TTableName extends keyof Schema> = TTableName extends keyof Verbs ? 'ops' extends keyof Verbs[TTableName] ? Verbs[TTableName]['ops'] : never : never;
+/**
+ * The `match` shape for `.modify()` on a given table — PK column values.
+ *
+ * Resolves to `never` for tables absent from the `Verbs` registry (same
+ * reasons as VerbOpsFor — engine-absent tables must fail at compile time).
+ */
+type VerbMatchFor<TTableName extends keyof Schema> = TTableName extends keyof Verbs ? 'match' extends keyof Verbs[TTableName] ? Verbs[TTableName]['match'] : never : never;
+/**
+ * The `guard` shape for `.modify()` on a given table — typed comparator
+ * objects per column. Falls back to `Record<string, Record<string, unknown>>`
+ * for tables absent from the `Verbs` registry.
+ */
+type VerbGuardFor<TTableName extends keyof Schema> = TTableName extends keyof Verbs ? 'guard' extends keyof Verbs[TTableName] ? Verbs[TTableName]['guard'] : Record<string, Record<string, unknown>> : Record<string, Record<string, unknown>>;
+/**
+ * Options for `.modify()`. Generic over the table name so `guard` is typed
+ * to the column + comparator shape generated by `vantis data build`.
+ *
+ * `guard` and `upsert` are mutually exclusive at the type level (XOR):
+ * providing both is a compile-time error. The engine enforces the same
+ * constraint at runtime (sending both raises INVALID_ARGUMENT).
+ *
+ * @property upsert - When present, activates the upsert branch: if the row
+ *   identified by `match` does not exist, it is inserted with the values
+ *   from this object. Use setOnInsert() in `ops` to set additional fields
+ *   only on INSERT (Mongo $setOnInsert semantics).
+ *
+ * @property guard - Optional single-column optimistic-concurrency check.
+ *   Shape: `{ "<col>": { "<comparator>": <value> } }`.
+ *   Comparators: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`.
+ *   If the guard condition is NOT met, the engine returns an empty array
+ *   (not-applied signal) without modifying the row or raising an error.
+ *   Check for `result.data?.length === 0` in your application logic.
+ */
+type ModifyOptions<T extends keyof Schema = keyof Schema> = {
+    upsert?: InsertPayload<T>;
+    guard?: undefined;
+} | {
+    upsert?: undefined;
+    guard?: VerbGuardFor<T>;
+};
+interface BuilderState {
+    table: string;
+    filters: string[];
+    selectCols: string;
+    orderParts: string[];
+    limitVal: number | null;
+    limitReferencedTable: string | null;
+    offsetVal: number | null;
+    countMode: 'exact' | 'planned' | 'estimated' | null;
+    headMode: boolean;
+    singleMode: boolean;
+    maybeSingleMode: boolean;
+    writeOp: 'insert' | 'update' | 'delete' | 'upsert' | null;
+    writeBody: unknown;
+    writeSelect: boolean;
+    writeSelectCols: string;
+    onConflict: string | null;
+    ignoreDuplicates: boolean;
+    embeds: string[];
+    searchQuery: string | null;
+    searchLimit: number | null;
+}
+/**
+ * Options for `.select()` when `head` is false or absent (normal query).
+ * - count: request a count total from PostgREST. Default none.
+ */
+interface SelectOptions {
+    head?: false;
+    count?: 'exact' | 'planned' | 'estimated';
+}
+/**
+ * Options for `.select()` when `head` is true (HEAD request — count-only).
+ *
+ * @note `head: true` returns `data: null` (HEAD has no body). The data
+ * field will always be null regardless of the row type parameter.
+ */
+interface SelectHeadOptions {
+    head: true;
+    count?: 'exact' | 'planned' | 'estimated';
+}
+/** Options for `.order()`. */
+interface OrderOptions {
+    ascending?: boolean;
+    nullsFirst?: boolean;
+    referencedTable?: string;
+}
+/** Options for `.limit()`. */
+interface LimitOptions {
+    referencedTable?: string;
+}
+/** Options for `.upsert()`. */
+interface UpsertOptions {
+    onConflict?: string;
+    ignoreDuplicates?: boolean;
+}
+/**
+ * Options for `.search()`.
+ *
+ * The server pre-sorts results best-first (relevance-ordered). The `limit`
+ * option caps results client-side via the PostgREST `/rpc` limit parameter
+ * (also bounded by `PGRST_DB_MAX_ROWS=1000` on the server).
+ */
+interface SearchOptions {
+    /** Maximum number of rows to return (passed as PostgREST `?limit=n`). */
+    limit?: number;
+}
+/**
+ * The QueryBuilder is a thenable — `await data.from('users')` resolves to
+ * a DataResult without requiring an explicit `.execute()` call.
+ *
+ * Generic parameters:
+ *   TTableName — the table name (keyof Schema).
+ *   TRow — the current row shape (modified by embed).
+ *   TResult — the full DataResult type for this builder's current state.
+ *
+ * v0 notes:
+ * - `.select(columns)` types as the FULL row for any column string (column-
+ *   subset Pick narrowing is a v1 follow-up).
+ * - `.insert(values)` payload is typed as `SchemaInsert[T]` when the Go emitter
+ *   has registered the table (strict: required NOT-NULL-no-default columns
+ *   enforced). Falls back to `Partial<Row[T]>` for unregistered tables.
+ * - `.embed(table)` cardinality is resolved from the `Embeds` registry:
+ *   `'one'` → single object; `'many'` → array. Unregistered → array default.
+ */
+declare class QueryBuilder<TTableName extends keyof Schema, TRow = Row<TTableName>, TResult extends DataResult<unknown> = DataResult<TRow[]>> implements PromiseLike<TResult> {
+    private readonly _state;
+    constructor(tableName: TTableName, state?: BuilderState);
+    /**
+     * Equality filter: column = value.
+     *
+     * The value is emitted raw (not quoted). URLSearchParams URL-encodes it, which
+     * is correct and sufficient for scalar operators — PostgREST takes the whole
+     * value after `eq.` and does NOT strip double-quotes for scalar ops (quoting
+     * would cause a literal string mismatch, e.g. `email=eq."a@b.com"` → 0 rows).
+     */
+    eq<K extends keyof TRow & string>(col: K, val: TRow[K]): this;
+    /**
+     * Inequality filter: column != value.
+     *
+     * Value emitted raw — see eq() for the scalar-quoting rationale.
+     */
+    neq<K extends keyof TRow & string>(col: K, val: TRow[K]): this;
+    /**
+     * Greater-than filter: column > value.
+     *
+     * Value emitted raw — see eq() for the scalar-quoting rationale.
+     */
+    gt<K extends keyof TRow & string>(col: K, val: TRow[K]): this;
+    /**
+     * Greater-than-or-equal filter: column >= value.
+     *
+     * Value emitted raw — see eq() for the scalar-quoting rationale.
+     */
+    gte<K extends keyof TRow & string>(col: K, val: TRow[K]): this;
+    /**
+     * Less-than filter: column < value.
+     *
+     * Value emitted raw — see eq() for the scalar-quoting rationale.
+     */
+    lt<K extends keyof TRow & string>(col: K, val: TRow[K]): this;
+    /**
+     * Less-than-or-equal filter: column <= value.
+     *
+     * Value emitted raw — see eq() for the scalar-quoting rationale.
+     */
+    lte<K extends keyof TRow & string>(col: K, val: TRow[K]): this;
+    /**
+     * LIKE filter. Pattern uses `%` (translated to PostgREST `*` on the wire)
+     * or `*` directly. Example: `.like('email', '%@example.com')`.
+     *
+     * The wildcard-translated pattern is emitted raw. URLSearchParams URL-encodes
+     * it, which is correct and sufficient — PostgREST takes the whole value after
+     * `like.` as the pattern. Do NOT quote like patterns: PostgREST does NOT strip
+     * double-quotes for scalar operators, so `like."a.b*"` would match a literal
+     * value containing `"` rather than performing `LIKE 'a.b%'`.
+     *
+     * NOTE: a LITERAL `*` in a user-supplied substring cannot be escaped —
+     * PostgREST has no like-escape mechanism and `*` is always the wildcard.
+     * Strip or reject literal `*` from user input at the call site if needed.
+     */
+    like<K extends keyof TRow & string>(col: K, pattern: string): this;
+    /**
+     * Case-insensitive LIKE filter. Pattern uses `%` or `*`.
+     *
+     * Pattern emitted raw after wildcard translation — see like() for the
+     * scalar-quoting rationale.
+     */
+    ilike<K extends keyof TRow & string>(col: K, pattern: string): this;
+    /**
+     * IN filter: column IN (values).
+     * Each element is quoted per the PostgREST URL grammar.
+     */
+    in<K extends keyof TRow & string>(col: K, values: TRow[K][]): this;
+    /**
+     * IS filter: column IS true/false/null.
+     * PostgREST wire: `?col=is.true` / `?col=is.false` / `?col=is.null`.
+     * Values are fixed keywords — NOT subject to quoteFilterValue.
+     */
+    is<K extends keyof TRow & string>(col: K, val: boolean | null): this;
+    /**
+     * Set the column selection and optional count/head options.
+     *
+     * v0 type-narrowing: column-subset narrowing (Pick) is not implemented for v0.
+     * `.select('id, name')` types as the full row (same as `.select('*')`).
+     *
+     * `head: true` returns `data: null` (HEAD has no body — it is a count-only
+     * request). The overload narrows the return to `DataResult<null>` when
+     * `head: true` is passed as an option.
+     *
+     * When chained after a write (.insert/.update/.delete/.upsert), sends
+     * `Prefer: return=representation` and emits `?select=<columns>` if a non-default
+     * column list is given (v0 fix: write-chained .select('id') correctly narrows
+     * the response columns, not silently over-returning all columns).
+     */
+    select(columns?: string, options?: SelectHeadOptions): QueryBuilder<TTableName, TRow, DataResult<null>>;
+    select(columns?: string, options?: SelectOptions): QueryBuilder<TTableName, TRow, DataResult<TRow[]>>;
+    /**
+     * Embed a related table by FK.
+     *
+     * Adds the related table to the PostgREST select: `?select=*,<relatedTable>(*)`.
+     * PostgREST resolves the FK automatically (requires a schema-cache reload after
+     * FK changes — https://postgrest.org/en/v14/references/api/resource_embedding.html).
+     *
+     * The result row type gains `{ <relatedTable>: EmbedResult<TTableName, TEmbedTable> }`.
+     * The cardinality is resolved from the `Embeds` registry populated by `vantis data build`:
+     *   - `'one'` (FK column is the referencing table's PK) → single object `Schema[TEmbedTable]`.
+     *   - `'many'` (all other FKs — one-to-many inverse) → array `Schema[TEmbedTable][]`.
+     *   - Unregistered relationships default to the array form.
+     *
+     * @example
+     * ```ts
+     * // posts.user_id FK → users (many-to-one; Embeds says 'one')
+     * const result = await data.from('posts').embed('users');
+     * // result.data[0].users — Schema['users'] (object, not array)
+     *
+     * // users.id → posts (one-to-many; Embeds says 'many')
+     * const result2 = await data.from('users').embed('posts');
+     * // result2.data[0].posts — Schema['posts'][] (array)
+     * ```
+     */
+    embed<TEmbedTable extends keyof Schema>(relatedTable: TEmbedTable): QueryBuilder<TTableName, TRow & {
+        [K in TEmbedTable]: EmbedResult<TTableName, TEmbedTable>;
+    }, DataResult<(TRow & {
+        [K in TEmbedTable]: EmbedResult<TTableName, TEmbedTable>;
+    })[]>>;
+    /**
+     * Order results by a column.
+     * @param col Column name.
+     * @param options ascending (default true), nullsFirst (default undefined), referencedTable.
+     */
+    order<K extends keyof TRow & string>(col: K, options?: OrderOptions): this;
+    /**
+     * Limit the number of rows returned.
+     *
+     * When `referencedTable` is set, emits `?<referencedTable>.limit=n` to limit
+     * an embedded resource (PostgREST embedded-resource limiting). Without
+     * `referencedTable`, emits the top-level `?limit=n`.
+     */
+    limit(n: number, options?: LimitOptions): this;
+    /**
+     * Return a range of rows by offset.
+     * @param from Start offset (0-indexed).
+     * @param to End offset (inclusive).
+     */
+    range(from: number, to: number): this;
+    /**
+     * Insert one or more rows.
+     *
+     * By default returns `data: null` (PostgREST `return=minimal`).
+     * Chain `.select()` to get the inserted rows back (`return=representation`).
+     *
+     * When the Go emitter (`vantis data build`) has registered the table in
+     * `SchemaInsert`, the payload enforces required NOT-NULL-no-default columns
+     * at compile time. Tables not yet registered fall back to `Partial<Row>`.
+     */
+    insert(values: InsertPayload<TTableName> | InsertPayload<TTableName>[]): QueryBuilder<TTableName, TRow, DataResult<null>>;
+    /**
+     * Update rows matching the current filters.
+     *
+     * By default returns `data: null`. Chain `.select()` for the updated rows.
+     *
+     * `values` is always `Partial<Row>` — you send only the columns to change.
+     * For insert/upsert, see `.insert()` and `.upsert()` (strict SchemaInsert typing).
+     */
+    update(values: UpdatePayload<TTableName>): QueryBuilder<TTableName, TRow, DataResult<null>>;
+    /**
+     * Delete rows matching the current filters.
+     *
+     * By default returns `data: null`. Chain `.select()` for the deleted rows.
+     */
+    delete(): QueryBuilder<TTableName, TRow, DataResult<null>>;
+    /**
+     * Upsert one or more rows.
+     *
+     * Uses `POST + Prefer: resolution=merge-duplicates` (or `ignore-duplicates`).
+     * By default returns `data: null`. Chain `.select()` for the upserted rows.
+     */
+    upsert(values: InsertPayload<TTableName> | InsertPayload<TTableName>[], options?: UpsertOptions): QueryBuilder<TTableName, TRow, DataResult<null>>;
+    /**
+     * Expect exactly one row. Returns `data: TRow` (not an array).
+     * If zero or more than one row is returned, PostgREST returns a 406 and this
+     * resolves to an error.
+     *
+     * Sets `Accept: application/vnd.pgrst.object+json`.
+     */
+    single(): QueryBuilder<TTableName, TRow, DataResult<TRow>>;
+    /**
+     * Expect zero or one row. Returns `data: TRow | null`.
+     *
+     * Client-side normalization (mirrors postgrest-js):
+     * - 0 rows → `{ data: null, error: null }` (no error)
+     * - 1 row → `{ data: <row>, error: null }`
+     * - >1 rows → `{ data: null, error: { code: 'PGRST116', ... } }`
+     *
+     * Uses the normal array `Accept: application/json` — PostgREST returns the
+     * array, and normalization happens client-side. This avoids the 406 that
+     * `vnd.pgrst.object+json` would return for 0 rows.
+     */
+    maybeSingle(): QueryBuilder<TTableName, TRow, DataResult<TRow | null>>;
+    /**
+     * Full-text search via the engine-provisioned rank RPC.
+     *
+     * Routes to `GET /rpc/search_<table>?query=<text>` (the PostgREST `/rpc`
+     * path, not the table path). Results are pre-sorted most-relevant-first by
+     * the server (`ts_rank_cd` ordering inside the function). Each result row
+     * carries a `rank` field — an OPAQUE ordering-only relevance score.
+     *
+     * The four swap invariants (VAN-830 / ADR-0044):
+     * (i)  One entry point — `.search(query, opts)`. Engine specifics never exposed.
+     * (ii) Text query in — engine-specific parsing is internal.
+     * (iii) Opaque `rank` — ordering-only, never normalized. A future BM25/rerank
+     *       swap changes the scale, not the contract.
+     * (iv) Pluggable transport — currently PostgREST `/rpc`; semantic search goes
+     *      to the AI gateway (opt-in, reserved).
+     *
+     * Security (INV-01/INV-02):
+     * - The query text is passed via URLSearchParams (URL-encoded by the browser
+     *   URLSearchParams API) — NOT double-quoted (no PostgREST scalar-op quoting
+     *   applies to RPC function arguments).
+     * - The DATA_API_TOKEN is in the Authorization header ONLY, never in the URL.
+     * - Filters/select/order from any previously chained methods are NOT emitted
+     *   in search mode — the RPC returns the full row shape + rank, ordered by
+     *   the server.
+     *
+     * Requires the table to have at least one `searchable: true` column in
+     * `vantis.schema.json` and a `vantis data apply` that provisions the search function.
+     *
+     * @example
+     * ```ts
+     * const result = await data.from('articles').search('hello world');
+     * if (result.error) { ... }
+     * for (const row of result.data) {
+     *   console.log(row.title, row.rank); // rank: opaque ordering-only score
+     * }
+     * ```
+     *
+     * With a limit:
+     * ```ts
+     * const result = await data.from('articles').search('typescript', { limit: 10 });
+     * ```
+     */
+    search(query: string, opts?: SearchOptions): QueryBuilder<TTableName, TRow, DataResult<Array<TRow & {
+        rank: number;
+    }>>>;
+    /**
+     * Atomically modify a single row via the server-side verb RPC
+     * (`__vantis_modify_<table>`). Each value in `ops` must be a VerbEnvelope
+     * returned by one of the verb helpers (increment, decrement, multiply, divide,
+     * min, max, toggle, serverTimestamp, concat, merge, jsonSet, setOnInsert).
+     * Bare objects or plain values are rejected synchronously.
+     *
+     * Wire: `POST /rpc/__vantis_modify_<table>`  `Content-Profile: api`
+     *   ```json
+     *   { "__vantis_match": {...}, "__vantis_ops": {...},
+     *     "__vantis_row"?: {...}, "__vantis_guard"?: {...} }
+     *   ```
+     *
+     * Returns:
+     * - `{ data: [row], error: null }` — applied (UPDATE path).
+     * - `{ data: [],   error: null }` — guard miss or row absent (not-applied).
+     *   Check `result.data?.length === 0` in your application logic.
+     * - `{ data: null, error }` — a DataError from PostgREST or the engine.
+     *
+     * Security: token in Authorization header only (INV-01/INV-02). Lazy env
+     * read (INV-11). Browser guard (secondary; browser.ts export condition is
+     * primary).
+     *
+     * @example
+     * ```ts
+     * const result = await data.from('orders').modify(
+     *   { total: increment(10) },
+     *   { id: orderId },
+     *   { guard: { total: { gte: 0 } } },
+     * );
+     * if (!result.error && result.data?.length === 0) {
+     *   // guard miss — row unchanged
+     * }
+     * ```
+     */
+    modify(ops: VerbOpsFor<TTableName>, match: VerbMatchFor<TTableName>, opts?: ModifyOptions<TTableName>): Promise<DataResult<TRow[]>>;
+    /**
+     * Guard: throws synchronously if `.search()` has already been called on this
+     * builder. `.search()` is terminal in v0 — no mutator may be chained after it.
+     *
+     * Without this guard, a trailing mutator (e.g. `.eq()`) would modify `_state`
+     * fields that `_buildRequest`'s search branch silently ignores, producing an
+     * unscoped query that returns rows the caller did not intend to receive.
+     *
+     * Called at the top of every state-mutating method.
+     */
+    private _assertNotSearch;
+    then<TFulfilled = TResult, TRejected = never>(onfulfilled?: ((value: TResult) => TFulfilled | PromiseLike<TFulfilled>) | null | undefined, onrejected?: ((reason: unknown) => TRejected | PromiseLike<TRejected>) | null | undefined): Promise<TFulfilled | TRejected>;
+    private _execute;
+    private _buildRequest;
+    private _parseResponse;
+}
+/** The typed shape of data.run — one method per Rpc registry entry. */
+type RunProxy = {
+    [K in keyof Rpc]: (args: Rpc[K]['Args']) => Promise<DataResult<Rpc[K]['Returns']>>;
+};
+/**
+ * The typed data client. Import and use directly — no construction required.
+ *
+ * Reads `DATA_API_URL` and `DATA_API_TOKEN` from the environment on the first
+ * query (lazy — so framework builds that import server modules before env
+ * injection do not throw at import time).
+ *
+ * @example
+ * ```ts
+ * import { data } from '@vantis/data';
+ *
+ * const result = await data.from('users').eq('email', 'alice@example.com').single();
+ * if (result.error) { ... }
+ * const user = result.data; // typed as Schema['users']
+ * ```
+ */
+declare const data: {
+    /**
+     * Start a query against the given table.
+     *
+     * `tableName` is typed as `keyof Schema` — the augmented Schema interface
+     * populated by `vantis data build`.
+     *
+     * Returns a `QueryBuilder` that is also PromiseLike — `await` it directly.
+     */
+    readonly from: <T extends keyof Schema>(tableName: T) => QueryBuilder<T>;
+    /**
+     * Call a typed RPC (VAN-832). `data.run.<name>(args)` POSTs to /rpc/<name>
+     * and returns the typed result. Names + arg/return types come from the
+     * generated Rpc registry (`vantis data build`).
+     *
+     * @example
+     * ```ts
+     * const r = await data.run.place_order({ product_id: id, qty: 2 });
+     * if (r.error) { ... }
+     * const orderId = r.data; // typed from the fn() declaration
+     * ```
+     */
+    readonly run: RunProxy;
+};
+
+/**
+ * @vantis/data — branded atomic modifier helpers (VAN-866, ADR-0047).
+ *
+ * Each helper returns a Symbol-branded VerbEnvelope that .modify() serializes
+ * into the __vantis_ops JSONB argument. JSON.stringify() ignores Symbol-keyed
+ * properties, so the brand never appears on the wire.
+ *
+ * Security: the server-side __vantis_modify_<t> function is the actual
+ * security boundary — it fully validates ops, match, and operand types.
+ * These helpers provide ergonomics + compile-time safety only.
+ *
+ * Wire contract (engine-generated function signature):
+ *   api.__vantis_modify_<t>(
+ *     __vantis_match jsonb,   -- PK columns object
+ *     __vantis_ops   jsonb,   -- { "<col>": { "op": "<opname>", "v"?: <operand>, "path"?: string[] } }
+ *     __vantis_row   jsonb,   -- optional insert row (upsert branch)
+ *     __vantis_guard jsonb    -- optional single-column guard { "<col>": { "<cmp>": <value> } }
+ *   ) RETURNS SETOF api.<t>
+ */
+/** Brand symbol for verb envelopes. Symbol-keyed, ignored by JSON.stringify. */
+declare const VERB_BRAND: unique symbol;
+/**
+ * A Symbol-branded atomic modifier envelope returned by the verb helpers.
+ *
+ * The VERB_BRAND property is non-enumerable and symbol-keyed, so
+ * JSON.stringify() never includes it on the wire — the brand exists solely
+ * to distinguish a modifier from a plain object (preventing a bare
+ * `{op: "merge", v: {...}}` from being misread as a modifier envelope).
+ *
+ * String-keyed properties (op, v?, path?) are enumerable and are the
+ * wire payload. .modify() serializes them directly into __vantis_ops.
+ */
+interface VerbEnvelope {
+    readonly [VERB_BRAND]: true;
+    /** The operation name sent to the engine (e.g. "increment", "toggle"). */
+    readonly op: string;
+    /** Operand value — absent for zero-operand ops (toggle, serverTimestamp). */
+    readonly v?: unknown;
+    /**
+     * JSON path for jsonSet — an array of path segments.
+     * Only present on envelopes returned by jsonSet().
+     * Sent as __vantis_ops->col->'path' alongside 'v'.
+     */
+    readonly path?: string[];
+}
+/**
+ * Phantom-branded subtype of VerbEnvelope for numeric column ops
+ * (increment / decrement / multiply / divide / min / max).
+ * The `__verb` property is optional and never-valued at runtime
+ * (TS-only phantom discriminant; JSON.stringify never emits it).
+ */
+interface NumericVerb extends VerbEnvelope {
+    readonly __verb?: 'numeric';
+}
+/**
+ * Phantom-branded subtype of VerbEnvelope for boolean column ops (toggle).
+ */
+interface BooleanVerb extends VerbEnvelope {
+    readonly __verb?: 'boolean';
+}
+/**
+ * Phantom-branded subtype of VerbEnvelope for timestamptz/date column ops
+ * (serverTimestamp).
+ */
+interface TemporalVerb extends VerbEnvelope {
+    readonly __verb?: 'temporal';
+}
+/**
+ * Phantom-branded subtype of VerbEnvelope for text/varchar column ops (concat).
+ */
+interface TextVerb extends VerbEnvelope {
+    readonly __verb?: 'text';
+}
+/**
+ * Phantom-branded subtype of VerbEnvelope for jsonb column ops
+ * (merge / jsonSet).
+ */
+interface JsonbVerb extends VerbEnvelope {
+    readonly __verb?: 'jsonb';
+}
+/**
+ * Phantom-branded subtype of VerbEnvelope for the cross-type setOnInsert op.
+ * Valid on ANY non-PK column in the upsert branch.
+ */
+interface SetOnInsertVerb extends VerbEnvelope {
+    readonly __verb?: 'setOnInsert';
+}
+/**
+ * Increment a numeric column by n (atomic server-side, no lost-update risk).
+ *
+ * @param n - The increment amount. bigint is serialized as a string to
+ *            preserve precision; the server casts it to the column type.
+ */
+declare function increment(n: number | string | bigint): NumericVerb;
+/**
+ * Decrement a numeric column by n (atomic server-side).
+ *
+ * @param n - The decrement amount. bigint is serialized as a string.
+ */
+declare function decrement(n: number | string | bigint): NumericVerb;
+/**
+ * Multiply a numeric column by n (atomic server-side).
+ *
+ * @param n - The multiplier. bigint is serialized as a string.
+ */
+declare function multiply(n: number | string | bigint): NumericVerb;
+/**
+ * Divide a numeric column by n.
+ *
+ * Division by zero raises SQLSTATE 22012 and rolls the whole operation back
+ * atomically — surfaced as a typed DataError. Integer/numeric overflow raises
+ * 22003 and is also rolled back atomically.
+ *
+ * @param n - The divisor. bigint is serialized as a string.
+ */
+declare function divide(n: number | string | bigint): NumericVerb;
+/**
+ * Set a numeric field to v only if v < the current value — Mongo $min semantics
+ * (running minimum / lower-clamp via LEAST(current, v)).
+ * If the current value is NULL, the field is set to v.
+ *
+ * @param v - The candidate lower bound. bigint is serialized as a string.
+ */
+declare function min(v: number | string | bigint): NumericVerb;
+/**
+ * Set a numeric field to v only if v > the current value — Mongo $max semantics
+ * (high-water-mark / upper-clamp via GREATEST(current, v)).
+ * If the current value is NULL, the field is set to v.
+ *
+ * @param v - The candidate upper bound. bigint is serialized as a string.
+ */
+declare function max(v: number | string | bigint): NumericVerb;
+/**
+ * Flip a boolean column atomically (server reads the current value and negates it).
+ *
+ * Only valid on the UPDATE branch — toggle on the upsert INSERT seed raises a
+ * server-side error (there is no "current value" to flip on a new row). Use
+ * setOnInsert() to seed a boolean value on the upsert path.
+ */
+declare function toggle(): BooleanVerb;
+/**
+ * Set a timestamptz or date column to the server transaction clock
+ * (PostgreSQL transaction_timestamp() — consistent within the same transaction,
+ * independent of the client clock).
+ *
+ * Named `serverTimestamp` (not `now`) to avoid collision with the `now()`
+ * builtin default (a column `default` in `vantis.schema.json`). No operand — the
+ * server supplies the value.
+ */
+declare function serverTimestamp(): TemporalVerb;
+/**
+ * Append s to a text or varchar column atomically (server-side col || s).
+ *
+ * @param s - The string to append. Concatenated at the server, not the client.
+ */
+declare function concat(s: string): TextVerb;
+/**
+ * Atomically shallow-merge obj into a jsonb column
+ * (PostgreSQL `col || obj` — union of top-level keys, obj wins on duplicates).
+ * Does NOT recursively merge nested objects — for deep merges, use jsonSet().
+ *
+ * @param obj - The object to shallow-merge into the column.
+ */
+declare function merge(obj: Record<string, unknown>): JsonbVerb;
+/**
+ * Atomically set a path within a jsonb column to v
+ * (PostgreSQL `jsonb_set(col, path, v, create_if_missing := true)`).
+ *
+ * Creates the LEAF key at `path` if absent, but intermediate path segments
+ * must already exist — if an intermediate key is missing, PostgreSQL returns
+ * the original column value unchanged (it does not create nested structure).
+ * Use `merge()` first to ensure the intermediate container exists if needed.
+ *
+ * @param path - Array of path segments (string keys; integer indices as strings).
+ * @param v    - The value to write at the path (any JSON-serializable value).
+ */
+declare function jsonSet(path: string[], v: unknown): JsonbVerb;
+/**
+ * On the upsert INSERT branch: set this column to v (Mongo $setOnInsert semantics).
+ * On the UPDATE branch: no-op — the column retains its current value.
+ *
+ * Only valid when `.modify()` is called with `opts.upsert` (the upsert branch);
+ * using setOnInsert without `opts.upsert` raises a server-side error.
+ *
+ * @param v - The value to set on INSERT. Must be a non-null JSON-serializable value.
+ *             Passing `null` is a compile-time error; the engine rejects an explicit
+ *             JSON null operand for setOnInsert at the server-side preamble.
+ */
+declare function setOnInsert<T>(v: T extends null ? never : T): SetOnInsertVerb;
+
+export { type BooleanVerb, type DataError, type DataResult, type Embeds, type JsonbVerb, type LimitOptions, type ModifyOptions, type NumericVerb, type OrderOptions, QueryBuilder, type Rpc, type Schema, type SchemaInsert, type SearchOptions, type SelectOptions, type SetOnInsertVerb, type TemporalVerb, type TextVerb, type UpsertOptions, type VerbEnvelope, type Verbs, concat, data, decrement, divide, increment, jsonSet, max, merge, min, multiply, serverTimestamp, setOnInsert, toggle };