@burojs/hasura 0.2.0 → 0.4.0

package/dist/index.d.ts

@@ -1,81 +1,81 @@
-import { DataOperationContext, DataProvider, FilterExpression, ErasedResourceHandle, DataLiveProvider } from '@burojs/core';
-
+import { DataLiveProvider, DataOperationContext, DataProvider, ErasedResourceHandle, FilterExpression } from "@burojs/core";
+//#region src/data-provider.d.ts
 interface HasuraDataProviderConfig {
-    /** Returns a fresh JWT or null if user is not authed. */
-    getToken: () => Promise<string | null>;
-    /**
-     * GraphQL endpoint every query/mutation is POSTed to, and the endpoint the
-     * live provider derives its WebSocket URL from. May be a same-origin path
-     * (`/gql/v1/graphql`, `/tandt/gql/v1/graphql`) or an absolute http(s) URL.
-     * Defaults to {@link DEFAULT_HASURA_ENDPOINT}.
-     */
-    endpoint?: string;
-    /**
-     * Hasura role sent as `X-Hasura-Role` for resources whose mapping does not
-     * declare a `role` of its own. `null` (the default) sends no role header at
-     * all, leaving the JWT's own default role in force.
-     *
-     * A resource mapping's `role` always wins when it is defined — including
-     * `role: null`, which suppresses the header for that one resource.
-     *
-     * `''` is treated as `null`, in both halves of the package: it is the shape
-     * of a missing env var, not a role. See {@link normalizeRole}.
-     */
-    defaultRole?: string | null;
-    /**
-     * Revalidates authentication after a request comes back with HTTP **401**.
-     * The callback owns any terminal sign-out; returning true permits one retry
-     * with a newly obtained token, while false preserves the original 401
-     * response.
-     *
-     * ⚠️ KNOWN GAP, stated here because this is where a consumer reads: HTTP 401
-     * is NOT how the Hasura deployment this provider was distilled from rejects
-     * a credential. The one capture in this repository of a real rejection
-     * (`packages/mock-kit/fixtures/hasura/error-unauthorized.json`, taken from
-     * the live backend with a deliberately malformed bearer token) came back
-     * **HTTP 200** with an `invalid-jwt` errors envelope. Replayed through this
-     * provider it surfaces as `{ kind: 'protocol', code: 'graphql-error' }` and
-     * `recoverAuth` is never consulted — no refresh, no retry, and app logic
-     * keyed on `kind: 'auth'` never fires either. Pinned by
-     * `tests/fixture-fidelity.test.ts`'s `error-unauthorized` case.
-     *
-     * So this callback fires only for a deployment that really answers 401 (a
-     * proxy or gateway in front of Hasura, typically). Keying recovery on the
-     * error envelope instead is a product decision, deliberately not taken here;
-     * the existing 401 tests use a FABRICATED 401 and must not be read as proof
-     * that recovery works against Hasura itself.
-     */
-    recoverAuth?: () => Promise<boolean>;
-    /** Map our resource name → table + field selection. */
-    resources: Record<string, ResourceMapping>;
-    /**
-     * Optional global scope read on every getList. Returns key → value pairs
-     * that get merged into the where clause as `{ <key>: { _eq: <value> } }`,
-     * but only for resources that whitelist the key in `scopeFields`.
-     *
-     * Example: `() => ({ pg: 'radio', location_id: 5 })` — applied to documents
-     * (which have both fields) but not products (which only have pg).
-     */
-    getScope?: (context: DataOperationContext) => Record<string, unknown>;
-    /**
-     * Closed, application-owned custom operation registry. A descriptor selects
-     * an entry by its already-declared `{ resource, operation }` binding; it can
-     * never supply a GraphQL document, URL, or result mapper itself.
-     */
-    operations?: HasuraOperationRegistry;
-    fetchImpl?: typeof fetch;
+  /** Returns a fresh JWT or null if user is not authed. */
+  getToken: () => Promise<string | null>;
+  /**
+   * GraphQL endpoint every query/mutation is POSTed to, and the endpoint the
+   * live provider derives its WebSocket URL from. May be a same-origin path
+   * (`/gql/v1/graphql`, `/tandt/gql/v1/graphql`) or an absolute http(s) URL.
+   * Defaults to {@link DEFAULT_HASURA_ENDPOINT}.
+   */
+  endpoint?: string;
+  /**
+   * Hasura role sent as `X-Hasura-Role` for resources whose mapping does not
+   * declare a `role` of its own. `null` (the default) sends no role header at
+   * all, leaving the JWT's own default role in force.
+   *
+   * A resource mapping's `role` always wins when it is defined — including
+   * `role: null`, which suppresses the header for that one resource.
+   *
+   * `''` is treated as `null`, in both halves of the package: it is the shape
+   * of a missing env var, not a role. See {@link normalizeRole}.
+   */
+  defaultRole?: string | null;
+  /**
+   * Revalidates authentication after a request comes back with HTTP **401**.
+   * The callback owns any terminal sign-out; returning true permits one retry
+   * with a newly obtained token, while false preserves the original 401
+   * response.
+   *
+   * ⚠️ KNOWN GAP, stated here because this is where a consumer reads: HTTP 401
+   * is NOT how the Hasura deployment this provider was distilled from rejects
+   * a credential. The one capture in this repository of a real rejection
+   * (`packages/mock-kit/fixtures/hasura/error-unauthorized.json`, taken from
+   * the live backend with a deliberately malformed bearer token) came back
+   * **HTTP 200** with an `invalid-jwt` errors envelope. Replayed through this
+   * provider it surfaces as `{ kind: 'protocol', code: 'graphql-error' }` and
+   * `recoverAuth` is never consulted — no refresh, no retry, and app logic
+   * keyed on `kind: 'auth'` never fires either. Pinned by
+   * `tests/fixture-fidelity.test.ts`'s `error-unauthorized` case.
+   *
+   * So this callback fires only for a deployment that really answers 401 (a
+   * proxy or gateway in front of Hasura, typically). Keying recovery on the
+   * error envelope instead is a product decision, deliberately not taken here;
+   * the existing 401 tests use a FABRICATED 401 and must not be read as proof
+   * that recovery works against Hasura itself.
+   */
+  recoverAuth?: () => Promise<boolean>;
+  /** Map our resource name → table + field selection. */
+  resources: Record<string, ResourceMapping>;
+  /**
+   * Optional global scope read on every getList. Returns key → value pairs
+   * that get merged into the where clause as `{ <key>: { _eq: <value> } }`,
+   * but only for resources that whitelist the key in `scopeFields`.
+   *
+   * Example: `() => ({ pg: 'radio', location_id: 5 })` — applied to documents
+   * (which have both fields) but not products (which only have pg).
+   */
+  getScope?: (context: DataOperationContext) => Record<string, unknown>;
+  /**
+   * Closed, application-owned custom operation registry. A descriptor selects
+   * an entry by its already-declared `{ resource, operation }` binding; it can
+   * never supply a GraphQL document, URL, or result mapper itself.
+   */
+  operations?: HasuraOperationRegistry;
+  fetchImpl?: typeof fetch;
 }
 interface HasuraCustomOperation {
-    /** Which native provider slot may execute this declaration. */
-    readonly kind: 'query' | 'mutation';
-    /** Static GraphQL document owned by the application/provider integration. */
-    readonly document: string;
-    /** Maps the declared operation input to the document's variables. */
-    readonly variables: (input: unknown) => Record<string, unknown> | undefined;
-    /** Maps the full GraphQL response to the declared operation output. */
-    readonly mapResult?: (data: unknown) => unknown;
-    /** Overrides the mapped resource role; undefined keeps that mapped role. */
-    readonly role?: string | null;
+  /** Which native provider slot may execute this declaration. */
+  readonly kind: 'query' | 'mutation';
+  /** Static GraphQL document owned by the application/provider integration. */
+  readonly document: string;
+  /** Maps the declared operation input to the document's variables. */
+  readonly variables: (input: unknown) => Record<string, unknown> | undefined;
+  /** Maps the full GraphQL response to the declared operation output. */
+  readonly mapResult?: (data: unknown) => unknown;
+  /** Overrides the mapped resource role; undefined keeps that mapped role. */
+  readonly role?: string | null;
 }
 /**
  * Registry entries are keyed by the resource binding first, then the declared
@@ -84,183 +84,251 @@ interface HasuraCustomOperation {
  */
 type HasuraOperationRegistry = Readonly<Record<string, Readonly<Record<string, HasuraCustomOperation>>>>;
 interface ResourceMapping {
-    table: string;
-    selectFields: string[];
-    /**
-     * GraphQL scalar name for this table's primary key, interpolated into the
-     * `$id` variable declaration of every by-pk query/mutation. Default
-     * `'bigint'`.
-     *
-     * DISTILLATION NOTE (divergence 3 of 7 — feature, additive, l2-web-ui only).
-     * l2-web-ui added `'String'` for tables whose pk is a genuine string
-     * business key (a GS1 marking code), not a uuid/Int/bigint
-     * wire type: Hasura's by-pk root for such a table is literally
-     * `<table>_by_pk(<pk>: $id)` with `$id: String!`, which none of the other
-     * three names can express (playground's union stopped at
-     * `'bigint' | 'uuid' | 'Int'`). Purely a type-union widening — no runtime
-     * branch reads `pkType` beyond interpolating it — so l2-web-ui's wider union
-     * is taken wholesale rather than forked.
-     */
-    pkType?: 'bigint' | 'uuid' | 'Int' | 'String';
-    /**
-     * Skip the aggregate on every `getList`. This is a COST decision, not a
-     * schema fact: the table has an `_aggregate` root but counting it on each
-     * page is too slow to pay for unprompted. (Measured in one of the apps this
-     * provider was distilled from: ~9.8M-row and ~28.9M-row tables, the latter
-     * taking ~55 s per count.) `total` is then omitted and the list renders the
-     * unknown-total shape.
-     *
-     * ⚠️ NOT the same thing as {@link ResourceMapping.aggregate} `: false`, and
-     * NOT a proxy for it — most `noAggregate` tables CAN be counted on demand,
-     * which is exactly what `getCount` is for. Deriving one from the other gets
-     * the flagship resources backwards.
-     */
-    noAggregate?: boolean;
-    /**
-     * Which aggregate root field backs this table, for the on-demand `getCount`
-     * (and for `getList`'s own count when it runs):
-     *  - absent  — derive `${table}_aggregate` (the Hasura default; today's behaviour);
-     *  - `false` — no aggregate root exists at all, under any name. `getCount`
-     *    answers `{ total: null }` without a round trip and the UI drops the
-     *    affordance for the session;
-     *  - a string — an explicitly-named root, for tables whose custom root fields
-     *    break the derivation.
-     *
-     * ⚠️ Establish this by introspecting the live schema under the role the app
-     * actually runs as, not by reading `noAggregate` or a code comment. Both
-     * have been wrong here.
-     */
-    aggregate?: false | string;
-    /**
-     * Root field for a single-row fetch by primary key. Defaults to the derived
-     * `${table}_by_pk`. Set `false` when the active role exposes only the
-     * collection root; `getOne` then queries it with pk `where` + `limit: 1`.
-     *
-     * ⚠️ Same class of fact as `aggregate`, and established the same way — by
-     * introspecting the live schema, not by reading a comment. In one of the
-     * source apps exactly one table of forty had a non-derivable by-pk root (a
-     * plural table whose root was singular), so the derived name 400'd and its
-     * Show page was a dead-end error reachable in two clicks from the sidebar.
-     */
-    byPkRoot?: string | false;
-    /** Field to order by in getList. Defaults to 'id'. */
-    orderByField?: string;
-    /** Name of the primary-key field in the row (for synthetic id in list rows). Defaults to 'id'. */
-    pkField?: string;
-    /**
-     * Hasura role for this resource. `null` (or `''`) means no role header (use
-     * the JWT's default role). Undefined falls back to
-     * {@link HasuraDataProviderConfig.defaultRole}.
-     */
-    role?: string | null;
-    /**
-     * Columns typed `int64` in a Hasura ClickHouse source. Hasura serialises
-     * int64 as a JSON STRING and REJECTS a numeric filter value with
-     * «expected a string for type 'int64'» — so a `document_id` filter sent as a
-     * number matched nothing and the affected list tabs came back empty.
-     * Filter values for these fields are coerced to strings before the where
-     * clause is built. (Verified live: numeric/int literal → error, string → rows.)
-     */
-    int64Fields?: string[];
-    /**
-     * Whitelist of scope keys this table actually has columns for. Only these
-     * keys from `getScope()` get injected into where clauses. Defaults to `[]`
-     * (no scope injection — useful for tables that lack the scope columns).
-     */
-    scopeFields?: string[];
-    /**
-     * JSONB-spill routing for tables whose forms submit a flat values record but
-     * whose real columns nest most of those keys inside JSONB blobs (e.g. a
-     * `documents` table where template head fields live inside `head`, a couple
-     * live inside `meta`, and only a handful — type/status/… — are real columns).
-     *
-     * When set, create/update partition the incoming flat `variables`:
-     *  - keys that ARE real columns (present in `selectFields`) stay top-level;
-     *  - keys listed in `metaKeys` nest under `metaColumn`;
-     *  - every OTHER key nests under `column` (the head spill).
-     * getOne does the inverse — it spreads the fetched `column`/`metaColumn`
-     * objects back onto the flat record so edit forms / show pages read those
-     * keys as flat fields (the raw blobs are kept too).
-     *
-     * SCOPE: scalar / relation / enum head+meta fields only. Data-body arrays
-     * (children) live in a sibling table — see `dataBody`.
-     */
-    jsonbSpill?: JsonbSpillConfig;
-    /**
-     * Data-body routing for resources whose heavy array payload lives in a
-     * SEPARATE 1:1 sibling table rather than a JSONB column on the row itself
-     * (e.g. a `documents.items[]` / `products[]` payload living in
-     * `documents_data.data`, keyed by `document_id`).
-     *
-     * When set, create/update peel the `keys` off the flat `variables` FIRST
-     * (before `jsonbSpill` runs, so they never leak into `head`), write the parent
-     * row, then upsert the sibling row (`insert_<table>_one … on_conflict`). getOne
-     * nested-selects the sibling via `relationship` and spreads its `column` blob
-     * back onto the flat record (so edit forms read `items` as a top-level field),
-     * dropping the raw relationship object so it can't round-trip into `head`.
-     * getList is left untouched — list columns are head/meta scalars, never the
-     * heavy data body.
-     */
-    dataBody?: DataBodyConfig;
-    /**
-     * Fixed, always-on Hasura `where` fragment ANDed into every getList /
-     * getOne query for this resource. Powers "per-type" / projection resources:
-     * several resource names can map to the SAME table, each scoped to a
-     * different slice — e.g. `fixedFilter: { type: { _eq: 'work_order' } }` turns
-     * a `work_orders` resource into a work-orders-only view of a shared
-     * `documents` table. The fragment is a raw Hasura `<table>_bool_exp` object
-     * (same shape `filtersToWhere` emits), so nested / `_and` / `_or` clauses are
-     * all valid. Merged with `mergeWhere` (AND) after user filters + scope, so
-     * the user can still filter/search WITHIN the fixed slice.
-     *
-     * getOne: because `<table>_by_pk` takes no `where`, a resource with a
-     * `fixedFilter` fetches its single row via a `where`-based `limit: 1` query
-     * (pk `_eq` id AND fixedFilter) instead — so the row is only returned when it
-     * actually belongs to the slice (a work-order id won't resolve under
-     * `movements`). Resources without a `fixedFilter` keep the `_by_pk` path.
-     */
-    fixedFilter?: Record<string, unknown>;
-    /**
-     * Opt this resource into real-time updates. The live provider then opens a
-     * cheap change-signal subscription for its list / single-record views and
-     * invalidates matching native runtime queries when the table changes.
-     *
-     * Off by default on purpose: every live resource holds an open server-side
-     * subscription, so it is a cost you opt into for data that actually moves
-     * (documents change constantly during processing; a country lookup does not).
-     */
-    live?: boolean;
+  table: string;
+  selectFields: string[];
+  /**
+   * GraphQL scalar name for this table's primary key, interpolated into the
+   * `$id` variable declaration of every by-pk query/mutation. Default
+   * `'bigint'`.
+   *
+   * DISTILLATION NOTE (divergence 3 of 7 — feature, additive, l2-web-ui only).
+   * l2-web-ui added `'String'` for tables whose pk is a genuine string
+   * business key (a GS1 marking code), not a uuid/Int/bigint
+   * wire type: Hasura's by-pk root for such a table is literally
+   * `<table>_by_pk(<pk>: $id)` with `$id: String!`, which none of the other
+   * three names can express (playground's union stopped at
+   * `'bigint' | 'uuid' | 'Int'`). Purely a type-union widening — no runtime
+   * branch reads `pkType` beyond interpolating it — so l2-web-ui's wider union
+   * is taken wholesale rather than forked.
+   */
+  pkType?: 'bigint' | 'uuid' | 'Int' | 'String';
+  /**
+   * Skip the aggregate on every `getList`. This is a COST decision, not a
+   * schema fact: the table has an `_aggregate` root but counting it on each
+   * page is too slow to pay for unprompted. (Measured in one of the apps this
+   * provider was distilled from: ~9.8M-row and ~28.9M-row tables, the latter
+   * taking ~55 s per count.) `total` is then omitted and the list renders the
+   * unknown-total shape.
+   *
+   * ⚠️ NOT the same thing as {@link ResourceMapping.aggregate} `: false`, and
+   * NOT a proxy for it — most `noAggregate` tables CAN be counted on demand,
+   * which is exactly what `getCount` is for. Deriving one from the other gets
+   * the flagship resources backwards.
+   */
+  noAggregate?: boolean;
+  /**
+   * Which aggregate root field backs this table, for the on-demand `getCount`
+   * (and for `getList`'s own count when it runs):
+   *  - absent  — derive `${table}_aggregate` (the Hasura default; today's behaviour);
+   *  - `false` — no aggregate root exists at all, under any name. `getCount`
+   *    answers `{ total: null }` without a round trip and the UI drops the
+   *    affordance for the session;
+   *  - a string — an explicitly-named root, for tables whose custom root fields
+   *    break the derivation.
+   *
+   * ⚠️ Establish this by introspecting the live schema under the role the app
+   * actually runs as, not by reading `noAggregate` or a code comment. Both
+   * have been wrong here.
+   */
+  aggregate?: false | string;
+  /**
+   * Root field for a single-row fetch by primary key. Defaults to the derived
+   * `${table}_by_pk`. Set `false` when the active role exposes only the
+   * collection root; `getOne` then queries it with pk `where` + `limit: 1`.
+   *
+   * ⚠️ Same class of fact as `aggregate`, and established the same way — by
+   * introspecting the live schema, not by reading a comment. In one of the
+   * source apps exactly one table of forty had a non-derivable by-pk root (a
+   * plural table whose root was singular), so the derived name 400'd and its
+   * Show page was a dead-end error reachable in two clicks from the sidebar.
+   */
+  byPkRoot?: string | false;
+  /** Field to order by in getList. Defaults to 'id'. */
+  orderByField?: string;
+  /** Name of the primary-key field in the row (for synthetic id in list rows). Defaults to 'id'. */
+  pkField?: string;
+  /**
+   * Hasura role for this resource. `null` (or `''`) means no role header (use
+   * the JWT's default role). Undefined falls back to
+   * {@link HasuraDataProviderConfig.defaultRole}.
+   */
+  role?: string | null;
+  /**
+   * Columns typed `int64` in a Hasura ClickHouse source. Hasura serialises
+   * int64 as a JSON STRING and REJECTS a numeric filter value with
+   * «expected a string for type 'int64'» — so a `document_id` filter sent as a
+   * number matched nothing and the affected list tabs came back empty.
+   * Filter values for these fields are coerced to strings before the where
+   * clause is built. (Verified live: numeric/int literal → error, string → rows.)
+   */
+  int64Fields?: string[];
+  /**
+   * Whitelist of scope keys this table actually has columns for. Only these
+   * keys from `getScope()` get injected into where clauses. Defaults to `[]`
+   * (no scope injection — useful for tables that lack the scope columns).
+   *
+   * ⚠️ SCOPE NARROWS THREE READ PATHS, NOT FIVE. `scopeToWhere` is reached
+   * only through {@link composeListWhere}, i.e. from `queries.list` (both
+   * branches), `queries.count` and `queries.many`. **`queries.one` composes
+   * `{pk _eq id} ∧ fixedFilter ∧ localeSlice` and carries NO scope**, so a
+   * record excluded from a scoped list is still readable by its id through
+   * this provider. `fixedFilter` — a slice that cannot depend on the session —
+   * does cover `one`; the session-dependent pair (`getScope` + `scopeFields`)
+   * does not. Treat a scoped projection as a LIST narrowing, and do not rely
+   * on it as an authorization boundary: that belongs in the backend's own row
+   * permissions, which is where a real Hasura deployment enforces it. Raised
+   * by the SP4 final review (M3); closing it is a change to the by-pk path
+   * with its own blast radius and is carried as a follow-up rather than made
+   * here.
+   */
+  scopeFields?: string[];
+  /**
+   * JSONB-spill routing for tables whose forms submit a flat values record but
+   * whose real columns nest most of those keys inside JSONB blobs (e.g. a
+   * `documents` table where template head fields live inside `head`, a couple
+   * live inside `meta`, and only a handful — type/status/… — are real columns).
+   *
+   * When set, create/update partition the incoming flat `variables`:
+   *  - keys that ARE real columns (present in `selectFields`) stay top-level;
+   *  - keys listed in `metaKeys` nest under `metaColumn`;
+   *  - every OTHER key nests under `column` (the head spill).
+   * getOne does the inverse — it spreads the fetched `column`/`metaColumn`
+   * objects back onto the flat record so edit forms / show pages read those
+   * keys as flat fields (the raw blobs are kept too).
+   *
+   * SCOPE: scalar / relation / enum head+meta fields only. Data-body arrays
+   * (children) live in a sibling table — see `dataBody`.
+   */
+  jsonbSpill?: JsonbSpillConfig;
+  /**
+   * Data-body routing for resources whose heavy array payload lives in a
+   * SEPARATE 1:1 sibling table rather than a JSONB column on the row itself
+   * (e.g. a `documents.items[]` / `products[]` payload living in
+   * `documents_data.data`, keyed by `document_id`).
+   *
+   * When set, create/update peel the `keys` off the flat `variables` FIRST
+   * (before `jsonbSpill` runs, so they never leak into `head`), write the parent
+   * row, then upsert the sibling row (`insert_<table>_one … on_conflict`). getOne
+   * nested-selects the sibling via `relationship` and spreads its `column` blob
+   * back onto the flat record (so edit forms read `items` as a top-level field),
+   * dropping the raw relationship object so it can't round-trip into `head`.
+   * getList is left untouched — list columns are head/meta scalars, never the
+   * heavy data body.
+   */
+  dataBody?: DataBodyConfig;
+  /**
+   * Fixed, always-on Hasura `where` fragment ANDed into every getList /
+   * getOne query for this resource. Powers "per-type" / projection resources:
+   * several resource names can map to the SAME table, each scoped to a
+   * different slice — e.g. `fixedFilter: { type: { _eq: 'work_order' } }` turns
+   * a `work_orders` resource into a work-orders-only view of a shared
+   * `documents` table. The fragment is a raw Hasura `<table>_bool_exp` object
+   * (same shape `filtersToWhere` emits), so nested / `_and` / `_or` clauses are
+   * all valid. Merged with `mergeWhere` (AND) after user filters + scope, so
+   * the user can still filter/search WITHIN the fixed slice.
+   *
+   * getOne: because `<table>_by_pk` takes no `where`, a resource with a
+   * `fixedFilter` fetches its single row via a `where`-based `limit: 1` query
+   * (pk `_eq` id AND fixedFilter) instead — so the row is only returned when it
+   * actually belongs to the slice (a work-order id won't resolve under
+   * `movements`). Resources without a `fixedFilter` keep the `_by_pk` path.
+   */
+  fixedFilter?: Record<string, unknown>;
+  /**
+   * The column on this table that holds a row's LANGUAGE, for a backend that
+   * translates by storing one row per locale (the "sidecar translation table"
+   * shape: `catalog_product_translation(product_id, locale, name, …)`).
+   *
+   * When set, every read handler of this resource ANDs `{ <localeField>: {
+   * _eq: <descriptor.locale> } }` into its `where` — `queries.list` (both the
+   * offset and the cursor branch), `queries.count`, `queries.many` and the
+   * by-pk `queries.one` alike — so the caller gets exactly the active
+   * language's rows.
+   *
+   * ⚠️ EXACTLY FOUR HANDLERS, not "every read anywhere in this module", and
+   * the difference is worth stating because an earlier revision of this
+   * sentence was broader than the code. Two reads are deliberately outside it:
+   *
+   *  - `readMutationRecord` — the re-read a mutation performs to return the
+   *    row it just wrote. It addresses ONE row the caller has just named by
+   *    primary key, and per the write rule below the caller supplied its
+   *    `locale` themselves. Narrowing it by the UI's active language could
+   *    only turn a successful write into a `null` result for a row the caller
+   *    is holding in its hand.
+   *  - `queries.many` with an EMPTY id set — see the note at its early
+   *    return; it refuses eagerly (`localeWhere` is called before the empty
+   *    read short-circuits) precisely so this list does not need a third
+   *    exception.
+   * `descriptor.locale` is put there by `@burojs/core`'s
+   * `resolveDescriptorLocale`, which fills it ONLY for a resource declaring
+   * `data: { localeVarying: true }`.
+   *
+   * ⚠️ THE TWO DECLARATIONS MUST AGREE, and this provider REFUSES rather than
+   * guessing when they do not. A mapping with a `localeField` whose descriptor
+   * carries no locale means the resource forgot `localeVarying`, and the
+   * consequence is not cosmetic: the query returns EVERY language's rows —
+   * three rows per product, in mixed languages, with duplicate business keys —
+   * which is a plausible-looking wrong answer, the defect class this package
+   * refuses on four other paths (cursor orderability, unsupported operators,
+   * unmapped resources, absent aggregate roots). So the read throws
+   * {@link LOCALE_REQUIRED_CODE} naming both halves of the fix.
+   *
+   * ⚠️ WRITES ARE NOT TOUCHED. `create`/`update`/`delete` do not inject the
+   * locale: a mutation on a translation row must name its own `locale` in the
+   * submitted values (it is a real column), and a by-pk update addresses one
+   * row by its own primary key, which already identifies the language. Silently
+   * stamping the UI's active language onto a write would be a different and
+   * much worse guess than the one refused above.
+   *
+   * Why a column name here rather than a Hasura ARGUMENT: this provider selects
+   * FLAT COLUMNS (see `selectFields`), and `ARRAY_RELATION_ARGS` carries no
+   * nested `where`, so a translated value cannot be pulled through a nested
+   * relation selection on the parent row at all. Reading the translation table
+   * as its own root query, narrowed by locale, is the access path the schema
+   * shape actually supports.
+   */
+  localeField?: string;
+  /**
+   * Opt this resource into real-time updates. The live provider then opens a
+   * cheap change-signal subscription for its list / single-record views and
+   * invalidates matching native runtime queries when the table changes.
+   *
+   * Off by default on purpose: every live resource holds an open server-side
+   * subscription, so it is a cost you opt into for data that actually moves
+   * (documents change constantly during processing; a country lookup does not).
+   */
+  live?: boolean;
 }
 /** @see ResourceMapping.jsonbSpill */
 interface JsonbSpillConfig {
-    /** JSONB column that catches every non-base, non-meta key (e.g. `head`). */
-    column: string;
-    /** JSONB column that catches the `metaKeys` (e.g. `meta`). */
-    metaColumn: string;
-    /** Flat keys routed to `metaColumn` instead of the `column` spill. */
-    metaKeys: string[];
-    /**
-     * Flat form key → dotted NESTED path inside the head `column`. Lets a flat
-     * field (e.g. `vsd_number`) persist to a nested head location (e.g.
-     * `regulator_data.crpt.vsd_number`) without dotted field keys. getOne reads
-     * the nested value back out to the flat key.
-     */
-    nestedKeys?: Record<string, string>;
+  /** JSONB column that catches every non-base, non-meta key (e.g. `head`). */
+  column: string;
+  /** JSONB column that catches the `metaKeys` (e.g. `meta`). */
+  metaColumn: string;
+  /** Flat keys routed to `metaColumn` instead of the `column` spill. */
+  metaKeys: string[];
+  /**
+   * Flat form key → dotted NESTED path inside the head `column`. Lets a flat
+   * field (e.g. `vsd_number`) persist to a nested head location (e.g.
+   * `regulator_data.crpt.vsd_number`) without dotted field keys. getOne reads
+   * the nested value back out to the flat key.
+   */
+  nestedKeys?: Record<string, string>;
 }
 /** @see ResourceMapping.dataBody */
 interface DataBodyConfig {
-    /** Sibling table holding the heavy data body, 1:1 with the parent (e.g. `documents_data`). */
-    table: string;
-    /** FK column on the sibling pointing back at the parent pk (e.g. `document_id`). */
-    fk: string;
-    /** JSONB column on the sibling that holds the whole data body (e.g. `data`). */
-    column: string;
-    /** Reverse object-relationship name on the PARENT row → sibling, for the getOne nested select (e.g. `document_data`). */
-    relationship: string;
-    /** `on_conflict` constraint enum for the upsert (e.g. `document_data_pkey`). */
-    constraint: string;
-    /** Flat value keys that belong to the data body — routed to the sibling `column` (e.g. `['items', 'products']`). */
-    keys: string[];
+  /** Sibling table holding the heavy data body, 1:1 with the parent (e.g. `documents_data`). */
+  table: string;
+  /** FK column on the sibling pointing back at the parent pk (e.g. `document_id`). */
+  fk: string;
+  /** JSONB column on the sibling that holds the whole data body (e.g. `data`). */
+  column: string;
+  /** Reverse object-relationship name on the PARENT row → sibling, for the getOne nested select (e.g. `document_data`). */
+  relationship: string;
+  /** `on_conflict` constraint enum for the upsert (e.g. `document_data_pkey`). */
+  constraint: string;
+  /** Flat value keys that belong to the data body — routed to the sibling `column` (e.g. `['items', 'products']`). */
+  keys: string[];
 }
 /**
  * Split a flat `values` record for a data-body resource into the sibling-table
@@ -277,9 +345,9 @@ interface DataBodyConfig {
  * Exported for unit testing; the provider calls it with `m.dataBody`.
  */
 declare function partitionDataBody(values: Record<string, unknown>, cfg: DataBodyConfig): {
-    dataBody: Record<string, unknown>;
-    rest: Record<string, unknown>;
-    hasDataBody: boolean;
+  dataBody: Record<string, unknown>;
+  rest: Record<string, unknown>;
+  hasDataBody: boolean;
 };
 /**
  * Partition a flat `values` record for a jsonb-spill resource.
@@ -329,6 +397,24 @@ declare function flattenJsonbSpill(item: unknown, spill: JsonbSpillConfig): unkn
  * stable symbol.
  */
 declare const NOT_AUTHENTICATED_CODE = "not-authenticated";
+/**
+ * Refusal code for "this mapping declares a `localeField` but the descriptor
+ * carries no locale". Exported so an application can match a symbol rather
+ * than a string — same treatment as {@link FILTER_OPERATOR_UNSUPPORTED_CODE}.
+ *
+ * @see ResourceMapping.localeField for why this is a refusal and not a default.
+ */
+declare const LOCALE_REQUIRED_CODE = "locale-required";
+/**
+ * The locale conjunct for a mapping that declares one, or `undefined` for a
+ * mapping that does not.
+ *
+ * The refusal is EAGER — it fires before any request leaves, so it does not
+ * depend on how many rows the table happens to hold. (Task 1 of this
+ * sub-project recorded the opposite mistake: an absence assertion that stayed
+ * green because a LAZY check downstream threw for its own reasons.)
+ */
+declare function localeWhere(m: ResourceMapping, locale: string | undefined): Record<string, unknown> | undefined;
 /**
  * The shared refusal code for "this provider cannot express that filter
  * operator". `@burojs/pocketbase` throws the SAME `kind` and the SAME code, so
@@ -348,6 +434,13 @@ declare function scopeToWhere(scope: Record<string, unknown>, scopeFields: strin
 declare function mergeWhere(a: Record<string, unknown> | undefined, b: Record<string, unknown> | undefined): Record<string, unknown> | undefined;
 /** Translate the native filter AST into a Hasura bool expression. */
 declare function filtersToWhere(filter?: FilterExpression<ErasedResourceHandle>): Record<string, unknown> | undefined;
+/**
+ * Exported for its own test: bigint coercion matches the WHOLE field string,
+ * so a nested predicate needs its full path declared in `int64Fields`.
+ * Matching the leaf would coerce a same-named column on any other table the
+ * path happens to traverse.
+ */
+declare function coerceInt64Filter(filter: FilterExpression<ErasedResourceHandle> | undefined, fields: readonly string[] | undefined): FilterExpression<ErasedResourceHandle> | undefined;
 /**
  * Resolve the Hasura aggregate root field for a mapping, or `null` when the
  * registry declares that none exists. Registry-driven on purpose: which tables
@@ -363,7 +456,202 @@ declare function aggregateRoot(m: ResourceMapping): string | null;
  */
 declare function byPkRoot(m: ResourceMapping): string | null;
 declare function createHasuraDataProvider(config: HasuraDataProviderConfig): DataProvider;
-
+//#endregion
+//#region src/cursor.d.ts
+/**
+ * Keyset ("seek") cursor pagination for Hasura.
+ *
+ * ── What a cursor IS here, and why it is synthesised ──────────────────────
+ *
+ * Hasura issues no opaque cursor tokens of its own — there is no `endCursor`
+ * to echo back, no server-side scroll state, nothing. A Relay-style
+ * `pageInfo.endCursor` on a Hasura root is a Relay-connection feature of
+ * *other* GraphQL servers; the roots this provider talks to take
+ * `limit`/`offset`/`order_by`/`where` and nothing else.
+ *
+ * So the cursor is BUILT by this provider out of the only durable thing a
+ * page leaves behind: the ordering values of its last row. The next page is
+ * then "every row that sorts strictly after that row", expressed as an
+ * ordinary `where` — which is why this needs no backend feature at all and
+ * works against any Hasura table.
+ *
+ * It is nevertheless **opaque above the provider**. Nothing outside this
+ * package parses, constructs, or compares a cursor: callers receive
+ * `pageInfo.nextCursor` and hand it back as `pagination.after`. The encoding
+ * below (base64url of a small JSON envelope) exists to make that boundary
+ * obvious at a glance, not to hide anything — a decoded cursor is inert
+ * data, and the provider re-validates every field of it before it can shape
+ * a query.
+ *
+ * ── Why a total order is mandatory, not a nicety ──────────────────────────
+ *
+ * "The rows after this one" is only well defined if the ordering is TOTAL —
+ * i.e. no two rows compare equal. Order a product list by `price_cents` and
+ * seven rows share the value 1999: a page ending inside that run leaves the
+ * provider unable to say which of the seven it stopped at. `price_cents >
+ * 1999` SKIPS the rest of the run; `price_cents >= 1999` REPEATS the ones
+ * already shown. Both answers look perfectly plausible on screen, which is
+ * what makes the bug expensive.
+ *
+ * The fix is the standard one: append the primary key as a final
+ * tie-breaker, and compare rows lexicographically over the whole ordering
+ * (see {@link keysetWhere}). The pk is unique, so ordering columns + pk is
+ * always total.
+ *
+ * ── Why this module refuses instead of falling back ───────────────────────
+ *
+ * Every refusal below is a case where the provider cannot express the
+ * request faithfully. None of them degrades to offset pagination, and that
+ * is deliberate: converting "not expressible" into a plausible wrong answer
+ * is the single defect class this codebase has caught most often (a
+ * branchless `_or: []` matching every row; `OP_MAP[op] ?? '_eq'` turning an
+ * unknown operator into equality). A cursor list silently served as offset
+ * would duplicate and skip rows under concurrent writes and would never
+ * report that it had done so.
+ */
+/** One column of the effective ordering, after the tie-breaker has been applied. */
+interface CursorOrderingColumn {
+  readonly field: string;
+  readonly direction: 'asc' | 'desc';
+}
+/**
+ * Every refusal this module can raise, as a frozen record so a consumer
+ * matches a symbol rather than re-typing a string literal — the same reason
+ * `NOT_AUTHENTICATED_CODE` and `FILTER_OPERATOR_UNSUPPORTED_CODE` are
+ * exported.
+ *
+ * `cursor-pagination-unsupported`, the blanket refusal this package threw
+ * before cursors existed, is GONE — nothing throws it any more. A consumer
+ * that matched on it was matching "this provider has no cursors at all",
+ * which is no longer true; the honest replacements are these six, each
+ * naming a specific request the provider still cannot serve.
+ */
+declare const HASURA_CURSOR_CODES: Readonly<{
+  /** The effective ordering cannot be made total — see {@link assertCursorOrderable}. */
+  readonly unorderable: "cursor-unorderable";
+  /** `pagination.before` was supplied; only forward paging is implemented. */
+  readonly backward: "cursor-backward-unsupported";
+  /** `pagination.limit` is not a positive integer. */
+  readonly limit: "cursor-limit-invalid";
+  /** The `after` string is not a cursor this provider minted. */
+  readonly malformed: "cursor-malformed";
+  /** The cursor was minted under a different ordering than this request asks for. */
+  readonly mismatch: "cursor-ordering-mismatch";
+  /** The boundary row's ordering value is NULL, so no keyset predicate can address it. */
+  readonly boundaryNull: "cursor-boundary-null";
+}>;
+/**
+ * The ordering a cursor was minted under, as a single comparable string.
+ * Recorded inside the cursor and re-checked on the way back in, so a cursor
+ * taken from a list sorted by price cannot be replayed against the same list
+ * sorted by name: the keyset predicate would be built from the wrong columns
+ * and the resulting page would be arbitrary rather than wrong-looking.
+ */
+declare function orderingSignature(ordering: readonly CursorOrderingColumn[]): string;
+/**
+ * The ordering this provider will actually emit for a cursor page: the
+ * caller's sort (or the mapping's default when there is none), with the
+ * primary key appended as the tie-breaker unless the caller already sorts by
+ * it.
+ *
+ * The tie-breaker inherits the direction of the last ordering column rather
+ * than being pinned to `asc`. Either choice yields a total order; inheriting
+ * keeps a `desc` list reading in one direction all the way down instead of
+ * flipping inside each run of equal values, which is what a reader would
+ * expect from "newest first, ties broken by newest id".
+ */
+declare function effectiveCursorOrdering(sort: readonly {
+  readonly field: string;
+  readonly direction: 'asc' | 'desc';
+}[] | undefined, mapping: {
+  readonly pkField?: string;
+  readonly orderByField?: string;
+}): readonly CursorOrderingColumn[];
+/**
+ * REFUSAL 1 — the ordering cannot produce a total order this provider can
+ * both emit and read back.
+ *
+ * Two conditions, both checked EAGERLY (before any request leaves the
+ * client), because a refusal that depends on how many rows happen to be in
+ * the table is not a refusal — it is a coin flip. That lesson is recorded in
+ * `@burojs/mock-kit`: an unsupported operator checked lazily answered `[]`
+ * for an empty table and threw for a populated one.
+ *
+ *  1. An ordering column is not in `selectFields`. The cursor is made of the
+ *     boundary row's ordering values, and a column the query does not select
+ *     is not in the row that comes back. This is also how the pk tie-breaker
+ *     is enforced: a mapping that does not select its own primary key cannot
+ *     be cursor-paginated at all.
+ *  2. A sort entry carries `nulls: 'first' | 'last'`. Hasura expresses that
+ *     as `asc_nulls_first`/`desc_nulls_last`, and a keyset predicate over a
+ *     nullable column under those semantics needs `IS NULL` branches this
+ *     provider does not build. The OFFSET path ignores `nulls` outright —
+ *     which is a real (pre-existing) infidelity there, but harmless in the
+ *     sense that offset paging stays self-consistent. Ignoring it here would
+ *     not: pages would be cut at boundaries the emitted `order_by` does not
+ *     actually produce, so rows would be skipped.
+ */
+declare function assertCursorOrderable(ordering: readonly CursorOrderingColumn[], sort: readonly {
+  readonly field: string;
+  readonly nulls?: 'first' | 'last';
+}[] | undefined, mapping: {
+  readonly table: string;
+  readonly selectFields: readonly string[];
+}): void;
+/** Positive-integer page size. A cursor page has no other way to bound itself. */
+declare function assertCursorLimit(limit: unknown, table: string): asserts limit is number;
+/**
+ * Mints the cursor that addresses the row AFTER `row`.
+ *
+ * REFUSAL 2 — a NULL (or absent) ordering value on the boundary row. A
+ * keyset predicate compares with `_gt`/`_lt`, and in SQL every comparison
+ * against NULL is NULL, i.e. matches nothing: a cursor minted from a NULL
+ * boundary would return an empty next page and the list would look finished
+ * while rows remained. Refused rather than silently truncating the list.
+ */
+declare function encodeCursor(ordering: readonly CursorOrderingColumn[], row: Record<string, unknown>, table: string): string;
+/**
+ * REFUSAL 3 / 4 — a cursor this provider did not mint (`malformed`), or one
+ * minted under a different ordering (`mismatch`).
+ *
+ * The mismatch check is the load-bearing half. Sorting a list re-issues the
+ * query, and a UI that kept the old `after` around would otherwise get a
+ * page built by comparing the NEW ordering's columns against the OLD
+ * ordering's values — a query that succeeds and returns rows that are simply
+ * not the ones asked for.
+ */
+declare function decodeCursor(raw: unknown, ordering: readonly CursorOrderingColumn[], table: string): readonly (string | number | boolean)[];
+/**
+ * The keyset predicate: "every row that sorts strictly after the boundary",
+ * as the lexicographic expansion of a row comparison.
+ *
+ * For ordering `(a asc, b desc, id asc)` and boundary `(a0, b0, id0)` this
+ * emits
+ *
+ * ```
+ * _or: [ {a: {_gt: a0}},
+ *        {_and: [{a: {_eq: a0}}, {b: {_lt: b0}}]},
+ *        {_and: [{a: {_eq: a0}}, {b: {_eq: b0}}, {id: {_gt: id0}}]} ]
+ * ```
+ *
+ * Postgres's own `(a, b) > (a0, b0)` row comparison would be shorter, but
+ * Hasura's `bool_exp` has no row-comparison operator — this expansion is the
+ * only form expressible through it, and it is what every keyset
+ * implementation over Hasura ends up emitting.
+ *
+ * NOT written as `>=` on the leading column with a `_neq` correction, and
+ * not as a single `_gte`: both of those are the shapes that duplicate or
+ * skip rows across a run of equal values, which is the entire failure this
+ * function exists to avoid.
+ *
+ * `int64Fields` coercion is applied for the same reason
+ * `coerceInt64Filter` applies it to user filters: Hasura serialises an
+ * `int64` column as a JSON string and REJECTS a numeric filter value for it.
+ * A keyset predicate is an ordinary filter and gets no exemption.
+ */
+declare function keysetWhere(ordering: readonly CursorOrderingColumn[], boundary: readonly (string | number | boolean)[], int64Fields: readonly string[] | undefined): Record<string, unknown>;
+//#endregion
+//#region src/endpoint.d.ts
 /**
  * Same-origin GraphQL path Hasura serves by default. The single source for
  * both halves of this package: `createHasuraDataProvider`'s POST target and
@@ -390,48 +678,49 @@ declare function createHasuraDataProvider(config: HasuraDataProviderConfig): Dat
  * `endpoint: `${prefix}/gql/v1/graphql``.
  */
 declare const DEFAULT_HASURA_ENDPOINT = "/gql/v1/graphql";
-
+//#endregion
+//#region src/live-provider.d.ts
 interface SubscriptionPayload {
-    readonly query: string;
-    readonly variables?: Record<string, unknown>;
+  readonly query: string;
+  readonly variables?: Record<string, unknown>;
 }
 interface SubscriptionSink {
-    next(value: unknown): void;
-    error(error: unknown): void;
-    complete(): void;
+  next(value: unknown): void;
+  error(error: unknown): void;
+  complete(): void;
 }
 interface GraphqlWsClient {
-    subscribe(payload: SubscriptionPayload, sink: SubscriptionSink): () => void;
+  subscribe(payload: SubscriptionPayload, sink: SubscriptionSink): () => void;
 }
 interface GraphqlWsClientOptions {
-    readonly url: string;
-    readonly lazy: boolean;
-    readonly keepAlive: number;
-    readonly retryAttempts: number;
-    readonly shouldRetry: () => boolean;
-    readonly connectionParams: () => Promise<Record<string, unknown>>;
-    readonly on: {
-        connecting(): void;
-        connected(): void;
-        closed(): void;
-    };
+  readonly url: string;
+  readonly lazy: boolean;
+  readonly keepAlive: number;
+  readonly retryAttempts: number;
+  readonly shouldRetry: () => boolean;
+  readonly connectionParams: () => Promise<Record<string, unknown>>;
+  readonly on: {
+    connecting(): void;
+    connected(): void;
+    closed(): void;
+  };
 }
 interface HasuraLiveProviderConfig {
-    readonly resources: Record<string, ResourceMapping>;
-    readonly getToken: () => Promise<string | null>;
-    /**
-     * The SAME GraphQL endpoint the data provider POSTs to — Hasura serves
-     * subscriptions on that exact path. Converted to `ws(s)://` by
-     * {@link hasuraWsUrl}. Defaults to {@link DEFAULT_HASURA_ENDPOINT}.
-     *
-     * `createHasuraDataProvider` forwards its own resolved endpoint here, so the
-     * socket and the POST target can never drift apart.
-     */
-    readonly endpoint?: string;
-    /** `X-Hasura-Role` sent in the socket's connection params. `null`/omitted sends none. */
-    readonly role?: string | null;
-    /** Test seam; production uses graphql-ws directly. */
-    readonly clientFactory?: (options: GraphqlWsClientOptions) => GraphqlWsClient;
+  readonly resources: Record<string, ResourceMapping>;
+  readonly getToken: () => Promise<string | null>;
+  /**
+   * The SAME GraphQL endpoint the data provider POSTs to — Hasura serves
+   * subscriptions on that exact path. Converted to `ws(s)://` by
+   * {@link hasuraWsUrl}. Defaults to {@link DEFAULT_HASURA_ENDPOINT}.
+   *
+   * `createHasuraDataProvider` forwards its own resolved endpoint here, so the
+   * socket and the POST target can never drift apart.
+   */
+  readonly endpoint?: string;
+  /** `X-Hasura-Role` sent in the socket's connection params. `null`/omitted sends none. */
+  readonly role?: string | null;
+  /** Test seam; production uses graphql-ws directly. */
+  readonly clientFactory?: (options: GraphqlWsClientOptions) => GraphqlWsClient;
 }
 /**
  * `https://host/path` → `wss://host/path` (Hasura serves subscriptions on the
@@ -462,5 +751,6 @@ declare function hasuraWsUrl(endpoint: string): string;
  * single-sourced in the data provider.
  */
 declare function createHasuraLiveProvider(config: HasuraLiveProviderConfig): DataLiveProvider;
-
-export { DEFAULT_HASURA_ENDPOINT, type DataBodyConfig, FILTER_OPERATOR_UNSUPPORTED_CODE, type HasuraCustomOperation, type HasuraDataProviderConfig, type HasuraLiveProviderConfig, type HasuraOperationRegistry, type JsonbSpillConfig, NOT_AUTHENTICATED_CODE, type ResourceMapping, aggregateRoot, byPkRoot, createHasuraDataProvider, createHasuraLiveProvider, filtersToWhere, flattenJsonbSpill, hasuraWsUrl, mergeWhere, partitionDataBody, partitionJsonbSpill, scopeToWhere };
+//#endregion
+export { type CursorOrderingColumn, DEFAULT_HASURA_ENDPOINT, type DataBodyConfig, FILTER_OPERATOR_UNSUPPORTED_CODE, HASURA_CURSOR_CODES, type HasuraCustomOperation, type HasuraDataProviderConfig, type HasuraLiveProviderConfig, type HasuraOperationRegistry, type JsonbSpillConfig, LOCALE_REQUIRED_CODE, NOT_AUTHENTICATED_CODE, type ResourceMapping, aggregateRoot, assertCursorLimit, assertCursorOrderable, byPkRoot, coerceInt64Filter, createHasuraDataProvider, createHasuraLiveProvider, decodeCursor, effectiveCursorOrdering, encodeCursor, filtersToWhere, flattenJsonbSpill, hasuraWsUrl, keysetWhere, localeWhere, mergeWhere, orderingSignature, partitionDataBody, partitionJsonbSpill, scopeToWhere };
+//# sourceMappingURL=index.d.ts.map