@rebasepro/types 0.7.0 → 0.9.0

package/dist/types/collections.d.ts

@@ -1,25 +1,26 @@
 import React from "react";
 import type { Entity, EntityStatus } from "./entities";
-import type { EntityCallbacks } from "./entity_callbacks";
-import type { Properties } from "./properties";
+import type { CollectionCallbacks } from "./entity_callbacks";
+import type { 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 { 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.
      * The `slug` value will be used to determine the URL of the collection.
@@ -47,12 +48,12 @@ 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.
@@ -66,17 +67,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.
      * - For Firestore: The Firestore database ID (e.g., for multi-database projects)
@@ -88,7 +90,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;
     /**
@@ -123,12 +125,12 @@ 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.
      */
@@ -175,19 +177,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}`)[];
     /**
@@ -200,11 +201,11 @@ export interface BaseEntityCollection<M extends Record<string, unknown> = Record
     pagination?: boolean | number;
     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
      * entities externally.
@@ -249,7 +250,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
      * an additional field delegate.
@@ -261,8 +262,8 @@ export interface BaseEntityCollection<M extends Record<string, unknown> = Record
     defaultSize?: CollectionSize;
     /**
      * 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;
     /**
@@ -275,7 +276,7 @@ export interface BaseEntityCollection<M extends Record<string, unknown> = Record
     hideFromNavigation?: boolean;
     /**
      * 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.
@@ -312,11 +313,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;
     /**
@@ -337,9 +334,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`.
@@ -399,7 +396,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
      * global overrides set on `<Rebase>`, but only within this collection's
@@ -411,7 +408,7 @@ export interface BaseEntityCollection<M extends Record<string, unknown> = Record
      *
      * @example
      * ```tsx
-     * const productsCollection: PostgresCollection = {
+     * const productsCollection: PostgresCollectionConfig = {
      *     name: "Products",
      *     slug: "products",
      *     table: "products",
@@ -429,18 +426,18 @@ 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.
      */
@@ -457,7 +454,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.
      *
@@ -471,81 +468,129 @@ 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";
     /**
-     * The driver for this collection. Must be set to `"firestore"`.
+     * Set of properties that compose a entity.
+     * Firestore collections support `reference` properties but not `relation`.
      */
-    driver: "firestore";
+    properties: FirebaseProperties;
+    /**
+     * 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: { ... }
+     * };
+     * ```
+     */
+    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 driver for this collection. Must be set to `"mongodb"`.
+     * The database engine for this collection. Must be set to `"mongodb"`.
      */
-    driver: "mongodb";
+    engine: "mongodb";
+    /**
+     * Set of properties that compose a entity.
+     * MongoDB collections support `reference` properties but not `relation`.
+     */
+    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>;
-/**
- * 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>>[];
-};
+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 declare function isPostgresCollection<M extends Record<string, unknown> = Record<string, unknown>, USER extends User = User>(collection: EntityCollection<M, USER>): collection is PostgresCollection<M, USER>;
+export declare function isPostgresCollectionConfig<M extends Record<string, unknown> = Record<string, unknown>, USER extends User = User>(collection: CollectionConfig<M, USER>): collection is PostgresCollectionConfig<M, USER>;
 /**
  * Type guard for Firebase / Firestore collections.
  * @group Models
  */
-export declare function isFirebaseCollection<M extends Record<string, unknown> = Record<string, unknown>, USER extends User = User>(collection: EntityCollection<M, USER>): collection is FirebaseCollection<M, USER>;
+export declare function isFirebaseCollectionConfig<M extends Record<string, unknown> = Record<string, unknown>, USER extends User = User>(collection: CollectionConfig<M, USER>): collection is FirebaseCollectionConfig<M, USER>;
 /**
  * Type guard for MongoDB collections.
  * @group Models
  */
-export declare function isMongoDBCollection<M extends Record<string, unknown> = Record<string, unknown>, USER extends User = User>(collection: EntityCollection<M, USER>): collection is MongoDBCollection<M, USER>;
+export declare function isMongoDBCollectionConfig<M extends Record<string, unknown> = Record<string, unknown>, USER extends User = User>(collection: CollectionConfig<M, USER>): collection is MongoDBCollectionConfig<M, USER>;
+/**
+ * Returns the data path for a collection.
+ * For Firestore or MongoDB collections with a `path`, returns that value;
+ * otherwise falls back to `slug`.
+ */
+export declare function getCollectionDataPath<M extends Record<string, unknown> = Record<string, unknown>, USER extends User = User>(collection: CollectionConfig<M, USER>): string;
+/**
+ * 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 declare function getDeclaredSubcollections<M extends Record<string, unknown> = Record<string, unknown>, USER extends User = User>(collection: CollectionConfig<M, USER>): (() => CollectionConfig<Record<string, unknown>>[]) | undefined;
 /**
  * Configuration for Kanban board view mode.
  * @group Collections
@@ -575,7 +620,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`
@@ -631,7 +676,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>> {
@@ -641,42 +686,7 @@ export interface SelectionController<M extends Record<string, unknown> = Record<
     isEntitySelected(entity: Entity<M>): boolean;
     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"];
-}
+export type { WhereFilterOp, FilterValues, WireFilterValues, FilterPreset } from "./filter-operators";
 /**
  * Used to indicate valid filter combinations (e.g. created in Firestore)
  * If the user selects a specific filter/sort combination, the CMS checks if it's
@@ -739,14 +749,14 @@ export interface AdditionalFieldDelegate<M extends Record<string, unknown> = Rec
         context: RebaseContext;
     }): string | number | Promise<string | number> | undefined;
 }
-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 = {
@@ -799,7 +809,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.
  *
@@ -812,15 +822,23 @@ 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.
  * @group Models
@@ -863,7 +881,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"`.
      *
@@ -872,7 +890,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"
      */
@@ -885,11 +903,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
@@ -899,7 +922,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 database roles the policy applies to.
      *
@@ -921,7 +944,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[];
 }
 /**
  * Security rule that grants access based on row ownership.
@@ -940,6 +963,8 @@ export interface OwnerSecurityRule extends SecurityRuleBase {
     access?: never;
     using?: never;
     withCheck?: never;
+    condition?: never;
+    check?: never;
 }
 /**
  * Security rule that grants unrestricted row access (no row filtering).
@@ -963,11 +988,57 @@ 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.
@@ -1003,6 +1074,8 @@ export interface RawSQLSecurityRule extends SecurityRuleBase {
     withCheck?: string;
     ownerField?: never;
     access?: never;
+    condition?: never;
+    check?: never;
 }
 /**
  * Security rule that only filters by application roles, without any
@@ -1022,6 +1095,8 @@ export interface RolesOnlySecurityRule extends SecurityRuleBase {
     access?: never;
     using?: never;
     withCheck?: never;
+    condition?: never;
+    check?: never;
 }
 /**
  * Configuration for authentication collections.