@rebasepro/common 0.9.1-canary.fd3754b → 0.10.0

package/dist/util/auth-default-policies.d.ts

@@ -0,0 +1,22 @@
+import { CollectionConfig, SecurityRule } from "@rebasepro/types";
+/**
+ * Returns the security rules that should be applied to a collection: the
+ * author's explicit `securityRules` plus the framework defaults described in
+ * the module doc (baseline server/admin read for all collections; self-read
+ * and the admin write gate for auth collections).
+ *
+ * Collections that opt out via `disableDefaultPolicies` are returned unchanged.
+ */
+export declare function getEffectiveSecurityRules(collection: CollectionConfig): SecurityRule[];
+/**
+ * The framework defaults that {@link getEffectiveSecurityRules} would add to a
+ * collection, without the author's own rules.
+ *
+ * These policies appear in the database under names the author never wrote, and
+ * a permissive policy ORs with every other permissive policy — so someone
+ * reading their `securityRules` and then the real ACL sees more access than they
+ * declared. Dropping them by hand does nothing either: `db push` is declarative,
+ * so the next push asserts them again. Callers use this to say, in the generated
+ * DDL, which policies are injected and how to take them off.
+ */
+export declare function getInjectedSecurityRules(collection: CollectionConfig): SecurityRule[];

package/dist/util/identity.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Row identity: the address of a row, and how to derive it.
+ *
+ * Postgres has no `id`. A row is identified by its primary key — one or more
+ * columns, with any names and any types. `id` is something we synthesize on top
+ * of that: a single string token, because the admin needs *one* value it can put
+ * in a URL (`/products/1:::2`), use as a cache key, and hang a relation ref off.
+ *
+ * That token is an address, not data. It is derived from the row's columns and
+ * never stored in them — a row is exactly its columns, with their real types.
+ * Writing the address back into the row is what used to rename primary keys
+ * (`sku` → `id`) and restringify them (`42` → `"42"`) on the way out.
+ *
+ * These live in `common` because both sides need them and must agree exactly:
+ * the driver parses an incoming address back into key columns, and the admin
+ * derives the address from a row it was served.
+ */
+/**
+ * A primary-key column: its name, the type it round-trips as, and whether it is
+ * a UUID (which is a string despite sometimes being described as an id "number").
+ */
+export interface PrimaryKeyInfo {
+    fieldName: string;
+    type: "string" | "number";
+    isUUID?: boolean;
+}
+/** Separator between the parts of a composite address. */
+export declare const COMPOSITE_ID_SEPARATOR = ":::";
+/**
+ * Derive a row's address from its key columns.
+ *
+ * Single key → the value as a string. Composite → each part joined by
+ * {@link COMPOSITE_ID_SEPARATOR}, in primary-key order, which is what
+ * {@link parseIdValues} expects to invert.
+ */
+export declare function buildCompositeId(values: Record<string, unknown>, primaryKeys: PrimaryKeyInfo[]): string;
+/**
+ * Invert {@link buildCompositeId}: turn an address back into key columns, each
+ * coerced to the type its column actually round-trips as.
+ *
+ * This is the boundary where a URL segment becomes a query parameter, so a
+ * malformed address must throw rather than silently produce a query that
+ * matches the wrong row (or none).
+ */
+export declare function parseIdValues(idValue: string | number, primaryKeys: PrimaryKeyInfo[]): Record<string, string | number>;
+/**
+ * The primary keys of a collection, as declared by its properties.
+ *
+ * This is the only tier both sides can read, because it is the only one written
+ * in the config: the postgres driver can also infer keys from the Drizzle
+ * schema, which the browser never sees and is never sent — the admin compiles
+ * the collection files into its own bundle rather than being served them. A key
+ * that lives only in the Drizzle schema is therefore invisible here, and the
+ * server says so at boot (`warnOnKeysTheAdminCannotResolve`) naming the `isId`
+ * to add.
+ *
+ * Returns an empty array when a collection declares none, which callers must
+ * treat as "not addressable" rather than defaulting to `id`: guessing a key
+ * that is not the real one produces confidently wrong addresses.
+ */
+export declare function getDeclaredPrimaryKeys(collection: {
+    properties?: Record<string, unknown>;
+}): PrimaryKeyInfo[];
+/**
+ * The keys to address a collection's rows with, resolved the way the driver
+ * resolves them — minus the tier the browser cannot reach.
+ *
+ * The postgres driver tries, in order: properties marked `isId`; the primary
+ * keys of the Drizzle schema; and finally a column literally named `id`. Only
+ * the first and last are visible in a `CollectionConfig`, which is what both
+ * sides share.
+ *
+ * So the two agree except on a collection that declares no `isId` and whose key
+ * is known only to Drizzle. There, the driver reads the real key, and this
+ * either resolves nothing (reported to the console by the caller) or — if the
+ * table happens to have an unrelated `id` property — resolves `id`, which is
+ * the wrong key and cannot be detected from here: the addresses look right and
+ * route wrong. Only the config can settle it, so the server names both cases
+ * at boot (`warnOnKeysTheAdminCannotResolve`) with the `isId` to add.
+ */
+export declare function resolvePrimaryKeys(collection: {
+    properties?: Record<string, unknown>;
+}): PrimaryKeyInfo[];

package/dist/util/index.d.ts

@@ -1,6 +1,7 @@
 export * from "./collections";
 export * from "./common";
 export * from "./entities";
+export * from "./identity";
 export * from "./enums";
 export * from "./paths";
 export * from "./resolutions";
@@ -13,6 +14,8 @@ export * from "./builders";
 export * from "./storage";
 export * from "./callbacks";
 export * from "./relations";
+export * from "./auth-default-policies";
+export * from "./junction-policies";
 export * from "./conditions";
 export * from "./navigation_utils";
 export * from "./filter-operator-resolution";

package/dist/util/junction-policies.d.ts

@@ -0,0 +1,108 @@
+import { CollectionConfig, PolicyExpression, Relation, SecurityRule } from "@rebasepro/types";
+/**
+ * RLS derivation for many-to-many junction tables.
+ *
+ * A `through` relation makes the generator create a table nobody declared as a
+ * collection — `posts_tags`, `user_roles`. Those tables used to be the one kind
+ * of generated table with **no** RLS at all: `rebase_user` holds full DML grants,
+ * so with the endpoints locked down, any signed-up user could still read or wipe
+ * every edge between them. There is also nowhere in the config to write rules
+ * for a junction, so the author could not even fix it by hand.
+ *
+ * The architecture here is that a junction's security is *derived*, never
+ * hand-written:
+ *
+ *  1. **Locked baseline.** The same server-or-admin `default_admin` grants every
+ *     collection gets, so the invariant holds again: every table the generator
+ *     creates is default-deny, and rules only broaden.
+ *
+ *  2. **Reads follow the endpoints.** An edge is visible iff *both* endpoint
+ *     rows are visible — two correlated `EXISTS` subqueries. The subqueries run
+ *     under the caller's role, so each endpoint's own RLS filters them: junction
+ *     visibility delegates to the endpoints' policies, whatever they become,
+ *     with nothing duplicated. A public blog keeps rendering its tags; a private
+ *     CRM's edges are exactly as hidden as its rows.
+ *
+ *  3. **Writes follow the owning side's update rules.** Linking or unlinking an
+ *     edge *is* an edit of the owning row — tagging a post is editing the post —
+ *     so edge writes inherit the declaring collection's explicit permissive
+ *     `update` rules, each wrapped in an `EXISTS` against the owning row. Where
+ *     a rule cannot be embedded faithfully (see below) it is dropped, so the
+ *     failure mode is always *too locked*, never open. Explicit **restrictive**
+ *     update rules are inherited as restrictive junction rules; if one of them
+ *     cannot be embedded, the whole derived write grant for that side is
+ *     suppressed — granting without the author's gate would be looser than the
+ *     parent itself.
+ *
+ * **Embeddability.** A parent rule is embedded by moving its condition inside
+ * `EXISTS (SELECT 1 FROM parent WHERE parent.pk = junction.fk AND <condition>)`.
+ * In that scope, `field` operands bind to the parent — which is what the author
+ * meant. But `outerField` operands and `{column}` placeholders in `raw` SQL bind
+ * to the RLS row, which is now the junction, not the parent the author wrote
+ * them against. So: `raw` anywhere disqualifies a rule; a top-level `outerField`
+ * (equivalent to `field` outside a subquery) is rewritten to `field`; an
+ * `outerField` inside a nested `existsIn` cannot be re-scoped and disqualifies
+ * the rule.
+ *
+ * Injected parent defaults are never inherited — the junction's own baseline
+ * already covers the server/admin plane, and an auth collection's restrictive
+ * `require_admin_write` gate exists to protect privileged parent *columns*,
+ * which an edge write cannot touch. Inheriting it would stop users managing
+ * e.g. their own interests through a `users_interests` junction for no gain.
+ *
+ * Everything flows through the shared naming machinery, so the Studio
+ * recognises these policies as generated instead of offering to "import" them.
+ */
+/** One side of a junction: the collection and the FK column pointing at it. */
+export interface JunctionEndpoint {
+    collection: CollectionConfig;
+    /** Junction column holding this endpoint's key. */
+    junctionColumn: string;
+}
+/** A collection that declares the `through` relation (owns the edge semantics). */
+export interface JunctionDeclaringSide extends JunctionEndpoint {
+    relation: Relation;
+}
+export interface JunctionSpec {
+    /** Bare table name (schema stripped). */
+    table: string;
+    /** Schema the junction is created in — mirrors the CREATE TABLE path. */
+    schema: string;
+    /** The two endpoints, in [source, target] order of the first declaring relation. */
+    endpoints: [JunctionEndpoint, JunctionEndpoint];
+    /** Every collection that declares a relation through this table. */
+    declaringSides: JunctionDeclaringSide[];
+}
+/**
+ * Walk every collection's resolved relations and aggregate the junction tables
+ * they declare. Two collections may declare the same junction from opposite
+ * sides (posts→tags and tags→posts through `posts_tags`); both become
+ * `declaringSides` of one spec, so derived write grants consider both.
+ */
+export declare function resolveJunctionSpecs(collections: CollectionConfig[]): Map<string, JunctionSpec>;
+/**
+ * A synthetic CollectionConfig standing in for the junction during policy
+ * compilation and naming. Its two FK columns carry explicit `columnName`s so
+ * `outerField` operands resolve to the exact columns the CREATE TABLE emitted,
+ * whatever their casing.
+ */
+export declare function getJunctionCollectionConfig(spec: JunctionSpec): CollectionConfig;
+/**
+ * Whether a parent-rule expression keeps its meaning when moved inside the
+ * junction's `EXISTS` subquery — and the re-scoped copy if it does.
+ *
+ * Returns `null` when the rule cannot be embedded faithfully: `raw` SQL
+ * anywhere (its `{column}` placeholders would bind to the junction), or an
+ * `outerField` inside a nested `existsIn` (it would bind to the junction while
+ * the author meant the parent, and no operand can express "the middle scope").
+ * Top-level `outerField`s are rewritten to `field`, which is what they meant.
+ */
+export declare function embedParentExpression(expr: PolicyExpression, depth?: number): PolicyExpression | null;
+/**
+ * The full derived policy set for a junction table: the locked server/admin
+ * baseline, the endpoint-visibility read grant, inherited write grants, and
+ * inherited restrictive gates. Returns `[]` when every declaring collection set
+ * `disableDefaultPolicies` — the junction is then the author's to police, and
+ * stays locked (RLS is still enabled) until they write policies for it.
+ */
+export declare function getJunctionSecurityRules(spec: JunctionSpec): SecurityRule[];

package/dist/util/policy/evaluatePolicy.d.ts

@@ -13,7 +13,14 @@ export type TriState = boolean | "unknown";
  * being evaluated (or none, for collection-level gating).
  */
 export interface PolicyEvalContext {
-    /** The current user's id, or null/undefined when unauthenticated. */
+    /**
+     * The current user's id, or null/undefined when no user is signed in.
+     *
+     * Null here means *anonymous visitor*, not "server context" — a client is
+     * never the server context. `authUid` operands therefore resolve to
+     * {@link ANONYMOUS_USER_ID} rather than `null`, matching the `auth.uid()`
+     * the database would see for the same request.
+     */
     uid?: string | null;
     /** The current user's application roles. */
     roles?: string[];

package/dist/util/policy/index.d.ts

@@ -1,3 +1,4 @@
 export * from "./securityRuleToConditions";
+export * from "./sqlToPolicy";
 export * from "./policyToPostgres";
 export * from "./evaluatePolicy";

package/dist/util/policy/sqlToPolicy.d.ts

@@ -1,20 +1,30 @@
 import { PolicyExpression } from "@rebasepro/types";
+export declare function sqlToPolicy(sql: string): PolicyExpression;
+/** A clause that reads as a lockdown but admits anonymous callers. */
+export interface AnonymousGrantRisk {
+    /** Which spelling was found. */
+    pattern: "foreign-uid-literal" | "uid-not-null";
+    /** The offending fragment — the literal, or the SQL that is a tautology. */
+    detail: string;
+    /** Why it admits anonymous callers, and what to write instead. */
+    explanation: string;
+}
 /**
- * A tiny, regex-based SQL "parser" for security rules.
+ * Find clauses that read as "signed-in users only" but admit anonymous callers.
+ *
+ * Both spellings come from the same place — Supabase, where `auth.uid()` really
+ * is NULL for an anonymous request. Rebase substitutes
+ * {@link ANONYMOUS_USER_ID} instead (a blank id would read back as NULL, which
+ * is how the trusted *server* context is recognised), so:
  *
- * 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.
+ *  - `auth.uid() IS NOT NULL` is a tautology on the user path, and
+ *  - `auth.uid() != 'anon'` compares against a string no caller ever has.
  *
- * It handles:
- * - `field = 'literal'`
- * - `field != 'literal'`
- * - `field = current_setting('app.user_id')`
- * - `A AND B`
- * - `true`
- * - `IN (...)` (as optimistic true)
+ * Either one turns a lockdown into a full grant, and neither looks wrong. No
+ * real user id is ever one of these literals, and a user-context request is
+ * never NULL, so a match is always a mistake rather than a deliberate check.
  *
- * For anything it doesn't understand, it returns a `raw` expression, which
- * the evaluator treats as "unknown" (and usually optimistic true).
+ * Structured expressions are checked too, not just parsed SQL: `policy.compare`
+ * can spell the same mistake.
  */
-export declare function sqlToPolicy(sql: string): PolicyExpression;
+export declare function findAnonymousGrants(expr: PolicyExpression): AnonymousGrantRisk[];

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@rebasepro/common",
   "type": "module",
-  "version": "0.9.1-canary.fd3754b",
+  "version": "0.10.0",
   "description": "Awesome Firebase/Firestore-based headless open-source CMS",
   "funding": {
     "url": "https://github.com/sponsors/rebaseco"
@@ -13,12 +13,12 @@
     "url": "https://github.com/rebasepro/rebase.git",
     "directory": "packages/common"
   },
-  "main": "./dist/index.umd.js",
+  "main": "./dist/index.es.js",
   "module": "./dist/index.es.js",
   "types": "./dist/index.d.ts",
   "source": "src/index.ts",
   "engines": {
-    "node": ">=14"
+    "node": ">=20"
   },
   "keywords": [
     "rebase",
@@ -33,16 +33,15 @@
     ".": {
       "types": "./dist/index.d.ts",
       "development": "./dist/index.es.js",
-      "import": "./dist/index.es.js",
-      "require": "./dist/index.umd.js"
+      "import": "./dist/index.es.js"
     },
     "./package.json": "./package.json"
   },
   "dependencies": {
     "fast-equals": "6.0.0",
     "json-logic-js": "^2.0.5",
-    "@rebasepro/types": "0.9.1-canary.fd3754b",
-    "@rebasepro/utils": "0.9.1-canary.fd3754b"
+    "@rebasepro/types": "0.10.0",
+    "@rebasepro/utils": "0.10.0"
   },
   "devDependencies": {
     "@jest/globals": "^30.4.1",
@@ -100,7 +99,7 @@
   },
   "scripts": {
     "watch": "vite build --watch",
-    "build": "vite build && tsc --emitDeclarationOnly -p tsconfig.prod.json",
+    "build": "vite build && tsc --emitDeclarationOnly -p tsconfig.prod.json && node ../../scripts/assert-build-output.mjs",
     "test:lint": "eslint \"src/**\" --quiet",
     "test": "jest --passWithNoTests",
     "clean": "rm -rf dist && find ./src -name '*.js' -type f | xargs rm -f",

package/src/collections/default-collections.ts

@@ -68,6 +68,7 @@ unique: true }
             name: "Password Hash",
             type: "string",
             columnName: "password_hash",
+            excludeFromApi: true,
             ui: { hideFromCollection: true,
 disabled: { hidden: true } }
         },
@@ -83,6 +84,7 @@ disabled: { hidden: true } }
             name: "Email Verification Token",
             type: "string",
             columnName: "email_verification_token",
+            excludeFromApi: true,
             ui: { hideFromCollection: true,
 disabled: { hidden: true } }
         },

package/src/data/buildRebaseData.ts

@@ -17,14 +17,79 @@ import {
 import { toSnakeCase } from "@rebasepro/utils";
 import { QueryBuilder } from "./query_builder";
 import { deserializeFilter } from "./filter-dialect";
+import { buildCompositeId, resolvePrimaryKeys, PrimaryKeyInfo } from "../util/identity";
+
+export interface EntityDataOptions {
+    /**
+     * Look up a collection's config by slug, to derive row addresses from its
+     * primary keys.
+     *
+     * Called lazily rather than up front: the data layer is created by `Rebase`,
+     * which sits *above* the admin that owns the collections, so a resolver
+     * registered on mount would otherwise arrive too late to be seen.
+     */
+    resolveCollection?: (slug: string) => { properties?: Record<string, unknown> } | undefined;
+}
+
+function createPrimaryKeyResolver(options?: EntityDataOptions) {
+    const cache = new Map<string, PrimaryKeyInfo[]>();
+    const warned = new Set<string>();
+
+    return function primaryKeysFor(slug: string): PrimaryKeyInfo[] {
+        const cached = cache.get(slug);
+        if (cached) return cached;
+
+        const collection = options?.resolveCollection?.(slug);
+        if (!collection) {
+            // The registry may not have been registered yet. Don't memoize a
+            // miss, or the collection would stay address-less for this session.
+            return [];
+        }
+
+        const keys = resolvePrimaryKeys(collection);
+        if (keys.length > 0) {
+            // Memoized for the session: a collection's key does not change
+            // while the app runs, and this is called once per row. Editing
+            // `isId` in the schema editor needs a reload to take effect here.
+            cache.set(slug, keys);
+            return keys;
+        }
+
+        if (!warned.has(slug)) {
+            warned.add(slug);
+            // Silence here surfaces much later as rows that cannot be opened,
+            // linked, or saved, with nothing pointing back at the cause.
+            console.warn(
+                `[rebase] Collection '${slug}' declares no primary key, so its rows have no address: ` +
+                `detail links, caching and relations will not work for it. ` +
+                `Mark the key property with \`isId\` in its collection config — the server logs which ` +
+                `column to mark at boot, if its schema knows the key.`
+            );
+        }
+        return keys;
+    };
+}
 
 /**
- * Convert a flat REST record (e.g. from RestFetchService) to Entity<M> format.
- * Mirrors the client SDK's rowToEntity conversion.
+ * 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
+ * does not contain one. Rows carry exactly what the table has, with the types
+ * Postgres returned; the id is this layer's invention, and this is the only
+ * place it is minted.
+ *
+ * `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<M extends Record<string, unknown>>(row: Record<string, unknown>, slug: string): Entity<M> {
+function rowToEntity<M extends Record<string, unknown>>(
+    row: Record<string, unknown>,
+    slug: string,
+    primaryKeys: PrimaryKeyInfo[] = []
+): Entity<M> {
     return {
-        id: row.id as string | number,
+        id: primaryKeys.length > 0
+            ? buildCompositeId(row, primaryKeys)
+            : row.id as string | number,
         path: slug,
         values: row as EntityValues<M>
     };
@@ -32,7 +97,8 @@ function rowToEntity<M extends Record<string, unknown>>(row: Record<string, unkn
 
 function createDriverAccessor<M extends Record<string, unknown> = Record<string, unknown>>(
     driver: DataDriver,
-    slug: string
+    slug: string,
+    getPks: () => PrimaryKeyInfo[] = () => []
 ): CollectionAccessor<M> {
     const accessor: CollectionAccessor<M> = {
         async find(params?: FindParams): Promise<FindResponse<M>> {
@@ -75,14 +141,14 @@ function createDriverAccessor<M extends Record<string, unknown> = Record<string,
             }
 
             return {
-                data: rows.map((row: Record<string, unknown>) => rowToEntity<M>(row, slug)),
+                data: rows.map((row: Record<string, unknown>) => rowToEntity<M>(row, slug, getPks())),
                 meta: { total, limit, offset, hasMore }
             };
         },
 
         async findById(id: string | number): Promise<Entity<M> | undefined> {
             const row = await driver.fetchOne<M>({ path: slug, id: id });
-            return row ? rowToEntity<M>(row, slug) : undefined;
+            return row ? rowToEntity<M>(row, slug, getPks()) : undefined;
         },
 
         async create(data: Partial<EntityValues<M>>, id?: string | number): Promise<Entity<M>> {
@@ -92,9 +158,20 @@ function createDriverAccessor<M extends Record<string, unknown> = Record<string,
                 id: id,
                 status: "new"
             });
-            return rowToEntity<M>(row, slug);
+            return rowToEntity<M>(row, slug, getPks());
         },
 
+        createMany: driver.saveMany
+            ? async (data: Partial<EntityValues<M>>[], options?: { upsert?: boolean }): Promise<Entity<M>[]> => {
+                const rows = await driver.saveMany!<M>({
+                    path: slug,
+                    rows: data,
+                    upsert: options?.upsert
+                });
+                return rows.map((row) => rowToEntity<M>(row, slug, getPks()));
+            }
+            : undefined,
+
         async update(id: string | number, data: Partial<EntityValues<M>>): Promise<Entity<M>> {
             const row = await driver.save<M>({
                 path: slug,
@@ -102,7 +179,7 @@ function createDriverAccessor<M extends Record<string, unknown> = Record<string,
                 id: id,
                 status: "existing"
             });
-            return rowToEntity<M>(row, slug);
+            return rowToEntity<M>(row, slug, getPks());
         },
 
         async delete(id: string | number): Promise<void> {
@@ -137,7 +214,7 @@ values: {} as Record<string, unknown> }
                     searchString: params?.searchString,
                     onUpdate: (entities) => {
                         onUpdate({
-                            data: entities.map((row: Record<string, unknown>) => rowToEntity<M>(row, slug)),
+                            data: entities.map((row: Record<string, unknown>) => rowToEntity<M>(row, slug, getPks())),
                             meta: {
                                 total: entities.length,
                                 limit,
@@ -155,7 +232,7 @@ values: {} as Record<string, unknown> }
                 return driver.listenOne!<M>({
                     path: slug,
                     id: id,
-                    onUpdate: (entity) => onUpdate(entity ? rowToEntity<M>(entity, slug) : undefined),
+                    onUpdate: (entity) => onUpdate(entity ? rowToEntity<M>(entity, slug, getPks()) : undefined),
                     onError
                 });
             } : undefined,
@@ -200,13 +277,14 @@ values: {} as Record<string, unknown> }
  * await data.products.create({ name: "Camera", price: 299 });
  * const { data: items } = await data.products.find({ where: { status: ["==", "published"] } });
  */
-export function buildRebaseData(driver: DataDriver): RebaseData {
+export function buildRebaseData(driver: DataDriver, options?: EntityDataOptions): RebaseData {
     const cache = new Map<string, CollectionAccessor>();
+    const primaryKeysFor = createPrimaryKeyResolver(options);
 
     function getAccessor(slug: string): CollectionAccessor {
         let accessor = cache.get(slug);
         if (!accessor) {
-            accessor = createDriverAccessor(driver, slug);
+            accessor = createDriverAccessor(driver, slug, () => primaryKeysFor(slug));
             cache.set(slug, accessor);
         }
         return accessor;
@@ -236,8 +314,9 @@ export function buildRebaseData(driver: DataDriver): RebaseData {
 // =============================================================================
 
 /**
- * Unwrap a Entity into a flat row. `rowToEntity` stores the whole flat row
- * (id included) under `.values`, so this is just that payload.
+ * Unwrap a Entity back into the flat row it was built from. `rowToEntity` keeps
+ * the row untouched under `.values` and derives `.id` alongside it, so dropping
+ * the wrapper is the whole operation — the address was never part of the row.
  */
 function entityToRow<M extends Record<string, unknown>>(entity: Entity<M>): M {
     return entity.values as unknown as M;
@@ -326,6 +405,20 @@ function toSdkCollectionClient<M extends Record<string, unknown>>(
         async create(data: Partial<M>, id?: string | number): Promise<M> {
             return entityToRow(await snap.create(data as Partial<EntityValues<M>>, id));
         },
+        async createMany(data: Partial<M>[], options?: { upsert?: boolean }): Promise<M[]> {
+            if (!Array.isArray(data)) {
+                throw new TypeError("createMany expects an array of records.");
+            }
+            if (data.length === 0) return [];
+            if (!snap.createMany) {
+                throw new Error(
+                    "Bulk writes are not supported by this collection's data source. " +
+                    "Fall back to create() per record."
+                );
+            }
+            const rows = await snap.createMany(data as Partial<EntityValues<M>>[], options);
+            return rows.map(entityToRow);
+        },
         async update(id: string | number, data: Partial<M>): Promise<M> {
             return entityToRow(await snap.update(id, data as Partial<EntityValues<M>>));
         },
@@ -364,24 +457,25 @@ function toSdkCollectionClient<M extends Record<string, unknown>>(
  */
 function toEntityAccessor<M extends Record<string, unknown>>(
     sdk: SDKCollectionClient<M>,
-    slug: string
+    slug: string,
+    getPks: () => PrimaryKeyInfo[] = () => []
 ): CollectionAccessor<M> {
     const accessor: CollectionAccessor<M> = {
         async find(params?: FindParams): Promise<FindResponse<M>> {
             const res = await sdk.find(params);
-            return { data: res.data.map((row) => rowToEntity<M>(row, slug)), meta: res.meta };
+            return { data: res.data.map((row) => rowToEntity<M>(row, slug, getPks())), meta: res.meta };
         },
         async findById(id: string | number): Promise<Entity<M> | undefined> {
             const row = await sdk.findById(id);
-            return row ? rowToEntity<M>(row, slug) : undefined;
+            return row ? rowToEntity<M>(row, slug, getPks()) : undefined;
         },
         async create(data: Partial<EntityValues<M>>, id?: string | number): Promise<Entity<M>> {
-            return rowToEntity<M>(await sdk.create(data as Partial<M>, id), slug);
+            return rowToEntity<M>(await sdk.create(data as Partial<M>, id), slug, getPks());
         },
         async update(id: string | number, data: Partial<EntityValues<M>>): Promise<Entity<M>> {
             const row = await sdk.update(id, data as Partial<M>);
             if (!row) throw new Error(`Update returned no data for id ${id}`);
-            return rowToEntity<M>(row, slug);
+            return rowToEntity<M>(row, slug, getPks());
         },
         delete(id: string | number): Promise<void> {
             return sdk.delete(id);
@@ -389,11 +483,11 @@ function toEntityAccessor<M extends Record<string, unknown>>(
         count: sdk.count ? (params?: FindParams) => sdk.count!(params) : undefined,
         listen: sdk.listen
             ? (params: FindParams | undefined, onUpdate: (r: FindResponse<M>) => void, onError?: (e: Error) => void) =>
-                sdk.listen!(params, (res) => onUpdate({ data: res.data.map((row) => rowToEntity<M>(row, slug)), meta: res.meta }), onError)
+                sdk.listen!(params, (res) => onUpdate({ data: res.data.map((row) => rowToEntity<M>(row, slug, getPks())), meta: res.meta }), onError)
             : undefined,
         listenById: sdk.listenById
             ? (id: string | number, onUpdate: (s: Entity<M> | undefined) => void, onError?: (e: Error) => void) =>
-                sdk.listenById!(id, (row) => onUpdate(row ? rowToEntity<M>(row, slug) : undefined), onError)
+                sdk.listenById!(id, (row) => onUpdate(row ? rowToEntity<M>(row, slug, getPks()) : undefined), onError)
             : undefined,
         where(columnOrCondition: string | LogicalCondition, operator?: WhereFilterOp, value?: unknown) {
             const builder = new QueryBuilder<M>(accessor);
@@ -420,13 +514,14 @@ function toEntityAccessor<M extends Record<string, unknown>>(
  * CMS `RebaseDataContext` — without it the admin renders rows with only their
  * `id`.
  */
-export function wrapAsEntityData(sdkData: RebaseSdkData): RebaseData {
+export function wrapAsEntityData(sdkData: RebaseSdkData, options?: EntityDataOptions): RebaseData {
     const cache = new Map<string, CollectionAccessor>();
+    const primaryKeysFor = createPrimaryKeyResolver(options);
 
     function getAccessor(slug: string): CollectionAccessor {
         let accessor = cache.get(slug);
         if (!accessor) {
-            accessor = toEntityAccessor(sdkData.collection(slug), slug);
+            accessor = toEntityAccessor(sdkData.collection(slug), slug, () => primaryKeysFor(slug));
             cache.set(slug, accessor);
         }
         return accessor;