@rebasepro/types 0.13.1-canary.gf57a27e → 0.14.0

package/dist/call_context.d.ts

@@ -23,11 +23,13 @@ export type RebaseCallContext<USER extends User = User> = {
      * Use it to call backend functions, access storage, send email, etc.
      *
      * ⚠️ **Not the same trust level as {@link data}.** Server-side this is the
-     * app singleton, so `client.dataAsAdmin` is **always** the RLS-bypassing
-     * plane — while {@link data}, one property over, follows whoever triggered
-     * the callback. On a user request, reaching for `context.client.dataAsAdmin`
-     * silently escalates a user-scoped operation to admin. For queries in a
-     * callback use {@link data}; come here for functions, storage and email.
+     * app singleton, so `client.dataAsAdmin` is **always** the admin-scoped
+     * plane — scoped as `{ uid: "service", roles: ["admin"] }`, so policies are
+     * evaluated against that identity rather than skipped — while {@link data},
+     * one property over, follows whoever triggered the callback. On a user
+     * request, reaching for `context.client.dataAsAdmin` silently escalates a
+     * user-scoped operation to admin. For queries in a callback use
+     * {@link data}; come here for functions, storage and email.
      *
      * @example
      * // In a beforeSave callback:
@@ -50,14 +52,21 @@ export type RebaseCallContext<USER extends User = User> = {
      *   user-scoped. The callback runs on the RLS-bound transaction opened for
      *   that request, so policies apply to reads *and* writes — a callback
      *   cannot see a row its caller could not.
-     * - Triggered by **server-context work** (`rebase.dataAsAdmin`, a cron):
-     *   unscoped, on the owner connection, bypassing RLS.
+     * - Triggered by **`rebase.dataAsAdmin` or a cron** (the same singleton):
+     *   admin-scoped, not unscoped. That driver is scoped as
+     *   `{ uid: "service", roles: ["admin"] }`, so the callback still runs on an
+     *   RLS-bound transaction — policies are evaluated against that identity.
+     * - Triggered by **the base driver** (auth flows, migrations): unscoped, on
+     *   the owner connection, bypassing RLS.
      *
      * So a callback that reads a sibling row will find it when an admin task
      * saves and may find nothing when an end user saves — without an error,
      * because RLS filters rather than raises. Write callbacks that tolerate
      * that, or reach for {@link client}`.dataAsAdmin` deliberately when the
-     * callback genuinely has to see past its caller.
+     * callback genuinely has to see what an admin may see. Note what that does
+     * *not* buy you: `policy.serverContext()` (`auth.uid() IS NULL`) is false
+     * for the service identity, so a collection whose only rule is
+     * `serverContext()` stays closed to it.
      *
      * Verified end-to-end against Postgres rather than asserted — see
      * `"scopes context.data to the caller when a callback runs on a user

package/dist/controllers/client.d.ts

@@ -296,18 +296,31 @@ export interface RebaseClient<DB = unknown> {
     /** Unified Data access layer */
     data: RebaseSdkData<DB>;
     /**
-     * Admin-scoped, **RLS-bypassing** data accessor.
+     * Admin-scoped data accessor — **not** an RLS bypass.
      *
      * Present on the **server** singleton only (see {@link RebaseServerClient}).
-     * It runs with `{ uid: "service", roles: ["admin"] }` — every read and write
-     * bypasses row-level-security policies. This is the correct tool for trusted
-     * background work (cron jobs, migrations, service-to-service tasks).
+     * It runs as the service identity `{ uid: "service", roles: ["admin"] }`,
+     * and the driver is scoped with `withAuth()` at boot, so every read and
+     * write runs in a transaction that has switched to the restricted
+     * `rebase_user` role with `app.uid = 'service'`: policies are evaluated,
+     * against that identity. This is the correct tool for trusted background
+     * work (cron jobs, migrations, service-to-service tasks).
+     *
+     * Two consequences the name does not suggest:
+     *
+     * - `policy.serverContext()` compiles to `auth.uid() IS NULL` and is
+     *   therefore **false** here. A collection with `disableDefaultPolicies:
+     *   true` whose only rule is `serverContext()` refuses these writes
+     *   (`42501`) and returns zero rows — HTTP 200, empty — for these reads.
+     * - Its reach equals an `admin`-roled application user's reach. It is not a
+     *   private channel. The true bypass is {@link sql}, which runs on the
+     *   owner connection and never goes through `withAuth`.
      *
      * ⚠️ **Do NOT use it to serve user-facing data.** Inside a request handler,
      * user-scoped queries must go through the request-scoped driver
-     * (`c.var.driver`), which carries the caller's identity so RLS applies.
-     * Reaching for `dataAsAdmin` (or its alias {@link data}) in a request handler
-     * silently exposes every row to every caller.
+     * (`c.var.driver`), which carries the caller's identity. Reaching for
+     * `dataAsAdmin` (or its alias {@link data}) in a request handler serves
+     * every caller whatever an admin may see.
      *
      * Undefined in the browser SDK.
      */
@@ -405,17 +418,20 @@ export interface RebaseClient<DB = unknown> {
  * the admin-scoped {@link dataAsAdmin} accessor, raw {@link sql}, and the
  * {@link email} service are all present (non-optional).
  *
- * **Trust levels.** {@link dataAsAdmin} is the admin-scoped, **RLS-bypassing**
- * driver, and it is the only name for it here — the `data` alias that used to
- * sit beside it is deliberately `Omit`ted from {@link RebaseClient} so the
- * privilege has to be spelled out at every call site. For user-scoped queries
- * inside a request handler use the request-scoped driver (`c.var.driver`)
- * instead — never `dataAsAdmin`.
+ * **Trust levels.** {@link dataAsAdmin} is the admin-scoped driver — scoped as
+ * `{ uid: "service", roles: ["admin"] }`, so policies are still evaluated
+ * against that identity rather than skipped — and it is the only name for it
+ * here: the `data` alias that used to sit beside it is deliberately `Omit`ted
+ * from {@link RebaseClient} so the privilege has to be spelled out at every
+ * call site. {@link sql} is the unconditional bypass: raw SQL on the owner
+ * connection, no policies. For user-scoped queries inside a request handler use
+ * the request-scoped driver (`c.var.driver`) instead — never `dataAsAdmin`.
  */
 export interface RebaseServerClient<DB = unknown> extends Omit<RebaseClient<DB>, "data"> {
     /**
-     * Admin-scoped, **RLS-bypassing** data accessor. Always present server-side.
-     * See {@link RebaseClient.dataAsAdmin} for the full safety contract.
+     * Admin-scoped data accessor (RLS is evaluated as the service identity, not
+     * skipped). Always present server-side. See {@link RebaseClient.dataAsAdmin}
+     * for the full safety contract.
      */
     dataAsAdmin: RebaseSdkData<DB>;
     /**

package/dist/controllers/data.d.ts

@@ -2,7 +2,66 @@ import type { VectorSearchParams } from "./data_driver";
 import type { ComputedSortField, SearchMatch } from "../types/search";
 import { Entity, EntityValues } from "../types/entities";
 import { WhereFilterOp, FieldPath, FilterValues, OrderByTuple } from "../types/filter-operators";
+/**
+ * Operator-blind filter value: whatever the column holds, a list of it, or null.
+ *
+ * @deprecated Superseded by {@link WhereValueFor}, which correlates the value
+ * with the operator. Kept exported because it is public API and downstream code
+ * annotates with it; every `where()` overload in this file uses `WhereValueFor`.
+ */
 export type WhereValue<T> = T | T[] | null;
+/**
+ * The element type of an array column, and the column's own type otherwise.
+ *
+ * A generated SDK emits an `array` property as `Array<X>` and a to-many
+ * relation as `Array<TargetRow>`, so this is what `array-contains` compares
+ * against on either.
+ */
+export type ElementOf<T> = T extends readonly (infer E)[] ? E : T;
+/**
+ * The `id` of a row-shaped element, and `never` for anything else.
+ *
+ * A to-many relation is emitted as `Array<TargetRow>`, but the filter compilers
+ * compare a relation by **id** — `buildRelationFilterPredicate` in
+ * `@rebasepro/server-postgres` unwraps a relation value down to its id — so
+ * `where("tags", "array-contains", tagId)` is the call that works, and the
+ * element type alone would refuse it.
+ */
+export type IdOf<E> = E extends {
+    id: infer I;
+} ? I : never;
+/**
+ * One member of an array column: its element, or — when the element is a row —
+ * that row's id, which is what a relation filter is actually compared against.
+ */
+export type WhereElementOf<T> = ElementOf<T> | IdOf<ElementOf<T>>;
+/**
+ * The value a given operator takes on a column of type `T`.
+ *
+ * `WhereValue<T>` was one value type for all sixteen operators, which made
+ * `array-contains` uncallable from a generated SDK — it is the one operator
+ * whose value is an *element* of the column rather than the column's own type,
+ * so on `tags: string[]` it wanted a `string[]` and the documented
+ * `.where("tags", "array-contains", "featured")` was a compile error. The
+ * spelling that did compile, `["featured"]`, builds `@> ARRAY[$1]` with the
+ * whole array bound as the single element and matches nothing: the correct
+ * query rejected, the accepted query silently wrong.
+ *
+ * The branches mirror `buildSingleFilterCondition` in `@rebasepro/server-postgres`:
+ *
+ * - `array-contains` → one element of the column (or a related row's id).
+ * - `in` / `not-in` / `array-contains-any` → a list of elements; a bare element
+ *   is read as the one-element list, and `null` is a null check.
+ * - `like` / `ilike` / `not-like` / `not-ilike` → a SQL pattern. Always a
+ *   string, including on numeric and date columns, which the driver casts.
+ * - `is-null` / `is-not-null` → nothing; the value is ignored everywhere.
+ * - everything else → the column's own type, or `null` for a null comparison.
+ *
+ * Distributes over `Op`, so a caller holding an unnarrowed `WhereFilterOp`
+ * (a dynamic filter UI, say) gets the union of every branch and stays as
+ * permissive as it was.
+ */
+export type WhereValueFor<Op extends WhereFilterOp, T> = Op extends "array-contains" ? WhereElementOf<T> : Op extends "in" | "not-in" | "array-contains-any" ? readonly WhereElementOf<T>[] | WhereElementOf<T> | null : Op extends "like" | "ilike" | "not-like" | "not-ilike" ? string : Op extends "is-null" | "is-not-null" ? null | undefined : T | null;
 export interface LogicalCondition {
     type: "and" | "or";
     conditions: (FilterCondition | LogicalCondition)[];
@@ -45,9 +104,14 @@ export interface FindParams<M extends Record<string, unknown> = Record<string, u
     /**
      * Maximum number of items to return.
      *
-     * Defaults to {@link DEFAULT_LIST_LIMIT}, and is clamped to
-     * {@link MAX_LIST_LIMIT}. Both bounds are applied by the backend, so a
-     * read is never unbounded whether or not a limit was asked for.
+     * Omit it and the backend applies {@link DEFAULT_LIST_LIMIT}, so a read is
+     * never unbounded. Provide it and it must be a whole number between 1 and
+     * {@link MAX_LIST_LIMIT}: the backend **rejects** anything else with a 400
+     * rather than trimming it to fit, because a page quietly smaller than the
+     * one you asked for is indistinguishable from having reached the end of the
+     * collection. To read past the ceiling, page with `offset` — or let
+     * {@link SDKCollectionClient.iterate} / {@link SDKCollectionClient.findAll}
+     * do it for you.
      */
     limit?: number;
     /**
@@ -160,7 +224,7 @@ export interface FindResponse<M extends Record<string, unknown> = Record<string,
  * @group Data
  */
 export interface QueryBuilderInterface<M extends Record<string, unknown> = Record<string, unknown>> {
-    where<K extends keyof M & string>(column: K, operator: WhereFilterOp, value: WhereValue<M[K]>): this;
+    where<K extends keyof M & string, Op extends WhereFilterOp>(column: K, operator: Op, value: WhereValueFor<Op, M[K]>): this;
     where(logicalCondition: LogicalCondition): this;
     orderBy(column: (keyof M & string) | ComputedSortField, direction?: "asc" | "desc"): this;
     limit(count: number): this;
@@ -265,7 +329,7 @@ export interface CollectionAccessor<M extends Record<string, unknown> = Record<s
      * one place the two halves of this API are not interchangeable.
      */
     count?(params?: FindParams<M>): Promise<number>;
-    where<K extends keyof M & string>(column: K, operator: WhereFilterOp, value: WhereValue<M[K]>): QueryBuilderInterface<M>;
+    where<K extends keyof M & string, Op extends WhereFilterOp>(column: K, operator: Op, value: WhereValueFor<Op, M[K]>): QueryBuilderInterface<M>;
     where(logicalCondition: LogicalCondition): QueryBuilderInterface<M>;
     orderBy(column: (keyof M & string) | ComputedSortField, direction?: "asc" | "desc"): QueryBuilderInterface<M>;
     limit(count: number): QueryBuilderInterface<M>;
@@ -444,7 +508,7 @@ export type FindAllParams<M extends Record<string, unknown> = Record<string, unk
  * @group Data
  */
 export interface SDKQueryBuilderInterface<M extends Record<string, unknown> = Record<string, unknown>> {
-    where<K extends keyof M & string>(column: K, operator: WhereFilterOp, value: WhereValue<M[K]>): this;
+    where<K extends keyof M & string, Op extends WhereFilterOp>(column: K, operator: Op, value: WhereValueFor<Op, M[K]>): this;
     where(logicalCondition: LogicalCondition): this;
     orderBy(column: (keyof M & string) | ComputedSortField, direction?: "asc" | "desc"): this;
     limit(count: number): this;
@@ -509,9 +573,20 @@ export interface WriteOptions {
      * it performs it again. On a table with a server-assigned id that is a
      * duplicate row, because the id the client chose was never used.
      *
+     * A key names **one** request, not a job. It records the method, the path
+     * and the body it was claimed for, so re-sending that exact request replays
+     * its answer, while the same key on a different one is refused with
+     * `IDEMPOTENCY_KEY_REUSED` (422) rather than silently answered with the
+     * first request's result. Pass a fresh key — a uuid — per call; a reusable
+     * business id shared by the create and the delete of one import means the
+     * second of them never runs.
+     *
      * Set by the offline queue on every replay. Honoured for 24 hours and scoped
-     * to the authenticated user; a server that cannot store keys ignores it
-     * rather than refusing the write.
+     * to the authenticated user — an unauthenticated caller has no principal to
+     * scope it to, so the key is ignored there. A retry sent while the first
+     * attempt is still being answered gets `IDEMPOTENCY_KEY_IN_PROGRESS` (409)
+     * and should be sent again. A server that cannot store keys ignores the
+     * header rather than refusing the write.
      */
     idempotencyKey?: string;
 }
@@ -729,7 +804,7 @@ export interface SDKCollectionClient<M extends Record<string, unknown> = Record<
      * Count the number of records matching the given filter.
      */
     count?(params?: FindParams<M>): Promise<number>;
-    where<K extends keyof M & string>(column: K, operator: WhereFilterOp, value: WhereValue<M[K]>): SDKQueryBuilderInterface<M>;
+    where<K extends keyof M & string, Op extends WhereFilterOp>(column: K, operator: Op, value: WhereValueFor<Op, M[K]>): SDKQueryBuilderInterface<M>;
     where(logicalCondition: LogicalCondition): SDKQueryBuilderInterface<M>;
     orderBy(column: (keyof M & string) | ComputedSortField, direction?: "asc" | "desc"): SDKQueryBuilderInterface<M>;
     limit(count: number): SDKQueryBuilderInterface<M>;

package/dist/controllers/data_driver.d.ts

@@ -1,3 +1,4 @@
+import { RebaseApiError } from "../errors";
 import type { EntityStatus, EntityValues } from "../types/entities";
 import type { CollectionConfig, FilterValues } from "../types/collections";
 import type { RebaseCallContext } from "../call_context";
@@ -37,7 +38,7 @@ export interface VectorSearchParams {
 export declare const DEFAULT_LIST_LIMIT = 50;
 /** Rows returned for a vector-search list read when the client sends no `limit`. */
 export declare const DEFAULT_VECTOR_LIST_LIMIT = 10;
-/** Hard ceiling clamped onto any client-supplied `limit`, on every surface. */
+/** Largest `limit` a client may ask for on any surface. Above it, the read is refused. */
 export declare const MAX_LIST_LIMIT = 1000;
 /** Overridable bounds for {@link resolveClientListLimit}. */
 export interface ListLimitBounds {
@@ -45,19 +46,36 @@ export interface ListLimitBounds {
     defaultLimit?: number;
     /** Default page size for vector-search reads. */
     vectorDefaultLimit?: number;
-    /** Upper bound clamped onto any client-supplied limit. */
+    /** Largest limit a client may ask for. A larger one is rejected, not clamped. */
     maxLimit?: number;
 }
+/**
+ * Thrown by {@link resolveClientListLimit} for a `limit` the platform will not
+ * serve. Carries an HTTP status so an ingress that speaks HTTP can forward it
+ * verbatim, and `maxLimit` so one can be built without re-deriving the ceiling.
+ *
+ * @group Errors
+ */
+export declare class ListLimitError extends RebaseApiError {
+    /** The ceiling that was exceeded — what the caller should page by instead. */
+    readonly maxLimit: number;
+    constructor(message: string, maxLimit: number);
+}
 /**
  * Resolve a client-supplied list `limit` into a safe, always-defined value.
  *
- * - A provided limit is coerced to an integer and clamped to `[1, maxLimit]`,
- *   so `0`, negatives, and absurd values can never bypass the cap.
- * - An absent / blank / non-numeric limit falls back to the mode default:
+ * - An absent / blank limit falls back to the mode default:
  *   `vectorDefaultLimit` for a vector search, otherwise `defaultLimit`.
+ * - A limit that is present must be an integer in `[1, maxLimit]`. Anything
+ *   else — `0`, a negative, `1.5`, `abc`, `100000000` — throws
+ *   {@link ListLimitError} rather than being coerced into range, because every
+ *   coercion answers a question the caller did not ask with a page it cannot
+ *   tell apart from the whole collection.
  *
  * The return is never `undefined` — no ingress that routes its client limit
  * through this can produce an unbounded read.
+ *
+ * @throws {ListLimitError} when a present `limit` is not an integer in range.
  */
 export declare function resolveClientListLimit(rawLimit: number | string | null | undefined, opts?: ListLimitBounds & {
     vectorSearch?: boolean;
@@ -250,9 +268,41 @@ export interface DataDriver {
      */
     updateMany?<M extends Record<string, unknown> = Record<string, unknown>>(props: UpdateManyProps<M>): Promise<Record<string, unknown>[]>;
     /**
-     * Delete a entity
-     * @param props
-     * @return was the whole deletion flow successful
+     * Delete the row `props.row` addresses.
+     *
+     * **Resolving means the row is gone because this call removed it.** A
+     * delete that matched nothing must reject with a not-found error
+     * (`ApiError.notFound`, `statusCode: 404`) rather than resolving quietly.
+     *
+     * The rule is here rather than in each driver because the two
+     * implementations answered differently and each had a test pinning its own
+     * habit: Postgres threw, Mongo logged a warning and resolved. Three things
+     * decide it in favour of rejecting.
+     *
+     * The REST layer already says 404 — `DELETE /api/data/<c>/<id>` reads the
+     * row before removing it — so a quiet resolve made the driver API disagree
+     * with the HTTP API about the same operation, and only in-process
+     * `rebase.data` callers could see the difference.
+     *
+     * A caller cannot tell "deleted" from "there was nothing there" without it,
+     * and those are different facts: one means the caller's model of the data
+     * was right, the other that it was stale. Silence hands back the wrong one
+     * and the caller carries on.
+     *
+     * And on a driver with row-level security, "matched nothing" is *also* how
+     * a policy refusal arrives — Postgres filters `DELETE` through `USING`
+     * rather than raising. A driver that resolves on zero rows therefore
+     * reports a refused delete as a completed one, which is the defect
+     * `explainZeroRowWrite` exists to prevent (see `write-denial.ts`).
+     *
+     * Conformance for both server drivers lives in
+     * `packages/server/test/contract/delete-contract.ts`, run by each driver's
+     * own suite against its own database. `packages/firebase`'s Firestore
+     * driver does not honour it: `deleteDoc` resolves for a missing document
+     * and reporting otherwise would cost a read on every delete. It runs in the
+     * browser against Firestore's own semantics rather than behind
+     * `rebase.data`, and that exception is stated here rather than left to be
+     * discovered.
      */
     delete<M extends Record<string, unknown> = Record<string, unknown>>(props: DeleteProps<M>): Promise<void>;
     /**

package/dist/index.es.js

@@ -250,6 +250,19 @@ var ALL_WHERE_FILTER_OPS = [
 /** All canonical operator strings for runtime validation. */
 var CANONICAL_OPS = new Set(ALL_WHERE_FILTER_OPS);
 /**
+* The REST table as a `Map`, because the key `toCanonicalOp` is handed comes
+* off the wire.
+*
+* Indexed as a plain object, every `Object.prototype` member answered:
+* `toCanonicalOp("valueOf")` returned the inherited *function* as though it
+* were a `WhereFilterOp`, and every caller here treats a defined result as
+* "known operator". Same defect the REST codec's own lookup tables were
+* converted away from in `filter-dialect.ts`; this is the copy that survived
+* one package over, and it now sits under the operator validation the REST
+* parser does, which would otherwise have admitted `["constructor", x]`.
+*/
+var REST_OP_LOOKUP = new Map(Object.entries(REST_TO_CANONICAL));
+/**
 * Resolve any operator string (canonical or REST short-code) to its
 * canonical `WhereFilterOp` form. Returns `undefined` for unknown operators.
 *
@@ -261,7 +274,7 @@ var CANONICAL_OPS = new Set(ALL_WHERE_FILTER_OPS);
 */
 function toCanonicalOp(op) {
 	if (CANONICAL_OPS.has(op)) return op;
-	return REST_TO_CANONICAL[op];
+	return REST_OP_LOOKUP.get(op);
 }
 //#endregion
 //#region src/types/admin_block.ts
@@ -383,6 +396,64 @@ var ADMIN_PROPERTY_KEYS = [
 	"urlPreview",
 	"widget"
 ];
+/**
+* Move flattened admin keys back down into the `admin` block.
+*
+* The admin panel works with a *flat* view model — the block merged onto the
+* collection — so what comes back from a form has `icon` and `defaultViewMode`
+* at the top level while `admin` still holds whatever the file was loaded with.
+* This is the way back.
+*
+* **The top-level value wins.** It is the one the form just wrote; the block is
+* the copy the collection was loaded with, and preferring it resolves every edit
+* in favour of the value the user changed away from.
+*
+* This lives here, next to the key lists, because it had two implementations —
+* `toAdminCollectionConfig` in `@rebasepro/admin-types` and `nestAdminKeys` in
+* `@rebasepro/server`'s schema editor — that agreed on everything except that
+* precedence, which is the only part that decides whether a save is visible.
+*
+* @group Models
+*/
+function nestAdminKeysOf(source, adminKeys) {
+	const keys = new Set(adminKeys);
+	const top = {};
+	const block = { ...source.admin ?? {} };
+	for (const [key, value] of Object.entries(source)) {
+		if (key === "admin") continue;
+		if (keys.has(key)) block[key] = value;
+		else top[key] = value;
+	}
+	if (Object.keys(block).length > 0) top.admin = block;
+	return top;
+}
+/**
+* {@link nestAdminKeysOf} for a collection.
+*
+* @group Models
+*/
+function nestAdminCollectionKeys(collection) {
+	return nestAdminKeysOf(collection, ADMIN_COLLECTION_KEYS);
+}
+/**
+* {@link nestAdminKeysOf} for a property, applied to its children too.
+*
+* A map property carries `properties`, an array property carries `of`, and both
+* hold properties with `admin` blocks of their own. A flat `readOnly` left on a
+* child is as dead — and as fatal at the next boot — as one left on the parent,
+* so the walk goes all the way down.
+*
+* @group Models
+*/
+function nestAdminPropertyKeys(property) {
+	const nested = nestAdminKeysOf(property, ADMIN_PROPERTY_KEYS);
+	const children = nested.properties;
+	if (children && typeof children === "object" && !Array.isArray(children)) nested.properties = Object.fromEntries(Object.entries(children).map(([key, child]) => [key, child && typeof child === "object" && !Array.isArray(child) ? nestAdminPropertyKeys(child) : child]));
+	const of = nested.of;
+	if (Array.isArray(of)) nested.of = of.map((entry) => entry && typeof entry === "object" && !Array.isArray(entry) ? nestAdminPropertyKeys(entry) : entry);
+	else if (of && typeof of === "object") nested.of = nestAdminPropertyKeys(of);
+	return nested;
+}
 //#endregion
 //#region src/types/data_source.ts
 /**
@@ -1239,24 +1310,51 @@ function computeSchemaVersion(collections) {
 var DEFAULT_LIST_LIMIT = 50;
 /** Rows returned for a vector-search list read when the client sends no `limit`. */
 var DEFAULT_VECTOR_LIST_LIMIT = 10;
-/** Hard ceiling clamped onto any client-supplied `limit`, on every surface. */
+/** Largest `limit` a client may ask for on any surface. Above it, the read is refused. */
 var MAX_LIST_LIMIT = 1e3;
 /**
+* Thrown by {@link resolveClientListLimit} for a `limit` the platform will not
+* serve. Carries an HTTP status so an ingress that speaks HTTP can forward it
+* verbatim, and `maxLimit` so one can be built without re-deriving the ceiling.
+*
+* @group Errors
+*/
+var ListLimitError = class ListLimitError extends RebaseApiError {
+	/** The ceiling that was exceeded — what the caller should page by instead. */
+	maxLimit;
+	constructor(message, maxLimit) {
+		super(message, {
+			status: 400,
+			code: "INVALID_LIMIT"
+		});
+		this.name = "ListLimitError";
+		this.maxLimit = maxLimit;
+		Object.setPrototypeOf(this, ListLimitError.prototype);
+	}
+};
+/**
 * Resolve a client-supplied list `limit` into a safe, always-defined value.
 *
-* - A provided limit is coerced to an integer and clamped to `[1, maxLimit]`,
-*   so `0`, negatives, and absurd values can never bypass the cap.
-* - An absent / blank / non-numeric limit falls back to the mode default:
+* - An absent / blank limit falls back to the mode default:
 *   `vectorDefaultLimit` for a vector search, otherwise `defaultLimit`.
+* - A limit that is present must be an integer in `[1, maxLimit]`. Anything
+*   else — `0`, a negative, `1.5`, `abc`, `100000000` — throws
+*   {@link ListLimitError} rather than being coerced into range, because every
+*   coercion answers a question the caller did not ask with a page it cannot
+*   tell apart from the whole collection.
 *
 * The return is never `undefined` — no ingress that routes its client limit
 * through this can produce an unbounded read.
+*
+* @throws {ListLimitError} when a present `limit` is not an integer in range.
 */
 function resolveClientListLimit(rawLimit, opts = {}) {
 	const maxLimit = opts.maxLimit ?? 1e3;
 	if (rawLimit != null && String(rawLimit).trim() !== "") {
-		const parsed = typeof rawLimit === "number" ? rawLimit : parseInt(String(rawLimit), 10);
-		if (Number.isFinite(parsed)) return Math.min(Math.max(1, Math.floor(parsed)), maxLimit);
+		const parsed = typeof rawLimit === "number" ? rawLimit : Number(String(rawLimit).trim());
+		if (!Number.isInteger(parsed) || parsed < 1) throw new ListLimitError(`Invalid \`limit\`: ${String(rawLimit)}. Expected a whole number between 1 and ${maxLimit}.`, maxLimit);
+		if (parsed > maxLimit) throw new ListLimitError(`\`limit\` ${parsed} is above the maximum of ${maxLimit}. Ask for at most ${maxLimit} rows per read and page through the rest with \`offset\` — answering with a smaller page would be indistinguishable from there being no more rows.`, maxLimit);
+		return parsed;
 	}
 	return opts.vectorSearch ? opts.vectorDefaultLimit ?? 10 : opts.defaultLimit ?? 50;
 }
@@ -1288,6 +1386,6 @@ function isPublicStoragePath(path) {
 	return p.startsWith("public/") || p.startsWith(`default/public/`);
 }
 //#endregion
-export { ADMIN_COLLECTION_KEYS, ADMIN_PROPERTY_KEYS, ALL_WHERE_FILTER_OPS, ANONYMOUS_USER_ID, ANONYMOUS_USER_IDS, BUNDLE_FORMAT_VERSION, CANONICAL_TO_REST, DEFAULT_CAPABILITIES, DEFAULT_DATA_SOURCE_KEY, DEFAULT_FILTERABLE_RELATION_KINDS, DEFAULT_FUZZY_THRESHOLD, DEFAULT_LIST_LIMIT, DEFAULT_SEARCH_COLUMN, DEFAULT_SEARCH_LANGUAGE, DEFAULT_SEARCH_WEIGHT, DEFAULT_STORAGE_SOURCE_KEY, DEFAULT_VECTOR_LIST_LIMIT, EntityReference, EntityRelation, FIREBASE_CAPABILITIES, GeoPoint, LEGACY_RLS_JWT_SQL, LEGACY_RLS_ROLES_SQL, LEGACY_RLS_SCHEMA, LEGACY_RLS_UID_SQL, MAX_LIST_LIMIT, MONGODB_CAPABILITIES, NULL_OPS, POSTGRES_CAPABILITIES, PUBLIC_STORAGE_PREFIX, REBASE_SCHEMA, RELEVANCE_SORT_FIELD, REST_TO_CANONICAL, RLS_JWT_SQL, RLS_ROLES_SQL, RLS_UID_SQL, RUNTIME_CONTRACT_VERSION, RebaseApiError, RebaseClientError, SCHEMA_VERSION_HEADER, Vector, canonicalSchemaPayload, computeSchemaVersion, deserializeCollections, findStorageSuffixCollision, getCollectionDataPath, getDataSourceCapabilities, getDeclaredSubcollections, hasForeignKeyOnTarget, isAnonymousUid, isBranchAdmin, isChannelBusInstance, isDocumentAdmin, isFirebaseCollectionConfig, isLazyComponentRef, isManyToMany, isMongoDBCollectionConfig, isPostgresCollectionConfig, isPublicStoragePath, isRelationalCollectionConfig, isSQLAdmin, isSchemaAdmin, isSerializedCollectionRef, isToMany, normalizeStorageSources, policy, registerDataSourceCapabilities, resolveClientListLimit, rewriteLegacyRlsFunctions, serializeCollections, storageEnvSuffix, toCanonicalOp, usesLegacyRlsFunctions };
+export { ADMIN_COLLECTION_KEYS, ADMIN_PROPERTY_KEYS, ALL_WHERE_FILTER_OPS, ANONYMOUS_USER_ID, ANONYMOUS_USER_IDS, BUNDLE_FORMAT_VERSION, CANONICAL_TO_REST, DEFAULT_CAPABILITIES, DEFAULT_DATA_SOURCE_KEY, DEFAULT_FILTERABLE_RELATION_KINDS, DEFAULT_FUZZY_THRESHOLD, DEFAULT_LIST_LIMIT, DEFAULT_SEARCH_COLUMN, DEFAULT_SEARCH_LANGUAGE, DEFAULT_SEARCH_WEIGHT, DEFAULT_STORAGE_SOURCE_KEY, DEFAULT_VECTOR_LIST_LIMIT, EntityReference, EntityRelation, FIREBASE_CAPABILITIES, GeoPoint, LEGACY_RLS_JWT_SQL, LEGACY_RLS_ROLES_SQL, LEGACY_RLS_SCHEMA, LEGACY_RLS_UID_SQL, ListLimitError, MAX_LIST_LIMIT, MONGODB_CAPABILITIES, NULL_OPS, POSTGRES_CAPABILITIES, PUBLIC_STORAGE_PREFIX, REBASE_SCHEMA, RELEVANCE_SORT_FIELD, REST_TO_CANONICAL, RLS_JWT_SQL, RLS_ROLES_SQL, RLS_UID_SQL, RUNTIME_CONTRACT_VERSION, RebaseApiError, RebaseClientError, SCHEMA_VERSION_HEADER, Vector, canonicalSchemaPayload, computeSchemaVersion, deserializeCollections, findStorageSuffixCollision, getCollectionDataPath, getDataSourceCapabilities, getDeclaredSubcollections, hasForeignKeyOnTarget, isAnonymousUid, isBranchAdmin, isChannelBusInstance, isDocumentAdmin, isFirebaseCollectionConfig, isLazyComponentRef, isManyToMany, isMongoDBCollectionConfig, isPostgresCollectionConfig, isPublicStoragePath, isRelationalCollectionConfig, isSQLAdmin, isSchemaAdmin, isSerializedCollectionRef, isToMany, nestAdminCollectionKeys, nestAdminKeysOf, nestAdminPropertyKeys, normalizeStorageSources, policy, registerDataSourceCapabilities, resolveClientListLimit, rewriteLegacyRlsFunctions, serializeCollections, storageEnvSuffix, toCanonicalOp, usesLegacyRlsFunctions };
 
 //# sourceMappingURL=index.es.js.map