@rebasepro/server 0.19.1 → 0.19.2-canary.g08eed46

package/dist/{src-Dq-I3Ybx.js → src-DqZ9YiGA.js}

@@ -3,7 +3,7 @@ import __rebaseProcess from "process";
 globalThis.process ??= __rebaseProcess;
 __rebaseCreateRequire(import.meta.url);
 import { r as __require, t as __commonJSMin } from "./rolldown-runtime-dW7B1o5h.js";
-import { A as REST_TO_CANONICAL, C as isPostgresCollectionConfig, D as ALL_WHERE_FILTER_OPS, E as getDataSourceCapabilities, N as sortKeyToString, O as CANONICAL_TO_REST, P as toCanonicalOp, S as getDeclaredSubcollections, j as isRelationAggregateSort, k as NULL_OPS, p as resolveResourceRefs, w as isRelationalCollectionConfig } from "./src-DHK4fHkw.js";
+import { A as LIST_OPS, C as getDeclaredSubcollections, D as getDataSourceCapabilities, F as sortKeyToString, I as toCanonicalOp, M as REST_TO_CANONICAL, N as isRelationAggregateSort, O as ALL_WHERE_FILTER_OPS, T as isRelationalCollectionConfig, j as NULL_OPS, k as CANONICAL_TO_REST, p as resolveResourceRefs, w as isPostgresCollectionConfig, x as rewriteLegacyRlsFunctions } from "./src-Br6ARbs6.js";
 //#region ../types/src/errors.ts
 /**
 * The single error type thrown across the entire Rebase client surface —
@@ -363,8 +363,124 @@ var policy = {
 		value
 	}),
 	authUid: () => ({ kind: "authUid" }),
-	authRoles: () => ({ kind: "authRoles" })
+	authRoles: () => ({ kind: "authRoles" }),
+	authClaim: (name) => ({
+		kind: "authClaim",
+		name
+	})
 };
+//#endregion
+//#region ../types/src/types/tenancy.ts
+/** Narrow a {@link TenantSource} to its claim form. @group Models */
+function isTenantClaimSource(source) {
+	return typeof source.claim === "string";
+}
+/**
+* The roles tenancy does not apply to, when the collection names none.
+*
+* `admin`, mirroring the security baseline every collection already carries
+* (`<table>_default_admin_read` / `_write`): the Studio, `dataAsAdmin` and a
+* support operator all run with it, and a tenancy rule that locked them out
+* would make the admin panel show an empty table on a collection full of rows.
+*
+* @group Models
+*/
+var DEFAULT_TENANT_BYPASS_ROLES = ["admin"];
+//#endregion
+//#region ../types/src/controllers/data.ts
+/**
+* SDK collection client — returns flat rows, no Entity wrapper.
+*
+* This is the public API surface for app developers using
+* `createRebaseClient()`. admin internals use `CollectionAccessor` instead.
+*
+* Type parameters:
+* - `M` — the **Row** shape returned by reads (`find`, `findById`, `listen`).
+* - `I` — the **Insert** shape accepted by {@link create}. Defaults to
+*   `Partial<M>`; the generated SDK supplies a dedicated `Insert` type where
+*   required columns are required and auto-generated / read-only columns are
+*   omitted, so `create({})` on a table with required fields is a compile error.
+* - `U` — the **Update** shape accepted by {@link update}. Defaults to
+*   `Partial<M>`; the generated SDK supplies a dedicated `Update` type.
+*
+* @example
+* const { data: posts } = await rebase.data.posts.find();
+* console.log(posts[0].title);       // flat access
+* console.log(posts[0].id);          // id at top level
+*
+* const post = await rebase.data.posts.findById(1);
+* console.log(post?.title);          // no .values needed
+*
+* @group Data
+*/
+/**
+* A change expressed as an operation on the column's current value, rather than
+* as the value to store.
+*
+* `{ views: 5 }` says what the number becomes; `{ views: { $inc: 1 } }` says
+* what happens to it. The difference is the read the caller no longer has to
+* make — and the race that read opens. Two requests that each read `4`, add one
+* and write `5` lose an increment between them; `SET views = views + 1` cannot,
+* because the arithmetic happens inside the statement holding the row lock.
+*
+* Exactly one operator per field. `{ views: { $inc: 1, $push: "x" } }` is
+* refused rather than applied in an order the caller cannot see.
+*
+* @group Data
+*/
+/**
+* The operator names, as a value.
+*
+* A runtime list beside the type because three layers have to *recognise* an
+* operation, not just accept one: the REST validator, the driver that compiles
+* it, and the offline queue that must refuse to apply one locally. Three copies
+* of four strings is three chances for one of them to miss an operator added to
+* the other two, and the failure is silent in the worst direction — an
+* unrecognised marker is written to the column as a JSON document.
+*
+* @group Data
+*/
+var FIELD_OPERATORS = [
+	"$inc",
+	"$push",
+	"$pull",
+	"$merge"
+];
+/**
+* The key of a {@link BatchRef}. Declared here, beside the field operators,
+* because the two share one namespace: a `$`-prefixed key in a write payload is
+* a marker, and every reader of that namespace has to know all of it.
+*
+* @group Data
+*/
+var BATCH_REF_KEY = "$ref";
+/**
+* Whether a value is *trying* to be a field operation — including a misspelled
+* one, which is the case worth catching.
+*
+* Any `$`-prefixed key counts, because `{ $increment: 1 }` written to a number
+* column as a JSON document is the failure this exists to prevent. No collection
+* can declare a column whose value legitimately has a key beginning with `$`: a
+* `map` property's sub-keys are declared, and `$` is not valid in the
+* identifiers the DDL generators emit.
+*
+* The one exception is `{ $ref: … }`, the batch's backward reference. It stands
+* where a *value* goes and is resolved to one before the row is written, so it
+* is not an operation on a column — reading it as a misspelled operator refused
+* every `$ref` in a batch with "unknown field operator '$ref'".
+*
+* @group Data
+*/
+function isFieldOperation(value) {
+	if (typeof value !== "object" || value === null || Array.isArray(value) || value instanceof Date) return false;
+	const keys = Object.keys(value);
+	if (keys.length === 1 && keys[0] === "$ref") return false;
+	return keys.some((key) => key.startsWith("$"));
+}
+/** True when any value in a write payload is (or is attempting to be) one. @group Data */
+function hasFieldOperation(values) {
+	return !!values && Object.values(values).some(isFieldOperation);
+}
 /** Largest `limit` a client may ask for on any surface. Above it, the read is refused. */
 var MAX_LIST_LIMIT = 1e3;
 /**
@@ -1469,6 +1585,16 @@ function removeFunctions(o) {
 	return o;
 }
 /**
+* Get a RegExp out of a serialized string
+* @param input
+*/
+function hydrateRegExp(input) {
+	if (!input) return void 0;
+	const fragments = input.match(/\/(.*?)\/([a-z]*)?$/i);
+	if (fragments) return new RegExp(fragments[1], fragments[2] || "");
+	else return new RegExp(input, "");
+}
+/**
 * Returns the singular of an English word.
 *
 * @param {string} word
@@ -1823,7 +1949,8 @@ function resolveRelation(relation, sourceCollection, propertyKey) {
 				through: {
 					table: relation.through?.table ?? [sourceTable, targetTable].sort().join("_"),
 					sourceColumn: relation.through?.sourceColumn ?? generateForeignKeyName(sourceName),
-					targetColumn: relation.through?.targetColumn ?? generateForeignKeyName(relationName)
+					targetColumn: relation.through?.targetColumn ?? generateForeignKeyName(relationName),
+					properties: relation.through?.properties ?? {}
 				}
 			};
 		}
@@ -2150,6 +2277,145 @@ function getSubcollections(collection) {
 //#endregion
 //#region ../common/src/util/policy/sqlToPolicy.ts
 /**
+* A tiny, regex-based SQL "parser" for security rules.
+*
+* This is NOT a full SQL parser. It is designed to handle the subset of SQL
+* commonly used in `USING` and `WITH CHECK` clauses, enough to drive the
+* optimistic client-side UI decision.
+*
+* It handles:
+* - `field = 'literal'`
+* - `field != 'literal'`
+* - `field = current_setting('app.uid')` (or the legacy `app.user_id`)
+* - `A AND B`, `A OR B` — only where the keyword is at the top level
+* - `true`
+* - `IN (...)` (as optimistic true)
+*
+* For anything it doesn't understand, it returns a `raw` expression, which
+* the evaluator treats as "unknown" (and usually optimistic true).
+*
+* **This output also round-trips back into DDL** via `policyToPostgres` (the
+* schema/policy generators), so decomposing a clause the parser only partly
+* understands is not a cosmetic mistake — it emits invalid SQL. When in doubt,
+* prefer `raw`: it is reproduced verbatim.
+*/
+/** True when `keyword` starts at `i` as a standalone word. */
+function isKeywordAt(upper, i, keyword) {
+	if (!upper.startsWith(keyword, i)) return false;
+	const before = i === 0 ? " " : upper[i - 1];
+	const after = upper[i + keyword.length] ?? " ";
+	return /[\s()]/.test(before) && /[\s()]/.test(after);
+}
+/**
+* Split `sql` on a boolean keyword, but only where it sits at paren depth 0 and
+* outside a string literal. Returns null when it never does, so the caller
+* leaves the clause alone.
+*
+* This used to be `sql.split(/ AND /i)`, which tore subqueries in half: the
+* `AND` inside
+*   `EXISTS (SELECT 1 FROM organization_members m WHERE m.org = t.org AND m.user_id = rebase.uid())`
+* split the expression, and re-emitting the halves produced
+*   `(EXISTS (...) AND m.user_id = rebase.uid())`
+* where `m` is no longer in scope — SQL that Postgres rejects outright with
+* "missing FROM-clause entry for table". Returning null instead keeps such a
+* clause as a `raw` expression, which round-trips verbatim.
+*/
+function splitTopLevel(sql, keyword) {
+	const upper = sql.toUpperCase();
+	const parts = [];
+	let depth = 0;
+	let inString = false;
+	let start = 0;
+	for (let i = 0; i < sql.length; i++) {
+		const ch = sql[i];
+		if (inString) {
+			if (ch === "'") if (sql[i + 1] === "'") i++;
+			else inString = false;
+			continue;
+		}
+		if (ch === "'") {
+			inString = true;
+			continue;
+		}
+		if (ch === "(") {
+			depth++;
+			continue;
+		}
+		if (ch === ")") {
+			depth--;
+			continue;
+		}
+		if (depth === 0 && isKeywordAt(upper, i, keyword)) {
+			parts.push(sql.slice(start, i));
+			i += keyword.length - 1;
+			start = i + 1;
+		}
+	}
+	if (parts.length === 0) return null;
+	parts.push(sql.slice(start));
+	const trimmedParts = parts.map((p) => p.trim()).filter((p) => p.length > 0);
+	return trimmedParts.length > 1 ? trimmedParts : null;
+}
+/** Drop redundant wrapping parens (`(a AND b)` → `a AND b`), never `(a) AND (b)`. */
+function stripOuterParens(sql) {
+	let s = sql.trim();
+	for (;;) {
+		if (!s.startsWith("(") || !s.endsWith(")")) return s;
+		let depth = 0;
+		let inString = false;
+		let wraps = true;
+		for (let i = 0; i < s.length; i++) {
+			const ch = s[i];
+			if (inString) {
+				if (ch === "'") if (s[i + 1] === "'") i++;
+				else inString = false;
+				continue;
+			}
+			if (ch === "'") {
+				inString = true;
+				continue;
+			}
+			if (ch === "(") depth++;
+			else if (ch === ")") {
+				depth--;
+				if (depth === 0 && i < s.length - 1) {
+					wraps = false;
+					break;
+				}
+			}
+		}
+		if (!wraps) return s;
+		s = s.slice(1, -1).trim();
+	}
+}
+function sqlToPolicy(sql) {
+	const trimmed = stripOuterParens(rewriteLegacyRlsFunctions(sql).trim());
+	if (trimmed.toLowerCase() === "true") return policy.true();
+	if (trimmed.toLowerCase() === "false") return policy.false();
+	const overlapMatch = trimmed.match(/^string_to_array\s*\(\s*rebase\.roles\(\)\s*,\s*','\s*\)\s*&&\s*ARRAY\s*\[(.+)\]$/i);
+	if (overlapMatch) {
+		const roles = overlapMatch[1].split(",").map((s) => s.trim().replace(/^'|'$/g, ""));
+		return policy.rolesOverlap(roles);
+	}
+	const containMatch = trimmed.match(/^string_to_array\s*\(\s*rebase\.roles\(\)\s*,\s*','\s*\)\s*@>\s*ARRAY\s*\[(.+)\]$/i);
+	if (containMatch) {
+		const roles = containMatch[1].split(",").map((s) => s.trim().replace(/^'|'$/g, ""));
+		return policy.rolesContain(roles);
+	}
+	const orParts = splitTopLevel(trimmed, "OR");
+	if (orParts) return policy.or(...orParts.map(sqlToPolicy));
+	const andParts = splitTopLevel(trimmed, "AND");
+	if (andParts) return policy.and(...andParts.map(sqlToPolicy));
+	const match = trimmed.match(/^(.+?)\s*(!?=)\s*(.+)$/);
+	if (match) {
+		const [, leftStr, op, rightStr] = match;
+		const left = parseOperand(leftStr.trim());
+		const right = parseOperand(rightStr.trim());
+		if (left && right) return policy.compare(left, op === "=" ? "eq" : "neq", right);
+	}
+	return policy.raw(trimmed);
+}
+/**
 * Literals from other BaaS platforms that people compare `rebase.uid()` against
 * out of habit. Mirrors the driver's `FOREIGN_CONVENTION_ROLES` guard on
 * `pgRoles`, one surface over: the same muscle memory inside a `using:` string
@@ -2178,6 +2444,87 @@ var FOREIGN_CONVENTION_UIDS = /* @__PURE__ */ new Map([
 	["service_role", "Supabase"]
 ]);
 new RegExp(String.raw`rebase\.uid\(\)\s*=\s*'(${[...FOREIGN_CONVENTION_UIDS.keys()].join("|")})'`, "i");
+function parseOperand(str) {
+	if (/^current_setting\s*\(\s*'app\.(uid|user_id)'\s*\)$/i.test(str) || /^rebase\.uid\(\)$/i.test(str)) return policy.authUid();
+	const literal = parseSingleQuoted(str);
+	if (literal !== null) return policy.literal(literal);
+	if (/^-?\d+$/.test(str)) return policy.literal(Number(str));
+	if (/^-?\d*\.\d+$/.test(str)) return policy.literal(Number(str));
+	if (/^true$/i.test(str)) return policy.literal(true);
+	if (/^false$/i.test(str)) return policy.literal(false);
+	if (/^null$/i.test(str)) return policy.literal(null);
+	if (/^\w+$/.test(str) && toSnakeCase(str) !== "") return policy.field(str);
+	return null;
+}
+/**
+* Decode a single-quoted SQL literal, or null when `str` is not exactly one.
+*
+* Rejecting is as important as decoding: `'a' = 'b'` is two literals and an
+* operator, not one literal whose body contains a quote, and a regex anchored
+* on the outer quotes would happily read it as the latter. Every interior quote
+* must therefore be part of a `''` pair.
+*/
+function parseSingleQuoted(str) {
+	if (str.length < 2 || !str.startsWith("'") || !str.endsWith("'")) return null;
+	const body = str.slice(1, -1);
+	let out = "";
+	for (let i = 0; i < body.length; i++) {
+		if (body[i] !== "'") {
+			out += body[i];
+			continue;
+		}
+		if (body[i + 1] === "'") {
+			out += "'";
+			i++;
+			continue;
+		}
+		return null;
+	}
+	return out;
+}
+//#endregion
+//#region ../common/src/util/policy/securityRuleToConditions.ts
+/**
+* Desugars a {@link SecurityRule} — its `access`/`ownerField`/`roles` shortcuts,
+* structured `condition`/`check`, and raw `using`/`withCheck` — into a single
+* normalized {@link PolicyExpression} pair.
+*
+* **This is the linchpin against drift:** both the Postgres DDL generators and
+* the client-side evaluator consume this one function, so there is exactly one
+* definition of what a rule means. In particular, application `roles` are folded
+* into the expression here (AND'd with the base condition, matching how Postgres
+* generates the clause) rather than being handled separately by each consumer.
+*/
+function securityRuleToConditions(rule) {
+	return {
+		usingExpr: withRoles(baseUsing(rule), rule),
+		withCheckExpr: withRoles(baseWithCheck(rule), rule)
+	};
+}
+function baseUsing(rule) {
+	if (rule.condition) return rule.condition;
+	if (rule.using != null) return sqlToPolicy(rule.using);
+	if (rule.access === "public") return policy.true();
+	if (rule.ownerField) return policy.compare(policy.field(rule.ownerField), "eq", policy.authUid());
+	return null;
+}
+function baseWithCheck(rule) {
+	if (rule.check) return rule.check;
+	if (rule.withCheck != null) return sqlToPolicy(rule.withCheck);
+	return baseUsing(rule);
+}
+/**
+* AND the base condition with an application-role check, or produce a roles-only
+* condition when there is no base. Mirrors the Postgres generator so that a
+* role-scoped restrictive rule denies exactly the same set of users on both
+* sides.
+*/
+function withRoles(base, rule) {
+	if (!rule.roles || rule.roles.length === 0) return base;
+	const rolesExpr = policy.rolesOverlap(rule.roles);
+	if (rule.mode === "restrictive") return base ? policy.or(policy.not(rolesExpr), base) : policy.not(rolesExpr);
+	return base ? policy.and(base, rolesExpr) : rolesExpr;
+}
 //#endregion
 //#region ../common/src/util/builders.ts
 /**
@@ -2190,6 +2537,103 @@ function defineCollection(collection) {
 	return resolveResourceRefs(collection);
 }
 //#endregion
+//#region ../common/src/util/tenant.ts
+/**
+* The one reading of `collection.tenant`.
+*
+* Four things have to agree for a tenant-scoped collection to work — the
+* column, the RLS policy, the value stamped on insert and the index — and
+* before this they were four hand-written declarations that nothing compared.
+* The three that are schema become a {@link SecurityRule} and a column effect
+* derived here and in `planSchema`; the fourth, the write path, is
+* {@link resolveTenantWrite}.
+*
+* Everything in this module is pure. The policy it builds is a `SecurityRule`
+* like any other, which is what makes `db push`, the doctor, boot-ensure, the
+* drift detector and the Studio treat the tenancy policy as what it is —
+* generated, named, and recognisable — rather than as somebody's hand-written
+* SQL that a push should offer to drop.
+*/
+/**
+* The collection's tenancy declaration, or nothing.
+*
+* Read through this rather than off the object, so the one shape check —
+* `tenant` is an object carrying a `field` and a `from` — is in one place. A
+* config that is *wrong* is refused by `validateCollectionConfig` with a
+* message; this is only asking whether there is one.
+*/
+function getTenantConfig(collection) {
+	const tenant = collection?.tenant;
+	if (!tenant || typeof tenant !== "object") return void 0;
+	if (typeof tenant.field !== "string" || !tenant.field) return void 0;
+	if (!tenant.from || typeof tenant.from !== "object") return void 0;
+	return tenant;
+}
+/** The roles tenancy does not apply to, defaulted. */
+function tenantBypassRoles(tenant) {
+	return tenant.bypassRoles ?? DEFAULT_TENANT_BYPASS_ROLES;
+}
+/**
+* The name of the policy a tenant declaration compiles to.
+*
+* Explicit — not a `getPolicyNameHash` of the rule — precisely because the
+* rule's *body* is compiled with more information in some callers than in
+* others (`planSchema` can resolve a relation's target collection and so knows
+* the column's type; the Studio, asking only for names, cannot). A hashed name
+* would then differ between the two, and the same policy would read as drift.
+* A frozen identifier: see `contracts/derived-names.txt`.
+*/
+function tenantPolicyName(tableName) {
+	return `${tableName}_tenant_scope`;
+}
+/**
+* The condition a tenant declaration means, as a policy expression.
+*
+* `serverContext()` first, for the same reason every injected baseline rule
+* carries it: the trusted plane runs migrations, the auth flows and the boot,
+* and a restrictive policy that excluded it would not protect a tenant, it
+* would stop the server from starting.
+*
+* Then the bypass roles, then the tenancy test itself — a claim comparison or a
+* correlated `EXISTS` over the membership table, which are the two ways a
+* deployment answers "which tenant is this caller in".
+*/
+function tenantScopeExpression(tenant) {
+	const match = isTenantClaimSource(tenant.from) ? policy.compare(policy.field(tenant.field), "eq", policy.authClaim(tenant.from.claim)) : policy.existsIn({
+		collection: tenant.from.membership.collection,
+		where: policy.and(policy.compare(policy.field(tenant.from.membership.tenantField), "eq", policy.outerField(tenant.field)), policy.compare(policy.field(tenant.from.membership.userField), "eq", policy.authUid()))
+	});
+	const bypass = tenantBypassRoles(tenant);
+	return bypass.length > 0 ? policy.or(policy.serverContext(), policy.rolesOverlap(bypass), match) : policy.or(policy.serverContext(), match);
+}
+/**
+* The rule a tenant declaration compiles to, or nothing when there is none.
+*
+* **Restrictive**, and that is the whole design. A restrictive policy is ANDed
+* with every other policy on the table, so tenancy narrows what the
+* collection's own `securityRules` allow and can never widen it. A permissive
+* one would OR with them, and a single `access: "public"` rule elsewhere in the
+* file would take the entire tenancy boundary off without contradicting
+* anything a reader could see.
+*
+* One rule with `operation: "all"` rather than four with `operations: [...]`:
+* `FOR ALL` gives Postgres the USING clause for SELECT/UPDATE/DELETE and the
+* WITH CHECK clause for INSERT/UPDATE, which is exactly the coverage wanted,
+* as one policy with one name instead of four.
+*/
+function buildTenantSecurityRule(collection) {
+	const tenant = getTenantConfig(collection);
+	if (!tenant) return void 0;
+	const expression = tenantScopeExpression(tenant);
+	return {
+		name: tenantPolicyName(getTableName(collection)),
+		mode: "restrictive",
+		operation: "all",
+		condition: expression,
+		check: expression
+	};
+}
+//#endregion
 //#region ../common/src/util/auth-default-policies.ts
 /**
 * Default RLS policies injected by the schema generator.
@@ -2234,8 +2678,16 @@ function defineCollection(collection) {
 * FORCE RLS. A *user* request never reaches that state: an anonymous one carries
 * `ANONYMOUS_USER_ID`, precisely so it cannot pass for the server here.
 *
+* **For a collection declaring `tenant`, additionally**
+*  5. A **restrictive** tenancy gate for every operation. Same kind of thing as
+*     the admin write gate and injected for the same reason: it is ANDed with
+*     every other policy, so it narrows what the author's permissive rules
+*     grant and can never widen them. See `./tenant.ts`.
+*
 * Opt out with `disableDefaultPolicies: true` to take full responsibility for
-* the collection's RLS.
+* the collection's RLS. The *restrictive* rules are not part of that opt-out:
+* dropping a rule that can only remove access could express nothing but "let
+* more people in", which is what the flag already does by removing the grants.
 */
 var SERVER_OR_ADMIN_EXPR$1 = policy.or(policy.serverContext(), policy.rolesOverlap(["admin"]));
 /** Write operations that must be admin-gated by default on auth collections. */
@@ -2279,11 +2731,27 @@ function adminWriteGate(tableName) {
 		check: SERVER_OR_ADMIN_EXPR$1
 	};
 }
+/**
+* The restrictive tenancy policy, as a list of zero or one.
+*
+* A list so the two call sites can splice it in without a conditional, and a
+* separate function so it is obvious that it is injected on *both* paths —
+* including the `disableDefaultPolicies` one, where it is the only permissive-
+* looking thing that stays. See `./tenant.ts`.
+*/
+function tenantRule(collection) {
+	const rule = buildTenantSecurityRule(collection);
+	return rule ? [rule] : [];
+}
 function getEffectiveSecurityRules(collection) {
 	const explicit = [...collection.securityRules ?? []];
 	const tableName = getTableName(collection);
 	const injected = [];
-	if (isPostgresCollectionConfig(collection) && collection.disableDefaultPolicies) return isAuthCollection(collection) ? [...explicit, adminWriteGate(tableName)] : explicit;
+	if (isPostgresCollectionConfig(collection) && collection.disableDefaultPolicies) return [
+		...explicit,
+		...tenantRule(collection),
+		...isAuthCollection(collection) ? [adminWriteGate(tableName)] : []
+	];
 	injected.push({
 		name: `${tableName}_default_admin_read`,
 		operations: ["select"],
@@ -2303,6 +2771,7 @@ function getEffectiveSecurityRules(collection) {
 		});
 		injected.push(adminWriteGate(tableName));
 	}
+	injected.push(...tenantRule(collection));
 	return [...explicit, ...injected];
 }
 policy.or(policy.serverContext(), policy.rolesOverlap(["admin"]));
@@ -3047,6 +3516,35 @@ function resolveDataSource(collection, registry) {
 		capabilities: getDataSourceCapabilities(engine)
 	};
 }
+/**
+* Does a SQL toolchain own this collection's storage?
+*
+* "Owns the storage" means: something generates a table for it, pushes that
+* table to a database, plans its RLS policies, and reports it as drifted when
+* the two disagree. That is true of a Postgres collection and false of a
+* Firestore or MongoDB one, whose documents live in a store Rebase never
+* migrates — and the two were never told apart. Every stage of the SQL
+* toolchain took "the collections" to mean *all* of them, so a Firestore
+* collection declared next to the Postgres ones got a `pgTable` in the
+* generated schema, a `CREATE TABLE` at boot, RLS policies, and a place in the
+* `db push` include list — where its name shielding a same-named real table
+* from Atlas's exclude list is the one that can lose data.
+*
+* The answer is the resolved engine's {@link DataSourceCapabilities}, not a
+* name check: an engine registered through `registerDataSourceCapabilities`
+* gets the same treatment as the built-in ones.
+*
+* Deliberately answers **true** for an engine nobody has heard of. Build-time
+* tooling (the CLI, the schema generator) has no data-source registry to
+* resolve a `dataSource` key against, so an unknown key resolves to an unknown
+* engine — and the cost of the two mistakes is not symmetric. Wrongly
+* including a collection generates a table nothing writes to; wrongly excluding
+* one silently stops generating a table the app is serving from. Declare
+* `engine` on a collection that is not SQL-backed and this is exact.
+*/
+function isRelationalCollection(collection, registry) {
+	return getDataSourceCapabilities(collection?.engine ?? (collection?.dataSource ? resolveDataSource(collection, registry).engine : void 0)).supportsRelations;
+}
 //#endregion
 //#region ../common/src/collections/CollectionRegistry.ts
 var CollectionRegistry = class {
@@ -3404,6 +3902,205 @@ var defaultUsersCollection = defineCollection({
 		}
 	}
 });
+/**
+* What a property's access rules actually are, with `excludeFromApi` expanded.
+*
+* Returns `undefined` when the property constrains nothing, so callers can skip
+* the whole check for the overwhelmingly common case.
+*/
+function effectiveAccess(property) {
+	if (!property) return void 0;
+	if (property.excludeFromApi) return EXCLUDED_ACCESS;
+	const access = property.access;
+	if (!access) return void 0;
+	if (access.read === void 0 && access.write === void 0) return void 0;
+	return access;
+}
+/** The rule `excludeFromApi: true` expands to. Frozen: it is shared by every caller. */
+var EXCLUDED_ACCESS = Object.freeze({
+	read: Object.freeze([]),
+	write: Object.freeze([])
+});
+/**
+* Does a caller holding `roles` satisfy `allowed`?
+*
+* Three cases, and the middle one is the one worth stating out loud:
+*
+* - `allowed` omitted — the field carries no rule of its own, so the row's
+*   policies have already answered. True.
+* - `allowed` empty — nobody, at any privilege, through any API. Not the admin,
+*   not the service key, not the trusted plane reading on a caller's behalf.
+*   This is what `excludeFromApi` has always meant on the read side, and
+*   collapsing the two spellings means the empty list has to keep meaning it.
+* - `allowed` non-empty — one of the named roles, or `admin`, or no viewer at
+*   all (the trusted server plane, which is not an API caller).
+*/
+function satisfies(allowed, viewer) {
+	if (allowed === void 0) return true;
+	if (allowed.length === 0) return false;
+	if (!viewer) return true;
+	const roles = viewer.roles;
+	if (!roles || roles.length === 0) return false;
+	return roles.includes("admin") || allowed.some((role) => roles.includes(role));
+}
+/** May this caller receive this field's value? */
+function canReadField(property, viewer) {
+	const access = effectiveAccess(property);
+	return access ? satisfies(access.read, viewer) : true;
+}
+/** May this caller set this field's value? */
+function canWriteField(property, viewer) {
+	const access = effectiveAccess(property);
+	return access ? satisfies(access.write, viewer) : true;
+}
+/**
+* The names on this collection a caller may not touch, in the two spellings a
+* caller can write them in.
+*
+* `declared` is the property keys, which is what has to leave a *known-fields*
+* set. `refused` is those plus the physical column names behind them: a caller
+* who knows the table can send `password_hash` as readily as `passwordHash`, and
+* a rule that only knew the wire name would be one rename away from useless.
+*
+* `kind` picks which half of the rule is read; nothing else differs.
+*/
+function restrictedFieldNames(collection, viewer, kind) {
+	const declared = [];
+	const refused = /* @__PURE__ */ new Set();
+	const allowed = kind === "read" ? canReadField : canWriteField;
+	for (const [name, property] of Object.entries(collection.properties ?? {})) {
+		if (allowed(property, viewer)) continue;
+		declared.push(name);
+		refused.add(name);
+		const columnName = property.columnName;
+		if (columnName) refused.add(columnName);
+	}
+	return {
+		declared,
+		refused
+	};
+}
+//#endregion
+//#region ../common/src/data/cursor.ts
+/** A cursor that cannot be read at all — truncated, re-encoded, or invented. */
+var CursorError = class CursorError extends Error {
+	code = "INVALID_CURSOR";
+	constructor(detail) {
+		super(`Invalid \`after\` cursor: ${detail}. Pass back the \`meta.nextCursor\` from the previous page unchanged — it is opaque and must not be built by hand.`);
+		this.name = "CursorError";
+		Object.setPrototypeOf(this, CursorError.prototype);
+	}
+};
+/**
+* A cursor that reads fine but describes a different query.
+*
+* Separate from {@link CursorError} because the fix is different: this one is
+* not a corrupt string, it is a correct cursor used against a sort it was not
+* produced under. Seeking anyway would return rows in an order nobody asked
+* for, and — worse — would look like it worked.
+*/
+var CursorMismatchError = class CursorMismatchError extends Error {
+	code = "CURSOR_ORDER_MISMATCH";
+	constructor(cursorKeys, queryKeys) {
+		super(`The \`after\` cursor was produced by a query ordered by ${cursorKeys.map((k) => `"${k}"`).join(", ") || "(nothing)"}, but this query orders by ${queryKeys.map((k) => `"${k}"`).join(", ") || "(nothing)"}. A cursor only continues the listing it came from — keep \`orderBy\` identical across pages, or drop \`after\` to start over.`);
+		this.name = "CursorMismatchError";
+		Object.setPrototypeOf(this, CursorMismatchError.prototype);
+	}
+};
+/**
+* Tag for a value whose JSON round-trip would otherwise lose its type.
+*
+* A `timestamp` column comes back from the driver as a `Date`; JSON turns it
+* into a string, and the string would then be compared against the column by
+* whatever cast Postgres chose. Round-tripping it as a `Date` keeps the
+* comparison the one the ORDER BY made.
+*/
+var DATE_TAG = "$date";
+function decodeValue(value) {
+	if (value && typeof value === "object" && !Array.isArray(value)) {
+		const tagged = value[DATE_TAG];
+		if (typeof tagged === "string") {
+			const date = new Date(tagged);
+			return Number.isNaN(date.getTime()) ? tagged : date;
+		}
+	}
+	return value;
+}
+function fromBase64Url(encoded) {
+	const padded = encoded.replace(/-/g, "+").replace(/_/g, "/") + "=".repeat((4 - encoded.length % 4) % 4);
+	const binary = atob(padded);
+	const bytes = new Uint8Array(binary.length);
+	for (let i = 0; i < binary.length; i++) bytes[i] = binary.charCodeAt(i);
+	return new TextDecoder().decode(bytes);
+}
+/**
+* Read a cursor produced by {@link encodeCursor}.
+*
+* @throws {CursorError} when the string is not a cursor this codec wrote.
+*/
+function decodeCursor(raw) {
+	let parsed;
+	try {
+		parsed = JSON.parse(fromBase64Url(raw.trim()));
+	} catch {
+		throw new CursorError("it is not a cursor this API issued");
+	}
+	if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) throw new CursorError("it does not decode to a cursor");
+	const body = parsed;
+	if (!Array.isArray(body.k)) throw new CursorError("it carries no sort keys");
+	if (body.i === void 0) throw new CursorError("it carries no row id");
+	const orderBy = [];
+	for (const entry of body.k) {
+		if (!Array.isArray(entry) || typeof entry[0] !== "string") throw new CursorError("one of its sort keys is malformed");
+		const direction = entry[1] === "desc" ? "desc" : "asc";
+		orderBy.push(entry[2] === "first" || entry[2] === "last" ? [
+			entry[0],
+			direction,
+			entry[2]
+		] : [entry[0], direction]);
+	}
+	const rawValues = body.v && typeof body.v === "object" && !Array.isArray(body.v) ? body.v : {};
+	const values = {};
+	for (const [field, value] of Object.entries(rawValues)) values[field] = decodeValue(value);
+	return {
+		orderBy,
+		values,
+		id: decodeValue(body.i)
+	};
+}
+/**
+* The `orderBy` a request should run under, given a cursor and whatever sort
+* the request itself named.
+*
+* A request that names no sort **adopts the cursor's** — that is what makes
+* `find({ after })` work without restating the `orderBy` from the previous
+* call, and it cannot be wrong, since the cursor is the only sort in play.
+* A request that names one must name the *same* one, key for key, direction for
+* direction, nulls for nulls; anything else is {@link CursorMismatchError}.
+*
+* @throws {CursorMismatchError}
+*/
+function reconcileCursorOrder(cursor, requested) {
+	if (!requested || requested.length === 0) return cursor.orderBy;
+	const spell = (keys) => keys.map(([field, direction, nulls]) => `${field}:${direction}${nulls ? `:${nulls}` : ""}`);
+	const cursorKeys = spell(cursor.orderBy);
+	const queryKeys = spell(requested);
+	if (cursorKeys.length !== queryKeys.length || cursorKeys.some((key, i) => key !== queryKeys[i])) throw new CursorMismatchError(cursorKeys, queryKeys);
+	return requested;
+}
+/**
+* The `startAfter` shape the driver contract takes, built from a cursor.
+*
+* The driver has always accepted `{ id, values }`; this is the one place that
+* shape is produced, so the REST route and the WebSocket ingress cannot drift
+* into two spellings of the same seek.
+*/
+function cursorToStartAfter(cursor) {
+	return {
+		id: cursor.id,
+		values: cursor.values
+	};
+}
 //#endregion
 //#region ../common/src/data/sort-dialect.ts
 /**
@@ -3450,13 +4147,24 @@ var OrderBySpecError = class extends Error {
 		this.name = "OrderBySpecError";
 	}
 };
+/** `first`/`last`, or a refusal naming the entry — see {@link NullsPlacement}. */
+function toStrictNulls(raw, index) {
+	if (raw === void 0 || raw === null) return void 0;
+	if (raw !== "first" && raw !== "last") throw new OrderBySpecError(`entry ${index} has nulls '${String(raw)}' — expected "first" or "last"`);
+	return raw;
+}
 function toStrictTuple(raw, index) {
 	if (!Array.isArray(raw)) throw new OrderBySpecError(`entry ${index} has no field name`);
 	const key = isRelationAggregateSort(raw[0]) ? sortKeyToString(raw[0]) : raw[0];
 	if (typeof key !== "string" || key.trim() === "") throw new OrderBySpecError(`entry ${index} has no field name`);
 	const direction = raw[1];
 	if (direction !== void 0 && direction !== "asc" && direction !== "desc") throw new OrderBySpecError(`entry ${index} has direction '${String(direction)}'`);
-	return [key, direction ?? "asc"];
+	const nulls = toStrictNulls(raw[2], index);
+	return nulls ? [
+		key,
+		direction ?? "asc",
+		nulls
+	] : [key, direction ?? "asc"];
 }
 /**
 * Serialize a sort to the wire.
@@ -3486,11 +4194,360 @@ function serializeOrderBy(orderBy) {
 	if (typeof orderBy === "string") return orderBy;
 	const list = normalizeOrderBy(orderBy);
 	if (!list) return void 0;
-	if (list.length === 1) return `${list[0][0]}:${list[0][1]}`;
-	return JSON.stringify(list.map(([field, direction]) => ({
+	if (list.length === 1) {
+		const [field, direction, nulls] = list[0];
+		return nulls ? `${field}:${direction}:${nulls}` : `${field}:${direction}`;
+	}
+	return JSON.stringify(list.map(([field, direction, nulls]) => nulls ? {
+		field,
+		direction,
+		nulls
+	} : {
 		field,
 		direction
-	})));
+	}));
+}
+/**
+* Deserialize a wire-format `"field:direction"` string into an {@link OrderByTuple}.
+*
+* Lenient parsing:
+* - Bare field name (no colon): `"name"` → `["name", "asc"]`
+* - Unknown direction: `"name:foo"` → `["name", "asc"]`
+* - Empty / falsy input, or a blank field name: → `undefined`
+*
+* The leniency is this end's alone; the *server* refuses the same value. This
+* used to say "matches existing server behaviour", and it stopped being true
+* when `parseOrderByParam` grew a strict direction check: `?orderBy=name:foo`
+* now answers `400 INVALID_ORDER_BY` ("entry 0 has direction 'foo'"). The split
+* is deliberate — see {@link parseOrderBySpecStrict} — because a value this
+* function is handed was produced by {@link serializeOrderBy} a moment earlier,
+* and one that reaches the server came from a stranger.
+*
+* A blank field is `undefined` rather than `[" ", "asc"]`: whitespace is not a
+* field name, and the tuple it used to produce could not be re-encoded — the
+* only value in this codec that survived a decode and failed the next encode.
+*
+* Reads the single-key shorthand only. For a value that may carry several keys,
+* use {@link deserializeOrderByList} — handed a JSON array this returns the
+* whole array as one nonsensical field name.
+*
+* @param raw - The wire-format string from an HTTP query parameter.
+* @returns The canonical tuple, or `undefined` if the input names no field.
+*/
+function deserializeOrderBy(raw) {
+	if (!raw) return void 0;
+	const idx = raw.indexOf(":");
+	if (idx === -1) return raw.trim() === "" ? void 0 : [raw, "asc"];
+	const field = raw.slice(0, idx);
+	if (field.trim() === "") return void 0;
+	const rest = raw.slice(idx + 1);
+	const nullsIdx = rest.indexOf(":");
+	const dir = nullsIdx === -1 ? rest : rest.slice(0, nullsIdx);
+	const nulls = nullsIdx === -1 ? void 0 : rest.slice(nullsIdx + 1);
+	const direction = dir === "desc" ? "desc" : "asc";
+	return nulls === "first" || nulls === "last" ? [
+		field,
+		direction,
+		nulls
+	] : [field, direction];
+}
+/**
+* Deserialize either wire spelling — the single-key shorthand or the JSON
+* array — into the list form.
+*
+* Lenient in the same way {@link deserializeOrderBy} is: this is the client end
+* of the codec, where the value was produced by {@link serializeOrderBy} a
+* moment earlier. The *server* end parses the same shapes strictly, in
+* `parseOrderByParam`, because there the value came from a stranger and a
+* direction it cannot read has to be refused rather than quietly turned into
+* `"asc"`.
+*/
+function deserializeOrderByList(raw) {
+	if (!raw) return void 0;
+	const trimmed = raw.trim();
+	if (trimmed.startsWith("[")) try {
+		const parsed = JSON.parse(trimmed);
+		if (Array.isArray(parsed)) {
+			const list = parsed.map((entry) => {
+				if (typeof entry === "string") return deserializeOrderBy(entry);
+				if (entry && typeof entry === "object" && typeof entry.field === "string") {
+					const direction = entry.direction === "desc" ? "desc" : "asc";
+					return entry.nulls === "first" || entry.nulls === "last" ? [
+						entry.field,
+						direction,
+						entry.nulls
+					] : [entry.field, direction];
+				}
+			}).filter((entry) => entry !== void 0);
+			return list.length > 0 ? list : void 0;
+		}
+	} catch {}
+	const single = deserializeOrderBy(trimmed);
+	return single ? [single] : void 0;
+}
+//#endregion
+//#region ../common/src/data/include-spec.ts
+/** An `include` that cannot be read, as opposed to one naming a relation that does not exist. */
+var IncludeSpecError = class IncludeSpecError extends Error {
+	code;
+	constructor(detail, code = "INVALID_INCLUDE") {
+		super(`Invalid \`include\`: ${detail}`);
+		this.name = "IncludeSpecError";
+		this.code = code;
+		Object.setPrototypeOf(this, IncludeSpecError.prototype);
+	}
+};
+var emptyNode = () => ({ children: {} });
+function ensureNode(tree, key) {
+	return tree[key] ??= emptyNode();
+}
+/**
+* Merge one dotted path (`"comments.author"`) into a tree.
+*
+* Merging rather than assigning is what makes `include=comments,comments.author`
+* mean the same thing as `include=comments.author`: the second path deepens the
+* node the first created instead of replacing it and losing its options.
+*/
+function addPath(tree, path) {
+	const segments = path.split(".").map((s) => s.trim()).filter(Boolean);
+	if (segments.length === 0) return;
+	if (segments.length > 3) throw new IncludeSpecError(`"${path}" nests ${segments.length} relations deep; the limit is 3. Each hop is another query, and an unbounded one walks a self-referencing relation forever.`, "INCLUDE_TOO_DEEP");
+	let level = tree;
+	for (const segment of segments) level = ensureNode(level, segment).children;
+}
+function normalizeOptions(key, options, depth) {
+	if (depth > 3) throw new IncludeSpecError(`"${key}" nests more than 3 relations deep.`, "INCLUDE_TOO_DEEP");
+	if (options.limit !== void 0 && (!Number.isInteger(options.limit) || options.limit < 1)) throw new IncludeSpecError(`"${key}" has limit ${JSON.stringify(options.limit)} — expected a whole number of 1 or more.`);
+	const node = { children: {} };
+	if (options.limit !== void 0) node.limit = options.limit;
+	if (options.where) node.where = options.where;
+	if (options.logical) node.logical = options.logical;
+	if (options.fields && options.fields.length > 0) node.fields = [...options.fields];
+	const orderBy = typeof options.orderBy === "string" ? deserializeOrderByList(options.orderBy) : normalizeOrderBy(options.orderBy);
+	if (orderBy) node.orderBy = orderBy;
+	if (options.include) {
+		const nested = normalizeIncludeAt(options.include, depth + 1);
+		if (nested.wildcard) throw new IncludeSpecError(`"${key}" asks for \`*\` inside a nested include. Name the relations you need.`);
+		node.children = nested.tree;
+	}
+	return node;
+}
+function normalizeIncludeAt(spec, depth) {
+	if (Array.isArray(spec)) {
+		const tree = {};
+		let wildcard = false;
+		for (const raw of spec) {
+			if (typeof raw !== "string") throw new IncludeSpecError(`${typeof raw} is not a relation name`);
+			const name = raw.trim();
+			if (!name) continue;
+			if (name === "*") {
+				wildcard = true;
+				continue;
+			}
+			addPath(tree, name);
+		}
+		return {
+			wildcard,
+			tree
+		};
+	}
+	if (typeof spec !== "object" || spec === null) throw new IncludeSpecError(`${typeof spec} is not a list of relations or an include tree`);
+	const tree = {};
+	let wildcard = false;
+	for (const [key, value] of Object.entries(spec)) {
+		if (key === "*") {
+			if (value) wildcard = true;
+			continue;
+		}
+		if (value === true) {
+			ensureNode(tree, key);
+			continue;
+		}
+		if (value === false || value === void 0 || value === null) continue;
+		if (typeof value !== "object" || Array.isArray(value)) throw new IncludeSpecError(`"${key}" must be \`true\` or an options object`);
+		tree[key] = normalizeOptions(key, value, depth);
+	}
+	return {
+		wildcard,
+		tree
+	};
+}
+/**
+* Collapse any {@link IncludeSpec} spelling into one tree.
+*
+* `["author", "comments.author"]` and
+* `{ author: true, comments: { include: { author: true } } }` normalize to the
+* same value — which is the whole point: the REST parameter can only carry the
+* flat spelling, the SDK prefers the tree, and the driver should never learn
+* about either.
+*
+* @throws {IncludeSpecError} for a shape that is not an include at all, or one
+*   that nests past {@link MAX_INCLUDE_DEPTH}.
+*/
+function normalizeInclude(spec) {
+	if (spec === void 0 || spec === null) return void 0;
+	const normalized = normalizeIncludeAt(spec, 1);
+	if (!normalized.wildcard && Object.keys(normalized.tree).length === 0) return void 0;
+	return normalized;
+}
+/**
+* Every relation name a tree names, as dotted paths — `["comments",
+* "comments.author"]`.
+*
+* Used to report which names an `include` asked for when one of them is not a
+* relation, and to serialize a tree that carries no per-relation options back
+* to the flat wire spelling.
+*/
+function includePaths(tree, prefix = "") {
+	const out = [];
+	for (const [key, node] of Object.entries(tree)) {
+		const path = prefix ? `${prefix}.${key}` : key;
+		out.push(path);
+		out.push(...includePaths(node.children, path));
+	}
+	return out;
+}
+/**
+* The relation names an `include` asks for at the top level.
+*
+* `["author", "comments.author"]` and `{author: true, comments: {...}}` both
+* answer `["author", "comments"]` — a *hop*, not a path, because the only
+* consumer is `?fields=`, which names keys on the row being returned and a
+* nested relation is not one of those.
+*
+* Derived rather than passed: `include` has four spellings and three of them
+* are not a `string[]`, so every consumer that wants the plain names either
+* calls this or reimplements the flattening.
+*/
+function topLevelIncludeNames(spec) {
+	const normalized = normalizeInclude(spec);
+	if (!normalized) return [];
+	return Object.keys(normalized.tree);
+}
+/** Whether any node in the tree carries per-relation options. */
+function hasOptions(tree) {
+	return Object.values(tree).some((node) => node.limit !== void 0 || node.where !== void 0 || node.logical !== void 0 || node.orderBy !== void 0 || node.fields !== void 0 || hasOptions(node.children));
+}
+/**
+* Serialize an {@link IncludeSpec} for the REST `?include=` parameter.
+*
+* Two spellings, and which one is used is decided by the request rather than
+* chosen:
+*
+* - **Comma-separated dotted paths** — `include=author,comments.author`. What a
+*   plain include is, what a human types, and what every existing client sends.
+* - **JSON**, when any relation carries options — `include={"comments":{"limit":5,
+*   "include":{"author":true}}}`. The flat spelling has nowhere to put a
+*   `limit`, and inventing a punctuation for it (`comments(limit:5)`) would be a
+*   third grammar to learn beside the two this API already has.
+*
+* The server accepts both on every list and get route, and tells them apart the
+* same way this does: a value starting with `{` is JSON.
+*/
+function serializeInclude(spec) {
+	const normalized = normalizeInclude(spec);
+	if (!normalized) return void 0;
+	if (normalized.wildcard && Object.keys(normalized.tree).length === 0) return "*";
+	if (!hasOptions(normalized.tree)) {
+		const paths = includePaths(normalized.tree);
+		const leaves = paths.filter((path) => !paths.some((other) => other.startsWith(`${path}.`)));
+		const all = normalized.wildcard ? ["*", ...leaves] : leaves;
+		return all.length > 0 ? all.join(",") : void 0;
+	}
+	return JSON.stringify(toWireTree(normalized));
+}
+/**
+* A normalized tree, back in the {@link IncludeSpec} spelling a caller writes.
+*
+* The round trip is what lets a builder accumulate `include` calls: normalize
+* each, merge, and hand the result back as a spec the next layer can normalize
+* again. Idempotent, so doing it twice changes nothing.
+*/
+function denormalizeInclude(normalized) {
+	return toWireTree(normalized);
+}
+function mergeTrees(into, from) {
+	for (const [key, node] of Object.entries(from)) {
+		const existing = into[key];
+		if (!existing) {
+			into[key] = node;
+			continue;
+		}
+		if (node.limit !== void 0) existing.limit = node.limit;
+		if (node.where !== void 0) existing.where = node.where;
+		if (node.logical !== void 0) existing.logical = node.logical;
+		if (node.orderBy !== void 0) existing.orderBy = node.orderBy;
+		if (node.fields !== void 0) existing.fields = node.fields;
+		existing.children = mergeTrees(existing.children, node.children);
+	}
+	return into;
+}
+/**
+* Combine several `include` requests into one.
+*
+* Repeated `.include(...)` calls on a query builder are additive: each names
+* more of the graph to load, and a later one must not discard what an earlier
+* one asked for. Assigning instead of merging is why `.include("author")
+* .include("tags")` used to load only tags.
+*/
+function mergeIncludeSpecs(existing, additions) {
+	const merged = {
+		wildcard: false,
+		tree: {}
+	};
+	const absorb = (spec) => {
+		const normalized = normalizeInclude(spec);
+		if (!normalized) return;
+		merged.wildcard ||= normalized.wildcard;
+		mergeTrees(merged.tree, normalized.tree);
+	};
+	absorb(existing);
+	const names = additions.filter((a) => typeof a === "string");
+	if (names.length > 0) absorb(names);
+	for (const addition of additions) if (typeof addition !== "string") absorb(addition);
+	if (!merged.wildcard && Object.keys(merged.tree).length === 0) return void 0;
+	return denormalizeInclude(merged);
+}
+function toWireTree(normalized) {
+	const emit = (tree) => {
+		const out = {};
+		for (const [key, node] of Object.entries(tree)) {
+			const options = {};
+			if (node.limit !== void 0) options.limit = node.limit;
+			if (node.where) options.where = node.where;
+			if (node.logical) options.logical = node.logical;
+			if (node.orderBy) options.orderBy = node.orderBy;
+			if (node.fields) options.fields = node.fields;
+			const children = emit(node.children);
+			if (Object.keys(children).length > 0) options.include = children;
+			out[key] = Object.keys(options).length > 0 ? options : true;
+		}
+		return out;
+	};
+	const tree = emit(normalized.tree);
+	if (normalized.wildcard) tree["*"] = true;
+	return tree;
+}
+/**
+* Read the REST `?include=` parameter, in either spelling.
+*
+* @throws {IncludeSpecError} for malformed JSON or a tree that nests too deep.
+*/
+function deserializeInclude(raw) {
+	if (raw === void 0 || raw === null) return void 0;
+	const text = raw.trim();
+	if (!text) return void 0;
+	if (text.startsWith("{")) {
+		let parsed;
+		try {
+			parsed = JSON.parse(text);
+		} catch {
+			throw new IncludeSpecError("the parametrised form must be a JSON object, e.g. {\"comments\":{\"limit\":5,\"include\":{\"author\":true}}}");
+		}
+		if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) throw new IncludeSpecError("the parametrised form must be a JSON object");
+		return parsed;
+	}
+	return text.split(",").map((s) => s.trim()).filter(Boolean);
 }
 //#endregion
 //#region ../common/src/data/query_builder.ts
@@ -3671,26 +4728,6 @@ function normalizeMaxRows(raw) {
 	return Math.max(0, Math.floor(raw));
 }
 /**
-* Add one condition to a `where` map without disturbing what is already there.
-*
-* The caller's own filter on the cursor column has to survive — dropping it
-* would widen the query, which is the silent-filter-loss failure mode — so a
-* second condition on the same column becomes the array-of-tuples form that
-* `FindParams.where` already accepts, and both are AND-ed.
-*/
-function appendCondition(where, column, condition) {
-	const next = { ...where ?? {} };
-	const existing = next[column];
-	if (existing === void 0) next[column] = condition;
-	else if (Array.isArray(existing) && existing.length > 0 && Array.isArray(existing[0])) next[column] = [...existing, condition];
-	else next[column] = [existing, condition];
-	return next;
-}
-function cursorEquals(a, b) {
-	if (a instanceof Date && b instanceof Date) return a.getTime() === b.getTime();
-	return Object.is(a, b);
-}
-/**
 * Walk every row a query matches, yielding one row at a time and fetching the
 * next page only when the consumer asks for it.
 *
@@ -3706,30 +4743,23 @@ async function* paginateFind(find, params, label = "collection") {
 	const findParams = { ...rest };
 	const size = normalizePageSize(pageSize);
 	const pageCap = normalizeMaxPages(maxPages);
-	const cursorField = typeof cursor === "string" ? cursor : cursor?.field;
-	const requestedDirection = typeof cursor === "object" && cursor !== null ? cursor.direction : void 0;
-	let direction = "asc";
-	if (cursorField) {
-		const orderBy = normalizeOrderBy(findParams.orderBy);
-		if (orderBy && orderBy.length > 1) throw new RebasePaginationError("cursor-order-mismatch", `Cannot seek on "${cursorField}" while ordering "${label}" by ${orderBy.map(([field]) => `"${field}"`).join(", ")}: keyset pagination advances along a single column. Order by "${cursorField}" alone, or drop the cursor and page by offset.`);
-		if (orderBy && orderBy[0][0] !== cursorField) throw new RebasePaginationError("cursor-order-mismatch", `Cannot seek on "${cursorField}" while ordering "${label}" by "${orderBy[0][0]}": keyset pagination only advances along the column the query is sorted by. Order by "${cursorField}", or drop the cursor and page by offset.`);
-		direction = requestedDirection ?? orderBy?.[0][1] ?? "asc";
-		findParams.orderBy = [cursorField, direction];
+	const seekRequested = cursor !== void 0 && cursor !== null;
+	if (seekRequested) {
+		const field = typeof cursor === "string" ? cursor : cursor.field;
+		const requested = typeof cursor === "object" && cursor !== null ? cursor.direction : void 0;
+		if (!normalizeOrderBy(findParams.orderBy)) findParams.orderBy = [field, requested ?? "asc"];
 	}
-	const seekOp = direction === "desc" ? "<" : ">";
-	const baseWhere = findParams.where;
 	let offset = 0;
 	let pages = 0;
-	let cursorValue;
-	let seeking = false;
+	let after;
 	for (;;) {
 		if (pages >= pageCap) throw new RebasePaginationError("max-pages", `Iterating "${label}" made ${pages} requests without the server reporting the end of the collection. Stopping rather than looping forever — raise \`maxPages\` if the walk is genuinely this long, or check that the backend sets \`meta.hasMore\`.`);
 		const pageParams = {
 			...findParams,
 			limit: size
 		};
-		if (cursorField) {
-			if (seeking) pageParams.where = appendCondition(baseWhere, cursorField, [seekOp, cursorValue]);
+		if (seekRequested) {
+			if (after) pageParams.after = after;
 		} else pageParams.offset = offset;
 		const page = await find(pageParams);
 		pages += 1;
@@ -3737,12 +4767,11 @@ async function* paginateFind(find, params, label = "collection") {
 		if (rows.length === 0) return;
 		for (const row of rows) yield row;
 		if (page?.meta?.hasMore !== true) return;
-		if (cursorField) {
-			const nextValue = rows[rows.length - 1]?.[cursorField];
-			if (nextValue === void 0 || nextValue === null) throw new RebasePaginationError("cursor-missing", `Cannot seek past the last row of "${label}": it has no value for the cursor column "${cursorField}". Pick a column that is present and non-null on every row.`);
-			if (seeking && cursorEquals(nextValue, cursorValue)) throw new RebasePaginationError("cursor-stalled", `Iterating "${label}" is stuck: two pages in a row ended at ${cursorField}=${String(nextValue)}. The cursor column has to be unique — a repeated value cannot be seeked past, and continuing would either loop forever or skip the duplicates. Use the primary key, or page by offset.`);
-			cursorValue = nextValue;
-			seeking = true;
+		if (seekRequested) {
+			const next = page.meta.nextCursor;
+			if (!next) throw new RebasePaginationError("cursor-missing", `Cannot seek past the last row of "${label}": the server reported another page but issued no cursor for it. An ordering with no stored value to compare against — relevance (\`_score\`) — cannot key a cursor. Drop \`cursor\` to page by offset.`);
+			if (next === after) throw new RebasePaginationError("cursor-stalled", `Iterating "${label}" is stuck: two pages in a row ended on the same cursor, so the walk cannot advance. Continuing would loop forever. Page by offset instead, or report this — a cursor that does not move is a server-side bug.`);
+			after = next;
 		} else offset += rows.length;
 	}
 }
@@ -4172,15 +5201,66 @@ function serializeFilter(filter) {
 	return result;
 }
 /**
+* The spellings a null-testing operator's operand may take.
+*
+* The serializer writes `isnull.null`; a hand-written `isnull.true` means the
+* same thing and has always been accepted. Anything else after the operator is
+* not an operand it has — `notnull.reason` is a *value* — see
+* {@link deserializeSingle}.
+*/
+var NULL_OPERANDS = /* @__PURE__ */ new Set([
+	"null",
+	"true",
+	"false",
+	""
+]);
+/**
 * Parse a single PostgREST dot-string into a `[WhereFilterOp, unknown]` tuple.
 *
 * All values are returned as strings — the wire format carries no type
 * metadata, so coercion is the data driver's responsibility.
 *
-* If the string doesn't match a known operator prefix, it falls back to
-* `["==", originalString]` (treating the whole string as an equality value).
-* This intentional defense handles values like `"user@host.com"` or
-* `"1.2.3"` that happen to contain dots.
+* ## When a leading segment is an operator, and when it is part of the value
+*
+* `?status=in.progress` and `?status=in.(a,b)` differ by one character and mean
+* entirely different things, and the reading here decides which. The rule, in
+* full:
+*
+* > A dot-string is read as `operator.operand` **only** when its first segment
+* > names a known REST operator **and** what follows is a well-formed operand
+* > *for that operator's arity*. Otherwise the whole string is the value.
+*
+* Arity, per operator family:
+*
+* - **List** operators (`in`, `nin`, `csa` — `LIST_OPS`) take a parenthesised
+*   list and nothing else. `in.(draft,review)` is the operator; `in.progress`
+*   is the *value* `"in.progress"`, because there is no list there and so no
+*   `in` filter that could have been written. That case used to compile to
+*   `status IN ('progress')` — a filter the caller never wrote, quietly
+*   matching the wrong rows and, on a status field, hiding every row they were
+*   looking for.
+* - **Null** operators (`isnull`, `notnull` — {@link NULL_OPS}) take no
+*   operand: only {@link NULL_OPERANDS}. `notnull.reason` is the value
+*   `"notnull.reason"`, not "reason is not null".
+* - **Everything else** takes one scalar, and any remainder is one — including
+*   the empty string, so `eq.` really is "equals the empty string".
+*
+* ### The one ambiguity that remains, and how to write past it
+*
+* A scalar operator's operand is unconstrained, so `?status=like.that` is a
+* `LIKE 'that'` and no rule at this layer can tell it from the literal value
+* `"like.that"` — both are well-formed encodings, and picking either by guess
+* would break the other. Two spellings say "value" unambiguously, and both
+* round-trip:
+*
+* - `?status=eq.like.that` — name the operator. The *first* segment is consumed
+*   as the operator and everything after it is the value, dots and all. This is
+*   what `serializeFilter` emits, which is why the SDK never meets the
+*   ambiguity at all.
+* - `?where={"status":["==","like.that"]}` — the JSON dialect's tuple form.
+*
+* Values that merely *contain* dots (`user@host.com`, `1.2.3`) were never
+* ambiguous: their first segment names no operator to begin with.
 */
 function deserializeSingle(raw) {
 	const dotIndex = raw.indexOf(".");
@@ -4189,11 +5269,15 @@ function deserializeSingle(raw) {
 	const rest = raw.substring(dotIndex + 1);
 	const canonicalOp = REST_OP_LOOKUP.get(prefix);
 	if (!canonicalOp) return ["==", raw];
-	if (NULL_OPS.has(canonicalOp)) return [canonicalOp, null];
+	if (NULL_OPS.has(canonicalOp)) {
+		if (!NULL_OPERANDS.has(rest)) return ["==", raw];
+		return [canonicalOp, null];
+	}
 	if (rest.startsWith("(") && rest.endsWith(")")) {
 		const inner = rest.slice(1, -1);
 		return [canonicalOp, inner === EMPTY_LIST_TOKEN ? [] : splitListItems(inner)];
 	}
+	if (LIST_OPS.has(canonicalOp)) return ["==", raw];
 	return [canonicalOp, rest];
 }
 /**
@@ -4321,7 +5405,7 @@ function splitLeafCondition(str) {
 }
 function deserializeLogicalCondition(str, nesting = 0) {
 	if (nesting > 32) throw new Error(`Filter groups nest more than 32 levels deep. Flatten the condition — \`or(a,or(b,c))\` is \`or(a,b,c)\`.`);
-	const logicalMatch = str.match(/^(and|or)\((.+)\)$/);
+	const logicalMatch = str.match(/^(and|or|not)\((.+)\)$/);
 	if (logicalMatch) {
 		const type = logicalMatch[1];
 		const innerStr = logicalMatch[2];
@@ -4375,6 +5459,33 @@ function deserializeLogicalCondition(str, nesting = 0) {
 var noRealtime = (slug) => `Realtime is not available for "${slug}": its data source does not support subscriptions.`;
 /** What a client says when its data source cannot count. */
 var noCount = (slug) => `Counting is not available for "${slug}": its data source does not support it.`;
+/**
+* Derive the response key an aggregate comes back under.
+*
+* `sum(total)` → `sum_total`, `count()` → `count`. Written once, here, because
+* the REST parser derives the same alias from `?select=sum(total)` and the two
+* have to agree — a caller reading `row.sum_total` off an SDK result and off an
+* HTTP response is reading the same key or the SDK is broken.
+*/
+function aggregateAlias(fn, field) {
+	return field ? `${fn}_${field}` : fn;
+}
+function toDriverAggregate(select) {
+	const field = select.field;
+	return {
+		fn: select.fn,
+		field,
+		alias: aggregateAlias(select.fn, field)
+	};
+}
+/**
+* What a client says when its data source cannot aggregate.
+*
+* A stub rather than a fallback that fetches and reduces in JavaScript: that
+* would be wrong under a `limit` and unaffordable without one, and it would look
+* like it had worked.
+*/
+var noAggregate = (slug) => `Aggregates are not available for "${slug}": its data source does not implement them.`;
 function createPrimaryKeyResolver(options) {
 	const cache = /* @__PURE__ */ new Map();
 	const warned = /* @__PURE__ */ new Set();
@@ -4396,6 +5507,89 @@ function createPrimaryKeyResolver(options) {
 	};
 }
 /**
+* Build the admin's view model out of the row the wire serves.
+*
+* The wire has ONE shape, for every consumer: flat columns, typed the way the
+* database typed them, and a relation rendered as the target's own columns (or
+* only its foreign key, when nothing asked for it). That is the REST contract,
+* what `find()` returns, what `listen()` pushes, and what the generated types
+* describe.
+*
+* The admin renders neither of those directly. Its date field requires a real
+* `Date` and rejects a string outright; its relation cells read `.data.values`
+* off a relation ref. Those requirements are the *admin's*, so they are met
+* here — in the browser, from the collection config the panel already has —
+* rather than by asking the server for a second wire shape.
+*
+* That second shape is what this replaces. Until 2026-09-09 the realtime wire
+* carried the view model and every other read carried flat rows, so `find()`
+* and `listen()` answered one query two ways; unifying the wire without doing
+* this conversion is what left every date cell reading "Invalid date value"
+* and every relation cell "Unexpected value".
+*
+* Values already in view-model form pass through untouched: a driver that
+* still sends `{ __type: "date" }` or a relation ref (the client revives both)
+* is served by the same walk.
+*/
+function toViewModelValues(values, properties, collection, resolveCollection) {
+	if (!properties) return values;
+	const relations = collection ? resolveCollectionRelations(collection) : {};
+	let out;
+	const write = (key, value) => {
+		out = out ?? { ...values };
+		out[key] = value;
+	};
+	for (const [key, rawProperty] of Object.entries(properties)) {
+		const property = rawProperty;
+		if (!property) continue;
+		if (!(key in values)) {
+			const fkRelation = relations[key];
+			const column = fkRelation && "localKey" in fkRelation ? fkRelation.localKey : void 0;
+			const fk = column !== void 0 ? values[column] ?? values[toWireKey(column)] : void 0;
+			const fkTarget = fkRelation?.targetSlug;
+			if (fkTarget && (typeof fk === "string" || typeof fk === "number")) write(key, new EntityRelation(fk, fkTarget));
+			continue;
+		}
+		const value = values[key];
+		if (value === null || value === void 0) continue;
+		const relation = relations[key];
+		if (relation && (property.type === "relation" || property.of?.type === "relation" || property.type === "array")) {
+			const target = relation.targetSlug;
+			if (!target) continue;
+			const targetProperties = resolveCollection?.(target)?.properties;
+			const targetCollection = resolveCollection?.(target);
+			const toRef = (item) => {
+				if (item instanceof EntityRelation) return item;
+				if (typeof item === "object" && item !== null && "__type" in item) return item;
+				if (typeof item === "object" && item !== null) {
+					const row = item;
+					const keys = targetCollection ? resolvePrimaryKeys(targetCollection) : [];
+					const id = keys.length > 0 ? buildCompositeId(row, keys) : row.id;
+					if (id === void 0 || id === null || id === "") return item;
+					return new EntityRelation(id, target, {
+						id,
+						path: target,
+						values: toViewModelValues(row, targetProperties, targetCollection, resolveCollection)
+					});
+				}
+				if (typeof item === "string" || typeof item === "number") return new EntityRelation(item, target);
+				return item;
+			};
+			write(key, Array.isArray(value) ? value.map(toRef) : toRef(value));
+			continue;
+		}
+		if (property.type === "date" && !(value instanceof Date)) {
+			if (typeof value === "string" || typeof value === "number") {
+				const date = new Date(value);
+				write(key, isNaN(date.getTime()) ? null : date);
+			}
+			continue;
+		}
+		if (property.type === "map" && property.properties && typeof value === "object" && !Array.isArray(value)) write(key, toViewModelValues(value, property.properties, void 0, resolveCollection));
+	}
+	return out ?? values;
+}
+/**
 * Give a flat row the Entity view-model the admin renders.
 *
 * The address is *derived here* — it is not a column, and the row it came from
@@ -4406,12 +5600,12 @@ function createPrimaryKeyResolver(options) {
 * `primaryKeys` empty falls back to a literal `id` on the row: drivers other
 * than postgres still serve rows with one, and this keeps them working.
 */
-function rowToEntity(row, slug, primaryKeys = []) {
+function rowToEntity(row, slug, primaryKeys = [], toViewModel) {
 	const { _matches, ...values } = row;
 	return {
 		id: primaryKeys.length > 0 ? buildCompositeId(row, primaryKeys) : row.id,
 		path: slug,
-		values,
+		values: toViewModel ? toViewModel(values) : values,
 		..._matches ? { searchMatches: _matches } : {}
 	};
 }
@@ -4431,14 +5625,16 @@ function inlineEnvelope(envelope) {
 * Replace every relation envelope on a row with the target's flat columns.
 *
 * The SDK serves one relation shape — the inlined one (see
-* {@link RestFetchService}) — and reads that come back through a *driver*
-* method rather than the REST pipeline still carry envelopes. Realtime is the
-* one such read left: there is no `listenForRest`, so the rows arrive shaped
-* for the admin and are flattened here instead.
+* {@link RestFetchService}) — and Postgres now serves it on every read, so
+* against that driver this walk finds nothing to do. It stays for the drivers
+* whose own `fetchCollection` still answers with refs: a developer reading
+* through this accessor gets one shape whichever driver is underneath.
 *
 * Only applied where the REST pipeline is the contract (see `find`); a driver
-* without a `restFetchService` keeps whatever it returns, so the admin's own
-* path through {@link buildRebaseData} is untouched.
+* without a `restFetchService` keeps whatever it returns.
+*
+* Note this is NOT how the admin gets its view model — that is built in the
+* browser by {@link toViewModelValues}, from the same flat row.
 */
 function inlineRelationRefs(row) {
 	let out;
@@ -4451,30 +5647,43 @@ function inlineRelationRefs(row) {
 	}
 	return out ?? row;
 }
-function createDriverAccessor(driver, slug, getPks = () => []) {
+function createDriverAccessor(driver, slug, getPks = () => [], toViewModel) {
 	const accessor = {
 		async find(params) {
 			const filter = params?.where ? deserializeFilter(params.where) : void 0;
 			const { limit, offset, driverOffset } = resolveFindWindow(params);
+			const cursor = params?.after ? decodeCursor(params.after) : void 0;
+			const orderBy = cursor ? reconcileCursorOrder(cursor, normalizeOrderBy(params?.orderBy)) : normalizeOrderBy(params?.orderBy);
+			const startAfter = cursor ? cursorToStartAfter(cursor) : void 0;
+			const probeLimit = startAfter ? limit + 1 : limit;
 			const fetchService = driver.restFetchService;
-			const rows = fetchService ? await fetchService.fetchCollectionForRest(slug, {
+			const fetched = fetchService ? await fetchService.fetchCollectionForRest(slug, {
 				filter,
 				logical: params?.logical,
-				limit,
-				offset: driverOffset,
-				orderBy: normalizeOrderBy(params?.orderBy),
-				searchString: params?.searchString
+				limit: probeLimit,
+				offset: startAfter ? void 0 : driverOffset,
+				startAfter,
+				orderBy,
+				searchString: params?.searchString,
+				fields: params?.fields,
+				distinct: params?.distinct
 			}, params?.include) : await driver.fetchCollection({
 				path: slug,
-				limit,
-				offset: driverOffset,
+				limit: probeLimit,
+				offset: startAfter ? void 0 : driverOffset,
+				startAfter,
 				filter,
 				logical: params?.logical,
-				orderBy: normalizeOrderBy(params?.orderBy),
-				searchString: params?.searchString
+				orderBy,
+				searchString: params?.searchString,
+				include: params?.include,
+				fields: params?.fields,
+				distinct: params?.distinct
 			});
+			const seeking = startAfter !== void 0;
+			const rows = seeking ? fetched.slice(0, limit) : fetched;
 			let total = rows.length + offset;
-			let hasMore = rows.length >= limit;
+			let hasMore = seeking ? fetched.length > limit : rows.length >= limit;
 			if (driver.count) {
 				total = await driver.count({
 					path: slug,
@@ -4482,15 +5691,18 @@ function createDriverAccessor(driver, slug, getPks = () => []) {
 					logical: params?.logical,
 					searchString: params?.searchString
 				});
-				hasMore = offset + rows.length < total;
+				if (!seeking) hasMore = offset + rows.length < total;
 			}
+			const last = rows[rows.length - 1];
+			const nextCursor = hasMore && last && driver.restFetchService?.cursorFor ? driver.restFetchService.cursorFor(slug, last, orderBy) : void 0;
 			return {
-				data: rows.map((row) => rowToEntity(row, slug, getPks())),
+				data: rows.map((row) => rowToEntity(row, slug, getPks(), toViewModel)),
 				meta: {
 					total,
 					limit,
 					offset,
-					hasMore
+					hasMore,
+					...nextCursor && { nextCursor }
 				}
 			};
 		},
@@ -4500,22 +5712,31 @@ function createDriverAccessor(driver, slug, getPks = () => []) {
 				path: slug,
 				id
 			});
-			return row ? rowToEntity(row, slug, getPks()) : void 0;
+			return row ? rowToEntity(row, slug, getPks(), toViewModel) : void 0;
 		},
+		aggregate: driver.restFetchService?.aggregate ? async (params) => driver.restFetchService.aggregate(slug, {
+			aggregates: params.select.map(toDriverAggregate),
+			groupBy: params.groupBy,
+			filter: params.where ? deserializeFilter(params.where) : void 0,
+			logical: params.logical,
+			searchString: params.searchString,
+			limit: params.limit
+		}) : void 0,
 		async create(data, id) {
 			return rowToEntity(await driver.save({
 				path: slug,
 				values: data,
 				id,
 				status: "new"
-			}), slug, getPks());
+			}), slug, getPks(), toViewModel);
 		},
 		createMany: driver.saveMany ? async (data, options) => {
 			return (await driver.saveMany({
 				path: slug,
 				rows: data,
-				upsert: options?.upsert
-			})).map((row) => rowToEntity(row, slug, getPks()));
+				upsert: options?.upsert,
+				onConflict: options?.onConflict
+			})).map((row) => rowToEntity(row, slug, getPks(), toViewModel));
 		} : void 0,
 		async update(id, data) {
 			return rowToEntity(await driver.save({
@@ -4523,7 +5744,7 @@ function createDriverAccessor(driver, slug, getPks = () => []) {
 				values: data,
 				id,
 				status: "existing"
-			}), slug, getPks());
+			}), slug, getPks(), toViewModel);
 		},
 		async delete(id) {
 			return driver.delete({ row: {
@@ -4539,7 +5760,7 @@ function createDriverAccessor(driver, slug, getPks = () => []) {
 					id: u.id,
 					values: u.data
 				}))
-			})).map((row) => rowToEntity(row, slug, getPks()));
+			})).map((row) => rowToEntity(row, slug, getPks(), toViewModel));
 		} : void 0,
 		deleteMany: driver.deleteMany ? async (ids) => {
 			await driver.deleteMany({
@@ -4571,7 +5792,7 @@ function createDriverAccessor(driver, slug, getPks = () => []) {
 				vectorSearch: params?.vectorSearch,
 				onUpdate: (entities) => {
 					onUpdate({
-						data: entities.map((row) => rowToEntity(normalize(row), slug, getPks())),
+						data: entities.map((row) => rowToEntity(normalize(row), slug, getPks(), toViewModel)),
 						meta: {
 							total: offset + entities.length,
 							limit,
@@ -4588,7 +5809,7 @@ function createDriverAccessor(driver, slug, getPks = () => []) {
 			return driver.listenOne({
 				path: slug,
 				id,
-				onUpdate: (entity) => onUpdate(entity ? rowToEntity(normalize(entity), slug, getPks()) : void 0),
+				onUpdate: (entity) => onUpdate(entity ? rowToEntity(normalize(entity), slug, getPks(), toViewModel) : void 0),
 				onError
 			});
 		} : void 0,
@@ -4630,13 +5851,32 @@ function createDriverAccessor(driver, slug, getPks = () => []) {
 * await data.products.create({ name: "Camera", price: 299 });
 * const { data: items } = await data.products.find({ where: { status: ["==", "published"] } });
 */
+/**
+* The view-model converter for one collection, or `undefined` when there is no
+* collection config to build it from.
+*
+* Absent is the honest answer for every consumer that is not the admin: the
+* flat SDK derives itself from this same layer (`buildSdkData`) and must keep
+* the wire's own types, and it registers no collection resolver.
+*/
+function createViewModelConverter(options) {
+	if (!options?.resolveCollection) return () => void 0;
+	return function converterFor(slug) {
+		return (values) => {
+			const collection = options.resolveCollection?.(slug);
+			if (!collection) return values;
+			return toViewModelValues(values, collection.properties, collection, options.resolveCollection);
+		};
+	};
+}
 function buildRebaseData(driver, options) {
 	const cache = /* @__PURE__ */ new Map();
 	const primaryKeysFor = createPrimaryKeyResolver(options);
+	const viewModelFor = createViewModelConverter(options);
 	function getAccessor(slug) {
 		let accessor = cache.get(slug);
 		if (!accessor) {
-			accessor = createDriverAccessor(driver, slug, () => primaryKeysFor(slug));
+			accessor = createDriverAccessor(driver, slug, () => primaryKeysFor(slug), viewModelFor(slug));
 			cache.set(slug, accessor);
 		}
 		return accessor;
@@ -4691,9 +5931,14 @@ var SdkQueryBuilder = class {
 		return this;
 	}
 	/** Called again, this adds a tie-breaker rather than replacing the sort. */
-	orderBy(column, direction = "asc") {
+	orderBy(column, direction = "asc", nulls) {
 		const existing = normalizeOrderBy(this.params.orderBy) ?? [];
-		this.params.orderBy = [...existing, [sortKeyToString(column), direction]];
+		const key = sortKeyToString(column);
+		this.params.orderBy = [...existing, nulls ? [
+			key,
+			direction,
+			nulls
+		] : [key, direction]];
 		return this;
 	}
 	limit(count) {
@@ -4718,13 +5963,39 @@ var SdkQueryBuilder = class {
 		};
 		return this;
 	}
+	/**
+	* Load relations. Merges rather than replaces, so `.include("author")` then
+	* `.include({ comments: { limit: 5 } })` asks for both — a builder call that
+	* silently discarded an earlier one is the same defect `where` had.
+	*/
 	include(...relations) {
-		this.params.include = relations;
+		this.params.include = mergeIncludeSpecs(this.params.include, relations);
+		return this;
+	}
+	fields(...columns) {
+		this.params.fields = [...this.params.fields ?? [], ...columns];
+		return this;
+	}
+	distinct(enabled = true) {
+		this.params.distinct = enabled;
+		return this;
+	}
+	after(cursor) {
+		this.params.after = cursor;
 		return this;
 	}
 	async find() {
 		return this.client.find(this.params);
 	}
+	/** Aggregate the matching rows. See {@link SDKCollectionClient.aggregate}. */
+	async aggregate(params) {
+		return this.client.aggregate({
+			...params,
+			where: this.params.where,
+			logical: this.params.logical,
+			searchString: this.params.searchString
+		});
+	}
 	/**
 	* Page through everything this query matches, one row at a time.
 	*
@@ -4802,6 +6073,24 @@ function toSdkCollectionClient(snap, slug = "collection") {
 			if (!snap.createMany) throw new Error("Bulk writes are not supported by this collection's data source. Fall back to create() per record.");
 			return (await snap.createMany(data, options)).map(entityToRow);
 		},
+		/**
+		* One row through the bulk path, because the bulk path is where the
+		* conflict target lives.
+		*
+		* `CollectionAccessor` has no single-row upsert and adding one would
+		* mean a second way to say the same thing to the same driver method —
+		* `saveMany` already takes `upsert` and `onConflict`, and a batch of
+		* one is exactly an upsert of one.
+		*/
+		async upsert(data, options) {
+			if (!snap.createMany) throw new Error("Upsert is not supported by this collection's data source: it needs a bulk write, which this driver does not implement. Fall back to create() or update().");
+			const row = (await snap.createMany([data], {
+				upsert: true,
+				onConflict: options?.onConflict
+			}))[0];
+			if (!row) throw new Error(`Upsert into "${slug}" returned no row.`);
+			return entityToRow(row);
+		},
 		async update(id, data) {
 			return entityToRow(await snap.update(id, data));
 		},
@@ -4834,12 +6123,16 @@ function toSdkCollectionClient(snap, slug = "collection") {
 			if (typeof columnOrCondition === "object") return builder.where(columnOrCondition);
 			return builder.where(columnOrCondition, operator, value);
 		},
-		orderBy: (column, direction) => new SdkQueryBuilder(client).orderBy(column, direction),
+		orderBy: (column, direction, nulls) => new SdkQueryBuilder(client).orderBy(column, direction, nulls),
 		limit: (count) => new SdkQueryBuilder(client).limit(count),
 		offset: (count) => new SdkQueryBuilder(client).offset(count),
 		search: (searchString) => new SdkQueryBuilder(client).search(searchString),
 		vectorSearch: (property, vector, options) => new SdkQueryBuilder(client).vectorSearch(property, vector, options),
-		include: (...relations) => new SdkQueryBuilder(client).include(...relations)
+		include: (...relations) => new SdkQueryBuilder(client).include(...relations),
+		fields: (...columns) => new SdkQueryBuilder(client).fields(...columns),
+		distinct: (enabled) => new SdkQueryBuilder(client).distinct(enabled),
+		after: (cursor) => new SdkQueryBuilder(client).after(cursor),
+		aggregate: snap.aggregate ? (params) => snap.aggregate(params) : unsupportedMethod(noAggregate(slug))
 	};
 	return client;
 }
@@ -4927,6 +6220,6 @@ function buildRoutedRebaseData({ defaultData, sources, resolveKey }) {
 	} });
 }
 //#endregion
-export { ANONYMOUS_USER_ID as A, buildCompositeId as C, ListLimitError as D, toSnakeCase as E, Vector as F, RebaseApiError as I, RebaseClientError as L, EntityReference as M, EntityRelation as N, MAX_LIST_LIMIT as O, GeoPoint as P, isUnsupported as R, resolveCollectionRelations as S, suggestNearMiss as T, getEffectiveSecurityRules as _, deserializeLogicalCondition as a, getTableName as b, collectAllPages as c, normalizeOrderBy as d, serializeOrderBy as f, resolveDataSource as g, createDataSourceRegistry as h, deserializeFilter as i, isAnonymousUid as j, resolveClientListLimit as k, paginateFind as l, CollectionRegistry as m, buildSdkData as n, serializeFilter as o, defaultUsersCollection as p, UnknownFilterOperatorError as r, serializeLogicalCondition as s, buildRoutedRebaseData as t, resolveFindWindow as u, fieldKeyForColumn as v, resolvePrimaryKeys as w, isRelationRequired as x, findRelation as y, unsupportedMethod as z };
+export { isFieldOperation as $, createDataSourceRegistry as A, resolveCollectionRelations as B, decodeCursor as C, restrictedFieldNames as D, effectiveAccess as E, securityRuleToConditions as F, suggestNearMiss as G, buildCompositeId as H, fieldKeyForColumn as I, MAX_LIST_LIMIT as J, toSnakeCase as K, findRelation as L, resolveDataSource as M, getEffectiveSecurityRules as N, defaultUsersCollection as O, getTenantConfig as P, hasFieldOperation as Q, getTableName as R, cursorToStartAfter as S, canWriteField as T, resolvePrimaryKeys as U, enumToObjectEntries as V, hydrateRegExp as W, BATCH_REF_KEY as X, resolveClientListLimit as Y, FIELD_OPERATORS as Z, OrderBySpecError as _, deserializeLogicalCondition as a, Vector as at, CursorError as b, collectAllPages as c, isUnsupported as ct, IncludeSpecError as d, ANONYMOUS_USER_ID as et, deserializeInclude as f, topLevelIncludeNames as g, serializeInclude as h, deserializeFilter as i, GeoPoint as it, isRelationalCollection as j, CollectionRegistry as k, paginateFind as l, unsupportedMethod as lt, normalizeInclude as m, buildSdkData as n, EntityReference as nt, serializeFilter as o, RebaseApiError as ot, mergeIncludeSpecs as p, ListLimitError as q, UnknownFilterOperatorError as r, EntityRelation as rt, serializeLogicalCondition as s, RebaseClientError as st, buildRoutedRebaseData as t, isAnonymousUid as tt, resolveFindWindow as u, normalizeOrderBy as v, reconcileCursorOrder as w, CursorMismatchError as x, serializeOrderBy as y, isRelationRequired as z };
 
-//# sourceMappingURL=src-Dq-I3Ybx.js.map
+//# sourceMappingURL=src-DqZ9YiGA.js.map