@rebasepro/types 0.7.0 → 0.9.0

package/src/types/collections.ts

@@ -1,27 +1,29 @@
 import React, { Dispatch, SetStateAction } from "react";
 import type { Entity, EntityStatus, EntityValues } from "./entities";
-import type { EntityCallbacks } from "./entity_callbacks";
+import type { CollectionCallbacks } from "./entity_callbacks";
 
-import type { EnumValues, Properties } from "./properties";
+import type { EnumValues, Properties, PostgresProperties, FirebaseProperties, MongoProperties } from "./properties";
 import type { ExportConfig } from "./export_import";
-import type { EntityOverrides } from "./entity_overrides";
+
 import type { User } from "../users";
 import type { RebaseContext } from "../rebase_context";
 import type { Relation } from "./relations";
 import type { EntityCustomView, FormViewConfig } from "./entity_views";
 import type { EntityAction } from "./entity_actions";
+import type { PolicyExpression } from "./policy";
 import type { ComponentRef } from "./component_ref";
 import type { CollectionComponentOverrideMap } from "./component_overrides";
+import type { WhereFilterOp, FilterValues, FilterPreset, OrderByTuple } from "./filter-operators";
 
 /**
  * Base interface containing all driver-agnostic collection properties.
- * Use {@link PostgresCollection} or {@link FirebaseCollection} for
- * driver-specific type safety, or {@link EntityCollection} when you
+ * Use {@link PostgresCollectionConfig} or {@link FirebaseCollectionConfig} for
+ * driver-specific type safety, or {@link CollectionConfig} when you
  * need to handle any collection regardless of backend.
  *
  * @group Models
  */
-export interface BaseEntityCollection<M extends Record<string, unknown> = Record<string, unknown>, USER extends User = User> {
+export interface BaseCollectionConfig<M extends Record<string, unknown> = Record<string, unknown>, USER extends User = User> {
 
     /**
      * You can set an alias that will be used internally instead of the collection name.
@@ -54,14 +56,14 @@ export interface BaseEntityCollection<M extends Record<string, unknown> = Record
      *
      * Custom drivers can set this directly to expose child collections to the UI.
      */
-    childCollections?: () => EntityCollection<Record<string, unknown>>[];
+    childCollections?: () => CollectionConfig<Record<string, unknown>>[];
 
 
     /**
      * The data source this collection belongs to — the routing key shared by
      * the frontend router and the backend driver registry. It points at a
      * {@link DataSourceDefinition} registered on `<Rebase dataSources>` (front)
-     * and `initRebase({ dataSources })` (back).
+     * and `initializeRebaseBackend({ dataSources })` (back).
      *
      * If not specified, the default data source `"(default)"` is used, which
      * for a standard Rebase app is the server-mediated Postgres backend.
@@ -76,17 +78,18 @@ export interface BaseEntityCollection<M extends Record<string, unknown> = Record
     dataSource?: string;
 
     /**
-     * The engine backing this collection (`"postgres"`, `"firestore"`,
-     * `"mongodb"`, or a custom id). Drives editor capabilities (relations vs
-     * subcollections, RLS, column types).
+     * The database engine backing this collection (`"postgres"`, `"firestore"`,
+     * `"mongodb"`, or a custom id).
      *
-     * @deprecated Prefer {@link dataSource} for routing. `driver` is retained
-     * as an engine hint and for backward compatibility: when `dataSource` is
-     * omitted it also acts as the data-source key.
+     * On concrete collection types ({@link PostgresCollectionConfig},
+     * {@link FirebaseCollectionConfig}, {@link MongoDBCollectionConfig}) this is a literal
+     * discriminant. On the base type it is optional and gets stamped
+     * automatically during collection normalization from the registered
+     * {@link DataSourceDefinition}.
      *
-     * If not specified, `"postgres"` is assumed.
+     * Prefer setting {@link dataSource} and letting the engine be resolved.
      */
-    driver?: string;
+    engine?: string;
 
     /**
      * Which database within the engine.
@@ -100,7 +103,7 @@ export interface BaseEntityCollection<M extends Record<string, unknown> = Record
     databaseId?: string;
 
     /**
-     * Set of properties that compose an entity
+     * Set of properties that compose a entity
      */
     properties: Properties;
 
@@ -142,13 +145,13 @@ export interface BaseEntityCollection<M extends Record<string, unknown> = Record
     readonly titleProperty?: Extract<keyof M, string> | (string & {});
 
     /**
-     * When editing an entity, you can choose to open the entity in a side dialog
+     * When editing a entity, you can choose to open the entity in a side dialog
      * or in a full screen dialog. Defaults to `full_screen`.
      */
     openEntityMode?: "side_panel" | "full_screen" | "split" | "dialog";
 
     /**
-     * Controls what happens when a user clicks on an entity in the collection view.
+     * Controls what happens when a user clicks on a entity in the collection view.
      * - `"edit"` (default): Opens the entity in the edit form.
      * - `"view"`: Opens a read-only detail view with an "Edit" button.
      */
@@ -201,19 +204,18 @@ export interface BaseEntityCollection<M extends Record<string, unknown> = Record
      * If you are specifying your collection as code, the order is the same as the
      * one you define in `properties`. Additional columns are added at the
      * end of the list, if the order is not specified.
+     *
      * You can use this prop to hide some properties from the table view.
      * Note that if you set this prop, other ways to hide fields, like
      * `hidden` in the property definition, will be ignored.
      * `propertiesOrder` has precedence over `hidden`.
-     *     - For properties use the property key.
-     *     - For additional fields use the field key.
-     *     - If you have subcollections, you get a column for each subcollection,
-     *       with the path (or alias) as the subcollection, prefixed with
-     *       `subcollection:`. e.g. `subcollection:orders`.
-     * You can use this prop to hide some properties from the table view.
-     * Note that if you set this prop, other ways to hide fields, like
-     * `hidden` in the property definition,will be ignored.
-     * `propertiesOrder` has precedence over `hidden`.
+     *
+     * Supported entry formats:
+     *     - For properties, use the property key.
+     *     - For additional fields, use the field key.
+     *     - Child collections (Firestore subcollections, or Postgres relations
+     *       with `many` cardinality) each get a column with id
+     *       `subcollection:<slug>`, e.g. `subcollection:orders`.
      */
     propertiesOrder?: (Extract<keyof M, string> | (string & {}) | string | `subcollection:${string}`)[];
 
@@ -230,11 +232,11 @@ export interface BaseEntityCollection<M extends Record<string, unknown> = Record
     selectionEnabled?: boolean;
 
     /**
-     * This interface defines all the callbacks that can be used when an entity
+     * This interface defines all the callbacks that can be used when a entity
      * is being created, updated or deleted.
      * Useful for adding your own logic or blocking the execution of the operation.
      */
-    readonly callbacks?: EntityCallbacks<M, USER>;
+    readonly callbacks?: CollectionCallbacks<M, USER>;
 
     /**
      * Pass your own selection controller if you want to control selected
@@ -284,7 +286,7 @@ export interface BaseEntityCollection<M extends Record<string, unknown> = Record
      * applied in the collection.
      * e.g. `sort: ["order", "asc"]`
      */
-    readonly sort?: [Extract<keyof M, string> | (string & {}), "asc" | "desc"];
+    readonly sort?: OrderByTuple<Extract<keyof M, string> | (string & {})>;
 
     /**
      * You can add additional fields to the collection view by implementing
@@ -299,8 +301,8 @@ export interface BaseEntityCollection<M extends Record<string, unknown> = Record
 
     /**
      * Can the elements in this collection be edited inline in the collection
-     * view. If this flag is set to false but `permissions.edit` is `true`, entities
-     * can still be edited in the side panel
+     * view. Even when inline editing is disabled, entities can still be
+     * edited in the side panel (subject to `securityRules`).
      */
     inlineEditing?: boolean;
 
@@ -315,7 +317,7 @@ export interface BaseEntityCollection<M extends Record<string, unknown> = Record
 
     /**
      * If you want to open custom views or subcollections by default when opening the edit
-     * view of an entity, you can specify the path to the view here.
+     * view of a entity, you can specify the path to the view here.
      * The path is relative to the current collection. For example if you have a collection
      * that has a custom view as well as a subcollection that refers to another entity, you can
      * either specify the path to the custom view or the path to the subcollection.
@@ -359,12 +361,7 @@ export interface BaseEntityCollection<M extends Record<string, unknown> = Record
     metadata?: Record<string, unknown>;
 
     /**
-     * Overrides for the entity view, like the data source or the storage source.
-     */
-    overrides?: EntityOverrides;
-
-    /**
-     * Width of the side dialog (in pixels) when opening an entity in this collection.
+     * Width of the side dialog (in pixels) when opening a entity in this collection.
      */
     sideDialogWidth?: number | string;
 
@@ -389,9 +386,9 @@ export interface BaseEntityCollection<M extends Record<string, unknown> = Record
     /**
      * Should local changes be backed up in local storage, to prevent data loss on
      * accidental navigations.
-     * - `manual_apply`: When the user navigates back to an entity with local changes,
+     * - `manual_apply`: When the user navigates back to a entity with local changes,
      *   they will be prompted to restore the changes.
-     * - `auto_apply`: When the user navigates back to an entity with local changes,
+     * - `auto_apply`: When the user navigates back to a entity with local changes,
      *   the changes will be automatically applied.
      * - `false`: Local changes will not be backed up.
      * Defaults to `manual_apply`.
@@ -460,7 +457,7 @@ export interface BaseEntityCollection<M extends Record<string, unknown> = Record
      * Security rules for this collection (Row Level Security).
      * When defined, the backend enforces access control policies.
      */
-    securityRules?: SecurityRule[];
+    securityRules?: readonly SecurityRule[];
 
     /**
      * Collection-scoped component overrides. These take precedence over
@@ -473,7 +470,7 @@ export interface BaseEntityCollection<M extends Record<string, unknown> = Record
      *
      * @example
      * ```tsx
-     * const productsCollection: PostgresCollection = {
+     * const productsCollection: PostgresCollectionConfig = {
      *     name: "Products",
      *     slug: "products",
      *     table: "products",
@@ -494,20 +491,20 @@ export interface BaseEntityCollection<M extends Record<string, unknown> = Record
  * A collection backed by PostgreSQL (or any SQL database).
  * Adds support for SQL-style relations (JOINs) and Row Level Security.
  *
- * Use this type instead of {@link EntityCollection} when you want
+ * Use this type instead of {@link CollectionConfig} when you want
  * compile-time safety that only SQL-relevant fields appear.
  *
  * @group Models
  */
-export interface PostgresCollection<M extends Record<string, unknown> = Record<string, unknown>, USER extends User = User>
-    extends BaseEntityCollection<M, USER> {
-    properties: Properties;
+export interface PostgresCollectionConfig<M extends Record<string, unknown> = Record<string, unknown>, USER extends User = User>
+    extends BaseCollectionConfig<M, USER> {
+    properties: PostgresProperties;
 
     /**
-     * The driver for this collection. For Postgres collections this
+     * The database engine for this collection. For Postgres collections this
      * can be omitted (Postgres is the default) or set to `"postgres"`.
      */
-    driver?: "postgres" | undefined;
+    engine?: "postgres" | undefined;
 
     /**
      * The PostgreSQL table name for this collection.
@@ -528,7 +525,7 @@ export interface PostgresCollection<M extends Record<string, unknown> = Record<s
     relations?: Relation[];
 
     /**
-     * Security rules for this collection (Supabase-style Row Level Security).
+     * Security rules for this collection (PostgreSQL Row Level Security).
      * When defined, the schema generator will enable RLS on the table and
      * create the corresponding PostgreSQL policies.
      *
@@ -542,110 +539,173 @@ export interface PostgresCollection<M extends Record<string, unknown> = Record<s
      * - `auth.roles()` — comma-separated app role IDs
      * - `auth.jwt()`   — full JWT claims as JSONB
      */
-    securityRules?: SecurityRule[];
+    securityRules?: readonly SecurityRule[];
 }
 
 /**
  * A collection backed by Firebase / Firestore.
  * Adds support for subcollections (nested document collections).
  *
- * Use this type instead of {@link EntityCollection} when you want
+ * Use this type instead of {@link CollectionConfig} when you want
  * compile-time safety that only Firestore-relevant fields appear.
  *
  * @group Models
  */
-export interface FirebaseCollection<M extends Record<string, unknown> = Record<string, unknown>, USER extends User = User>
-    extends BaseEntityCollection<M, USER> {
+export interface FirebaseCollectionConfig<M extends Record<string, unknown> = Record<string, unknown>, USER extends User = User>
+    extends BaseCollectionConfig<M, USER> {
+    /**
+     * The database engine for this collection. Must be set to `"firestore"`.
+     */
+    engine: "firestore";
+
+    /**
+     * Set of properties that compose a entity.
+     * Firestore collections support `reference` properties but not `relation`.
+     */
+    properties: FirebaseProperties;
+
     /**
-     * The driver for this collection. Must be set to `"firestore"`.
+     * The Firestore collection path to query. Defaults to `slug` if not set.
+     * Use this when the Firestore path differs from the slug
+     * (e.g., when a PostgreSQL collection already uses the same slug).
+     *
+     * @example
+     * ```typescript
+     * const fsCustomer: FirebaseCollectionConfig = {
+     *     slug: "fs_customer",        // URL: /c/fs_customer
+     *     path: "customer",           // Firestore path: customer
+     *     name: "Customers (Firestore)",
+     *     engine: "firestore",
+     *     properties: { ... }
+     * };
+     * ```
      */
-    driver: "firestore";
+    path?: string;
 
     /**
      * You can add subcollections to your entity in the same way you define the root
      * collections. The collections added here will be displayed when opening
-     * the side dialog of an entity.
+     * the side dialog of a entity.
      */
-    subcollections?: () => EntityCollection<Record<string, unknown>>[];
+    subcollections?: () => CollectionConfig<Record<string, unknown>>[];
 }
 
 /**
  * A collection backed by MongoDB.
  *
- * Use this type instead of {@link EntityCollection} when you want
+ * Use this type instead of {@link CollectionConfig} when you want
  * compile-time safety that only MongoDB-relevant fields appear.
  *
  * @group Models
  */
-export interface MongoDBCollection<M extends Record<string, unknown> = Record<string, unknown>, USER extends User = User>
-    extends BaseEntityCollection<M, USER> {
+export interface MongoDBCollectionConfig<M extends Record<string, unknown> = Record<string, unknown>, USER extends User = User>
+    extends BaseCollectionConfig<M, USER> {
+
+    /**
+     * The database engine for this collection. Must be set to `"mongodb"`.
+     */
+    engine: "mongodb";
 
     /**
-     * The driver for this collection. Must be set to `"mongodb"`.
+     * Set of properties that compose a entity.
+     * MongoDB collections support `reference` properties but not `relation`.
      */
-    driver: "mongodb";
+    properties: MongoProperties;
+
+    /**
+     * The MongoDB collection name to use. Defaults to `slug` if not set.
+     * Use this when the MongoDB collection name differs from the slug
+     * (e.g., when a PostgreSQL collection already uses the same slug).
+     *
+     * @example
+     * ```typescript
+     * const mongoCustomer: MongoDBCollectionConfig = {
+     *     slug: "mongo_customer",      // URL: /c/mongo_customer
+     *     path: "customer",            // MongoDB collection: customer
+     *     name: "Customers (MongoDB)",
+     *     engine: "mongodb",
+     *     properties: { ... }
+     * };
+     * ```
+     */
+    path?: string;
 }
 
 /**
  * A collection backed by any data source.
- * This is a discriminated union — use {@link PostgresCollection},
- * {@link FirebaseCollection}, or {@link MongoDBCollection} for
+ * This is a discriminated union — use {@link PostgresCollectionConfig},
+ * {@link FirebaseCollectionConfig}, or {@link MongoDBCollectionConfig} for
  * driver-specific type safety.
  *
  * @group Models
  */
-export type EntityCollection<M extends Record<string, unknown> = Record<string, unknown>, USER extends User = User> =
-    | PostgresCollection<M, USER>
-    | FirebaseCollection<M, USER>
-    | MongoDBCollection<M, USER>;
-
-// ── Capability intersection types ─────────────────────────────────────
-// Use these after a `getDataSourceCapabilities()` guard to safely access
-// driver-specific fields without coupling to a concrete driver type.
-
-/**
- * An EntityCollection that supports SQL-style relations (e.g. Postgres).
- * @deprecated Use `EntityCollection` directly — `table`, `relations`, and `securityRules` are now on `BaseEntityCollection`.
- */
-export type CollectionWithRelations<M extends Record<string, unknown> = Record<string, unknown>> =
-    EntityCollection<M> & { table?: string; relations?: Relation[]; securityRules?: SecurityRule[] };
-
-/** An EntityCollection that supports subcollections (e.g. Firestore). */
-export type CollectionWithSubcollections<M extends Record<string, unknown> = Record<string, unknown>> =
-    EntityCollection<M> & { subcollections?: () => EntityCollection<Record<string, unknown>>[] };
-
-
-// ── Type guards ───────────────────────────────────────────────────────
+export type CollectionConfig<M extends Record<string, unknown> = Record<string, unknown>, USER extends User = User> =
+    | PostgresCollectionConfig<M, USER>
+    | FirebaseCollectionConfig<M, USER>
+    | MongoDBCollectionConfig<M, USER>;
 
 /**
  * Type guard for PostgreSQL collections.
- * Returns true if the collection uses the Postgres driver (or the default driver).
+ * Returns true if the collection uses the Postgres engine (or the default engine).
  * @group Models
  */
-export function isPostgresCollection<M extends Record<string, unknown> = Record<string, unknown>, USER extends User = User>(
-    collection: EntityCollection<M, USER>
-): collection is PostgresCollection<M, USER> {
-    return !collection.driver || collection.driver === "postgres";
+export function isPostgresCollectionConfig<M extends Record<string, unknown> = Record<string, unknown>, USER extends User = User>(
+    collection: CollectionConfig<M, USER>
+): collection is PostgresCollectionConfig<M, USER> {
+    return !collection.engine || collection.engine === "postgres";
 }
 
 /**
  * Type guard for Firebase / Firestore collections.
  * @group Models
  */
-export function isFirebaseCollection<M extends Record<string, unknown> = Record<string, unknown>, USER extends User = User>(
-    collection: EntityCollection<M, USER>
-): collection is FirebaseCollection<M, USER> {
-    return collection.driver === "firestore";
+export function isFirebaseCollectionConfig<M extends Record<string, unknown> = Record<string, unknown>, USER extends User = User>(
+    collection: CollectionConfig<M, USER>
+): collection is FirebaseCollectionConfig<M, USER> {
+    return collection.engine === "firestore";
 }
 
 /**
  * Type guard for MongoDB collections.
  * @group Models
  */
-export function isMongoDBCollection<M extends Record<string, unknown> = Record<string, unknown>, USER extends User = User>(
-    collection: EntityCollection<M, USER>
-): collection is MongoDBCollection<M, USER> {
-    return collection.driver === "mongodb";
+export function isMongoDBCollectionConfig<M extends Record<string, unknown> = Record<string, unknown>, USER extends User = User>(
+    collection: CollectionConfig<M, USER>
+): collection is MongoDBCollectionConfig<M, USER> {
+    return collection.engine === "mongodb";
+}
+
+/**
+ * Returns the data path for a collection.
+ * For Firestore or MongoDB collections with a `path`, returns that value;
+ * otherwise falls back to `slug`.
+ */
+export function getCollectionDataPath<M extends Record<string, unknown> = Record<string, unknown>, USER extends User = User>(
+    collection: CollectionConfig<M, USER>
+): string {
+    if (isFirebaseCollectionConfig(collection) && collection.path) {
+        return collection.path;
+    }
+    if (isMongoDBCollectionConfig(collection) && collection.path) {
+        return collection.path;
+    }
+    return collection.slug;
+}
+
+/**
+ * Reads a collection's driver-declared subcollections thunk (the `subcollections`
+ * field) independent of engine identity, so engine-agnostic code doesn't have to
+ * type-guard against a specific driver. Returns `undefined` when the collection
+ * declares none.
+ *
+ * Pair with `getDataSourceCapabilities(engine).supportsSubcollections` to decide
+ * whether the engine honours subcollections at all before reading them.
+ * @group Models
+ */
+export function getDeclaredSubcollections<M extends Record<string, unknown> = Record<string, unknown>, USER extends User = User>(
+    collection: CollectionConfig<M, USER>
+): (() => CollectionConfig<Record<string, unknown>>[]) | undefined {
+    return (collection as FirebaseCollectionConfig<M, USER>).subcollections;
 }
 
 
@@ -680,7 +740,7 @@ export type ViewMode = "list" | "table" | "cards" | "kanban";
  *
  * @group Models
  */
-export interface CollectionActionsProps<M extends Record<string, unknown> = Record<string, unknown>, USER extends User = User, EC extends EntityCollection<M> = EntityCollection<M>> {
+export interface CollectionActionsProps<M extends Record<string, unknown> = Record<string, unknown>, USER extends User = User, EC extends CollectionConfig<M> = CollectionConfig<M>> {
     /**
      * Full collection path of this entity. This is the full path, like
      * `users/1234/addresses`
@@ -746,7 +806,7 @@ export interface CollectionActionsProps<M extends Record<string, unknown> = Reco
 
 /**
  * Use this controller to retrieve the selected entities or modify them in
- * an {@link EntityCollection}
+ * an {@link CollectionConfig}
  * @group Models
  */
 export interface SelectionController<M extends Record<string, unknown> = Record<string, unknown>> {
@@ -757,57 +817,8 @@ export interface SelectionController<M extends Record<string, unknown> = Record<
     toggleEntitySelection(entity: Entity<M>, newSelectedState?: boolean): void;
 }
 
-/**
- * Filter conditions in a `Query.where()` clause are specified using the
- * strings `<`, `<=`, `==`, `>=`, `>`, `array-contains`, `in`, and `array-contains-any`.
- * @group Models
- */
-export type WhereFilterOp =
-    | "<"
-    | "<="
-    | "=="
-    | "!="
-    | ">="
-    | ">"
-    | "array-contains"
-    | "in"
-    | "not-in"
-    | "array-contains-any";
-
-/**
- * Used to define filters applied in collections
- *
- * e.g. `{ age: [">=", 18] }`
- *
- * @group Models
- */
-export type FilterValues<Key extends string> =
-    Partial<Record<Key, [WhereFilterOp, unknown] | [WhereFilterOp, unknown][]>>;
-
-/**
- * A pre-defined filter preset for quick access in the collection toolbar.
- * Users can select a preset to instantly apply a set of filters and
- * optionally a sort order.
- *
- * @group Models
- */
-export interface FilterPreset<Key extends string = string> {
-    /**
-     * Display label shown in the preset menu.
-     * If omitted, a summary is auto-generated from the filter keys.
-     */
-    label?: string;
-
-    /**
-     * The filter values to apply when this preset is selected.
-     */
-    filterValues: FilterValues<Key>;
-
-    /**
-     * Optional sort override to apply alongside the filter values.
-     */
-    sort?: [Key, "asc" | "desc"];
-}
+// Canonical filter types — re-exported from the single source-of-truth.
+export type { WhereFilterOp, FilterValues, WireFilterValues, FilterPreset } from "./filter-operators";
 
 
 /**
@@ -882,16 +893,16 @@ export interface AdditionalFieldDelegate<M extends Record<string, unknown> = Rec
 }
 
 
-export type InferCollectionType<S extends EntityCollection> = S extends EntityCollection<infer M> ? M : never;
+export type InferCollectionConfigType<S extends CollectionConfig> = S extends CollectionConfig<infer M> ? M : never;
 
 /**
- * Used in the {@link EntityCollection#defaultSelectedView} to define the default
+ * Used in the {@link CollectionConfig#defaultSelectedView} to define the default
  * @group Models
  */
 export type DefaultSelectedViewBuilder = (params: DefaultSelectedViewParams) => string | undefined;
 
 /**
- * Used in the {@link EntityCollection#defaultSelectedView} to define the default
+ * Used in the {@link CollectionConfig#defaultSelectedView} to define the default
  * @group Models
  */
 export type DefaultSelectedViewParams = {
@@ -949,7 +960,7 @@ export type SecurityOperation = "select" | "insert" | "update" | "delete" | "all
 /**
  * Flexible Row Level Security rule for a collection.
  *
- * Inspired by Supabase's approach to PostgreSQL RLS. Rules can range from
+ * Built on PostgreSQL Row Level Security. Rules can range from
  * simple convenience shortcuts to fully custom SQL expressions, giving you the
  * full power of PostgreSQL Row Level Security.
  *
@@ -962,15 +973,28 @@ export type SecurityOperation = "select" | "insert" | "update" | "delete" | "all
  *
  * **How rules combine:** PostgreSQL evaluates all matching policies for an
  * operation. Permissive rules are OR'd together (any one passing is enough).
- * Restrictive rules are AND'd (all must pass). This mirrors Supabase behavior.
+ * Restrictive rules are AND'd (all must pass). This is standard PostgreSQL RLS behavior.
  *
- * **Mutual exclusivity:** `ownerField`, `access`, and raw SQL (`using`/`withCheck`)
- * cannot be combined. The type system enforces this — attempting to set
- * conflicting fields will produce a compile-time error.
+ * **Mutual exclusivity:** `ownerField`, `access`, structured `condition`, and
+ * raw SQL (`using`/`withCheck`) cannot be combined. The type system enforces
+ * this — attempting to set conflicting fields will produce a compile-time
+ * error.
+ *
+ * **Which form to reach for:** prefer the structured {@link StructuredSecurityRule}
+ * (`condition`/`check`) or the shortcuts (`ownerField`, `access`, `roles`). These
+ * are engine-agnostic and evaluated identically by the database and the admin UI,
+ * so the UI never shows an action the database will reject. Raw SQL
+ * ({@link RawSQLSecurityRule}) keeps full PostgreSQL power but is Postgres-only
+ * and server-authoritative (the UI cannot evaluate arbitrary SQL locally).
  *
  * @group Models
  */
-export type SecurityRule = OwnerSecurityRule | PublicSecurityRule | RawSQLSecurityRule | RolesOnlySecurityRule;
+export type SecurityRule =
+    | OwnerSecurityRule
+    | PublicSecurityRule
+    | StructuredSecurityRule
+    | RawSQLSecurityRule
+    | RolesOnlySecurityRule;
 
 /**
  * Shared fields for all SecurityRule variants.
@@ -1016,7 +1040,7 @@ export interface SecurityRuleBase {
      * // Equivalent to operation: "all"
      * { operations: ["all"], ownerField: "user_id" }
      */
-    operations?: SecurityOperation[];
+    operations?: readonly SecurityOperation[];
 
     /**
      * Whether this policy is `"permissive"` (default) or `"restrictive"`.
@@ -1026,7 +1050,7 @@ export interface SecurityRuleBase {
      * - **restrictive**: Restrictive policies are AND'd with all permissive
      *   policies — they act as additional gates that *must* also pass.
      *
-     * This is the same model as PostgreSQL / Supabase.
+     * This is the standard PostgreSQL RLS model.
      *
      * @default "permissive"
      */
@@ -1040,11 +1064,16 @@ export interface SecurityRuleBase {
      * application roles managed by Rebase, stored in the `rebase.user_roles`
      * table, and injected into each transaction via `auth.roles()`.
      *
-     * Generates a condition like:
-     *   `auth.roles() ~ '<role1>|<role2>'`
+     * Generates a safe array-overlap condition — the user passes if they hold
+     * *any* of the listed roles:
+     *   `string_to_array(auth.roles(), ',') && ARRAY['<role1>', '<role2>']`
+     *
+     * (Note: this is a true set intersection, NOT a regex/substring match, so
+     * a role named `admin` never matches `nonadmin` or `superadmin`.)
      *
-     * Can be combined with `ownerField`, `access`, or raw `using`/`withCheck`.
-     * When combined, the role check is AND'd with the other condition.
+     * Can be combined with `ownerField`, `access`, `condition`, or raw
+     * `using`/`withCheck`. When combined, the role check is AND'd with the
+     * other condition.
      *
      * @example
      * // Only admins can delete
@@ -1054,7 +1083,7 @@ export interface SecurityRuleBase {
      * // Admins have unfiltered read access to all rows
      * { operation: "select", roles: ["admin"], using: "true" }
      */
-    roles?: string[];
+    roles?: readonly string[];
 
     // ── Advanced: native PostgreSQL role targeting ───────────────────────
 
@@ -1079,7 +1108,7 @@ export interface SecurityRuleBase {
      * // Only apply this policy when connected as `app_role`
      * { operation: "select", access: "public", pgRoles: ["app_role"] }
      */
-    pgRoles?: string[];
+    pgRoles?: readonly string[];
 }
 
 /**
@@ -1099,6 +1128,8 @@ export interface OwnerSecurityRule extends SecurityRuleBase {
     access?: never;
     using?: never;
     withCheck?: never;
+    condition?: never;
+    check?: never;
 }
 
 /**
@@ -1123,12 +1154,61 @@ export interface PublicSecurityRule extends SecurityRuleBase {
     ownerField?: never;
     using?: never;
     withCheck?: never;
+    condition?: never;
+    check?: never;
+}
+
+/**
+ * Security rule expressed as a structured, engine-agnostic
+ * {@link PolicyExpression}. This is the **recommended** way to write a
+ * non-trivial condition: it compiles to PostgreSQL `USING`/`WITH CHECK` SQL
+ * *and* is evaluated identically by the admin UI, so the UI can never show an
+ * action the database will reject.
+ *
+ * Cannot be combined with `ownerField`, `access`, or raw `using`/`withCheck`.
+ *
+ * @example
+ * // Owner, or any user holding the `moderator` role
+ * {
+ *   operation: "update",
+ *   condition: policy.or(
+ *       policy.compare(policy.field("user_id"), "eq", policy.authUid()),
+ *       policy.rolesOverlap(["moderator"])
+ *   )
+ * }
+ *
+ * @group Models
+ */
+export interface StructuredSecurityRule extends SecurityRuleBase {
+    /**
+     * Structured condition for the `USING` clause — which *existing* rows are
+     * visible / can be modified / deleted (SELECT, UPDATE, DELETE).
+     */
+    condition: PolicyExpression;
+
+    /**
+     * Structured condition for the `WITH CHECK` clause — which *new/updated*
+     * row values are allowed (INSERT, UPDATE). Defaults to `condition` when
+     * omitted, mirroring PostgreSQL's own behavior.
+     */
+    check?: PolicyExpression;
+
+    ownerField?: never;
+    access?: never;
+    using?: never;
+    withCheck?: never;
 }
 
 /**
  * Security rule using raw SQL expressions for full PostgreSQL RLS power.
  *
- * Cannot be combined with `ownerField` or `access`.
+ * **Postgres-only and server-authoritative.** Arbitrary SQL cannot be
+ * evaluated by the admin UI, so a rule using this form is treated as *unknown*
+ * client-side (never silently allowed) and its effect on visible actions is
+ * reflected from the server. For conditions that should also drive the UI
+ * precisely, prefer the structured {@link StructuredSecurityRule}.
+ *
+ * Cannot be combined with `ownerField`, `access`, or structured `condition`.
  *
  * You can reference columns via `{column_name}` which will be resolved to
  * `table.column_name` in the generated Drizzle code.
@@ -1166,6 +1246,8 @@ export interface RawSQLSecurityRule extends SecurityRuleBase {
 
     ownerField?: never;
     access?: never;
+    condition?: never;
+    check?: never;
 }
 
 /**
@@ -1186,6 +1268,8 @@ export interface RolesOnlySecurityRule extends SecurityRuleBase {
     access?: never;
     using?: never;
     withCheck?: never;
+    condition?: never;
+    check?: never;
 }
 
 /**