@rebasepro/common 0.13.0 → 0.13.1-canary.g394d868

package/dist/util/builders.d.ts

@@ -3,7 +3,7 @@ import { FirebaseCollectionConfig, FirebaseProperties, InferEntityType, MongoDBC
  * Define a PostgreSQL-backed collection with full type inference.
  *
  * The `const P` generic captures literal property types from your
- * `properties` object, which enables autocomplete on `titleProperty`,
+ * `properties` object, which enables autocomplete on `display.title`,
  * `sort`, `propertiesOrder`, `fixedFilter`, and entity callbacks.
  *
  * @example
@@ -16,7 +16,7 @@ import { FirebaseCollectionConfig, FirebaseProperties, InferEntityType, MongoDBC
  *         name: { name: "Name", type: "string", validation: { required: true } },
  *         price: { name: "Price", type: "number" },
  *     },
- *     titleProperty: "name",  // ✅ autocomplete: "name" | "price"
+ *     display: { title: "name" },  // ✅ autocomplete: "name" | "price"
  *     sort: ["price", "asc"], // ✅ autocomplete on first element
  * });
  * ```

package/dist/util/conditions.d.ts

@@ -1,13 +1,17 @@
-import { AuthState, ConditionContext, JsonLogicRule } from "@rebasepro/types";
+import { AuthState, ConditionContext, ConditionRule } from "@rebasepro/types";
 /**
  * Register custom JSON Logic operations for Rebase.
  * Call this once at app initialization.
  */
 export declare function registerConditionOperations(): void;
 /**
- * Evaluate a JSON Logic rule against the given context.
+ * Evaluate a condition against the given context.
+ *
+ * A condition may be stated as a literal instead of a rule — `hidden: true`
+ * rather than `hidden: { "==": [1, 1] }` — and a literal is already its own
+ * answer, so it is returned rather than handed to the evaluator.
  */
-export declare function evaluateCondition(rule: JsonLogicRule, context: ConditionContext): unknown;
+export declare function evaluateCondition(rule: ConditionRule, context: ConditionContext): unknown;
 /**
  * Build a ConditionContext from the current property resolution context.
  */

package/dist/util/entities.d.ts

@@ -31,9 +31,16 @@ export declare function getRelationFrom<M extends Record<string, unknown>>(entit
  * have `id` and `path` fields — these are relation-shaped objects from
  * edge cases in the data pipeline (REST fallback, stale cache, custom data source).
  *
+ * When `targetPath` is given, also accepts a bare id. A relation column is a
+ * foreign key, and the REST layer returns it as the scalar it is; only some
+ * fetch paths hydrate it into an object. Which form a caller sees therefore
+ * depends on how the row was loaded, and a caller that only accepted objects
+ * reported half of its own data as a type error. The declared target is the
+ * missing half: with it, an id is a relation that has not been fetched yet.
+ *
  * Returns null if the value cannot be coerced.
  */
-export declare function normalizeToEntityRelation(value: unknown, propertyType?: string): EntityRelation | null;
+export declare function normalizeToEntityRelation(value: unknown, propertyType?: string, targetPath?: string): EntityRelation | null;
 export declare function traverseValuesProperties<M extends Record<string, unknown>>(inputValues: Partial<EntityValues<M>>, properties: Properties, operation: (value: unknown, property: Property) => unknown): EntityValues<M> | undefined;
 export declare function traverseValueProperty(inputValue: unknown, property: Property, operation: (value: unknown, property: Property) => unknown): unknown;
 /**

package/dist/util/relations.d.ts

@@ -1,4 +1,4 @@
-import { CollectionConfig, ResolvedRelation } from "@rebasepro/types";
+import { CollectionConfig, ResolvedRelation, RelationProperty } from "@rebasepro/types";
 /**
  * Whether the target rows are shared with other parents — a many-to-many, or a
  * multi-hop `via` chain.
@@ -27,6 +27,23 @@ export declare function isJunctionBackedRelation(relation: ResolvedRelation): bo
  * which is worth hearing about.
  */
 export declare function resolveCollectionRelations(collection: CollectionConfig): Record<string, ResolvedRelation>;
+/**
+ * The path of the collection a relation property points at, derived from the
+ * property alone.
+ *
+ * A preview holds a property and a value and no collection, so it cannot call
+ * `resolveRelationProperty`. It does not need to: both forms that carry a
+ * target — the stamped `resolvedRelation` and the inline `relation` — name it
+ * directly. Only the third form, a relation declared by name in the
+ * collection's `relations` array, is out of reach, and that one has no target
+ * to read without the collection anyway.
+ *
+ * This is what lets a preview render a relation column that arrived as a bare
+ * foreign key: the id says *which* row, the declared target says *which
+ * collection*, and `RelationPreview` fetches the rest. Without it a scalar id
+ * is indistinguishable from a value of the wrong type.
+ */
+export declare function getRelationTargetPath(property: RelationProperty): string | undefined;
 export declare function getTableName(collection: CollectionConfig): string;
 export declare function getTableVarName(tableName: string): string;
 export declare function getEnumVarName(tableName: string, propName: string): string;

package/dist/util/resolutions.d.ts

@@ -92,6 +92,37 @@ export declare function resolveEnumValues(input: EnumValues): EnumValueConfig[]
  *   3. many-relations on an engine that has relations (SQL).
  */
 export declare function getEntityChildViews<M extends Record<string, unknown> = Record<string, unknown>>(collection: CollectionConfig<M>): EntityChildView[];
+/**
+ * Each of `collection`'s tabs paired with the property that declared it, when a
+ * property declared it: child view key → property key.
+ *
+ * A many-relation can only be declared as a property — that is the documented
+ * and only mechanism — and {@link getEntityChildViews} promotes it to a tab. So
+ * one declaration reaches the panel twice, and neither surface knew about the
+ * other. The form rendered a relation picker beside the tab, and the collection
+ * table rendered *two* columns under one heading: the relation's own column,
+ * showing the child rows, and a jump-to-tab button carrying the same name.
+ *
+ * The pairing is what lets each surface decide which half is redundant, and it
+ * has to be a pairing rather than two sets because the two keys differ whenever
+ * a relation is named. The match is on the resolved `relationName` — the
+ * identity `getEntityChildViews` itself dedupes on — so a relation declared in
+ * `relations` and pointed at by a differently-named property is recognised too.
+ *
+ * A relation with no property of its own is absent here, which is the point: it
+ * has exactly one surface already, and nothing to weigh it against.
+ *
+ * Only top-level properties: a relation nested inside a `map` gets no tab.
+ */
+export declare function getChildViewDeclaringProperties<M extends Record<string, unknown> = Record<string, unknown>>(collection: CollectionConfig<M>): Map<string, string>;
+/**
+ * The property keys of `collection` whose relation is already one of its tabs.
+ *
+ * What a form asks: the tab is the treatment for a list of child rows, so the
+ * picker beside it is the redundant half. See
+ * {@link getChildViewDeclaringProperties}.
+ */
+export declare function getChildViewRelationPropertyKeys<M extends Record<string, unknown> = Record<string, unknown>>(collection: CollectionConfig<M>): Set<string>;
 /**
  * The child views of `collection` as bare collections.
  *

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@rebasepro/common",
   "type": "module",
-  "version": "0.13.0",
+  "version": "0.13.1-canary.g394d868",
   "description": "Awesome Firebase/Firestore-based headless open-source CMS",
   "funding": {
     "url": "https://github.com/sponsors/rebaseco"
@@ -40,8 +40,8 @@
   "dependencies": {
     "fast-equals": "6.0.2",
     "json-logic-js": "^2.0.5",
-    "@rebasepro/types": "0.13.0",
-    "@rebasepro/utils": "0.13.0"
+    "@rebasepro/types": "0.13.1-canary.g394d868",
+    "@rebasepro/utils": "0.13.1-canary.g394d868"
   },
   "devDependencies": {
     "@jest/globals": "^30.4.1",

package/src/data/buildRebaseData.ts

@@ -18,7 +18,7 @@ import {
 } from "@rebasepro/types";
 import { toSnakeCase } from "@rebasepro/utils";
 import { QueryBuilder } from "./query_builder";
-import { collectAllPages, paginateFind } from "./paginate";
+import { collectAllPages, paginateFind, resolveFindWindow } from "./paginate";
 import { deserializeFilter } from "./filter-dialect";
 import { buildCompositeId, resolvePrimaryKeys, PrimaryKeyInfo } from "../util/identity";
 
@@ -153,8 +153,7 @@ function createDriverAccessor<M extends Record<string, unknown> = Record<string,
         async find(params?: FindParams<M>): Promise<FindResponse<M>> {
             // Ensure filters are in canonical [op, value] format even if passed as PostgREST strings
             const filter = params?.where ? deserializeFilter(params.where as Record<string, unknown>) : undefined;
-            const limit = params?.limit ?? 20;
-            const offset = params?.offset ?? 0;
+            const { limit, offset, driverOffset } = resolveFindWindow(params);
 
             // One relation shape, whatever the call looks like.
             //
@@ -177,8 +176,12 @@ function createDriverAccessor<M extends Record<string, unknown> = Record<string,
                     slug,
                     {
                         filter,
-                        limit: params?.limit,
-                        offset: params?.offset,
+                        // Without this the group was dropped and the read ran
+                        // unfiltered — every row the caller's policies allow,
+                        // in place of the ones they asked for.
+                        logical: params?.logical,
+                        limit,
+                        offset: driverOffset,
                         orderBy: params?.orderBy?.[0],
                         order: params?.orderBy?.[1],
                         searchString: params?.searchString
@@ -187,9 +190,10 @@ function createDriverAccessor<M extends Record<string, unknown> = Record<string,
                 )
                 : await driver.fetchCollection<M>({
                     path: slug,
-                    limit: params?.limit,
-                    offset: params?.offset,
+                    limit,
+                    offset: driverOffset,
                     filter,
+                    logical: params?.logical,
                     orderBy: params?.orderBy?.[0],
                     order: params?.orderBy?.[1],
                     searchString: params?.searchString
@@ -199,7 +203,16 @@ function createDriverAccessor<M extends Record<string, unknown> = Record<string,
             let total = rows.length + offset;
             let hasMore = rows.length >= limit;
             if (driver.count) {
-                total = await driver.count({ path: slug, filter });
+                // The same narrowing the rows were read with. Counting only by
+                // `filter` reported the whole collection beside a narrowed
+                // page, and `hasMore` is derived from it — so the list offered
+                // a next page that did not exist.
+                total = await driver.count({
+                    path: slug,
+                    filter,
+                    logical: params?.logical,
+                    searchString: params?.searchString
+                });
                 hasMore = offset + rows.length < total;
             }
 
@@ -258,29 +271,56 @@ values: {} as Record<string, unknown> }
             });
         },
 
+        // Present only when the driver is: exposing these unconditionally and
+        // looping single writes underneath would give a caller neither the
+        // atomicity nor the single round trip they reached for a batch to get,
+        // while looking exactly like it had.
+        updateMany: driver.updateMany
+            ? async (updates: { id: string | number; data: Partial<EntityValues<M>> }[]): Promise<Entity<M>[]> => {
+                const rows = await driver.updateMany!<M>({
+                    path: slug,
+                    updates: updates.map(u => ({ id: u.id,
+values: u.data })),
+                });
+                return rows.map(row => rowToEntity<M>(row, slug, getPks()));
+            }
+            : undefined,
+
+        deleteMany: driver.deleteMany
+            ? async (ids: (string | number)[]): Promise<void> => {
+                await driver.deleteMany!<M>({ path: slug,
+ids });
+            }
+            : undefined,
+
         count: driver.count
             ? async (params?: FindParams<M>): Promise<number> => {
                 const filter = params?.where ? deserializeFilter(params.where as Record<string, unknown>) : undefined;
+                // Every narrowing `find()` applies has to apply here too, or
+                // the count describes a different query than the one it is
+                // reported against.
                 return driver.count!({
                     path: slug,
-                    filter
+                    filter,
+                    logical: params?.logical,
+                    searchString: params?.searchString
                 });
             }
             : undefined,
 
         listen: driver.listenCollection
             ? (params: FindParams<M> | undefined, onUpdate: (response: FindResponse<M>) => void, onError?: (error: Error) => void) => {
-                const limit = params?.limit ?? 20;
-                const offset = params?.offset ?? 0;
+                const { limit, offset, driverOffset } = resolveFindWindow(params);
                 // Realtime has no REST-pipeline equivalent, so the rows arrive
                 // admin-shaped. Flatten them to the one shape the rest of this
                 // accessor serves.
                 const normalize = driver.restFetchService ? inlineRelationRefs : (row: Record<string, unknown>) => row;
                 return driver.listenCollection!<M>({
                     path: slug,
-                    limit: params?.limit,
-                    offset: params?.offset,
+                    limit,
+                    offset: driverOffset,
                     filter: params?.where,
+                    logical: params?.logical,
                     orderBy: params?.orderBy?.[0],
                     order: params?.orderBy?.[1],
                     searchString: params?.searchString,
@@ -288,7 +328,12 @@ values: {} as Record<string, unknown> }
                         onUpdate({
                             data: entities.map((row: Record<string, unknown>) => rowToEntity<M>(normalize(row), slug, getPks())),
                             meta: {
-                                total: entities.length,
+                                // No count is issued on this path, so the total
+                                // is unknown; the lower bound is the rows in
+                                // hand plus the ones paged past to reach them.
+                                // Reporting `entities.length` claimed a read at
+                                // offset 100 had found a collection of two.
+                                total: offset + entities.length,
                                 limit,
                                 offset,
                                 hasMore: entities.length >= limit
@@ -506,9 +551,39 @@ function toSdkCollectionClient<M extends Record<string, unknown>>(
         async update(id: string | number, data: Partial<M>): Promise<M> {
             return entityToRow(await snap.update(id, data as Partial<EntityValues<M>>));
         },
+        async updateMany(updates: { id: string | number; data: Partial<M> }[]): Promise<M[]> {
+            if (!Array.isArray(updates)) {
+                throw new TypeError("updateMany expects an array of { id, data } entries.");
+            }
+            if (updates.length === 0) return [];
+            if (!snap.updateMany) {
+                throw new Error(
+                    "Bulk updates are not supported by this collection's data source. " +
+                    "Fall back to update() per record."
+                );
+            }
+            const rows = await snap.updateMany(
+                updates.map(u => ({ id: u.id,
+data: u.data as Partial<EntityValues<M>> }))
+            );
+            return rows.map(entityToRow);
+        },
         delete(id: string | number): Promise<void> {
             return snap.delete(id);
         },
+        async deleteMany(ids: (string | number)[]): Promise<void> {
+            if (!Array.isArray(ids)) {
+                throw new TypeError("deleteMany expects an array of ids.");
+            }
+            if (ids.length === 0) return;
+            if (!snap.deleteMany) {
+                throw new Error(
+                    "Bulk deletes are not supported by this collection's data source. " +
+                    "Fall back to delete() per record."
+                );
+            }
+            await snap.deleteMany(ids);
+        },
         count: snap.count ? (params?: FindParams<M>) => snap.count!(params) : undefined,
         listen: snap.listen
             ? (params: FindParams<M> | undefined, onUpdate: (r: FindResult<M>) => void, onError?: (e: Error) => void) =>
@@ -537,7 +612,7 @@ function toSdkCollectionClient<M extends Record<string, unknown>>(
 /**
  * Wrap a flat {@link SDKCollectionClient} into a Entity-shaped
  * {@link CollectionAccessor}. Every returned row is re-wrapped into the
- * `{ id, path, values }` view-model the admin admin renders.
+ * `{ id, path, values }` view-model the admin panel renders.
  */
 function toEntityAccessor<M extends Record<string, unknown>>(
     sdk: SDKCollectionClient<M>,

package/src/data/filter-dialect.ts

@@ -354,9 +354,34 @@ export function serializeLogicalCondition(
  * deserializeLogicalCondition("or(status.eq.active,age.gte.18)")
  * // → { type: "or", conditions: [...] }
  */
+/**
+ * How deeply `or(...)`/`and(...)` groups may nest.
+ *
+ * This parser recurses once per level, on a value that arrives in a query
+ * string. Unbounded, twenty thousand levels reached `RangeError: Maximum call
+ * stack size exceeded`, which a caller sees as a 500 about the call stack
+ * rather than a 400 about their filter. Node's 16 KB header cap keeps a GET
+ * below that in practice, but "the HTTP layer happens to stop it" is not a
+ * bound this parser should rely on.
+ *
+ * Thirty-two is far past anything a real filter expresses; the deepest in this
+ * repository's own tests is three.
+ */
+export const MAX_LOGICAL_NESTING_DEPTH = 32;
+
 export function deserializeLogicalCondition(
-    str: string
+    str: string,
+    // Not `depth`: the body already uses that name for paren tracking, inside a
+    // block that shadows a parameter of the same name — so the recursion
+    // counter silently became the paren counter and never grew.
+    nesting = 0
 ): LogicalCondition | FilterCondition {
+    if (nesting > MAX_LOGICAL_NESTING_DEPTH) {
+        throw new Error(
+            `Filter groups nest more than ${MAX_LOGICAL_NESTING_DEPTH} levels deep. ` +
+            "Flatten the condition — `or(a,or(b,c))` is `or(a,b,c)`."
+        );
+    }
     // Check for logical group: "and(...)" or "or(...)"
     const logicalMatch = str.match(/^(and|or)\((.+)\)$/);
     if (logicalMatch) {
@@ -371,11 +396,11 @@ export function deserializeLogicalCondition(
             if (innerStr[i] === "(") depth++;
             else if (innerStr[i] === ")") depth--;
             else if (innerStr[i] === "," && depth === 0) {
-                conditions.push(deserializeLogicalCondition(innerStr.slice(start, i)));
+                conditions.push(deserializeLogicalCondition(innerStr.slice(start, i), nesting + 1));
                 start = i + 1;
             }
         }
-        conditions.push(deserializeLogicalCondition(innerStr.slice(start)));
+        conditions.push(deserializeLogicalCondition(innerStr.slice(start), nesting + 1));
 
         return { type, conditions };
     }

package/src/data/paginate.ts

@@ -1,4 +1,5 @@
 import {
+    DEFAULT_LIST_LIMIT,
     FilterValues,
     FieldPath,
     FindAllParams,
@@ -70,6 +71,35 @@ export class RebasePaginationError extends Error {
 export type PageFinder<M extends Record<string, unknown> = Record<string, unknown>> =
     (params: FindParams<M>) => Promise<FindResult<M>>;
 
+/**
+ * Resolve `limit`/`offset`/`page` into the window a read will actually use.
+ *
+ * Lives here, next to the walk, for the reason at the top of this file: every
+ * transport has to mean the same thing by "page two". Four of them did not —
+ * the REST layer strode by {@link DEFAULT_LIST_LIMIT}, the local-first
+ * evaluator by {@link DEFAULT_PAGE_SIZE}, the in-process accessor by 20, and
+ * the published type documented a fourth number. Pages that overlap or skip
+ * rows are the mildest of those outcomes.
+ *
+ * `page` wins over `offset`, as {@link FindParams} documents. `driverOffset`
+ * is the value to hand a driver: it stays `undefined` when the caller named no
+ * offset, because keyset pagination seeks with a `where` clause and must not
+ * look like it is paging by offset.
+ */
+export function resolveFindWindow(
+    params?: Pick<FindParams, "limit" | "offset" | "page">
+): { limit: number; offset: number; driverOffset: number | undefined } {
+    const limit = params?.limit ?? DEFAULT_LIST_LIMIT;
+    const offset = params?.page != null
+        ? Math.max(0, (params.page - 1) * limit)
+        : (params?.offset ?? 0);
+    return {
+        limit,
+        offset,
+        driverOffset: params?.page != null ? offset : params?.offset
+    };
+}
+
 function normalizePageSize(raw: number | undefined): number {
     if (raw === undefined || !Number.isFinite(raw)) return DEFAULT_PAGE_SIZE;
     return Math.max(1, Math.floor(raw));

package/src/data/resolveDataSource.ts

@@ -77,3 +77,59 @@ export function resolveDataSource(
         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.
+ */
+export function isRelationalCollection(
+    collection: DataSourceResolvable | undefined,
+    registry?: DataSourceRegistry
+): boolean {
+    // The collection's own `engine` wins over a registered definition's. That
+    // is the opposite of {@link resolveDataSource}'s precedence, deliberately:
+    // there a definition describes where the data *goes*, so it should override;
+    // here the question is what the author said this collection is, and a
+    // collection declaring `engine: "firestore"` with no `dataSource` must not
+    // come back as the default source's engine and be handed a table.
+    const engine = collection?.engine
+        ?? (collection?.dataSource ? resolveDataSource(collection, registry).engine : undefined);
+    return getDataSourceCapabilities(engine).supportsRelations;
+}
+
+/**
+ * The subset of `collections` a SQL toolchain owns — see
+ * {@link isRelationalCollection}.
+ *
+ * Every stage that generates SQL from collections starts by calling this, so
+ * the rule lives in one place rather than being re-decided per generator. It
+ * keeps the input order.
+ */
+export function relationalCollections<C extends DataSourceResolvable>(
+    collections: readonly C[],
+    registry?: DataSourceRegistry
+): C[] {
+    return collections.filter(collection => isRelationalCollection(collection, registry));
+}

package/src/util/builders.ts

@@ -14,14 +14,14 @@ import {
 // ── defineCollection ─────────────────────────────────────────────────────
 // A smarter builder that uses `const` type-parameter inference (TS 5.0+)
 // to capture literal property types automatically. This gives you
-// autocomplete on `titleProperty`, `sort`, `propertiesOrder`, `fixedFilter`,
+// autocomplete on `display.title`, `sort`, `propertiesOrder`, `fixedFilter`,
 // callbacks, etc. — without writing `as const` or passing manual generics.
 
 /**
  * Define a PostgreSQL-backed collection with full type inference.
  *
  * The `const P` generic captures literal property types from your
- * `properties` object, which enables autocomplete on `titleProperty`,
+ * `properties` object, which enables autocomplete on `display.title`,
  * `sort`, `propertiesOrder`, `fixedFilter`, and entity callbacks.
  *
  * @example
@@ -34,7 +34,7 @@ import {
  *         name: { name: "Name", type: "string", validation: { required: true } },
  *         price: { name: "Price", type: "number" },
  *     },
- *     titleProperty: "name",  // ✅ autocomplete: "name" | "price"
+ *     display: { title: "name" },  // ✅ autocomplete: "name" | "price"
  *     sort: ["price", "asc"], // ✅ autocomplete on first element
  * });
  * ```

package/src/util/conditions.ts

@@ -3,8 +3,8 @@ import {
     ArrayProperty,
     AuthState,
     ConditionContext,
+    ConditionRule,
     EnumValueConfig,
-    JsonLogicRule,
     NumberProperty,
     PropertyConditions,
     Property,
@@ -66,9 +66,14 @@ export function registerConditionOperations(): void {
 }
 
 /**
- * Evaluate a JSON Logic rule against the given context.
+ * Evaluate a condition against the given context.
+ *
+ * A condition may be stated as a literal instead of a rule — `hidden: true`
+ * rather than `hidden: { "==": [1, 1] }` — and a literal is already its own
+ * answer, so it is returned rather than handed to the evaluator.
  */
-export function evaluateCondition(rule: JsonLogicRule, context: ConditionContext): unknown {
+export function evaluateCondition(rule: ConditionRule, context: ConditionContext): unknown {
+    if (typeof rule === "boolean") return rule;
     // Ensure operations are registered
     registerConditionOperations();
     return jsonLogic.apply(rule, context);

package/src/util/entities.ts

@@ -143,10 +143,24 @@ export function getRelationFrom<M extends Record<string, unknown>>(entity: Entit
  * have `id` and `path` fields — these are relation-shaped objects from
  * edge cases in the data pipeline (REST fallback, stale cache, custom data source).
  *
+ * When `targetPath` is given, also accepts a bare id. A relation column is a
+ * foreign key, and the REST layer returns it as the scalar it is; only some
+ * fetch paths hydrate it into an object. Which form a caller sees therefore
+ * depends on how the row was loaded, and a caller that only accepted objects
+ * reported half of its own data as a type error. The declared target is the
+ * missing half: with it, an id is a relation that has not been fetched yet.
+ *
  * Returns null if the value cannot be coerced.
  */
-export function normalizeToEntityRelation(value: unknown, propertyType?: string): EntityRelation | null {
+export function normalizeToEntityRelation(value: unknown, propertyType?: string, targetPath?: string): EntityRelation | null {
     if (value instanceof EntityRelation) return value;
+
+    if (targetPath && (typeof value === "string" || typeof value === "number")) {
+        // An empty string is an unset foreign key, not row "".
+        if (value === "") return null;
+        return new EntityRelation(value, targetPath);
+    }
+
     if (!value || typeof value !== "object" || Array.isArray(value)) return null;
 
     const obj = value as Record<string, unknown>;

package/src/util/relations.ts

@@ -66,6 +66,37 @@ export function resolveCollectionRelations(
     return relations;
 }
 
+/**
+ * The path of the collection a relation property points at, derived from the
+ * property alone.
+ *
+ * A preview holds a property and a value and no collection, so it cannot call
+ * `resolveRelationProperty`. It does not need to: both forms that carry a
+ * target — the stamped `resolvedRelation` and the inline `relation` — name it
+ * directly. Only the third form, a relation declared by name in the
+ * collection's `relations` array, is out of reach, and that one has no target
+ * to read without the collection anyway.
+ *
+ * This is what lets a preview render a relation column that arrived as a bare
+ * foreign key: the id says *which* row, the declared target says *which
+ * collection*, and `RelationPreview` fetches the rest. Without it a scalar id
+ * is indistinguishable from a value of the wrong type.
+ */
+export function getRelationTargetPath(property: RelationProperty): string | undefined {
+    const stamped = property.resolvedRelation?.targetSlug;
+    if (stamped) return stamped;
+
+    const target = property.relation?.target;
+    if (typeof target !== "function") return undefined;
+    try {
+        return target()?.slug;
+    } catch (_e) {
+        // A thunk reaching into a module that has not finished initialising:
+        // there is no target to name yet, and a preview is not worth throwing over.
+        return undefined;
+    }
+}
+
 export function getTableName(collection: CollectionConfig): string {
     if (isRelationalCollectionConfig(collection)) {
         return collection.table ?? toSnakeCase(collection.slug) ?? toSnakeCase(collection.name);