@rebasepro/types 0.12.0 → 0.12.1-canary.gdfba2a1

package/dist/index.es.js

@@ -222,7 +222,7 @@ var REST_TO_CANONICAL = {
 * Operators that test for null/not-null and therefore ignore their value.
 * Codecs normalize the value of these conditions to `null`.
 */
-var NULL_OPS = new Set(["is-null", "is-not-null"]);
+var NULL_OPS = /* @__PURE__ */ new Set(["is-null", "is-not-null"]);
 /**
 * Every canonical operator, in a stable order. Useful for engine capability
 * declarations ({@link DataSourceCapabilities.filterOperators}) and for

package/dist/index.es.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.es.js","names":[],"sources":["../src/errors.ts","../src/types/entities.ts","../src/types/filter-operators.ts","../src/types/admin_block.ts","../src/types/data_source.ts","../src/types/collections.ts","../src/types/relations.ts","../src/types/policy.ts","../src/types/backend.ts","../src/types/channel_bus.ts","../src/types/storage_source.ts","../src/types/component_ref.ts","../src/types/project_manifest.ts","../src/types/collection_contract.ts","../src/types/schema_version.ts","../src/controllers/data_driver.ts","../src/controllers/storage.ts"],"sourcesContent":["/**\n * Structured initializer for {@link RebaseApiError}.\n *\n * @group Errors\n */\nexport interface RebaseErrorInit {\n    /**\n     * HTTP status code, when the error originated from an HTTP response.\n     * Left `undefined` for realtime/WebSocket, network, and client-side\n     * logic errors that have no HTTP status.\n     */\n    status?: number;\n    /** Stable, machine-readable error code (e.g. `\"NOT_FOUND\"`, `\"BAD_REQUEST\"`). */\n    code?: string;\n    /** Structured error payload returned by the server, when present. */\n    details?: unknown;\n    /** The underlying error this one wraps, if any. */\n    cause?: unknown;\n}\n\n/**\n * The single error type thrown across the entire Rebase client surface —\n * HTTP data/control-plane calls, realtime/WebSocket operations, and\n * client-side logic errors (e.g. an unknown collection accessor). A `catch`\n * block only ever needs to check for this one class:\n *\n * ```ts\n * import { RebaseApiError } from \"@rebasepro/client\"; // re-exported\n *\n * try {\n *   await client.data.products.update(id, { price: 9 });\n * } catch (e) {\n *   if (e instanceof RebaseApiError) {\n *     if (e.status === 404) { ... }   // HTTP failures carry a status\n *     console.error(e.code, e.details);\n *   }\n * }\n * ```\n *\n * `status` is present for HTTP failures and `undefined` otherwise, so its\n * presence distinguishes transport-level errors from realtime/logic errors.\n *\n * @group Errors\n */\nexport class RebaseApiError extends Error {\n    /** HTTP status code, or `undefined` for non-HTTP errors. */\n    readonly status?: number;\n    /** Stable machine-readable error code, when the server supplied one. */\n    readonly code?: string;\n    /** Structured error payload from the server, when present. */\n    readonly details?: unknown;\n\n    constructor(message: string, init: RebaseErrorInit = {}) {\n        super(message);\n        this.name = \"RebaseApiError\";\n        this.status = init.status;\n        this.code = init.code;\n        this.details = init.details;\n        if (init.cause !== undefined) {\n            // `cause` is standard on Error but not always in the lib target's type.\n            (this as { cause?: unknown }).cause = init.cause;\n        }\n    }\n}\n\n/**\n * Client-side logic error — raised before any request is made (e.g. accessing\n * an unknown collection accessor when a typed dictionary is configured).\n *\n * A subclass of {@link RebaseApiError} (with no `status`), so a single\n * `catch (e) { if (e instanceof RebaseApiError) ... }` handles it too.\n *\n * @group Errors\n */\nexport class RebaseClientError extends RebaseApiError {\n    constructor(message: string) {\n        super(message);\n        this.name = \"RebaseClientError\";\n    }\n}\n","/**\n * New or existing status\n * @group Models\n */\nexport type EntityStatus = \"new\" | \"existing\" | \"copy\";\n\n/**\n * Representation of a entity fetched from the driver\n * @group Models\n */\nexport interface Entity<M extends Record<string, unknown> = Record<string, unknown>> {\n\n    /**\n     * ID of the entity\n     */\n    id: string | number;\n\n    /**\n     * A string representing the path of the referenced document (relative\n     * to the root of the database).\n     */\n    path: string;\n\n    /**\n     * Current values\n     */\n    values: EntityValues<M>;\n\n    /**\n     * Which driver this entity belongs to (e.g., 'postgres', 'firestore').\n     * If not specified, the default driver is assumed.\n     */\n    driver?: string;\n\n    /**\n     * Which database within the driver (e.g., for Firestore multi-database).\n     * If not specified, the default database of the driver is used.\n     */\n    databaseId?: string;\n}\n\n/**\n * This type represents a record of key value pairs as described in an\n * entity collection.\n * @group Models\n */\nexport type EntityValues<M extends Record<string, unknown>> = M;\n\n/**\n * Props for creating a EntityReference\n */\nexport interface EntityReferenceProps {\n    /** ID of the entity */\n    id: string;\n    /** Path of the collection (relative to the root of the database) */\n    path: string;\n    /** Which driver (e.g., 'postgres', 'firestore'). Defaults to \"(default)\" */\n    driver?: string;\n    /** Which database within the driver. Defaults to \"(default)\" */\n    databaseId?: string;\n}\n\n/**\n * Class used to create a reference to a entity in a different path.\n *\n * @example\n * // Simple reference (most common case - single driver, single db)\n * new EntityReference({ id: \"123\", path: \"users\" })\n *\n * // Reference to a different driver (e.g., Firestore)\n * new EntityReference({ id: \"123\", path: \"analytics\", driver: \"firestore\" })\n *\n * // Reference to a specific database within a driver\n * new EntityReference({ id: \"123\", path: \"orders\", driver: \"postgres\", databaseId: \"orders_db\" })\n */\nexport class EntityReference {\n\n    readonly __type = \"reference\";\n    /**\n     * ID of the entity\n     */\n    readonly id: string;\n    /**\n     * A string representing the path of the referenced document (relative\n     * to the root of the database).\n     */\n    readonly path: string;\n\n    /**\n     * Which driver (e.g., 'postgres', 'firestore').\n     * Defaults to \"(default)\" if not specified.\n     */\n    readonly driver?: string;\n\n    /**\n     * Which database within the driver.\n     * Defaults to \"(default)\" if not specified.\n     */\n    readonly databaseId?: string;\n\n    /**\n     * Create a reference to a entity.\n     *\n     * @example\n     * // Simple reference (most common case)\n     * new EntityReference({ id: \"123\", path: \"users\" })\n     *\n     * // With driver\n     * new EntityReference({ id: \"123\", path: \"analytics\", driver: \"firestore\" })\n     */\n    constructor(props: EntityReferenceProps) {\n        this.id = props.id;\n        this.path = props.path;\n        this.driver = props.driver;\n        this.databaseId = props.databaseId;\n    }\n\n    get pathWithId() {\n        return `${this.path}/${this.id}`;\n    }\n\n    /**\n     * Get the full path including driver and database prefixes if specified.\n     * For the common case (single driver, single db), this just returns pathWithId.\n     */\n    get fullPath() {\n        const parts: string[] = [];\n\n        // Add driver prefix if not default\n        if (this.driver && this.driver !== \"(default)\") {\n            parts.push(this.driver);\n        }\n\n        // Add database prefix if specified\n        if (this.databaseId && this.databaseId !== \"(default)\") {\n            parts.push(this.databaseId);\n        }\n\n        if (parts.length > 0) {\n            return `${parts.join(\":\")}:::${this.path}/${this.id}`;\n        }\n        return this.pathWithId;\n    }\n\n    isEntityReference() {\n        return true;\n    }\n}\n\n/**\n * Class used to create a reference to a entity in a different path\n */\nexport class EntityRelation {\n\n    readonly __type = \"relation\";\n    /**\n     * ID of the entity\n     */\n    readonly id: string | number;\n    /**\n     * A string representing the path of the referenced document (relative\n     * to the root of the database).\n     */\n    readonly path: string;\n\n    /**\n     * Pre-fetched data payload to eliminate N+1 queries.\n     * When present, clients can use this directly instead of fetching.\n     */\n    readonly data?: Record<string, unknown>;\n\n    constructor(id: string | number, path: string, data?: Record<string, unknown>) {\n        this.id = id;\n        this.path = path;\n        this.data = data;\n    }\n\n    get pathWithId() {\n        return `${this.path}/${this.id}`;\n    }\n\n    isEntityReference() {\n        return false;\n    }\n\n    isEntityRelation() {\n        return true;\n    }\n}\n\nexport class GeoPoint {\n\n    /**\n     * The latitude of this GeoPoint instance.\n     */\n    readonly latitude: number;\n    /**\n     * The longitude of this GeoPoint instance.\n     */\n    readonly longitude: number;\n\n    constructor(latitude: number, longitude: number) {\n        this.latitude = latitude;\n        this.longitude = longitude;\n    }\n}\n\nexport class Vector {\n    readonly value: number[];\n\n    constructor(value: number[]) {\n        this.value = value;\n    }\n}\n","/**\n * Canonical filter operators and REST wire-format mappings.\n *\n * `WhereFilterOp` is THE operator type used at every layer — from React\n * components through the SDK, server, and down to the database driver.\n *\n * PostgREST short-codes (`eq`, `gt`, `cs`, …) exist **only** at the\n * HTTP wire boundary, handled by `serializeFilter` / `deserializeFilter`\n * in `@rebasepro/common`.\n *\n * ┌──────────────────────┬───────────────┬──────────────────────────────┐\n * │ Canonical            │ REST short    │ Meaning                      │\n * ├──────────────────────┼───────────────┼──────────────────────────────┤\n * │ \"==\"                 │ \"eq\"          │ Equal                        │\n * │ \"!=\"                 │ \"neq\"         │ Not equal                    │\n * │ \">\"                  │ \"gt\"          │ Greater than                 │\n * │ \">=\"                 │ \"gte\"         │ Greater than or equal        │\n * │ \"<\"                  │ \"lt\"          │ Less than                    │\n * │ \"<=\"                 │ \"lte\"         │ Less than or equal           │\n * │ \"in\"                 │ \"in\"          │ Value in list                │\n * │ \"not-in\"             │ \"nin\"         │ Value not in list            │\n * │ \"array-contains\"     │ \"cs\"          │ Array contains element       │\n * │ \"array-contains-any\" │ \"csa\"         │ Array contains any of        │\n * │ \"like\"               │ \"like\"        │ SQL LIKE (case-sensitive)    │\n * │ \"ilike\"              │ \"ilike\"       │ SQL ILIKE (case-insensitive) │\n * │ \"not-like\"           │ \"nlike\"       │ NOT LIKE (case-sensitive)    │\n * │ \"not-ilike\"          │ \"nilike\"      │ NOT ILIKE (case-insensitive) │\n * │ \"is-null\"            │ \"isnull\"      │ Field IS NULL                │\n * │ \"is-not-null\"        │ \"notnull\"     │ Field IS NOT NULL            │\n * └──────────────────────┴───────────────┴──────────────────────────────┘\n *\n * Pattern matching (`like`/`ilike`) uses SQL wildcard syntax: `%` matches any\n * sequence of characters, `_` matches a single character. On MongoDB these are\n * translated to anchored regular expressions; Firestore has no native pattern\n * matching and rejects these operators (use `searchString` instead).\n *\n * @module\n */\n\n/**\n * Canonical sort representation: `[fieldName, direction]`.\n *\n * Used in `FindParams.orderBy`, `collection.sort`, and `FilterPreset.sort`.\n * The colon-string form (`\"field:direction\"`) exists only at the HTTP wire\n * boundary, handled by `serializeOrderBy` / `deserializeOrderBy` in\n * `@rebasepro/common`.\n *\n * Design note: the natural extension for multi-column sort is\n * `OrderByTuple[]` — not implemented yet (server consumes only the first).\n *\n * @group Models\n */\nexport type OrderByTuple<Key extends string = string> = [Key, \"asc\" | \"desc\"];\n\n/**\n * Canonical filter operators supported across all database backends.\n * Each DB driver translates these to its native query format.\n *\n * @group Models\n */\nexport type WhereFilterOp =\n    | \"<\"\n    | \"<=\"\n    | \"==\"\n    | \"!=\"\n    | \">=\"\n    | \">\"\n    | \"array-contains\"\n    | \"in\"\n    | \"not-in\"\n    | \"array-contains-any\"\n    | \"like\"\n    | \"ilike\"\n    | \"not-like\"\n    | \"not-ilike\"\n    | \"is-null\"\n    | \"is-not-null\";\n\n/**\n * Used to define filters applied in collections.\n *\n * A single condition is a tuple `[operator, value]`.\n * Multiple conditions on the same field use an array of tuples.\n *\n * @example\n * // Single condition per field\n * { status: [\"==\", \"active\"], price: [\">=\", 9.99] }\n *\n * // Multiple conditions on one field\n * { age: [[\">=\", 18], [\"<\", 65]] }\n *\n * // Array operators\n * { role: [\"in\", [\"admin\", \"editor\"]] }\n * { tags: [\"array-contains\", \"featured\"] }\n *\n * // Pattern matching (SQL wildcards: % and _)\n * { name: [\"ilike\", \"%john%\"] }\n * { slug: [\"like\", \"post-%\"] }\n *\n * // Null checks (the value is ignored; `null` is conventional)\n * { deleted_at: [\"is-null\", null] }\n * { published_at: [\"is-not-null\", null] }\n *\n * @group Models\n */\nexport type FilterValues<Key extends string> =\n    Partial<Record<Key, [WhereFilterOp, unknown] | [WhereFilterOp, unknown][]>>;\n\n/**\n * The field names a query may address on a row type: every column, plus a\n * dotted path reaching inside one.\n *\n * Only the **root** of a dotted path is checked. `\"meta.tag\"` requires a `meta`\n * column and says nothing about what is under it, because what is under it is a\n * `map`/jsonb value whose shape the row type does not describe — and rejecting\n * paths we cannot verify would make jsonb columns unqueryable.\n *\n * When `M` is left at its default `Record<string, unknown>`, `keyof M` is\n * `string` and a template literal over `string` is itself assignable to\n * `string`, so this collapses to `string` and every query stays permissive.\n * That is what keeps an untyped `createRebaseClient()` behaving exactly as it\n * did before the row type was threaded through.\n *\n * @group Models\n */\nexport type FieldPath<M extends Record<string, unknown> = Record<string, unknown>> =\n    | Extract<keyof M, string>\n    | `${Extract<keyof M, string>}.${string}`;\n\n/**\n * Relaxed filter type that also accepts pre-serialized PostgREST strings.\n * **Internal only** — used at the wire-format boundary\n * (`serializeFilter` / `deserializeFilter` in `@rebasepro/common`).\n *\n * Application code, UI components, and SDK consumers should use\n * {@link FilterValues} instead.\n *\n * @internal\n */\nexport type WireFilterValues<Key extends string> =\n    Partial<Record<Key, [WhereFilterOp, unknown] | [WhereFilterOp, unknown][] | string>>;\n\n/**\n * A pre-defined filter preset for quick access in the collection toolbar.\n * Users can select a preset to instantly apply a set of filters and\n * optionally a sort order.\n *\n * @group Models\n */\nexport interface FilterPreset<Key extends string = string> {\n    /**\n     * Display label shown in the preset menu.\n     * If omitted, a summary is auto-generated from the filter keys.\n     */\n    label?: string;\n\n    /**\n     * The filter values to apply when this preset is selected.\n     */\n    filterValues: FilterValues<Key>;\n\n    /**\n     * Optional sort override to apply alongside the filter values.\n     */\n    sort?: OrderByTuple<Key>;\n}\n\n/**\n * PostgREST short-code operators. Wire format only — these never appear\n * in application code. Used by `serializeFilter`/`deserializeFilter`\n * in `@rebasepro/common`.\n */\nexport type RestFilterOp =\n    | \"eq\" | \"neq\"\n    | \"gt\" | \"gte\"\n    | \"lt\" | \"lte\"\n    | \"in\" | \"nin\"\n    | \"cs\" | \"csa\"\n    | \"like\" | \"ilike\"\n    | \"nlike\" | \"nilike\"\n    | \"isnull\" | \"notnull\";\n\n/** Maps canonical operators to their REST short-code equivalents. */\nexport const CANONICAL_TO_REST: Readonly<Record<WhereFilterOp, RestFilterOp>> = {\n    \"==\": \"eq\",\n    \"!=\": \"neq\",\n    \">\": \"gt\",\n    \">=\": \"gte\",\n    \"<\": \"lt\",\n    \"<=\": \"lte\",\n    \"in\": \"in\",\n    \"not-in\": \"nin\",\n    \"array-contains\": \"cs\",\n    \"array-contains-any\": \"csa\",\n    \"like\": \"like\",\n    \"ilike\": \"ilike\",\n    \"not-like\": \"nlike\",\n    \"not-ilike\": \"nilike\",\n    \"is-null\": \"isnull\",\n    \"is-not-null\": \"notnull\"\n};\n\n/** Maps REST short-code operators to their canonical equivalents. */\nexport const REST_TO_CANONICAL: Readonly<Record<RestFilterOp, WhereFilterOp>> = {\n    \"eq\": \"==\",\n    \"neq\": \"!=\",\n    \"gt\": \">\",\n    \"gte\": \">=\",\n    \"lt\": \"<\",\n    \"lte\": \"<=\",\n    \"in\": \"in\",\n    \"nin\": \"not-in\",\n    \"cs\": \"array-contains\",\n    \"csa\": \"array-contains-any\",\n    \"like\": \"like\",\n    \"ilike\": \"ilike\",\n    \"nlike\": \"not-like\",\n    \"nilike\": \"not-ilike\",\n    \"isnull\": \"is-null\",\n    \"notnull\": \"is-not-null\"\n};\n\n/**\n * Operators that test for null/not-null and therefore ignore their value.\n * Codecs normalize the value of these conditions to `null`.\n */\nexport const NULL_OPS: ReadonlySet<WhereFilterOp> = new Set<WhereFilterOp>([\n    \"is-null\", \"is-not-null\"\n]);\n\n/**\n * Every canonical operator, in a stable order. Useful for engine capability\n * declarations ({@link DataSourceCapabilities.filterOperators}) and for\n * building operator subsets.\n * @group Models\n */\nexport const ALL_WHERE_FILTER_OPS: readonly WhereFilterOp[] = [\n    \"<\", \"<=\", \"==\", \"!=\", \">=\", \">\",\n    \"in\", \"not-in\",\n    \"array-contains\", \"array-contains-any\",\n    \"like\", \"ilike\", \"not-like\", \"not-ilike\",\n    \"is-null\", \"is-not-null\"\n];\n\n/** All canonical operator strings for runtime validation. */\nconst CANONICAL_OPS: ReadonlySet<string> = new Set<WhereFilterOp>(ALL_WHERE_FILTER_OPS);\n\n/**\n * Resolve any operator string (canonical or REST short-code) to its\n * canonical `WhereFilterOp` form. Returns `undefined` for unknown operators.\n *\n * @example\n * toCanonicalOp(\"==\")   // \"==\"\n * toCanonicalOp(\"eq\")   // \"==\"\n * toCanonicalOp(\"cs\")   // \"array-contains\"\n * toCanonicalOp(\"xyz\")  // undefined\n */\nexport function toCanonicalOp(op: string): WhereFilterOp | undefined {\n    if (CANONICAL_OPS.has(op)) return op as WhereFilterOp;\n    return (REST_TO_CANONICAL as Record<string, WhereFilterOp | undefined>)[op];\n}\n","/**\n * The keys of a collection's admin block, as data.\n *\n * There is no *type* for the block in this package any more, and that is the point:\n * `admin` is not declared on `BaseCollectionConfig` or on any property here, so a\n * BaaS install cannot even write one. `@rebasepro/admin-types` adds the field back by\n * declaration merging, which is why installing it is what makes the admin surface\n * appear.\n *\n * The *list* still has to live here, because three runtime consumers need it and two\n * of them are core — see below.\n */\n\n/**\n * Every key that belongs inside a collection's `admin` block, as data.\n *\n * The type that describes these fields is `AdminCollectionOptions` in\n * `@rebasepro/admin-types`, and it is erased at build time — but three runtime\n * consumers need the list, and two of them are core:\n *\n * - `serializeCollections`, to drop the block from the contract\n * - the ts-morph schema editor in `@rebasepro/server`, which rewrites collection\n *   files on disk from the admin panel and has to know where each key goes. A key\n *   missing from this list gets written to the *top level* of the file, where the\n *   backend ignores it and the panel never finds it again.\n * - the `collections-admin-block` codemod\n *\n * `@rebasepro/admin-types` re-exports this and asserts it names only real option\n * keys; the count is pinned by a test there.\n *\n * @group Models\n */\nexport const ADMIN_COLLECTION_KEYS = [\n    \"Actions\",\n    \"additionalFields\",\n    \"alwaysApplyDefaultValues\",\n    \"components\",\n    \"defaultEntityAction\",\n    \"defaultFilter\",\n    \"defaultSelectedView\",\n    \"defaultSize\",\n    \"defaultViewMode\",\n    \"disableDefaultActions\",\n    \"enabledViews\",\n    \"entityActions\",\n    \"entityViews\",\n    \"exportable\",\n    \"filterPresets\",\n    \"fixedFilter\",\n    \"formAutoSave\",\n    \"formView\",\n    \"group\",\n    \"hideFromNavigation\",\n    \"hideIdFromCollection\",\n    \"hideIdFromForm\",\n    \"icon\",\n    \"includeJsonView\",\n    \"inlineEditing\",\n    \"kanban\",\n    \"listProperties\",\n    \"localChangesBackup\",\n    \"openEntityMode\",\n    \"orderProperty\",\n    \"pagination\",\n    \"previewProperties\",\n    \"propertiesOrder\",\n    \"selectionController\",\n    \"selectionEnabled\",\n    \"sideDialogWidth\",\n    \"sort\",\n    \"titleProperty\"\n] as const;\n\n/** A key of a collection's `admin` block. @group Models */\nexport type AdminCollectionKey = typeof ADMIN_COLLECTION_KEYS[number];\n\n/**\n * Every key that belongs inside a *property's* `admin` block, as data.\n *\n * The union of `AdminPropertyOptions` and its per-type extensions\n * (`AdminStringOptions`, `AdminArrayOptions`, …) in `@rebasepro/admin-types`.\n * It lives here for the same reason {@link ADMIN_COLLECTION_KEYS} does: the\n * runtime consumers are core packages that the BaaS guard forbids from\n * importing `@rebasepro/admin-types`. Here it is the boot-time collection\n * validator in `@rebasepro/server`, which has to tell \"you left `readOnly` at\n * the top of the property, where nothing reads it\" apart from \"you invented a\n * key we have never heard of\".\n *\n * `@rebasepro/admin-types` re-exports this and asserts it names only real\n * option keys.\n *\n * @group Models\n */\nexport const ADMIN_PROPERTY_KEYS = [\n    \"canAddElements\",\n    \"clearable\",\n    \"columnWidth\",\n    \"customProps\",\n    \"disabled\",\n    \"expanded\",\n    \"Field\",\n    \"Filter\",\n    \"filterOperators\",\n    \"fixedFilter\",\n    \"hideFromCollection\",\n    \"includeEntityLink\",\n    \"includeId\",\n    \"markdown\",\n    \"minimalistView\",\n    \"multiline\",\n    \"Preview\",\n    \"previewAsTag\",\n    \"previewProperties\",\n    \"readOnly\",\n    \"sortable\",\n    \"spreadChildren\",\n    \"urlPreview\",\n    \"widget\",\n    \"widthPercentage\"\n] as const;\n\n/** A key of a property's `admin` block. @group Models */\nexport type AdminPropertyKey = typeof ADMIN_PROPERTY_KEYS[number];\n","import { ALL_WHERE_FILTER_OPS, WhereFilterOp } from \"./filter-operators\";\n\n/**\n * Describes the capabilities and features supported by a data source (driver).\n *\n * Each driver (Postgres, Firebase, MongoDB, etc.) declares which features it\n * supports. The admin uses this descriptor to:\n * - Show/hide editor tabs (e.g. Relations for SQL, Subcollections for Firebase)\n * - Filter the property type picker (e.g. `relation` for SQL, `reference` for Firebase)\n * - Toggle driver-specific form controls (e.g. `columnType` for SQL)\n *\n * @group Models\n */\nexport interface DataSourceCapabilities {\n    /** Unique driver key (e.g. \"postgres\", \"firestore\", \"mongodb\") */\n    key: string;\n\n    /** Human-readable label for the UI (e.g. \"PostgreSQL\", \"Firebase / Firestore\") */\n    label: string;\n\n    // ── Feature flags ─────────────────────────────────────────────────\n    /** Does this source support SQL-style relations (JOINs)? */\n    supportsRelations: boolean;\n\n    /** Does this source support nested subcollections? */\n    supportsSubcollections: boolean;\n\n    /** Does this source support Row Level Security policies? */\n    supportsRLS: boolean;\n\n    /** Does this source support document references (Firebase-style)? */\n    supportsReferences: boolean;\n\n    /** Does this source support SQL column type annotations? */\n    supportsColumnTypes: boolean;\n\n    /** Does this source support real-time listeners? */\n    supportsRealtime: boolean;\n\n    /**\n     * Does this source store vectors natively?\n     *\n     * `VectorProperty` carries a `dimensions` and is pgvector-shaped. It was\n     * the one driver-specific property kind with no flag to gate it, so unlike\n     * every other field in this descriptor there was not even a runtime answer\n     * to appeal to — a Firestore collection could declare an embedding column\n     * and no driver would do anything with it.\n     */\n    supportsVectors: boolean;\n\n    /**\n     * Canonical filter operators this engine can execute.\n     *\n     * The admin UI intersects this set with the property-type defaults and\n     * any per-property narrowing (`property.ui.filterOperators`) to decide\n     * which operators to offer in filter fields — so an engine that cannot\n     * run `ilike` (e.g. Firestore) never shows a \"Contains\" filter that\n     * would throw at query time.\n     */\n    filterOperators: readonly WhereFilterOp[];\n\n    /**\n     * Relation kinds this engine's driver can compile into a filter.\n     *\n     * Only `belongsTo` puts a column on the row being filtered; the others are\n     * answered with a correlated subquery over the junction or the target\n     * table, which not every driver can build. An engine with no relations at\n     * all declares none.\n     *\n     * The admin uses this to decide whether a relation column offers a filter\n     * control. Offering one an engine cannot answer is not cosmetic: a driver\n     * that drops the key it cannot resolve *widens* the read to every row, and\n     * one that fails closed answers a control the admin itself put on screen\n     * with a 400.\n     *\n     * Optional, so a third-party driver registered before this existed still\n     * compiles. Omitted means {@link DEFAULT_FILTERABLE_RELATION_KINDS} — the\n     * one kind that is a plain column comparison, which every relational\n     * driver can do. The subquery kinds are a real capability and have to be\n     * claimed rather than assumed: assuming them wrongly is the widening.\n     */\n    filterableRelationKinds?: readonly string[];\n\n    // ── Admin capability flags ───────────────────────────────────────\n    /** Does this source support SQL admin operations (SQL editor, EXPLAIN, etc.)? */\n    supportsSQLAdmin: boolean;\n\n    /** Does this source support document admin operations (aggregation, stats)? */\n    supportsDocumentAdmin: boolean;\n\n    /** Does this source support schema admin (unmapped tables, table metadata)? */\n    supportsSchemaAdmin: boolean;\n}\n\n/**\n * Subset of DataSourceCapabilities containing only feature flags.\n * Useful when you only need to check capabilities without UI metadata.\n * @group Models\n */\nexport type DataSourceFeatures = Omit<DataSourceCapabilities, \"key\" | \"label\">;\n\n/**\n * The default data-source key, used when a collection does not name a\n * `dataSource`. Shared by the frontend router and the backend driver\n * registry so both agree on \"the default database\".\n * @group Models\n */\nexport const DEFAULT_DATA_SOURCE_KEY = \"(default)\";\n\n/**\n * How the *frontend* reaches a data source.\n *\n * - `\"server\"` — through the Rebase backend (the `RebaseClient`). The backend\n *   holds the actual database adapter and routes by data-source key. This is\n *   the default and covers Postgres, MongoDB, and any other server-mediated\n *   engine.\n * - `\"direct\"` — straight from the client to the external backend via its own\n *   SDK driver (e.g. Firestore). The Rebase backend is not in the data path.\n * - `\"custom\"` — a developer-supplied {@link DataDriver}, transport unspecified.\n *\n * @group Models\n */\nexport type DataSourceTransport = \"server\" | \"direct\" | \"custom\";\n\n/**\n * Declarative definition of a data source — a named place data lives.\n *\n * Declared once and shared front and back: the frontend uses it to decide\n * transport (client vs direct driver), the backend uses the same `key` to\n * resolve a database adapter, and the editor derives capabilities from\n * `engine`. Collections reference a definition by its `key` via\n * `collection.dataSource`.\n *\n * @group Models\n */\nexport interface DataSourceDefinition {\n    /**\n     * Unique identifier for this data source. Collections point at it via\n     * `dataSource`. Defaults to {@link DEFAULT_DATA_SOURCE_KEY}.\n     */\n    key: string;\n\n    /**\n     * The engine backing this data source (e.g. `\"postgres\"`, `\"mongodb\"`,\n     * `\"firestore\"`, or a custom id). Determines the\n     * {@link DataSourceCapabilities} surfaced in the editor.\n     */\n    engine: string;\n\n    /**\n     * How the frontend reaches this source. Optional — when omitted it is\n     * inferred: `\"direct\"` if the definition carries a client-side driver,\n     * `\"server\"` otherwise.\n     */\n    transport?: DataSourceTransport;\n\n    /**\n     * The physical database/schema/Firestore-database within the engine.\n     * Threaded to drivers/adapters as the existing `databaseId` runtime\n     * parameter. Defaults to the engine's own default.\n     */\n    databaseId?: string;\n\n    /** Human-readable label for the UI. */\n    label?: string;\n}\n\n/**\n * The resolved data source for a collection: the single source of truth that\n * the frontend router, backend registry, and editor all derive from.\n * Produced by `resolveDataSource(collection, registry)`.\n *\n * @group Models\n */\nexport interface ResolvedDataSource {\n    /** Data-source key (routing key, shared front + back). */\n    key: string;\n    /** Engine backing the source (drives capabilities). */\n    engine: string;\n    /** Frontend transport. */\n    transport: DataSourceTransport;\n    /** Within-engine instance, if any (the `databaseId` runtime param). */\n    databaseId?: string;\n    /** Capabilities derived from {@link engine}. */\n    capabilities: DataSourceCapabilities;\n}\n\n/**\n * Relation kinds assumed filterable when a driver does not say.\n *\n * `belongsTo` alone: its filter is a comparison on a column of the row being\n * filtered, the one shape that needs no query construction a driver might not\n * have. Everything else is a correlated subquery over another table.\n *\n * @group Models\n */\nexport const DEFAULT_FILTERABLE_RELATION_KINDS: readonly string[] = [\"belongsTo\"];\n\n// ── Built-in driver capabilities ─────────────────────────────────────\n\n/** @group Models */\nexport const POSTGRES_CAPABILITIES: DataSourceCapabilities = {\n    key: \"postgres\",\n    label: \"PostgreSQL\",\n    supportsRelations: true,\n    supportsSubcollections: false,\n    supportsRLS: true,\n    supportsReferences: false,\n    supportsColumnTypes: true,\n    supportsRealtime: true,\n    supportsVectors: true,\n    filterOperators: ALL_WHERE_FILTER_OPS,\n    // `via` is absent: its join path is authored source → target with no\n    // stated inverse, so the driver has nothing to reverse into a filter.\n    filterableRelationKinds: [\"belongsTo\", \"manyToMany\", \"hasMany\", \"hasOne\"],\n    supportsSQLAdmin: true,\n    supportsDocumentAdmin: false,\n    supportsSchemaAdmin: true\n};\n\n/** @group Models */\nexport const FIREBASE_CAPABILITIES: DataSourceCapabilities = {\n    key: \"firestore\",\n    label: \"Firebase / Firestore\",\n    supportsRelations: false,\n    supportsSubcollections: true,\n    supportsRLS: false,\n    supportsReferences: true,\n    supportsColumnTypes: false,\n    supportsRealtime: true,\n    supportsVectors: false,\n    // Firestore has no SQL pattern matching — the driver throws on the LIKE\n    // family, so the UI must never offer it.\n    filterOperators: ALL_WHERE_FILTER_OPS.filter(op =>\n        op !== \"like\" && op !== \"ilike\" && op !== \"not-like\" && op !== \"not-ilike\"),\n    // No relations at all — a document store links by reference.\n    filterableRelationKinds: [],\n    supportsSQLAdmin: false,\n    supportsDocumentAdmin: false,\n    supportsSchemaAdmin: false\n};\n\n/** @group Models */\nexport const MONGODB_CAPABILITIES: DataSourceCapabilities = {\n    key: \"mongodb\",\n    label: \"MongoDB\",\n    supportsRelations: false,\n    supportsSubcollections: true,\n    supportsRLS: false,\n    supportsReferences: true,\n    supportsColumnTypes: false,\n    supportsRealtime: false,\n    supportsVectors: false,\n    filterOperators: ALL_WHERE_FILTER_OPS,\n    filterableRelationKinds: [],\n    supportsSQLAdmin: false,\n    supportsDocumentAdmin: true,\n    supportsSchemaAdmin: true\n};\n\n/**\n * Fallback capabilities when the driver is unknown.\n * Enables everything so nothing is hidden unexpectedly.\n * @group Models\n */\nexport const DEFAULT_CAPABILITIES: DataSourceCapabilities = {\n    key: \"(default)\",\n    label: \"Default\",\n    supportsRelations: true,\n    supportsSubcollections: true,\n    supportsRLS: true,\n    supportsReferences: true,\n    supportsColumnTypes: true,\n    supportsRealtime: true,\n    supportsVectors: true,\n    filterOperators: ALL_WHERE_FILTER_OPS,\n    // The exception to this descriptor's \"enable everything\" rule. The other\n    // flags hide a tab or a picker when they are wrong; this one decides\n    // whether a query is sent that an unknown driver may answer by dropping\n    // the condition — which returns every row rather than none.\n    filterableRelationKinds: DEFAULT_FILTERABLE_RELATION_KINDS,\n    supportsSQLAdmin: true,\n    supportsDocumentAdmin: true,\n    supportsSchemaAdmin: true\n};\n\nconst CAPABILITIES_REGISTRY: Record<string, DataSourceCapabilities> = {\n    postgres: POSTGRES_CAPABILITIES,\n    firestore: FIREBASE_CAPABILITIES,\n    mongodb: MONGODB_CAPABILITIES,\n    \"(default)\": DEFAULT_CAPABILITIES\n};\n\n/**\n * Look up capabilities for a given engine key.\n * If `engine` is undefined or not found, returns `DEFAULT_CAPABILITIES`.\n * @group Models\n */\nexport function getDataSourceCapabilities(engine?: string): DataSourceCapabilities {\n    if (!engine) return POSTGRES_CAPABILITIES; // postgres is the default engine\n    return CAPABILITIES_REGISTRY[engine] ?? DEFAULT_CAPABILITIES;\n}\n\n/**\n * Register custom capabilities for a third-party driver.\n * @group Models\n */\nexport function registerDataSourceCapabilities(capabilities: DataSourceCapabilities): void {\n    CAPABILITIES_REGISTRY[capabilities.key] = capabilities;\n}\n","import type { CollectionCallbacks } from \"./entity_callbacks\";\n\nimport type { EnumValues, Properties, PostgresProperties, FirebaseProperties, MongoProperties } from \"./properties\";\n\nimport type { User } from \"../users\";\nimport type { Relation } from \"./relations\";\nimport type { SecurityRule } from \"./security_rules\";\nimport { getDataSourceCapabilities } from \"./data_source\";\nimport type { WhereFilterOp, FilterValues, FilterPreset } from \"./filter-operators\";\n\n/**\n * Base interface containing all driver-agnostic collection properties.\n * Use {@link PostgresCollectionConfig} or {@link FirebaseCollectionConfig} for\n * driver-specific type safety, or {@link CollectionConfig} when you\n * need to handle any collection regardless of backend.\n *\n * @group Models\n */\nexport interface BaseCollectionConfig<M extends Record<string, unknown> = Record<string, unknown>, USER extends User = User> {\n\n    /**\n     * You can set an alias that will be used internally instead of the collection name.\n     * The `slug` value will be used to determine the URL of the collection.\n     * Note that you can use this value in reference properties too.\n     */\n    slug: string;\n\n    /**\n     * Name of the collection, typically plural.\n     * E.g. `Products`, `Blog`\n     */\n    name: string;\n\n    /**\n     * Singular name of an entry in this collection\n     * E.g. `Product`, `Blog entry`\n     */\n    singularName?: string;\n\n    /**\n     * Optional description of this view. You can use Markdown.\n     */\n    description?: string;\n\n    /**\n     * Child collections nested under entities of this collection.\n     * Populated automatically during normalization from driver-specific fields\n     * (e.g. Firebase `subcollections`, Postgres `relations` with many-cardinality).\n     *\n     * Custom drivers can set this directly to expose child collections to the UI.\n     */\n    childCollections?: () => CollectionConfig<Record<string, unknown>>[];\n\n\n    /**\n     * The data source this collection belongs to — the routing key shared by\n     * the frontend router and the backend driver registry. It points at a\n     * {@link DataSourceDefinition} registered on `<Rebase dataSources>` (front)\n     * and `initializeRebaseBackend({ dataSources })` (back).\n     *\n     * If not specified, the default data source `\"(default)\"` is used, which\n     * for a standard Rebase app is the server-mediated Postgres backend.\n     *\n     * @example\n     * // Default data source (server-mediated Postgres)\n     * { slug: \"products\" }\n     *\n     * // A direct-transport Firestore data source registered as \"analytics\"\n     * { slug: \"events\", dataSource: \"analytics\" }\n     */\n    dataSource?: string;\n\n    /**\n     * The database engine backing this collection (`\"postgres\"`, `\"firestore\"`,\n     * `\"mongodb\"`, or a custom id).\n     *\n     * On concrete collection types ({@link PostgresCollectionConfig},\n     * {@link FirebaseCollectionConfig}, {@link MongoDBCollectionConfig}) this is a literal\n     * discriminant. On the base type it is optional and gets stamped\n     * automatically during collection normalization from the registered\n     * {@link DataSourceDefinition}.\n     *\n     * Prefer setting {@link dataSource} and letting the engine be resolved.\n     */\n    engine?: string;\n\n    /**\n     * Which database within the engine.\n     * - For Firestore: The Firestore database ID (e.g., for multi-database projects)\n     * - For PostgreSQL: Schema or database name\n     * - For MongoDB: Database name\n     *\n     * If not specified, the default database of the engine is used. Resolved\n     * from the collection's {@link DataSourceDefinition} when omitted here.\n     */\n    databaseId?: string;\n\n    /**\n     * Set of properties that compose a entity\n     */\n    properties: Properties;\n\n\n\n\n\n\n\n\n\n\n\n\n    /**\n     * Mark this collection as an authentication collection.\n     * When true, this collection is used for user management, login, password hashing, and invitation flows.\n     */\n    auth?: boolean | AuthCollectionConfig;\n\n\n\n\n\n\n\n    /**\n     * Row-level authorization rules for this collection.\n     *\n     * Driver-agnostic on purpose, unlike `disableDefaultPolicies`, `table` and\n     * `relations`, which are declared on {@link PostgresCollectionConfig} only.\n     * The rules are a *contract* — who may read or write which rows — and each\n     * engine enforces it its own way:\n     *\n     * - **Postgres** compiles them to real `CREATE POLICY` statements and lets\n     *   the database enforce them (see {@link PostgresCollectionConfig.securityRules},\n     *   which narrows this with the raw-SQL details).\n     * - **MongoDB** translates them into a query filter it AND-s into every\n     *   read and write, honouring `access`, `ownerField`, `roles`, `mode` and\n     *   the `operation`/`operations` selectors, and making a best effort at raw\n     *   `using`/`withCheck` SQL.\n     * - **Firestore** does not implement them at all; its own rules language is\n     *   evaluated by Google, not from here. `supportsRLS` on\n     *   {@link DataSourceCapabilities} reports which engines generate policies,\n     *   which is not the same question as whether an engine honours a rule.\n     */\n    securityRules?: readonly SecurityRule[];\n\n    /**\n     * This interface defines all the callbacks that can be used when a entity\n     * is being created, updated or deleted.\n     * Useful for adding your own logic or blocking the execution of the operation.\n     */\n    readonly callbacks?: CollectionCallbacks<M, USER>;\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n    /**\n     * User id of the owner of this collection. This is used only by plugins, or if you\n     * are writing custom code\n     */\n    ownerId?: string;\n\n    /**\n     * Arbitrary key-value metadata for external consumers.\n     * Not interpreted by Rebase — passed through serialization unchanged.\n     * Used by domain apps to store custom per-collection config.\n     */\n    metadata?: Record<string, unknown>;\n\n\n\n\n    /**\n     * If set to true, changes to the entity will be saved in a subcollection.\n     * This prop has no effect if the history plugin is not enabled\n     */\n    history?: boolean;\n\n    /**\n     * Whether a write naming a field this collection does not declare is\n     * rejected with a 400. Defaults to `true`.\n     *\n     * Set to `false` to let unknown keys through to the database, which is what\n     * happened before this existed: a typo reached the INSERT and came back as\n     * a Postgres error about a column, or — where a column really does exist\n     * that the config never declared, populated by a trigger or a default —\n     * quietly worked. The second case is the reason for the escape hatch.\n     */\n    strictWrites?: boolean;\n\n\n\n\n\n\n\n\n}\n\n// ── Driver-specific collection types ──────────────────────────────────\n\n/**\n * A collection backed by PostgreSQL (or any SQL database).\n * Adds support for SQL-style relations (JOINs) and Row Level Security.\n *\n * Use this type instead of {@link CollectionConfig} when you want\n * compile-time safety that only SQL-relevant fields appear.\n *\n * @group Models\n */\nexport interface PostgresCollectionConfig<M extends Record<string, unknown> = Record<string, unknown>, USER extends User = User>\n    extends BaseCollectionConfig<M, USER> {\n    properties: PostgresProperties;\n\n    /**\n     * The database engine for this collection. For Postgres collections this\n     * can be omitted (Postgres is the default) or set to `\"postgres\"`.\n     */\n    engine?: \"postgres\" | undefined;\n\n    /**\n     * The PostgreSQL table name for this collection.\n     */\n    table: string;\n\n    /**\n     * The PostgreSQL schema name for this table.\n     * E.g. \"public\", \"rebase\", \"auth\".\n     * If not specified, \"public\" is used (or the default search path).\n     */\n    schema?: string;\n\n    /**\n     * For SQL databases, you can define the relations between collections here.\n     * Relations describe JOINs, foreign keys, and junction tables.\n     */\n    relations?: Relation[];\n\n    /**\n     * Security rules for this collection (PostgreSQL Row Level Security).\n     * When defined, the schema generator will enable RLS on the table and\n     * create the corresponding PostgreSQL policies.\n     *\n     * Supports three levels of expressiveness:\n     * 1. **Convenience shortcuts** — `ownerField`, `access`, `roles`\n     * 2. **Raw SQL** — `using` and `withCheck` for full PostgreSQL power\n     * 3. **Combined** — mix shortcuts with `roles` for common patterns\n     *\n     * The authenticated user context is available in raw SQL via:\n     * - `auth.uid()`   — the current user's ID\n     * - `auth.roles()` — comma-separated app role IDs\n     * - `auth.jwt()`   — full JWT claims as JSONB\n     */\n    securityRules?: readonly SecurityRule[];\n\n    /**\n     * Opt out of the framework's default Row Level Security policies.\n     *\n     * The schema generator automatically injects, for every collection, a\n     * baseline SELECT policy granting the trusted server context and the\n     * `admin` role read access (reads run under a restricted role, so RLS\n     * default-denies without it). For auth collections it additionally injects\n     * a self-read policy (`id = auth.uid()`) and an admin-only write gate\n     * (INSERT/UPDATE/DELETE require the `admin` role or the trusted server\n     * context), making privileged columns such as `roles` safe by default.\n     *\n     * Author-defined `securityRules` are permissive and broaden access on top\n     * of these defaults. Set this flag to `true` to remove the defaults\n     * entirely and take full responsibility for the collection's RLS.\n     *\n     * @default false\n     */\n    disableDefaultPolicies?: boolean;\n}\n\n/**\n * A collection backed by Firebase / Firestore.\n * Adds support for subcollections (nested document collections).\n *\n * Use this type instead of {@link CollectionConfig} when you want\n * compile-time safety that only Firestore-relevant fields appear.\n *\n * @group Models\n */\nexport interface FirebaseCollectionConfig<M extends Record<string, unknown> = Record<string, unknown>, USER extends User = User>\n    extends BaseCollectionConfig<M, USER> {\n    /**\n     * The database engine for this collection. Must be set to `\"firestore\"`.\n     */\n    engine: \"firestore\";\n\n    /**\n     * Set of properties that compose a entity.\n     * Firestore collections support `reference` properties but not `relation`.\n     */\n    properties: FirebaseProperties;\n\n    /**\n     * The Firestore collection path to query. Defaults to `slug` if not set.\n     * Use this when the Firestore path differs from the slug\n     * (e.g., when a PostgreSQL collection already uses the same slug).\n     *\n     * @example\n     * ```typescript\n     * const fsCustomer: FirebaseCollectionConfig = {\n     *     slug: \"fs_customer\",        // URL: /c/fs_customer\n     *     path: \"customer\",           // Firestore path: customer\n     *     name: \"Customers (Firestore)\",\n     *     engine: \"firestore\",\n     *     properties: { ... }\n     * };\n     * ```\n     */\n    path?: string;\n\n    /**\n     * You can add subcollections to your entity in the same way you define the root\n     * collections. The collections added here will be displayed when opening\n     * the side dialog of a entity.\n     */\n    subcollections?: () => CollectionConfig<Record<string, unknown>>[];\n}\n\n/**\n * A collection backed by MongoDB.\n *\n * Use this type instead of {@link CollectionConfig} when you want\n * compile-time safety that only MongoDB-relevant fields appear.\n *\n * @group Models\n */\nexport interface MongoDBCollectionConfig<M extends Record<string, unknown> = Record<string, unknown>, USER extends User = User>\n    extends BaseCollectionConfig<M, USER> {\n\n    /**\n     * The database engine for this collection. Must be set to `\"mongodb\"`.\n     */\n    engine: \"mongodb\";\n\n    /**\n     * Set of properties that compose a entity.\n     * MongoDB collections support `reference` properties but not `relation`.\n     */\n    properties: MongoProperties;\n\n    /**\n     * The MongoDB collection name to use. Defaults to `slug` if not set.\n     * Use this when the MongoDB collection name differs from the slug\n     * (e.g., when a PostgreSQL collection already uses the same slug).\n     *\n     * @example\n     * ```typescript\n     * const mongoCustomer: MongoDBCollectionConfig = {\n     *     slug: \"mongo_customer\",      // URL: /c/mongo_customer\n     *     path: \"customer\",            // MongoDB collection: customer\n     *     name: \"Customers (MongoDB)\",\n     *     engine: \"mongodb\",\n     *     properties: { ... }\n     * };\n     * ```\n     */\n    path?: string;\n}\n\n/**\n * A collection backed by any data source.\n * This is a discriminated union — use {@link PostgresCollectionConfig},\n * {@link FirebaseCollectionConfig}, or {@link MongoDBCollectionConfig} for\n * driver-specific type safety.\n *\n * @group Models\n */\nexport type CollectionConfig<M extends Record<string, unknown> = Record<string, unknown>, USER extends User = User> =\n    | PostgresCollectionConfig<M, USER>\n    | FirebaseCollectionConfig<M, USER>\n    | MongoDBCollectionConfig<M, USER>;\n\n/**\n * A collection of *any* row type.\n *\n * `CollectionConfig` is **invariant** in `M`: `callbacks` both consumes `M`\n * (`AfterReadProps<M>`) and produces it, so neither direction of assignment\n * holds. `CollectionConfig<SomeRow>` is therefore not assignable to a bare\n * `CollectionConfig`, whose `M` defaults to `Record<string, unknown>`.\n *\n * That matters wherever a collection is merely *referred to* rather than read\n * from. `defineCollection` returns a config whose `M` is inferred from the\n * properties — the whole point of it — so a field typed `() => CollectionConfig`\n * rejects every collection the builder produces, and `target: () => otherCollection`\n * (the documented way to point a relation at its other end) does not compile in\n * any project that uses the builder.\n *\n * `any` is deliberate and is what it is for here: these positions never read the\n * target's rows, they only identify which collection is meant, so there is no\n * type safety to preserve and invariance is pure obstruction.\n *\n * @group Models\n */\nexport type AnyCollectionConfig = CollectionConfig<any, any>;\n\n/**\n * Type guard for PostgreSQL collections.\n * Returns true if the collection uses the Postgres engine (or the default engine).\n *\n * Generic over the *input* type, and narrows by intersection rather than\n * replacement. Narrowing to a bare `PostgresCollectionConfig` discarded whatever\n * the caller actually had — most visibly the admin panel's view model, whose\n * flattened presentation fields vanished the moment a collection passed through\n * one of these guards.\n *\n * @group Models\n */\nexport function isPostgresCollectionConfig<C extends CollectionConfig<any, any>>(\n    collection: C\n): collection is C & PostgresCollectionConfig<any, any> {\n    return !collection.engine || collection.engine === \"postgres\";\n}\n\n/**\n * Narrows to the SQL collection fields — `table`, `relations`,\n * `disableDefaultPolicies` — by asking the engine's declared capabilities\n * rather than by naming Postgres.\n *\n * The two halves of this already existed and were never joined. The engine\n * split (`PostgresCollectionConfig` / `FirebaseCollectionConfig` /\n * `MongoDBCollectionConfig`) said which fields belong to which engine at the\n * type level; {@link DataSourceCapabilities} said the same thing at runtime,\n * down to a `supportsRelations` flag. So call sites guarded on the capability\n * and then read a field the base type had to declare for them — which is why\n * those fields were on the base, and why a MongoDB collection could be written\n * with a `table`.\n *\n * Prefer this over {@link isPostgresCollectionConfig} wherever the question is\n * \"does this collection live in a SQL table\", so a custom SQL engine\n * registered through `registerDataSourceCapabilities` is included.\n *\n * @group Models\n */\nexport function isRelationalCollectionConfig<C extends CollectionConfig<any, any>>(\n    collection: C\n): collection is C & PostgresCollectionConfig<any, any> {\n    return getDataSourceCapabilities(collection.engine).supportsRelations;\n}\n\n/**\n * Type guard for Firebase / Firestore collections.\n * @group Models\n */\nexport function isFirebaseCollectionConfig<C extends CollectionConfig<any, any>>(\n    collection: C\n): collection is C & FirebaseCollectionConfig<any, any> {\n    return collection.engine === \"firestore\";\n}\n\n/**\n * Type guard for MongoDB collections.\n * @group Models\n */\nexport function isMongoDBCollectionConfig<C extends CollectionConfig<any, any>>(\n    collection: C\n): collection is C & MongoDBCollectionConfig<any, any> {\n    return collection.engine === \"mongodb\";\n}\n\n/**\n * Returns the data path for a collection.\n * For Firestore or MongoDB collections with a `path`, returns that value;\n * otherwise falls back to `slug`.\n */\nexport function getCollectionDataPath<M extends Record<string, unknown> = Record<string, unknown>, USER extends User = User>(\n    collection: CollectionConfig<M, USER>\n): string {\n    if (isFirebaseCollectionConfig(collection) && collection.path) {\n        return collection.path;\n    }\n    if (isMongoDBCollectionConfig(collection) && collection.path) {\n        return collection.path;\n    }\n    return collection.slug;\n}\n\n/**\n * Reads a collection's driver-declared subcollections thunk (the `subcollections`\n * field) independent of engine identity, so engine-agnostic code doesn't have to\n * type-guard against a specific driver. Returns `undefined` when the collection\n * declares none.\n *\n * Pair with `getDataSourceCapabilities(engine).supportsSubcollections` to decide\n * whether the engine honours subcollections at all before reading them.\n * @group Models\n */\nexport function getDeclaredSubcollections<M extends Record<string, unknown> = Record<string, unknown>, USER extends User = User>(\n    collection: CollectionConfig<M, USER>\n): (() => CollectionConfig<Record<string, unknown>>[]) | undefined {\n    return (collection as FirebaseCollectionConfig<M, USER>).subcollections;\n}\n\n/**\n * Where the rows in an {@link EntityChildView} come from.\n *\n * The two are not the same thing, and conflating them is what made a Postgres\n * relation borrow Firestore's addressing:\n *\n * - `subcollection` is **containment**. The rows live under the parent; the\n *   path is their identity, and they cannot exist without it. This is what\n *   Firestore has natively.\n * - `relation` is a **link**. The rows are an ordinary collection, narrowed to\n *   those the parent reaches. `owned` means the child carries the parent's\n *   foreign key and belongs to it alone; `linked` means the row is shared\n *   through a junction, so what the parent controls is the link, not the row.\n *\n * @group Models\n */\nexport type ChildViewSource =\n    | { kind: \"subcollection\" }\n    | {\n        kind: \"relation\";\n        relationKey: string;\n        mode: \"owned\" | \"linked\";\n        /**\n         * Slug of the collection the rows actually live in.\n         *\n         * Distinct from the view's `key`, which is the relation. A `linked` view\n         * needs both: the key addresses the parent's set, and this addresses the\n         * whole collection to pick an existing row out of.\n         */\n        targetSlug: string;\n    };\n\n/**\n * A list of rows rendered inside an entity view — the tab under a record.\n *\n * This is a *presentation* descriptor, which is the whole point: rendering a\n * related list as a tab used to require minting a child `CollectionConfig` with\n * its own slug, which dragged a URL grammar, a path resolver and a second\n * read/write pipeline along with it. A tab needs a key, a collection to list,\n * and to know where its rows come from.\n *\n * @group Models\n */\nexport interface EntityChildView<M extends Record<string, unknown> = Record<string, unknown>> {\n    /**\n     * Stable identifier for this view: the tab id and the path segment.\n     *\n     * For a relation this is the **relation key** — the name the backend\n     * resolves a nested path segment by — not the target collection's slug.\n     * Those differ whenever a relation is named, which is every inline relation\n     * property, and the mismatch is why such a tab used to open onto an error.\n     */\n    key: string;\n\n    /** The collection whose rows this view lists, with any overrides applied. */\n    collection: CollectionConfig<M>;\n\n    source: ChildViewSource;\n}\n\n\nexport type { WhereFilterOp, FilterValues, WireFilterValues, FilterPreset } from \"./filter-operators\";\n\n\nexport type InferCollectionConfigType<S extends CollectionConfig> = S extends CollectionConfig<infer M> ? M : never;\n\n/**\n * Configuration for authentication collections.\n *\n * Controls what happens when admins create users, reset passwords,\n * and which entity actions are auto-injected.\n *\n * Use `auth: true` as sugar for `{ enabled: true }` with all defaults.\n *\n * @example Override user creation\n * ```ts\n * auth: {\n *     enabled: true,\n *     onCreateUser: async (values, ctx) => {\n *         const hash = await ctx.hashPassword(\"welcome123\");\n *         return {\n *             values: { ...values, passwordHash: hash, emailVerified: true },\n *             temporaryPassword: \"welcome123\",\n *         };\n *     },\n * }\n * ```\n *\n * @example Disable the reset-password entity action\n * ```ts\n * auth: {\n *     enabled: true,\n *     actions: { resetPassword: false },\n * }\n * ```\n *\n * @group Models\n */\nexport interface AuthCollectionConfig {\n    /** Set to true to mark this collection as the authentication collection. */\n    enabled: boolean;\n\n    /**\n     * Called when an admin creates a user via the collection REST API.\n     *\n     * Default: generate password → hash → normalize email → save →\n     *          send invitation email (or return temp password if no email configured).\n     *\n     * Override to implement custom invitation flows, LDAP sync, etc.\n     */\n    onCreateUser?: (\n        values: Record<string, unknown>,\n        ctx: AuthCollectionContext\n    ) => Promise<AuthCollectionCreateResult>;\n\n    /**\n     * Called when an admin resets a user's password via the admin panel.\n     *\n     * Default: generate reset token → send email (or generate + return temp password).\n     * Override for custom reset flows.\n     */\n    onResetPassword?: (\n        uid: string,\n        ctx: AuthCollectionContext\n    ) => Promise<AuthCollectionResetResult>;\n\n    /**\n     * Control which auth-specific entity actions are auto-injected.\n     *\n     * Default: `{ resetPassword: true }` — the framework auto-injects\n     * the built-in `resetPasswordAction` into the collection's entity actions.\n     *\n     * Set to `false` to disable, or pass a custom `EntityAction` to replace the UI.\n     *\n     * The object form is an `EntityAction` from `@rebasepro/admin-types`, typed\n     * here as `object` because it is a React component with admin controllers in\n     * its props and nothing on the server reads it — only whether the built-in\n     * action is injected, which is the boolean.\n     */\n    actions?: {\n        resetPassword?: boolean | object;\n    };\n}\n\n/**\n * Context provided to collection-level auth hooks.\n *\n * This is a simplified facade over the server internals —\n * it exposes only what's needed for custom auth flows without\n * coupling collection config to internal interfaces.\n *\n * @group Models\n */\nexport interface AuthCollectionContext {\n    /** Hash a password using the configured algorithm (scrypt by default). */\n    hashPassword: (password: string) => Promise<string>;\n    /** Send an email. Only available when email service is configured. */\n    sendEmail?: (options: { to: string; subject: string; html: string; text?: string }) => Promise<void>;\n    /** Whether the email service is configured and available. */\n    emailConfigured: boolean;\n    /** The app name from email config (for templates). */\n    appName: string;\n    /** The base URL for password reset links. */\n    resetPasswordUrl: string;\n}\n\n/**\n * Result of a collection-level `onCreateUser` hook.\n * @group Models\n */\nexport interface AuthCollectionCreateResult {\n    /** Processed values to persist (must include passwordHash, NOT raw password). */\n    values: Record<string, unknown>;\n    /** If set, shown to the admin in the creation result dialog. */\n    temporaryPassword?: string;\n    /** Whether an invitation email was sent. */\n    invitationSent?: boolean;\n}\n\n/**\n * Result of a collection-level `onResetPassword` hook.\n * @group Models\n */\nexport interface AuthCollectionResetResult {\n    /** If set, shown to the admin. */\n    temporaryPassword?: string;\n    /** Whether a reset email was sent. */\n    invitationSent?: boolean;\n}\n","import type { AnyCollectionConfig } from \"./collections\";\n\n/**\n * @group Models\n */\nexport type OnAction = \"cascade\" | \"restrict\" | \"no action\" | \"set null\" | \"set default\";\n\n/**\n * What kind of link a relation is.\n *\n * The discriminant. Every other field a relation carries belongs to exactly one\n * of these, which is the point: a relation used to be a single open interface\n * where `cardinality`, `direction`, `localKey`, `foreignKeyOnTarget`, `through`\n * and `joinPath` were all optional and any combination typechecked. Which link\n * you meant then had to be *inferred* from which fields you happened to set,\n * and the inference was ~200 lines that guessed, fell back on naming\n * conventions, and swallowed its own failures.\n *\n * Most of that guessing produced bugs rather than convenience. A `many`\n * relation carrying a `localKey` — a combination the old type permitted — made\n * the write path stamp the parent's own foreign key onto the child row. Under\n * these kinds that state cannot be written down.\n *\n * @group Models\n */\nexport type RelationKind = \"belongsTo\" | \"hasOne\" | \"hasMany\" | \"manyToMany\" | \"via\";\n\n/** Fields every relation carries, whatever its kind. @group Models */\nexport interface RelationBase {\n    /**\n     * The name this link is addressed by: the key in `include`, the tab in the\n     * admin panel, and the path segment of a nested URL.\n     *\n     * Defaults to the declaring property's key, or to the target's slug for an\n     * entry in `relations`.\n     */\n    relationName?: string;\n\n    /** The collection on the other end. */\n    target: () => AnyCollectionConfig;\n\n    onUpdate?: OnAction;\n    onDelete?: OnAction;\n\n    /** Presentation overrides applied when this relation is rendered as a tab. */\n    overrides?: Partial<AnyCollectionConfig>;\n\n    validation?: {\n        required?: boolean;\n    };\n}\n\n/**\n * This collection holds the foreign key. One target row per source row.\n *\n * ```ts\n * author: { kind: \"belongsTo\", target: () => authors, localKey: \"author_id\" }\n * ```\n * @group Models\n */\nexport interface BelongsToRelation extends RelationBase {\n    kind: \"belongsTo\";\n    /**\n     * Column on **this** collection's table holding the target's key.\n     * Defaults to `<relationName>_id`.\n     */\n    localKey?: string;\n}\n\n/**\n * The target holds the foreign key, and at most one target row points back.\n *\n * ```ts\n * profile: { kind: \"hasOne\", target: () => profiles, foreignKeyOnTarget: \"user_id\" }\n * ```\n * @group Models\n */\nexport interface HasOneRelation extends RelationBase {\n    kind: \"hasOne\";\n    /**\n     * Column on the **target's** table holding this collection's key.\n     * Defaults to `<thisCollection>_id`.\n     */\n    foreignKeyOnTarget?: string;\n}\n\n/**\n * The target holds the foreign key, and many target rows point back. The\n * children belong to this parent alone — deleting one deletes a row.\n *\n * ```ts\n * posts: { kind: \"hasMany\", target: () => posts, foreignKeyOnTarget: \"author_id\" }\n * ```\n * @group Models\n */\nexport interface HasManyRelation extends RelationBase {\n    kind: \"hasMany\";\n    /**\n     * Column on the **target's** table holding this collection's key.\n     * Defaults to `<thisCollection>_id`.\n     */\n    foreignKeyOnTarget?: string;\n}\n\n/**\n * Both sides hold many, through a junction table. The target rows are shared,\n * so this collection owns the *link* and not the row: removing one removes a\n * junction row and leaves the target alone.\n *\n * Declared the same way from either side — there is no owning and inverse\n * version. Swap `sourceColumn` and `targetColumn` to describe the other\n * direction.\n *\n * ```ts\n * tags: { kind: \"manyToMany\", target: () => tags }\n * ```\n * @group Models\n */\nexport interface ManyToManyRelation extends RelationBase {\n    kind: \"manyToMany\";\n    /**\n     * The junction table and its two key columns. Every part defaults: the\n     * table to both table names sorted and joined, the columns to\n     * `<collection>_id` and `<relationName>_id`.\n     */\n    through?: {\n        table?: string;\n        /** Junction column holding **this** collection's key. */\n        sourceColumn?: string;\n        /** Junction column holding the **target's** key. */\n        targetColumn?: string;\n    };\n}\n\n/**\n * An explicit chain of joins, for links the four shapes above cannot express:\n * multi-hop paths, composite keys, or a join whose condition is not a plain\n * foreign key.\n *\n * Read-only. Rebase will not infer how to write through an arbitrary join\n * chain, and guessing is what this type exists to stop.\n *\n * ```ts\n * permissions: {\n *     kind: \"via\",\n *     target: () => permissions,\n *     cardinality: \"many\",\n *     joinPath: [\n *         { table: \"user_roles\",       on: { from: \"id\",            to: \"user_id\" } },\n *         { table: \"role_permissions\", on: { from: \"role_id\",       to: \"role_id\" } },\n *         { table: \"permissions\",      on: { from: \"permission_id\", to: \"id\" } }\n *     ]\n * }\n * ```\n * @group Models\n */\nexport interface ViaRelation extends RelationBase {\n    kind: \"via\";\n    /** Whether the chain yields one row or many. Cannot be derived from a join chain. */\n    cardinality: \"one\" | \"many\";\n    joinPath: JoinStep[];\n}\n\n/**\n * A link from one collection to another, as authored.\n *\n * A closed union: pick the kind that describes the link and the type offers\n * exactly the fields that kind needs. See {@link ResolvedRelation} for the form\n * the runtime works with, which has every default filled in.\n *\n * @group Models\n */\nexport type Relation =\n    | BelongsToRelation\n    | HasOneRelation\n    | HasManyRelation\n    | ManyToManyRelation\n    | ViaRelation;\n\n/**\n * A relation with every default filled in — the form the runtime works with.\n *\n * The authored {@link Relation} and this are deliberately different types.\n * They used to be one, which meant no reader could tell which fields had been\n * supplied and which had been guessed, and so every consumer re-derived what it\n * needed with its own chain of `if (through) … else if (localKey) …` fallbacks.\n * Those chains disagreed with each other; that disagreement is what produced\n * silently wrong reads and corrupt writes.\n *\n * Here each variant carries exactly its own fields, all required. A consumer\n * switches on `kind` and gets what it needs without a fallback, and the cases\n * it forgot are a compile error rather than a wrong answer at runtime.\n *\n * @group Models\n */\nexport type ResolvedRelation =\n    | ResolvedBelongsTo\n    | ResolvedHasOne\n    | ResolvedHasMany\n    | ResolvedManyToMany\n    | ResolvedVia;\n\n/** Fields present on every resolved relation. @group Models */\nexport interface ResolvedRelationBase {\n    /** Always set: defaulted during resolution if the author omitted it. */\n    relationName: string;\n    target: () => AnyCollectionConfig;\n    /** The target's slug, resolved once so consumers need not call `target()`. */\n    targetSlug: string;\n    onUpdate?: OnAction;\n    onDelete?: OnAction;\n    overrides?: Partial<AnyCollectionConfig>;\n    validation?: { required?: boolean };\n    /**\n     * Whether one row or many come back. Derived from `kind` — kept because it\n     * is what most consumers actually branch on, and because `via` is the one\n     * kind where it is authored rather than implied.\n     */\n    cardinality: \"one\" | \"many\";\n    /**\n     * Whether Rebase knows how to write through this link. False only for\n     * {@link ResolvedVia}, whose join chain it will not invent a write for.\n     */\n    writable: boolean;\n    /**\n     * Whether the target rows are shared with other parents. True for\n     * many-to-many and for multi-hop `via`: what the parent owns is the link,\n     * so removing one must not delete the row.\n     */\n    shared: boolean;\n}\n\n/** @group Models */\nexport interface ResolvedBelongsTo extends ResolvedRelationBase {\n    kind: \"belongsTo\";\n    cardinality: \"one\";\n    writable: true;\n    shared: false;\n    /** Column on this collection's table. */\n    localKey: string;\n}\n\n/** @group Models */\nexport interface ResolvedHasOne extends ResolvedRelationBase {\n    kind: \"hasOne\";\n    cardinality: \"one\";\n    writable: true;\n    shared: false;\n    /** Column on the target's table. */\n    foreignKeyOnTarget: string;\n}\n\n/** @group Models */\nexport interface ResolvedHasMany extends ResolvedRelationBase {\n    kind: \"hasMany\";\n    cardinality: \"many\";\n    writable: true;\n    shared: false;\n    /** Column on the target's table. */\n    foreignKeyOnTarget: string;\n}\n\n/** @group Models */\nexport interface ResolvedManyToMany extends ResolvedRelationBase {\n    kind: \"manyToMany\";\n    cardinality: \"many\";\n    writable: true;\n    shared: true;\n    through: {\n        table: string;\n        sourceColumn: string;\n        targetColumn: string;\n    };\n}\n\n/** @group Models */\nexport interface ResolvedVia extends ResolvedRelationBase {\n    kind: \"via\";\n    writable: false;\n    joinPath: JoinStep[];\n}\n\n// ── Narrowing helpers ────────────────────────────────────────────────\n//\n// Consumers that only care about one axis — \"does this list many rows\",\n// \"is there a column on the target\" — should ask that question rather\n// than enumerate kinds, so adding a kind later does not silently skip them.\n\n/** Relations whose target row carries this collection's key. @group Models */\nexport type ResolvedForeignKeyOnTarget = ResolvedHasOne | ResolvedHasMany;\n\n/** @group Models */\nexport function hasForeignKeyOnTarget(relation: ResolvedRelation): relation is ResolvedForeignKeyOnTarget {\n    return relation.kind === \"hasOne\" || relation.kind === \"hasMany\";\n}\n\n/** @group Models */\nexport function isManyToMany(relation: ResolvedRelation): relation is ResolvedManyToMany {\n    return relation.kind === \"manyToMany\";\n}\n\n/** @group Models */\nexport function isToMany(relation: ResolvedRelation): boolean {\n    return relation.cardinality === \"many\";\n}\n\n/**\n * Defines a single, explicit step in a multi-join path.\n *\n * Each step represents one JOIN operation in the sequence. The `from` columns\n * refer to the previous table in the chain (or the source table for the first step),\n * and the `to` columns refer to the current table being joined.\n *\n * @example Single column join:\n * ```typescript\n * {\n *   table: \"authors\",\n *   on: {\n *     from: \"author_id\",  // Column from previous table (e.g., posts.author_id)\n *     to: \"id\"           // Column from current table (authors.id)\n *   }\n * }\n * ```\n *\n * @example Multi-column composite key join:\n * ```typescript\n * {\n *   table: \"order_items\",\n *   on: {\n *     from: [\"order_id\", \"store_id\"],    // Multiple columns from previous table\n *     to: [\"order_id\", \"store_id\"]       // Corresponding columns in current table\n *   }\n * }\n * ```\n */\nexport interface JoinStep {\n    /**\n     * The database table name to join TO in this step.\n     * This is the table you're joining into, not the table you're joining from.\n     *\n     * @example \"authors\", \"user_roles\", \"product_categories\"\n     */\n    table: string;\n\n    /**\n     * The join condition for this step. Defines how the previous table\n     * connects to the current table.\n     *\n     * - `from`: Column name(s) on the PREVIOUS table in the join chain\n     * - `to`: Column name(s) on the CURRENT table (specified in `table`)\n     *\n     * For the first step, `from` refers to the source collection's table.\n     * For subsequent steps, `from` refers to the table from the previous step.\n     *\n     * Both `from` and `to` support:\n     * - Single column: `\"user_id\"`\n     * - Multiple columns: `[\"company_id\", \"region_id\"]` for composite keys\n     *\n     * When using arrays, both `from` and `to` must have the same length,\n     * and columns are matched by position (index 0 with index 0, etc.).\n     */\n    on: {\n        from: string | string[];\n        to: string | string[];\n    };\n}\n","/**\n * Structured, engine-agnostic policy expressions.\n *\n * A {@link PolicyExpression} is the single source of truth for a row-level\n * security condition. It is compiled to Postgres `USING`/`WITH CHECK` SQL\n * (authoritative enforcement) and independently evaluated in JavaScript (to\n * drive the admin UI, and — in future — to enforce on engines without native\n * RLS such as MongoDB). Because both the SQL and the JS decision derive from\n * the *same* expression, the UI matches database enforcement by construction —\n * no drift between two hand-written implementations.\n *\n * The only escape hatch that cannot be evaluated client-side is the\n * {@link RawPolicyExpression} node (`{ kind: \"raw\" }`): it preserves full\n * PostgreSQL power but, being arbitrary SQL, is treated as *unknown* by the\n * JavaScript evaluator (never silently allowed) and reflected exactly in the UI\n * via server-computed capability flags.\n *\n * @group Models\n */\nexport type PolicyExpression =\n    | TruePolicyExpression\n    | FalsePolicyExpression\n    | AndPolicyExpression\n    | OrPolicyExpression\n    | NotPolicyExpression\n    | ComparePolicyExpression\n    | RolesOverlapPolicyExpression\n    | RolesContainPolicyExpression\n    | AuthenticatedPolicyExpression\n    | ServerContextPolicyExpression\n    | ExistsInPolicyExpression\n    | RawPolicyExpression;\n\n/**\n * The id a request without a logged-in user reports as `auth.uid()`.\n *\n * A user-context request always sets `app.uid`: blank would read back as\n * `NULL`, and `NULL` is how the trusted server context is recognised, so an\n * anonymous visitor would be promoted to server privileges. The driver\n * therefore substitutes this sentinel at the single chokepoint where the GUC\n * is set.\n *\n * The consequence for policy authors is that **`auth.uid() IS NOT NULL` is a\n * tautology on the user path** — it is true for anonymous visitors too. Use\n * {@link policy.authenticated} (or `auth.uid() <> 'anonymous'`) to mean \"signed\n * in\", and {@link policy.serverContext} to mean \"the trusted server context\".\n *\n * @group Models\n */\nexport const ANONYMOUS_USER_ID = \"anonymous\";\n\n/** Always allows. Compiles to `true`. @group Models */\nexport interface TruePolicyExpression {\n    kind: \"true\";\n}\n\n/** Always denies. Compiles to `false`. @group Models */\nexport interface FalsePolicyExpression {\n    kind: \"false\";\n}\n\n/** Logical AND — every operand must pass. @group Models */\nexport interface AndPolicyExpression {\n    kind: \"and\";\n    operands: readonly PolicyExpression[];\n}\n\n/** Logical OR — at least one operand must pass. @group Models */\nexport interface OrPolicyExpression {\n    kind: \"or\";\n    operands: readonly PolicyExpression[];\n}\n\n/** Logical negation. @group Models */\nexport interface NotPolicyExpression {\n    kind: \"not\";\n    operand: PolicyExpression;\n}\n\n/** Comparison operators available to {@link ComparePolicyExpression}. @group Models */\nexport type PolicyCompareOperator = \"eq\" | \"neq\" | \"lt\" | \"lte\" | \"gt\" | \"gte\";\n\n/**\n * Compares two operands, e.g. `owner_id = auth.uid()`.\n * @group Models\n */\nexport interface ComparePolicyExpression {\n    kind: \"compare\";\n    op: PolicyCompareOperator;\n    left: PolicyOperand;\n    right: PolicyOperand;\n}\n\n/**\n * True when the user holds *at least one* of the given application roles.\n * Compiles to `string_to_array(auth.roles(), ',') && ARRAY[...]`.\n * @group Models\n */\nexport interface RolesOverlapPolicyExpression {\n    kind: \"rolesOverlap\";\n    roles: readonly string[];\n}\n\n/**\n * True when the user holds *all* of the given application roles.\n * Compiles to `string_to_array(auth.roles(), ',') @> ARRAY[...]`.\n * @group Models\n */\nexport interface RolesContainPolicyExpression {\n    kind: \"rolesContain\";\n    roles: readonly string[];\n}\n\n/**\n * True when a signed-in user is making the request. Compiles to\n * `auth.uid() IS NOT NULL AND auth.uid() <> 'anonymous'`.\n *\n * Both halves are load-bearing. `IS NOT NULL` excludes the server context;\n * the {@link ANONYMOUS_USER_ID} comparison excludes anonymous visitors, who\n * *do* carry a non-null `auth.uid()`. Checking only `IS NOT NULL` grants to\n * everyone — see {@link ANONYMOUS_USER_ID}.\n *\n * `policy.not(policy.authenticated())` therefore means \"anonymous visitor or\n * the server context\". To single out the server context, use\n * {@link ServerContextPolicyExpression}.\n * @group Models\n */\nexport interface AuthenticatedPolicyExpression {\n    kind: \"authenticated\";\n}\n\n/**\n * True only in the trusted **server context** — the built-in flows that run\n * without a user (signup, migrations, `dataAsAdmin`) set no user GUC, so\n * `auth.uid()` is `NULL` for them and only for them. Compiles to\n * `auth.uid() IS NULL`.\n *\n * This is what lets the owner connection satisfy a policy even under FORCE RLS.\n * It is deliberately a primitive rather than `not(authenticated())`: the two\n * meant the same thing while `authenticated` ignored {@link ANONYMOUS_USER_ID},\n * and conflating them is what turns a server-only grant into an anonymous one.\n *\n * The JavaScript evaluator always returns `false` for this node — a client is\n * never the server context.\n * @group Models\n */\nexport interface ServerContextPolicyExpression {\n    kind: \"serverContext\";\n}\n\n/**\n * Membership / relational access: true when at least one row exists in another\n * collection (a join/membership table) matching `where`. This is what lets you\n * scope reads to \"rows whose team the caller belongs to\" without an N+1\n * per-row lookup — it compiles to a single correlated `EXISTS` subquery.\n *\n * Inside `where`, {@link FieldPolicyOperand} (`policy.field`) references a column\n * of the joined collection, while {@link OuterFieldPolicyOperand}\n * (`policy.outerField`) references a column of the row being checked (the outer\n * table under RLS). Combine with {@link AuthUidPolicyOperand} to correlate to\n * the caller.\n *\n * @example\n * ```ts\n * // documents visible only to members of the document's team:\n * policy.existsIn({\n *   collection: \"team_members\",\n *   where: policy.and(\n *     policy.compare(policy.field(\"team_id\"), \"eq\", policy.outerField(\"team_id\")),\n *     policy.compare(policy.field(\"user_id\"), \"eq\", policy.authUid()),\n *   ),\n * })\n * // → EXISTS (SELECT 1 FROM team_members _ex0\n * //           WHERE _ex0.team_id = documents.team_id AND _ex0.user_id = auth.uid())\n * ```\n *\n * Postgres-authoritative: like {@link RawPolicyExpression}, the JavaScript\n * evaluator treats it as *unknown* (it cannot run a subquery client-side), so\n * enforcement is always the database's.\n * @group Models\n */\nexport interface ExistsInPolicyExpression {\n    kind: \"existsIn\";\n    /** Slug of the collection to search (the join / membership table). */\n    collection: string;\n    /** Condition evaluated against the joined collection's rows. */\n    where: PolicyExpression;\n}\n\n/**\n * A raw PostgreSQL boolean expression — the full-power escape hatch.\n *\n * Columns can be referenced as `{column_name}`. This is Postgres-only and\n * **server-authoritative**: the JavaScript evaluator cannot evaluate arbitrary\n * SQL, so it treats this node as *unknown* rather than guessing.\n * @group Models\n */\nexport interface RawPolicyExpression {\n    kind: \"raw\";\n    sql: string;\n}\n\n/**\n * An operand referenced by a {@link ComparePolicyExpression}.\n * @group Models\n */\nexport type PolicyOperand =\n    | FieldPolicyOperand\n    | OuterFieldPolicyOperand\n    | LiteralPolicyOperand\n    | AuthUidPolicyOperand\n    | AuthRolesPolicyOperand;\n\n/** A column value on the row being evaluated. @group Models */\nexport interface FieldPolicyOperand {\n    kind: \"field\";\n    /** The property/column name (resolved to its DB column when compiled). */\n    name: string;\n}\n\n/**\n * A column value on the *outer* row when used inside {@link ExistsInPolicyExpression}\n * — i.e. the row the RLS policy is being evaluated for, referenced from within the\n * subquery. Outside an `existsIn` it is equivalent to {@link FieldPolicyOperand}.\n * @group Models\n */\nexport interface OuterFieldPolicyOperand {\n    kind: \"outerField\";\n    /** The property/column name on the outer collection. */\n    name: string;\n}\n\n/** A constant value. @group Models */\nexport interface LiteralPolicyOperand {\n    kind: \"literal\";\n    value: string | number | boolean | null;\n}\n\n/** The current user's id — compiles to `auth.uid()`. @group Models */\nexport interface AuthUidPolicyOperand {\n    kind: \"authUid\";\n}\n\n/**\n * The current user's roles as an array — compiles to\n * `string_to_array(auth.roles(), ',')`.\n * @group Models\n */\nexport interface AuthRolesPolicyOperand {\n    kind: \"authRoles\";\n}\n\n// ── Constructor helpers ──────────────────────────────────────────────\n// Small, dependency-free builders so callers (and the desugaring in\n// `@rebasepro/common`) can assemble expressions without object-literal noise.\n\n/** @group Models */\nexport const policy = {\n    true: (): TruePolicyExpression => ({ kind: \"true\" }),\n    false: (): FalsePolicyExpression => ({ kind: \"false\" }),\n    and: (...operands: readonly PolicyExpression[]): AndPolicyExpression => ({ kind: \"and\",\noperands: operands as PolicyExpression[] }),\n    or: (...operands: readonly PolicyExpression[]): OrPolicyExpression => ({ kind: \"or\",\noperands: operands as PolicyExpression[] }),\n    not: (operand: PolicyExpression): NotPolicyExpression => ({ kind: \"not\",\noperand }),\n    compare: (left: PolicyOperand, op: PolicyCompareOperator, right: PolicyOperand): ComparePolicyExpression =>\n        ({ kind: \"compare\",\nop,\nleft,\nright }),\n    rolesOverlap: (roles: readonly string[]): RolesOverlapPolicyExpression => ({ kind: \"rolesOverlap\",\nroles: roles as string[] }),\n    rolesContain: (roles: readonly string[]): RolesContainPolicyExpression => ({ kind: \"rolesContain\",\nroles: roles as string[] }),\n    authenticated: (): AuthenticatedPolicyExpression => ({ kind: \"authenticated\" }),\n    serverContext: (): ServerContextPolicyExpression => ({ kind: \"serverContext\" }),\n    existsIn: (args: { collection: string; where: PolicyExpression }): ExistsInPolicyExpression =>\n        ({ kind: \"existsIn\",\ncollection: args.collection,\nwhere: args.where }),\n    raw: (sql: string): RawPolicyExpression => ({ kind: \"raw\",\nsql }),\n    field: (name: string): FieldPolicyOperand => ({ kind: \"field\",\nname }),\n    outerField: (name: string): OuterFieldPolicyOperand => ({ kind: \"outerField\",\nname }),\n    literal: (value: string | number | boolean | null): LiteralPolicyOperand => ({ kind: \"literal\",\nvalue }),\n    authUid: (): AuthUidPolicyOperand => ({ kind: \"authUid\" }),\n    authRoles: (): AuthRolesPolicyOperand => ({ kind: \"authRoles\" })\n};\n","import type { CollectionConfig, FilterValues, WhereFilterOp } from \"./collections\";\nimport type { AuthAdapter } from \"./auth_adapter\";\nimport type { HistoryConfig } from \"../controllers/client\";\nimport type { ChannelBusSetting } from \"./channel_bus\";\n\n// =============================================================================\n// DATABASE CONNECTION INTERFACES\n// =============================================================================\n\n/**\n * Abstract database connection interface.\n * Represents a connection to any database system.\n */\nexport interface DatabaseConnection {\n    /**\n     * Type identifier for this database (e.g., 'postgres', 'mongodb', 'mysql')\n     */\n    readonly type: string;\n\n    /**\n     * Whether the connection is currently active\n     */\n    readonly isConnected?: boolean;\n\n    /**\n     * Close the database connection and release resources.\n     */\n    close?(): Promise<void>;\n}\n\n// =============================================================================\n// QUERY BUILDING INTERFACES\n// =============================================================================\n\n/**\n * A single filter condition for database queries\n */\nexport interface QueryFilter {\n    field: string;\n    operator: WhereFilterOp;\n    value: unknown;\n}\n\n/**\n * Options for fetching a collection of entities\n */\nexport interface FetchCollectionOptions<M extends Record<string, unknown> = Record<string, unknown>> {\n    filter?: FilterValues<Extract<keyof M, string>>;\n    orderBy?: string;\n    order?: \"desc\" | \"asc\";\n    limit?: number;\n    offset?: number;\n    startAfter?: unknown;\n    searchString?: string;\n    databaseId?: string;\n    collection?: CollectionConfig;\n}\n\n/**\n * Options for searching entities\n */\nexport interface SearchOptions<M extends Record<string, unknown> = Record<string, unknown>> {\n    filter?: FilterValues<Extract<keyof M, string>>;\n    orderBy?: string;\n    order?: \"desc\" | \"asc\";\n    limit?: number;\n    databaseId?: string;\n    collection?: CollectionConfig;\n}\n\n/**\n * Options for counting entities\n */\nexport interface CountOptions<M extends Record<string, unknown> = Record<string, unknown>> {\n    filter?: FilterValues<Extract<keyof M, string>>;\n    searchString?: string;\n    databaseId?: string;\n}\n\n/**\n * Abstract condition builder interface.\n * Implementations translate Rebase filter conditions to database-specific queries.\n *\n * Note: This interface can be implemented as instance methods or as a class with static methods.\n * For static implementations (like DrizzleConditionBuilder), use the ConditionBuilderStatic type.\n *\n * @template T The type of condition returned by the builder (e.g., SQL for PostgreSQL, Filter<Document> for MongoDB)\n */\nexport interface ConditionBuilder<T = unknown> {\n    /**\n     * Build filter conditions from Rebase FilterValues\n     */\n    buildFilterConditions<M extends Record<string, unknown>>(\n        filter: FilterValues<Extract<keyof M, string>>,\n        collectionPath: string,\n        ...args: unknown[]\n    ): T[];\n\n    /**\n     * Build search conditions for text search\n     */\n    buildSearchConditions(\n        searchString: string,\n        properties: Record<string, unknown>,\n        ...args: unknown[]\n    ): T[];\n\n    /**\n     * Combine multiple conditions with AND operator\n     */\n    combineConditionsWithAnd(conditions: T[]): T | undefined;\n\n    /**\n     * Combine multiple conditions with OR operator\n     */\n    combineConditionsWithOr(conditions: T[]): T | undefined;\n}\n\n/**\n * Static condition builder type for implementations using static methods.\n * Use this type when the class provides static methods rather than instance methods.\n *\n * @example\n * // DrizzleConditionBuilder satisfies this type\n * const builder: ConditionBuilderStatic<SQL> = DrizzleConditionBuilder;\n */\nexport type ConditionBuilderStatic<T = unknown> = {\n    buildFilterConditions<M extends Record<string, unknown>>(\n        filter: FilterValues<Extract<keyof M, string>>,\n        ...args: unknown[]\n    ): T[];\n    buildSearchConditions(\n        searchString: string,\n        properties: Record<string, unknown>,\n        ...args: unknown[]\n    ): T[];\n    combineConditionsWithAnd(conditions: T[]): T | undefined;\n    combineConditionsWithOr(conditions: T[]): T | undefined;\n};\n\n// =============================================================================\n// ENTITY REPOSITORY INTERFACES\n// =============================================================================\n\n/**\n * Abstract entity repository interface.\n * Handles all CRUD operations for entities in the database.\n *\n * Implementations should handle:\n * - Entity serialization/deserialization\n * - Relation resolution\n * - ID generation and conversion\n */\nexport interface DataRepository {\n    /**\n     * Fetch a single entity by ID\n     */\n    fetchOne<M extends Record<string, unknown>>(\n        collectionPath: string,\n        id: string | number,\n        databaseId?: string\n    ): Promise<Record<string, unknown> | undefined>;\n\n    /**\n     * Fetch a collection of entities with optional filtering, ordering, and pagination\n     */\n    fetchCollection<M extends Record<string, unknown>>(\n        collectionPath: string,\n        options?: FetchCollectionOptions<M>\n    ): Promise<Record<string, unknown>[]>;\n\n    /**\n     * Search entities by text\n     */\n    searchRows<M extends Record<string, unknown>>(\n        collectionPath: string,\n        searchString: string,\n        options?: SearchOptions<M>\n    ): Promise<Record<string, unknown>[]>;\n\n    /**\n     * Count entities in a collection\n     */\n    count<M extends Record<string, unknown>>(\n        collectionPath: string,\n        options?: CountOptions<M>\n    ): Promise<number>;\n\n    /**\n     * Save a entity (create or update)\n     */\n    save<M extends Record<string, unknown>>(\n        collectionPath: string,\n        values: Partial<M>,\n        id?: string | number,\n        databaseId?: string\n    ): Promise<Record<string, unknown>>;\n\n    /**\n     * Delete a entity by ID\n     */\n    delete(\n        collectionPath: string,\n        id: string | number,\n        databaseId?: string\n    ): Promise<void>;\n\n    /**\n     * Check if a field value is unique in a collection\n     */\n    checkUniqueField(\n        collectionPath: string,\n        fieldName: string,\n        value: unknown,\n        excludeEntityId?: string,\n        databaseId?: string\n    ): Promise<boolean>;\n\n}\n\n// =============================================================================\n// REALTIME INTERFACES\n// =============================================================================\n\n/**\n * Configuration for subscribing to a collection\n */\nexport interface CollectionSubscriptionConfig {\n    clientId: string;\n    path: string;\n    filter?: unknown;\n    orderBy?: string;\n    order?: \"desc\" | \"asc\";\n    limit?: number;\n    startAfter?: unknown;\n    databaseId?: string;\n    searchString?: string;\n}\n\n/**\n * Configuration for subscribing to a single entity\n */\nexport interface SingleSubscriptionConfig {\n    clientId: string;\n    path: string;\n    id: string | number;\n}\n\n/**\n * Opt-in retention for one set of broadcast channels.\n *\n * Retention is configured on the server and nowhere else. A channel is created\n * by whoever names it, so letting a client ask for its own history depth would\n * let any visitor commit the backend to unbounded storage; and presence-only or\n * notification-only channels — the overwhelming majority — must not pay for a\n * feature they never use. With no rules configured nothing is written, no table\n * is created, and broadcast behaves exactly as it did before history existed.\n */\nexport interface ChannelRetentionRule {\n    /**\n     * Channel name to match. Either exact (`\"doc:42\"`) or a trailing-`*` prefix\n     * (`\"doc:*\"`). Deliberately not a full glob or RegExp: this decides what\n     * gets written to disk, and a rule whose blast radius is not obvious at a\n     * glance is the wrong shape for that.\n     */\n    match: string;\n    /** Keep at most this many of the most recent messages per channel. */\n    limit?: number;\n    /**\n     * Keep messages for at most this long. Accepts a millisecond count or a\n     * short duration string (`\"30s\"`, `\"15m\"`, `\"24h\"`, `\"7d\"`).\n     */\n    ttl?: number | string;\n}\n\n/**\n * Server-side realtime options.\n *\n * The channel bus contract and its config live in `./channel_bus` so that a\n * transport shipped as its own package depends on the contract alone.\n */\nexport interface RealtimeChannelsConfig {\n    /**\n     * Retention rules, most specific first — the first match wins. Omitted or\n     * empty means no channel retains anything.\n     */\n    channels?: ChannelRetentionRule[];\n    /**\n     * How channel broadcast and presence reach other backend instances.\n     * Defaults to `{ type: \"memory\" }` — i.e. they don't.\n     */\n    bus?: ChannelBusSetting;\n}\n\n/**\n * Abstract realtime provider interface.\n * Handles real-time subscriptions and notifications for entity changes.\n */\nexport interface RealtimeProvider {\n    /**\n     * Subscribe to collection changes\n     */\n    subscribeToCollection(\n        subscriptionId: string,\n        config: CollectionSubscriptionConfig,\n        callback?: (rows: Record<string, unknown>[]) => void\n    ): void;\n\n    /**\n     * Subscribe to single entity changes\n     */\n    subscribeToOne(\n        subscriptionId: string,\n        config: SingleSubscriptionConfig,\n        callback?: (row: Record<string, unknown> | null) => void\n    ): void;\n\n    /**\n     * Unsubscribe from a subscription\n     */\n    unsubscribe(subscriptionId: string): void;\n\n    /**\n     * Notify all relevant subscribers of a entity update\n     */\n    notifyUpdate(\n        path: string,\n        id: string,\n        row: Record<string, unknown> | null,\n        databaseId?: string\n    ): Promise<void>;\n\n    /**\n     * Called when the HTTP server is ready and listening.\n     * Useful for providers that need the server address for callbacks.\n     */\n    onServerReady?(serverInfo: { port: number; hostname?: string }): void;\n\n    /**\n     * Gracefully shut down the realtime provider.\n     * Called during server shutdown to clean up resources.\n     */\n    destroy?(): Promise<void>;\n\n    /**\n     * Stop the internal LISTEN client (e.g., PostgreSQL LISTEN/NOTIFY).\n     * Called during graceful shutdown before closing database connections.\n     */\n    stopListening?(): Promise<void>;\n}\n\n// =============================================================================\n// COLLECTION REGISTRY INTERFACES\n// =============================================================================\n\n/**\n * Abstract collection registry interface.\n * Manages registration and lookup of entity collections.\n */\nexport interface CollectionRegistryInterface {\n    /**\n     * Register a collection\n     */\n    register(collection: CollectionConfig): void;\n\n    /**\n     * Get a collection by its path\n     */\n    getCollectionByPath(path: string): CollectionConfig | undefined;\n\n    /**\n     * Get all registered collections\n     */\n    getCollections(): CollectionConfig[];\n\n    /**\n     * Get the currently registered global callbacks, if any.\n     */\n    getGlobalCallbacks(): any | undefined;\n}\n\n// =============================================================================\n// DATA TRANSFORMER INTERFACES\n// =============================================================================\n\n/**\n * Abstract data transformer interface.\n * Handles serialization/deserialization between frontend and database formats.\n */\nexport interface DataTransformer {\n    /**\n     * Transform entity data for storage in the database\n     */\n    serializeToDatabase<M extends Record<string, unknown>>(\n        entity: M,\n        collection: CollectionConfig\n    ): Record<string, unknown>;\n\n    /**\n     * Transform database data back to entity format\n     */\n    deserializeFromDatabase<M extends Record<string, unknown>>(\n        data: Record<string, unknown>,\n        collection: CollectionConfig\n    ): Promise<M>;\n}\n\n// =============================================================================\n// DATABASE ADMIN — CAPABILITY-SPECIFIC INTERFACES (1.3)\n// =============================================================================\n\n/**\n * Administrative operations for SQL-based databases (PostgreSQL, MySQL, etc.).\n * Used by the SQL Editor, RLS Editor, and schema browser.\n *\n * @group Admin\n */\nexport interface SQLAdmin {\n    /**\n     * Execute raw SQL against the database.\n     */\n    executeSql(sql: string, options?: { database?: string; role?: string; params?: unknown[] }): Promise<Record<string, unknown>[]>;\n\n    /**\n     * Fetch the available databases on the server.\n     */\n    fetchAvailableDatabases?(): Promise<string[]>;\n\n    /**\n     * Fetch the available *native PostgreSQL* database roles (from `pg_roles`).\n     *\n     * These are connection-level roles — what the SQL editor can `SET ROLE` to,\n     * and what `SecurityRule.pgRoles` targets. They are NOT application roles;\n     * for those use {@link fetchApplicationRoles}.\n     */\n    fetchAvailableRoles?(): Promise<string[]>;\n\n    /**\n     * Fetch the *application-level* roles in use in this project.\n     *\n     * These are the strings stored on the users table's `roles` column and\n     * exposed to policies as `auth.roles()` — what `SecurityRule.roles`\n     * matches against. Distinct from {@link fetchAvailableRoles}; the two are\n     * not interchangeable.\n     */\n    fetchApplicationRoles?(): Promise<string[]>;\n\n    /**\n     * Fetch the current database name.\n     */\n    fetchCurrentDatabase?(): Promise<string | undefined>;\n}\n\n/**\n * Administrative operations for document-based databases (MongoDB, Firestore, etc.).\n * Used by future document administration tools.\n *\n * @group Admin\n */\nexport interface DocumentAdmin {\n    /**\n     * Execute an aggregation pipeline or equivalent query.\n     */\n    executeAggregate?(pipeline: Record<string, unknown>[]): Promise<Record<string, unknown>[]>;\n\n    /**\n     * Fetch statistics for a collection (document count, size, etc.).\n     */\n    fetchCollectionStats?(collectionName: string): Promise<{ count: number; sizeBytes?: number }>;\n}\n\n/**\n * Administrative operations for schema management.\n * Shared across SQL and document databases.\n *\n * @group Admin\n */\nexport interface SchemaAdmin {\n    /**\n     * Fetch database tables/collections not yet mapped to a Rebase collection.\n     */\n    fetchUnmappedTables?(mappedPaths?: string[]): Promise<string[]>;\n\n    /**\n     * Fetch column/field metadata for a single table/collection.\n     * The return type is generic — SQL backends return TableMetadata,\n     * document backends may return a different shape.\n     */\n    fetchTableMetadata?(tableName: string): Promise<unknown>;\n}\n\n/**\n * Metadata for a database branch.\n * @group Admin\n */\nexport interface BranchInfo {\n    /** Branch name (without prefix). */\n    name: string;\n    /** The database this branch was created from. */\n    parentDatabase: string;\n    /** When the branch was created. */\n    createdAt: Date;\n    /** Size in bytes, if available from the server. */\n    sizeBytes?: number;\n}\n\n/**\n * Administrative operations for database branching.\n * Allows creating isolated database copies for development/preview workflows.\n *\n * @group Admin\n */\nexport interface BranchAdmin {\n    /** Create a new branch (database copy) from the current or specified source database. */\n    createBranch(name: string, options?: { source?: string }): Promise<BranchInfo>;\n\n    /** Delete a branch database. Cannot delete the main/default database. */\n    deleteBranch(name: string): Promise<void>;\n\n    /** List all branches (databases that were created via branching). */\n    listBranches(): Promise<BranchInfo[]>;\n\n    /** Get info about a specific branch. */\n    getBranchInfo(name: string): Promise<BranchInfo | undefined>;\n}\n\n/**\n * Union type for all admin capabilities.\n * A backend may implement any combination of these interfaces.\n *\n * Use type guards (`isSQLAdmin`, `isDocumentAdmin`, `isSchemaAdmin`, `isBranchAdmin`)\n * to safely narrow the type before calling methods.\n *\n * @group Admin\n */\nexport type DatabaseAdmin = Partial<SQLAdmin> & Partial<DocumentAdmin> & Partial<SchemaAdmin> & Partial<BranchAdmin>;\n\n/**\n * Type guard: does this admin support SQL operations?\n * @group Admin\n */\nexport function isSQLAdmin(admin: DatabaseAdmin | undefined): admin is SQLAdmin {\n    return !!admin && typeof (admin as SQLAdmin).executeSql === \"function\";\n}\n\n/**\n * Type guard: does this admin support document operations?\n * @group Admin\n */\nexport function isDocumentAdmin(admin: DatabaseAdmin | undefined): admin is DocumentAdmin {\n    return !!admin && (\n        typeof (admin as DocumentAdmin).executeAggregate === \"function\" ||\n        typeof (admin as DocumentAdmin).fetchCollectionStats === \"function\"\n    );\n}\n\n/**\n * Type guard: does this admin support schema management?\n * @group Admin\n */\nexport function isSchemaAdmin(admin: DatabaseAdmin | undefined): admin is SchemaAdmin {\n    return !!admin && (\n        typeof (admin as SchemaAdmin).fetchUnmappedTables === \"function\" ||\n        typeof (admin as SchemaAdmin).fetchTableMetadata === \"function\"\n    );\n}\n\n/**\n * Type guard: does this admin support database branching?\n * @group Admin\n */\nexport function isBranchAdmin(admin: DatabaseAdmin | undefined): admin is BranchAdmin {\n    return !!admin && typeof (admin as BranchAdmin).createBranch === \"function\";\n}\n\n// =============================================================================\n// LIFECYCLE INTERFACES (1.4)\n// =============================================================================\n\n/**\n * Health check result returned by `healthCheck()`.\n * @group Lifecycle\n */\nexport interface HealthCheckResult {\n    /** Whether the backend is healthy and able to serve requests. */\n    healthy: boolean;\n    /** Round-trip latency to the database in milliseconds. */\n    latencyMs: number;\n    /** Optional details (e.g., pool stats, replication lag). */\n    details?: Record<string, unknown>;\n}\n\n/**\n * Lifecycle contract for backend components that hold resources\n * (database connections, WebSocket pools, timers, etc.).\n *\n * All methods are optional — simple backends (e.g., in-memory) can skip them.\n * @group Lifecycle\n */\nexport interface BackendLifecycle {\n    /**\n     * Initialize the backend: open connections, run migrations, seed data.\n     * Called once during startup. Idempotent.\n     */\n    initialize?(): Promise<void>;\n\n    /**\n     * Check whether the backend is healthy and reachable.\n     * Should be fast (< 1 s) and safe to call frequently.\n     */\n    healthCheck?(): Promise<HealthCheckResult>;\n\n    /**\n     * Gracefully shut down: close connections, flush buffers, cancel timers.\n     * After calling `destroy()`, no other methods should be called.\n     */\n    destroy?(): Promise<void>;\n}\n\n// =============================================================================\n// BACKEND FACTORY INTERFACES\n// =============================================================================\n\n/**\n * Configuration for creating a database backend\n */\nexport interface BackendConfig {\n    /**\n     * Type of database backend\n     */\n    type: string;\n\n    /**\n     * Database connection (implementation-specific)\n     */\n    connection: unknown;\n\n    /**\n     * Schema definition (implementation-specific, e.g., Drizzle schema for PostgreSQL)\n     */\n    schema?: unknown;\n}\n\n/**\n * A complete backend instance with all required services.\n *\n * Now includes optional lifecycle management and admin capabilities.\n */\nexport interface BackendInstance extends BackendLifecycle {\n    /**\n     * Entity repository for CRUD operations\n     */\n    entityRepository: DataRepository;\n\n    /**\n     * Realtime provider for subscriptions\n     */\n    realtimeProvider: RealtimeProvider;\n\n    /**\n     * Collection registry\n     */\n    collectionRegistry: CollectionRegistryInterface;\n\n    /**\n     * The underlying database connection\n     */\n    connection: DatabaseConnection;\n\n    /**\n     * Administrative operations (SQL, schema, documents).\n     * What's available depends on the backend type — use type guards\n     * (`isSQLAdmin`, `isSchemaAdmin`, etc.) to narrow.\n     */\n    admin?: DatabaseAdmin;\n}\n\n/**\n * Factory function type for creating backend instances\n */\nexport type BackendFactory<TConfig extends BackendConfig = BackendConfig> =\n    (config: TConfig) => BackendInstance;\n\n// =============================================================================\n// BACKEND BOOTSTRAPPER (1.2)\n// =============================================================================\n\n/**\n * A `BackendBootstrapper` encapsulates all driver-specific initialization logic.\n *\n * Instead of hard-coding Postgres setup into `initializeRebaseBackend()`,\n * each database backend provides its own bootstrapper that knows how to:\n * - Create the DataDriver from a config object\n * - Optionally initialize auth tables\n * - Optionally create a realtime service\n * - Mount driver-specific API routes\n *\n * The main `initializeRebaseBackend()` becomes a **coordinator** that iterates\n * registered bootstrappers, calls their hooks, and wires the results together.\n *\n * @group Backend\n *\n * @example\n * ```typescript\n * // Third-party MySQL bootstrapper\n * const mysqlBootstrapper: BackendBootstrapper = {\n *   type: \"mysql\",\n *   initializeDriver: async (config) => new MySQLDataDriver(config.connection),\n *   initializeRealtime: async (config) => new MySQLChangeStreamRealtime(config.connection),\n * };\n *\n * initializeRebaseBackend({\n *   ...config,\n *   bootstrappers: [postgresBootstrapper, mysqlBootstrapper]\n * });\n * ```\n */\nexport interface BackendBootstrapper {\n    /**\n     * Which driver type this bootstrapper handles.\n     * Must match the `type` field on the driver config object\n     * (e.g., `\"postgres\"`, `\"mongodb\"`, `\"mysql\"`).\n     */\n    type: string;\n\n    /**\n     * Unique identifier for this bootstrapper instance.\n     * Used to register the driver in the driver registry.\n     * Defaults to `type` if not set.\n     */\n    id?: string;\n\n    /**\n     * Whether this bootstrapper provides the default driver.\n     * When true, the coordinator uses this driver as the primary one.\n     */\n    isDefault?: boolean;\n\n    /**\n     * Run database migrations for this driver.\n     * Called by the coordinator after all drivers are initialized.\n     */\n    runMigrations?(config: unknown, driverResult: InitializedDriver): Promise<void>;\n\n    /**\n     * Create a DataDriver from the given config.\n     * This is the only **required** method.\n     */\n    initializeDriver(config: unknown): Promise<InitializedDriver>;\n\n    /**\n     * Initialize auth tables / services if this driver supports them.\n     * Return undefined if auth is not supported by this backend.\n     */\n    initializeAuth?(config: unknown, driverResult: InitializedDriver): Promise<BootstrappedAuth | undefined>;\n\n    /**\n     * Initialize history tables / services if this driver supports them.\n     * Return undefined if history is not supported by this backend.\n     */\n    initializeHistory?(config: HistoryConfig, driverResult: InitializedDriver): Promise<{ historyService: unknown } | undefined>;\n\n    /**\n     * Create a realtime provider for this driver.\n     * Return undefined if the driver does not support realtime.\n     */\n    initializeRealtime?(config: unknown, driverResult: InitializedDriver): Promise<RealtimeProvider | undefined>;\n\n    /**\n     * Mount any driver-specific HTTP routes (e.g., custom admin endpoints).\n     * Called after all drivers are initialized.\n     */\n    mountRoutes?(app: unknown, basePath: string, driverResult: InitializedDriver): void;\n\n    /**\n     * Return admin capabilities for this driver.\n     */\n    getAdmin?(driverResult: InitializedDriver): DatabaseAdmin | undefined;\n\n    /**\n     * Bring the database's collection tables up to date, additively.\n     *\n     * Optional because it is only meaningful for schema-ful drivers. A managed\n     * runtime boots a compiled project against a database it has never seen; auth\n     * tables are ensured on boot but collection tables were created by nothing,\n     * so every data request answered 500 on a missing relation. The CLI's `db\n     * push` cannot fill the gap — it needs Atlas, and the runtime image ships no\n     * CLI.\n     *\n     * Implementations MUST be additive-only: create missing tables, columns and\n     * enum types, and never drop, narrow or rewrite anything. This runs\n     * unattended against live customer data with nobody reading a diff, so the\n     * destructive half stays a deliberate migration.\n     */\n    ensureCollectionSchema?(\n        collections: unknown[],\n        driverResult: InitializedDriver,\n        log?: (message: string) => void\n    ): Promise<{ applied: number }>;\n\n    /**\n     * Initialize WebSocket server for realtime operations.\n     */\n    initializeWebsockets?(server: unknown, realtimeService: RealtimeProvider, driver: import(\"../controllers/data_driver\").DataDriver, config?: unknown, authAdapter?: AuthAdapter): Promise<void> | void;\n}\n\n/**\n * Result of `BackendBootstrapper.initializeDriver()`.\n * @group Backend\n */\nexport interface InitializedDriver {\n    /** The DataDriver instance, ready for use. */\n    driver: import(\"../controllers/data_driver\").DataDriver;\n\n    /** The realtime service, if the driver created one during init. */\n    realtimeProvider?: RealtimeProvider;\n\n    /** A collection registry to register schema / tables into. */\n    collectionRegistry?: CollectionRegistryInterface;\n\n    /**\n     * Collections the driver derived from the live database schema.\n     *\n     * Set by drivers that introspect in `baas` mode; the server serves these\n     * instead of collections loaded from config files.\n     */\n    collections?: import(\"./collections\").CollectionConfig[];\n\n    /** The underlying database connection (for lifecycle management). */\n    connection?: DatabaseConnection;\n\n    /**\n     * Opaque handle that the bootstrapper can use in subsequent hooks\n     * (e.g., `initializeAuth`, `mountRoutes`) to access driver internals.\n     * Not used by the coordinator.\n     */\n    internals?: unknown;\n}\n\n/**\n * Result of `BackendBootstrapper.initializeAuth()`.\n * @group Backend\n */\nexport interface BootstrappedAuth {\n    /** User management service. */\n    userService: unknown;\n    /** Role management service (optional, roles are now simple strings). */\n    roleService?: unknown;\n    /** Email service (optional). */\n    emailService?: unknown;\n    /** Combined Auth Repository for unified token and user management. */\n    authRepository?: unknown;\n    /**\n     * Whether the auth schema in the database is one this runtime can serve.\n     *\n     * Folded into `healthCheck()` so a schema mismatch shows up as a degraded\n     * health response. Without it, a server whose auth is entirely broken still\n     * reports healthy — the database connection it probes is fine, and the\n     * mismatch is only discovered one failed login at a time.\n     */\n    schemaHealthCheck?(): Promise<AuthSchemaHealth>;\n}\n\n/**\n * Result of {@link BootstrappedAuth.schemaHealthCheck}.\n * @group Lifecycle\n */\nexport interface AuthSchemaHealth {\n    /** False when this runtime cannot be trusted to serve auth against this database. */\n    healthy: boolean;\n    /** Human-readable descriptions of each mismatch found. Empty when healthy. */\n    problems: string[];\n    /** Auth schema version recorded in the database, when it records one. */\n    databaseVersion?: number | null;\n    /** Auth schema version this runtime expects. */\n    runtimeVersion?: number;\n}\n","/**\n * The cross-instance transport for channel broadcast and presence, and the\n * contract anyone implementing one has to meet.\n *\n * These types live in `@rebasepro/types` rather than in the Postgres adapter on\n * purpose: a transport package should depend on the contract, not on the\n * database driver that happens to ship the default implementation. A\n * `@rebasepro/channel-bus-<something>` package needs this file and nothing else.\n *\n * Why a transport exists at all: entity/collection realtime already spans\n * instances (CDC, or per-mutation LISTEN/NOTIFY). Channel broadcast and presence\n * did not — they fanned out from per-process maps, so two clients served by\n * different replicas could not see each other, and nothing errored. The bus is\n * the missing hop, and deliberately *only* that hop: which local clients receive\n * a frame stays in the realtime service, so a transport never has to know what a\n * subscription, a WebSocket or a presence roster is.\n */\n\n/**\n * A frame in flight between instances.\n *\n * `sid` identifies the publishing instance. The realtime service drops frames\n * carrying its own `sid` on arrival — local fan-out already happened before the\n * publish — so a transport that echoes a publisher's own messages back to it is\n * still correct, merely wasteful.\n *\n * Keys are spelled out rather than abbreviated. The one shipped transport with a\n * size limit has a pointer path for anything that would approach it, so shaving\n * bytes off key names buys nothing worth the opacity.\n */\nexport type ChannelBusFrame =\n    /** A broadcast carrying its payload. */\n    | {\n        kind: \"broadcast\";\n        sid: string;\n        channel: string;\n        event: string;\n        /** Originating client, echoed so receivers can skip it if it is theirs. */\n        from?: string;\n        /** Sequence number, present only on retained channels. */\n        seq?: number;\n        payload: unknown;\n    }\n    /**\n     * A broadcast too large for the transport to carry inline: the body is\n     * already durable in `rebase.channel_messages`, so the frame carries only\n     * its address and each receiver reads it back. Only ever emitted for\n     * retained channels, and only by a transport with a finite\n     * {@link ChannelBus.maxFrameBytes}.\n     */\n    | {\n        kind: \"broadcast_ref\";\n        sid: string;\n        channel: string;\n        from?: string;\n        seq: number;\n    }\n    /** A presence join/leave/update, small by construction. */\n    | {\n        kind: \"presence_diff\";\n        sid: string;\n        channel: string;\n        joins: Record<string, Record<string, unknown>>;\n        leaves: Record<string, Record<string, unknown>>;\n    };\n\n/** Receives frames published by *other* instances. */\nexport type ChannelBusHandler = (frame: ChannelBusFrame) => void | Promise<void>;\n\n/**\n * A cross-instance transport.\n *\n * ## What an implementation must guarantee\n *\n * - **`start()` rejects if the transport is unusable.** The caller falls back to\n *   in-process delivery when it does. Resolving while disconnected produces a\n *   cluster that believes it is connected and silently is not, which is the\n *   exact failure this whole mechanism exists to remove.\n * - **`publish()` reaches every *other* instance, or rejects.** Delivery back to\n *   the publisher is permitted but pointless (see {@link ChannelBusFrame.sid}).\n * - **`stop()` is idempotent** and releases everything, including anything\n *   holding the event loop open.\n * - **A malformed message never throws out of the transport.** Parsing happens\n *   inside the implementation; drop and log what you cannot understand, so one\n *   bad frame cannot take the listener down.\n *\n * ## What it does *not* have to guarantee\n *\n * - **Ordering.** Retained channels carry `seq`, and the client SDK orders by\n *   it. Unsequenced broadcasts are cursor-grade traffic where order is not\n *   meaningful.\n * - **Durability.** A frame lost in transit is a missed live update; retained\n *   channels repair themselves through the client's `channel_history` replay.\n * - **Exactly-once.** Duplicates are tolerated — retained frames are deduped by\n *   `seq`, and presence diffs are idempotent by construction.\n */\nexport interface ChannelBus {\n    /**\n     * Identifies the transport in logs and in `getChannelBusKind()`. Use your\n     * own name; the framework only compares against `\"memory\"` to decide\n     * whether publishing is worth attempting at all.\n     */\n    readonly kind: string;\n\n    /**\n     * Largest frame this transport will carry, in bytes of encoded JSON, or\n     * `Infinity` when there is no meaningful ceiling.\n     *\n     * A broadcast that exceeds it is published as a `broadcast_ref` pointer when\n     * the channel is retained, and refused with an error to the sender when it\n     * is not. Implementations with no limit should return `Infinity` rather than\n     * a large number, so the pointer path is never taken needlessly.\n     */\n    readonly maxFrameBytes: number;\n\n    /** Connect and begin delivering remote frames to `handler`. */\n    start(handler: ChannelBusHandler): Promise<void>;\n\n    /** Publish a frame to the other instances. */\n    publish(frame: ChannelBusFrame): Promise<void>;\n\n    /** Disconnect and release resources. Idempotent. */\n    stop(): Promise<void>;\n}\n\n/**\n * Which transport to use, for the two that ship with the Postgres adapter.\n *\n * To use one that does not ship here — a Redis package, or your own class —\n * pass the {@link ChannelBus} instance itself instead of a config object.\n *\n * There are deliberately only two built in, and neither adds a service to a\n * deployment. Rebase deploys as Postgres + backend + frontend; a bus that\n * required a message broker would put a second stateful service into every\n * `docker-compose.yml` the CLI scaffolds, for a feature most applications never\n * use. Measured across two backend instances against one Postgres container,\n * the Postgres bus carried ~10k cross-instance messages/second with no losses,\n * and stayed flat out to eight instances — comfortably past what live-cursor\n * collaboration generates. The extension point below is the answer for anyone\n * who does outgrow it.\n */\nexport type ChannelBusConfig =\n    /**\n     * In-process only — the historical behaviour. Broadcast and presence reach\n     * the clients connected to *this* instance and no further.\n     */\n    | { type: \"memory\" }\n    /**\n     * Postgres LISTEN/NOTIFY, reusing infrastructure the deployment already has.\n     *\n     * `pg_notify` caps a payload at 8000 bytes, so a broadcast larger than that\n     * is delivered cross-instance only on a *retained* channel, where the\n     * notification carries a pointer (`seq`) instead of the message and each\n     * receiver reads the body back from `rebase.channel_messages`. An oversized\n     * broadcast on an ephemeral channel is refused rather than silently\n     * delivered to half the cluster.\n     *\n     * NOTE: `LISTEN` needs a session-mode connection. Behind PgBouncer in\n     * transaction mode this must point at the database directly\n     * (`DATABASE_DIRECT_URL`), not at the pooler.\n     */\n    | {\n        type: \"postgres\";\n        /** Direct connection for the LISTEN client. Defaults to `DATABASE_DIRECT_URL`. */\n        connectionString?: string;\n        /**\n         * How long to coalesce outgoing frames into a single notification, in\n         * milliseconds. Defaults to 10.\n         *\n         * A notify is a query on your primary database, so under load this is\n         * the difference between one query per message and one per window. The\n         * window is leading-edge: a frame arriving when none is open goes out\n         * immediately, so an idle channel pays no added latency and only a\n         * sustained stream is batched.\n         *\n         * Set to 0 to disable coalescing and send every frame on its own.\n         */\n        batchWindowMs?: number;\n    };\n\n/**\n * What `realtime.bus` accepts: a built-in transport by name, or any\n * {@link ChannelBus} instance.\n *\n * ```typescript\n * realtime: { bus: { type: \"postgres\" } }        // shipped\n * realtime: { bus: new MyRedisChannelBus(url) }  // a separate package, or your own\n * ```\n */\nexport type ChannelBusSetting = ChannelBusConfig | ChannelBus;\n\n/**\n * Whether `setting` is an already-constructed transport rather than a request\n * for a built-in one.\n *\n * Structural rather than nominal so that an instance from a *different copy* of\n * `@rebasepro/types` — an entirely normal outcome of a separately versioned\n * transport package — is still recognised.\n */\nexport function isChannelBusInstance(setting: ChannelBusSetting | undefined): setting is ChannelBus {\n    return typeof (setting as ChannelBus | undefined)?.publish === \"function\";\n}\n","/**\n * Describes a named storage backend — a place files live.\n *\n * Declared once and shared front + back: the frontend uses it to decide\n * transport (HTTP proxy vs direct SDK), the backend uses the same `key`\n * to resolve a StorageController, and collection properties reference\n * a definition by its `key` via `StorageConfig.storageSource`.\n *\n * This mirrors the {@link DataSourceDefinition} pattern used for databases.\n *\n * @group Models\n */\n\n/**\n * The default storage source key, used when a property does not specify\n * a `storageSource`. Shared by the frontend and backend registries so\n * both agree on \"the default storage backend\".\n * @group Models\n */\nexport const DEFAULT_STORAGE_SOURCE_KEY = \"(default)\";\n\n/**\n * How the *frontend* reaches a storage backend.\n *\n * - `\"server\"` — through the Rebase backend REST API (`/api/storage`).\n *   The backend holds the actual `StorageController` and routes by\n *   storage-source key. This is the default and covers Local, S3, GCS,\n *   and any other server-mediated engine.\n * - `\"direct\"` — straight from the client to the external backend via\n *   its own SDK (e.g. Firebase Storage via `@firebase/storage`).\n *   The Rebase backend is **not** in the upload/download path.\n *\n * @group Models\n */\nexport type StorageSourceTransport = \"server\" | \"direct\";\n\n/**\n * Declarative definition of a storage source — a named place files live.\n *\n * Declared once and shared front and back: the frontend uses it to decide\n * transport (client HTTP proxy vs direct provider SDK), the backend uses\n * the same `key` to resolve a `StorageController`, and collection\n * properties reference a definition by its `key` via\n * `StorageConfig.storageSource`.\n *\n * @group Models\n */\nexport interface StorageSourceDefinition {\n    /**\n     * Unique identifier for this storage source. Collection properties\n     * point at it via `StorageConfig.storageSource`.\n     * Defaults to {@link DEFAULT_STORAGE_SOURCE_KEY}.\n     */\n    key: string;\n\n    /**\n     * The engine backing this storage source (e.g. `\"local\"`, `\"s3\"`,\n     * `\"gcs\"`, `\"firebase\"`, `\"azure\"`, or a custom id).\n     */\n    engine: string;\n\n    /**\n     * How the frontend reaches this storage. Defaults to `\"server\"`.\n     *\n     * When `\"direct\"`, the client uses a provider-specific SDK\n     * (e.g. `@firebase/storage`) and the backend does not proxy\n     * upload/download traffic for this source.\n     */\n    transport: StorageSourceTransport;\n\n    /** Human-readable label for the UI (e.g. \"Firebase Storage\", \"S3 Media\"). */\n    label?: string;\n}\n\n/**\n * A resolved storage source: the single source of truth that the frontend\n * router and backend registry both derive from.\n *\n * @group Models\n */\nexport interface ResolvedStorageSource {\n    /** Storage source key (routing key, shared front + back). */\n    key: string;\n    /** Engine backing the source. */\n    engine: string;\n    /** Frontend transport. */\n    transport: StorageSourceTransport;\n    /** Human-readable label. */\n    label?: string;\n}\n\n/**\n * The environment-variable suffix for a storage or data source key.\n *\n * `\"\"` for the default source — so a single-bucket project keeps configuring\n * plain `S3_BUCKET` — and `__<KEY>` for every named one, uppercased with\n * non-alphanumerics collapsed to underscores: `media-cdn` → `S3_BUCKET__MEDIA_CDN`.\n *\n * The rule derives the variable name from the declared key rather than\n * discovering keys by scanning the environment. Scanning would have to guess how\n * `S3_BUCKET__MEDIA_CDN` splits into a key; deriving cannot be ambiguous, and a\n * typo surfaces as a missing source at boot instead of a silently ignored\n * variable.\n *\n * It lives in this package, with no dependencies, because four things must agree\n * on it exactly: the CLI (validating a build), the runtime (reading its own\n * environment), the control plane (writing a tenant's Secret), and the docs. A\n * second implementation of a naming convention is a second chance to disagree.\n *\n * @group Models\n */\nexport function storageEnvSuffix(key: string, defaultKey: string = DEFAULT_STORAGE_SOURCE_KEY): string {\n    if (!key || key === defaultKey) return \"\";\n    const normalized = key\n        .replace(/[^A-Za-z0-9]+/g, \"_\")\n        .replace(/^_+|_+$/g, \"\")\n        .toUpperCase();\n    if (!normalized) {\n        throw new Error(\n            `Source key \"${key}\" cannot be turned into an environment variable name. ` +\n            \"Use a key containing at least one letter or digit.\"\n        );\n    }\n    return `__${normalized}`;\n}\n\n/**\n * Two distinct keys that collapse onto the same variable name, or `null`.\n *\n * `media-cdn` and `media_cdn` are different source keys but the same suffix, so\n * without this one of them silently reads the other's configuration. Returns the\n * offending pair rather than throwing, so each caller can raise it in its own\n * idiom — a `BundleError` at boot, a build failure in the CLI, a rejected deploy\n * in a control plane.\n *\n * @group Models\n */\nexport function findStorageSuffixCollision(\n    keys: string[],\n    defaultKey: string = DEFAULT_STORAGE_SOURCE_KEY\n): { a: string; b: string; suffix: string } | null {\n    const seen = new Map<string, string>();\n    for (const key of keys) {\n        const suffix = storageEnvSuffix(key, defaultKey);\n        const existing = seen.get(suffix);\n        if (existing !== undefined && existing !== key) {\n            return { a: existing, b: key, suffix };\n        }\n        seen.set(suffix, key);\n    }\n    return null;\n}\n\n/** The `storage` block of `rebase.json`, structurally. */\nexport type DeclaredStorageSources = Record<string, {\n    engine: string;\n    transport?: StorageSourceTransport;\n    label?: string;\n}>;\n\n/**\n * Merge the two places a project may declare storage sources into one list.\n *\n * `rebase.json` is authoritative for every field it states. Config code may add\n * sources it does not mention and fill in fields it left out, but may not\n * contradict it: the manifest is what a host reads to decide which buckets need\n * configuring, and a runtime that quietly disagreed with it would put the\n * console back to describing a topology the tenant does not have — the exact\n * failure this whole mechanism exists to end.\n *\n * Note what is *not* here: no default source is invented when both inputs are\n * empty. That decision belongs to the resolver, which knows whether declaring\n * nothing means \"one plain bucket\" (it does) or \"no storage at all\".\n *\n * @group Models\n */\nexport function normalizeStorageSources(\n    declared: DeclaredStorageSources | StorageSourceDefinition[] | undefined,\n    exported: StorageSourceDefinition[] | undefined\n): StorageSourceDefinition[] {\n    const merged = new Map<string, StorageSourceDefinition>();\n\n    // Two shapes, one meaning. `rebase.json` states sources as a record keyed by\n    // source key, which is how JSON expresses a set of named things; the bundle\n    // manifest stores the already-resolved array. Accepting both is what lets the\n    // CLI and the runtime call this with what each of them happens to hold.\n    const declaredEntries: [string, { engine: string; transport?: StorageSourceTransport; label?: string }][] =\n        Array.isArray(declared)\n            ? declared.filter(d => d?.key).map(d => [d.key, d])\n            : Object.entries(declared ?? {});\n\n    for (const [key, config] of declaredEntries) {\n        merged.set(key, {\n            key,\n            engine: config.engine,\n            transport: config.transport ?? \"server\",\n            ...(config.label !== undefined ? { label: config.label } : {})\n        });\n    }\n\n    for (const definition of exported ?? []) {\n        if (!definition?.key) continue;\n        const existing = merged.get(definition.key);\n        if (!existing) {\n            merged.set(definition.key, {\n                key: definition.key,\n                engine: definition.engine,\n                transport: definition.transport ?? \"server\",\n                ...(definition.label !== undefined ? { label: definition.label } : {})\n            });\n            continue;\n        }\n        // Fill gaps only. `rebase.json` stated these; code does not overrule it.\n        if (existing.label === undefined && definition.label !== undefined) {\n            existing.label = definition.label;\n        }\n    }\n\n    return Array.from(merged.values());\n}\n","/**\n * How a collection points at a UI component without the backend learning about React.\n *\n * This file is the hinge the BaaS/admin split turns on. `ComponentRef` is named\n * by `properties.ts` (`ui.Field`, `ui.Preview`, `ui.Filter`), and `properties.ts`\n * must stay in the React-free core because every backend subsystem — validation,\n * the drizzle schema generator, the OpenAPI generator, the SDK codegen — reads\n * property definitions. If `ComponentRef` needed `React.ComponentType`, the whole\n * property model would have to move to the admin layer with it.\n *\n * So the React types are described structurally instead of imported. Every form\n * a React component takes is assignable to {@link ComponentLike}:\n *\n * - a function component is `(props: P) => ReactNode`\n * - a class component satisfies the construct signature (`Component` has `render`)\n * - `memo` and `forwardRef` return exotic components, which are callable\n *\n * The cost is that the return type is `unknown` rather than `ReactNode`, so a\n * function that returns something React could not render is accepted here.\n * `@rebasepro/admin-types` re-exports a `ReactComponentRef<P>` narrowed against\n * the real `React.ComponentType` for authoring and for the admin's internals,\n * which restores that check where it can be enforced.\n */\n\n/**\n * Structural stand-in for `React.ComponentType<P>`.\n *\n * Deliberately not `Function` or `unknown`: those would accept anything and the\n * resolver's runtime heuristics ({@link ComponentRef} form 3) would be all that\n * stood between a typo and a blank screen.\n */\nexport type ComponentLike<P = any> =\n    | ((props: P) => unknown)\n    | (new (props: P, context?: unknown) => { render(): unknown });\n\n/**\n * Internal marker for a lazily-loaded component reference.\n * Created by the Vite transform plugin when converting string paths\n * to deferred `import()` calls. Users should NOT create these manually.\n *\n * @internal\n */\nexport interface LazyComponentRef<P = unknown> {\n    readonly __rebaseLazy: true;\n    readonly load: () => Promise<{ default: ComponentLike<P> }>;\n}\n\n/**\n * A reference to a UI component that can be provided in three forms:\n *\n * 1. **String path** (recommended for collection configs):\n *    ```ts\n *    Field: \"../../frontend/src/components/MyField\"\n *    ```\n *    The Vite plugin transforms this into a `LazyComponentRef` at build time.\n *    On the backend, the string stays inert and is never evaluated.\n *\n * 2. **Lazy import function**:\n *    ```ts\n *    Field: () => import(\"../../frontend/src/components/MyField\")\n *    ```\n *    Standard ES dynamic import. Backend never calls the function.\n *\n * 3. **Direct component reference** (use only in frontend-only code):\n *    ```ts\n *    Field: MyFieldComponent\n *    ```\n *    Importing a component at the top level will pull React into the\n *    backend runtime — only safe in code that the backend never imports.\n *    `pnpm check:headless` fails on a collection file that does this.\n *\n * @group Types\n */\nexport type ComponentRef<P = any> =\n    | string\n    | LazyComponentRef<P>\n    | (() => Promise<{ default: ComponentLike<P> }>)\n    | ComponentLike<P>;\n\n/**\n * Type guard: checks if a value is a `LazyComponentRef` produced by the\n * Vite transform plugin.\n */\nexport function isLazyComponentRef<P = unknown>(ref: unknown): ref is LazyComponentRef<P> {\n    return (\n        typeof ref === \"object\" &&\n        ref !== null &&\n        \"__rebaseLazy\" in ref &&\n        (ref as Record<string, unknown>).__rebaseLazy === true\n    );\n}\n","/**\n * The project manifest (`rebase.json`) and the build artifacts derived from it.\n *\n * Three separate documents live in this file, and keeping them distinct matters:\n *\n * 1. {@link RebaseProjectManifest} — `rebase.json`. **Authored** by the developer,\n *    committed to the repository. Declares topology only: which runtime major the\n *    project targets, and which apps *this repository* contributes to the project.\n *    Schema, security rules, hooks and functions stay in TypeScript under the\n *    config package — nothing that needs a type system belongs here.\n *\n * 2. {@link RebaseProjectLink} — the per-checkout link (`.rebase/cloud.json`).\n *    **Not committed**, because it is per-developer like a git remote. Says which\n *    deployed project this working copy points at, whether that is a Rebase Cloud\n *    project or the base URL of a self-hosted backend.\n *\n * 3. {@link RebaseBundleManifest} — `manifest.json` inside a built bundle.\n *    **Generated**, never hand-edited. It is the lockfile analogue: the exact\n *    contract a built artifact claims to satisfy, which the runtime validates\n *    before it boots and a control plane validates before it deploys.\n *\n * A repository declares only the apps it contains. The set of apps belonging to a\n * project is held by the project itself, which is what makes multi-repo projects\n * work: two repositories never need to know about each other, only about the\n * project.\n */\n\nimport type { StorageSourceDefinition } from \"./storage_source\";\n\n/**\n * Which kind of thing an app is.\n *\n * - `backend` — the collections/hooks/functions that define the project's API.\n *   Exactly one per *project* (not per repository); the registry enforces it.\n * - `static`  — a pre-built client bundle (SPA, static site), served from the\n *   backend process at its declared `path` or from a CDN. The admin panel is\n *   one of these: it is an app in the user's repository like any other.\n *\n * That is the whole list. Ownership of the server process is a property of the\n * backend app ({@link RebaseBackendAppConfig.runtime}), not an app type.\n */\nexport type RebaseAppType = \"backend\" | \"static\";\n\n/**\n * The backend app: the project's API surface.\n *\n * Paths are relative to the directory holding `rebase.json`. The defaults match\n * the layout `rebase init` scaffolds, so a stock project may declare simply\n * `{ \"type\": \"backend\", \"runtime\": \"managed\" }`.\n */\nexport interface RebaseBackendAppConfig {\n    type: \"backend\";\n    /**\n     * Who owns the process this backend runs in.\n     *\n     * - `managed` — the platform's runtime image boots this project's bundle.\n     *   You supply collections, functions, crons and schema; Rebase supplies the\n     *   server.\n     * - `custom` — this repository builds its own image and entrypoint. The\n     *   escape hatch: full control, no managed-runtime guarantees.\n     *\n     * Independent of *where* it runs. Both run on Rebase Cloud and both\n     * self-host — the destination lives in `.rebase/cloud.json`, not here. See\n     * `docker/docker-compose.selfhost.yml`, which boots a managed bundle on a\n     * developer's own Docker host.\n     *\n     * This is authored rather than inferred on purpose. It is the single most\n     * consequential fact about a deployment, and inferring it is what used to\n     * land projects on the custom runtime without anyone choosing it.\n     */\n    runtime: \"managed\" | \"custom\";\n    /** Directory of the config package (collections + index). Default `config`. */\n    config?: string;\n    /** Directory of server functions. Default `backend/functions`. */\n    functions?: string;\n    /** Directory of cron job definitions. Default `backend/crons` when present. */\n    crons?: string;\n    /**\n     * Path to the generated Drizzle schema module (tables/enums/relations).\n     * Default `backend/src/schema.generated.ts`.\n     */\n    schema?: string;\n    /**\n     * Module path (relative to `config`) exporting the auth users collection as\n     * its default export. Default `collections/users`.\n     */\n    usersCollection?: string;\n\n    /**\n     * `runtime: \"custom\"` only. Dockerfile path relative to the repository root.\n     * Default `Dockerfile`.\n     */\n    dockerfile?: string;\n    /** `runtime: \"custom\"` only. Build context relative to the root. Default `.`. */\n    context?: string;\n    /** `runtime: \"custom\"` only. Port the container listens on. Default 8080. */\n    port?: number;\n}\n\n/**\n * A static client bundle — SPA or static site — built here and served at `path`.\n */\nexport interface RebaseStaticAppConfig {\n    type: \"static\";\n    /** Package directory containing the client sources. */\n    root: string;\n    /** Command that produces `output`. Run from the repository root. */\n    build?: string;\n    /** Directory of built assets, relative to the repository root. */\n    output: string;\n    /**\n     * Public base path this app is served under. Default `/`.\n     *\n     * Several static apps run in one process, each at its own path — the API at\n     * `/api`, a site at `/`, the admin at `/admin` — which is what keeps a\n     * self-hosted deployment a single container.\n     *\n     * **This is a build-time input, not only a serving concern.** An app mounted\n     * at `/admin` must be *built* for `/admin` (Vite's `base`), or `index.html`\n     * loads and every asset 404s: a blank page with no server error. `rebase\n     * build` passes it as `REBASE_APP_BASE` and asserts the emitted HTML honours\n     * it. Changing this value requires rebuilding the app.\n     */\n    path?: string;\n    /**\n     * Serve `index.html` for unmatched paths under `path` (client-side routing).\n     * Default `true` — the overwhelmingly common case for a client app, and a\n     * static *site* generator emits real files for its routes anyway.\n     */\n    spa?: boolean;\n}\n\nexport type RebaseAppConfig = RebaseBackendAppConfig | RebaseStaticAppConfig;\n\n/**\n * One declared storage source, as authored in `rebase.json`.\n *\n * The key comes from the enclosing record, so this is\n * {@link StorageSourceDefinition} minus its `key` — the same document the\n * runtime registry and the frontend router consume, expressed the way a JSON\n * object naturally expresses \"a set of named things\".\n */\nexport interface RebaseStorageSourceConfig {\n    /** Engine backing this source: `local`, `s3`, `gcs`, or a custom id. */\n    engine: string;\n    /**\n     * How the frontend reaches it. Default `server` (proxied through\n     * `/api/storage`). `direct` means a provider SDK talks to the bucket and the\n     * backend is not in the upload path.\n     */\n    transport?: \"server\" | \"direct\";\n    /** Human-readable label for the console and the admin UI. */\n    label?: string;\n}\n\n/**\n * `rebase.json` — the authored project manifest.\n */\nexport interface RebaseProjectManifest {\n    /** JSON Schema URL, for editor completion. Ignored by the tooling. */\n    $schema?: string;\n    /**\n     * The runtime contract **major** this project targets, as a semver range\n     * (e.g. `^1`, `~1.4`, or an exact `1.4.2` to pin).\n     *\n     * The platform upgrades patches and minors underneath a project without\n     * asking; it never crosses a major. See {@link RUNTIME_CONTRACT_VERSION}.\n     *\n     * Named `rebase` rather than `runtime` so that `runtime` means exactly one\n     * thing — {@link RebaseBackendAppConfig.runtime}, who owns the process. It\n     * reads like `engines` in a `package.json`, which is what it is.\n     */\n    rebase: string;\n    /**\n     * Apps this repository contributes, keyed by app name. The key is the app's\n     * identity within the project: it is what `rebase deploy <app>` names, what\n     * client credentials are issued against, and what a second repository must\n     * not collide with.\n     */\n    apps: Record<string, RebaseAppConfig>;\n    /**\n     * Storage sources this project uses, keyed by source key.\n     *\n     * **Topology only — never credentials.** Which buckets exist is a property of\n     * the project and belongs in the repository; how to reach each one is a\n     * property of the deployment and lives in the environment, read per source\n     * from `<BASE>__<KEY>` (`S3_BUCKET__MEDIA` for a source keyed `media`). The\n     * default source takes no suffix, so a single-bucket project configured with\n     * plain `S3_BUCKET` keeps working having declared nothing at all.\n     *\n     * Declared here rather than only in the config package because this file is\n     * the one artifact a host can read *before* running a build. That is what\n     * lets a console show \"this project wants a `media` bucket, and it has none\"\n     * on a project's first deploy, and it is why the managed and custom runtimes\n     * can present the same list — a custom build emits no bundle manifest, so a\n     * declaration that lived only in compiled config would leave every custom\n     * project invisible.\n     *\n     * Omitted entirely means one default source, which is the overwhelmingly\n     * common project and must not be required to say so.\n     */\n    storage?: Record<string, RebaseStorageSourceConfig>;\n}\n\n/**\n * The per-checkout project link.\n *\n * Deliberately separate from `rebase.json`: the manifest is committed and shared,\n * while the link is per-developer. Keeping them in one file would mean either\n * committing someone's project id or gitignoring the topology.\n */\nexport interface RebaseProjectLink {\n    /**\n     * A Rebase Cloud project id, or the base URL of any running Rebase backend\n     * (`https://api.example.com`). Both are first-class: every command that\n     * accepts a project reference accepts either, so a self-hosted project has\n     * the same tooling as a cloud one.\n     */\n    project: string;\n    /** Organization slug. Cloud projects only. */\n    org?: string;\n    /** Explicit API base URL, when it differs from the project's default. */\n    apiUrl?: string;\n}\n\n/**\n * Whether a project can run on the managed runtime, and if not, precisely why.\n *\n * The reasons are returned rather than summarised so tooling can print something\n * a developer can act on. \"Not eligible\" is never a dead end — it selects the\n * custom-runtime path, which still deploys.\n */\nexport interface ManagedCompatibility {\n    eligible: boolean;\n    reasons: string[];\n}\n\n// ─────────────────────────────────────────────────────────────────────────────\n// Bundle\n// ─────────────────────────────────────────────────────────────────────────────\n\n/**\n * Version of the bundle *format* itself.\n *\n * Bumped only when the on-disk layout changes in a way an older runtime could\n * not read. A runtime accepts any bundle whose `bundleFormat` is less than or\n * equal to its own — old bundles keep booting on new runtimes, which is the\n * whole point of separating the artifact from the engine.\n *\n * - **1** — `mode: \"cms\" | \"baas\" | \"static\"`, `entry.static` a single directory\n *   string, `entry.admin` for a bundled admin panel.\n * - **2** — `kind: \"backend\" | \"static\"`, `entry.static` a list of\n *   {@link RebaseBundleStatic}, `entry.admin` removed. A format-1 runtime reading\n *   one of these would find no `mode` and an array where it expects a string, so\n *   the bump is what turns that into a refusal to boot instead of a bundle that\n *   starts and serves nothing.\n */\nexport const BUNDLE_FORMAT_VERSION = 2;\n\n/**\n * The runtime contract major.\n *\n * Distinct from the `@rebasepro/server` package version: the package may release\n * any number of minors and patches while this stays put. It changes only when\n * the bundle/runtime contract breaks compatibility, and a project's\n * `manifest.runtime` range is matched against *this*.\n */\nexport const RUNTIME_CONTRACT_VERSION = 1;\n\n/** Where the runtime finds each part of the bundle. Paths are bundle-relative. */\nexport interface RebaseBundleEntrypoints {\n    /** Compiled config package directory (collections live under it). */\n    config?: string;\n    /** Compiled collections directory, when it differs from `<config>/collections`. */\n    collections?: string;\n    /** Compiled functions directory. */\n    functions?: string;\n    /** Compiled crons directory. */\n    crons?: string;\n    /** Compiled Drizzle schema module. */\n    schema?: string;\n    /** Module exporting the auth users collection (default export). */\n    usersCollection?: string;\n    /**\n     * Built static apps to serve from this process, in declaration order.\n     *\n     * A list rather than a single directory because one process serves several\n     * apps at different paths — a site at `/` and the admin at `/admin`. The\n     * runtime mounts them longest-path-first so the `/`-rooted app's catch-all\n     * does not claim its siblings' URLs.\n     */\n    static?: RebaseBundleStatic[];\n}\n\n/** One built static app inside a bundle. */\nexport interface RebaseBundleStatic {\n    /** Public base path, e.g. `/` or `/admin`. */\n    path: string;\n    /** Bundle-relative directory holding the built assets. */\n    dir: string;\n    /** Serve `index.html` for unmatched paths under `path`. */\n    spa: boolean;\n}\n\n/**\n * A native module found in the dependency closure.\n *\n * Recorded rather than merely counted so a rejection can name the offending\n * package instead of saying \"something here is native\".\n */\nexport interface NativeDependency {\n    name: string;\n    /** Why it was flagged — a `.node` binary, a gyp build, or an install script. */\n    reason: string;\n}\n\n/**\n * `manifest.json` — generated, and the document the runtime and control plane\n * both validate against.\n */\nexport interface RebaseBundleManifest {\n    /** @see BUNDLE_FORMAT_VERSION */\n    bundleFormat: number;\n    runtime: {\n        /** The `runtime` range copied from `rebase.json`. */\n        range: string;\n        /** Exact `@rebasepro/server` version this bundle was built against. */\n        builtAgainst: string;\n        /** Runtime contract major this bundle requires. */\n        contract: number;\n    };\n    /**\n     * Hash of the compiled collection definitions.\n     *\n     * This is the contract stamp. A generated SDK records the value it was built\n     * from, a client sends it back, and a mismatch is what lets the platform say\n     * \"this app was built against an older schema\" instead of failing mysteriously\n     * at the first request. It covers collections only — a hook edit does not\n     * change a client's contract, so it must not invalidate every SDK.\n     */\n    schemaVersion: string;\n    /** Which app in `rebase.json` this bundle was built from. */\n    app: string;\n    /**\n     * What the runtime does with this bundle.\n     *\n     * - `backend` — boot the full server: database, auth and the data API, plus\n     *   any static apps in `entry.static`.\n     * - `static` — no backend at all: serve `entry.static` and nothing else. No\n     *   database, no auth, no data sources. This is how a static app runs on the\n     *   same image as the backend.\n     *\n     * Replaces an earlier `mode: \"cms\" | \"baas\" | \"static\"`. The cms/baas\n     * distinction was never a third kind of thing — it is simply whether\n     * `entry.config` is present, so it is derived rather than declared.\n     */\n    kind: \"backend\" | \"static\";\n    entry: RebaseBundleEntrypoints;\n    /** Collection slugs contained in the bundle, for quick inspection. */\n    collections?: string[];\n    hooks: {\n        /**\n         * Whether the dependency closure contains native code.\n         *\n         * The managed runtime refuses these: a prebuilt binary cannot be run on\n         * an image the platform did not build it for, and the honest failure is\n         * at deploy time rather than at 3am in a crash loop.\n         */\n        native: boolean;\n        nativeModules?: NativeDependency[];\n    };\n    /**\n     * What the bundle's config says about storage access control.\n     *\n     * Storage is not under RLS and its keys share one flat namespace, so a\n     * deployment with file storage enabled and no access model serves every\n     * user's files to every signed-in user. The runtime refuses to boot in that\n     * state — which, on a hosted platform that enables storage from the *console*\n     * rather than from the bundle, surfaces as a crash loop the developer cannot\n     * read.\n     *\n     * Recording it here lets a host reject the deploy with the reason instead.\n     * Absent on bundles built before this field existed.\n     */\n    storage?: {\n        /** Whether the config package exports a `storageAuthorize` hook. */\n        authorize: boolean;\n        /**\n         * Every storage source this bundle expects, resolved at build time from\n         * `rebase.json`'s `storage` block merged with any `storageSources` the\n         * config package exports.\n         *\n         * Recorded so the runtime does not have to import user code to learn its\n         * own topology, and so a host can tell — from the artifact alone, before\n         * starting anything — which buckets need configuring. Absent on bundles\n         * built before this field existed, which means one default source.\n         */\n        sources?: StorageSourceDefinition[];\n    };\n    deps: {\n        /** Runtime dependencies of user code, as declared. */\n        declared: Record<string, string>;\n    };\n    build: {\n        /** `@rebasepro/cli` version that produced this bundle. */\n        cli: string;\n        /** Node major the bundle was compiled on. */\n        node: string;\n        /** ISO-8601. */\n        createdAt: string;\n    };\n}\n\n/** The contract a running backend serves at `GET /api/meta/contract`. */\nexport interface RebaseProjectContract {\n    /** Matches {@link RebaseBundleManifest.schemaVersion}. */\n    schemaVersion: string;\n    runtime: {\n        /** `@rebasepro/server` version currently running. */\n        version: string;\n        contract: number;\n    };\n    /** Full collection definitions, serialized — the input to SDK generation. */\n    collections: unknown[];\n    /** Collection slugs, for cheap inspection without parsing the definitions. */\n    collectionSlugs: string[];\n    generatedAt: string;\n}\n\n/** Header carrying the schema version an SDK was generated from. */\nexport const SCHEMA_VERSION_HEADER = \"x-rebase-schema\";\n","import type { CollectionConfig } from \"./collections\";\n\n/**\n * Serializing collections so they survive a network hop.\n *\n * A collection definition is not plain data. Relations point at their target\n * with a *function* (`target: () => usersCollection`) so two collections can\n * reference each other without an import cycle, and collections also carry\n * callbacks, custom views and component references. `JSON.stringify` silently\n * drops every one of those, which matters because the SDK generator *calls*\n * `relation.target()` to decide whether a foreign key is a string or a number.\n * Serialize naively and remote SDK generation produces subtly wrong types\n * instead of failing — the worst possible outcome.\n *\n * So relation targets are resolved to a slug reference on the way out and\n * rebuilt into functions on the way in. Everything else that cannot cross a wire\n * is dropped deliberately: an SDK is generated from the *shape* of the data, and\n * server-side behaviour is neither useful to a client nor safe to publish.\n */\n\n/** Marker replacing a relation's `target` function in serialized form. */\nexport interface SerializedCollectionRef {\n    __collectionRef: string;\n}\n\nexport function isSerializedCollectionRef(value: unknown): value is SerializedCollectionRef {\n    return typeof value === \"object\"\n        && value !== null\n        && typeof (value as SerializedCollectionRef).__collectionRef === \"string\";\n}\n\n/** Depth limit for the walk — deep enough for real configs, finite for cyclic ones. */\nconst MAX_DEPTH = 64;\n\n/**\n * Resolve whatever a `target` thunk returns down to a collection.\n *\n * A target may be the collection, a module namespace (when the authoring file\n * used `import * as`), or a default-export wrapper. All three appear in real\n * projects, and the SDK generator already unwraps them the same way.\n */\nfunction unwrapTarget(value: unknown): CollectionConfig | undefined {\n    if (!value || typeof value !== \"object\") return undefined;\n    const candidate = value as { default?: unknown; __esModule?: boolean; properties?: unknown };\n    if (candidate.default || candidate.__esModule) {\n        const inner = candidate.default;\n        if (inner && typeof inner === \"object\") return inner as CollectionConfig;\n    }\n    if (candidate.properties) return value as CollectionConfig;\n    return undefined;\n}\n\n/** The identity a serialized reference uses. Slug first — it is the routing key. */\nfunction refFor(collection: CollectionConfig | undefined): string | undefined {\n    if (!collection) return undefined;\n    const withPath = collection as CollectionConfig & { path?: string };\n    return collection.slug || withPath.path || collection.name;\n}\n\n/**\n * Deep-copy a value into something JSON can carry.\n *\n * `target` keys are special-cased into refs. Other functions vanish, cycles are\n * cut, and everything else is copied structurally.\n */\n/** Shared walk state: the memo, plus a count of depth-cap hits. */\ninterface WalkState {\n    memo: WeakMap<object, unknown>;\n    /**\n     * How many times the walk has truncated a subtree — by hitting the depth\n     * cap, or by cutting a cycle.\n     *\n     * Either kind of truncation makes a result valid only at the *position* it\n     * was produced at, so caching it and serving it elsewhere silently drops\n     * content that would have been included. Comparing this counter before and\n     * after a node's children tells us whether its result is position-\n     * independent and therefore safe to memoize.\n     *\n     * The cycle case is the subtle one: with `a.b = b` and `b.a = a`, serializing\n     * `{ first: b, second: a }` visits `a` beneath `b` — where the cycle back to\n     * `b` is cut — and would then reuse that truncated `a` for `second`, where\n     * nothing needed cutting.\n     */\n    truncations: number;\n}\n\nfunction toSerializable(\n    value: unknown,\n    seen: WeakSet<object>,\n    depth: number,\n    state: WalkState,\n    key?: string\n): unknown {\n    if (depth > MAX_DEPTH) {\n        state.truncations++;\n        return undefined;\n    }\n\n    if (typeof value === \"function\") {\n        // Only a relation target carries information a client needs. Calling it\n        // is safe here — this runs on the server, where the target module is\n        // already loaded — and a throwing target simply yields no reference,\n        // which degrades the generated FK type rather than failing the request.\n        if (key === \"target\") {\n            try {\n                const resolved = unwrapTarget((value as () => unknown)());\n                const ref = refFor(resolved);\n                return ref ? { __collectionRef: ref } : undefined;\n            } catch {\n                return undefined;\n            }\n        }\n        return undefined;\n    }\n\n    if (value === null || typeof value !== \"object\") {\n        return value;\n    }\n\n    if (value instanceof Date) return value.toISOString();\n    if (value instanceof RegExp) return value.source;\n\n    if (seen.has(value as object)) {\n        state.truncations++;\n        return undefined;\n    }\n\n    // A shared (non-cyclic) subgraph is reachable by many paths, and `seen` is a\n    // *path* set — released in the `finally` below so a node referenced twice in\n    // different branches is emitted twice rather than dropped as a false cycle.\n    // Without memoization that makes the walk exponential in depth: a diamond\n    // graph 20 levels deep took ~400ms, and each further level doubled it. The\n    // result is a plain data tree, so handing back the same converted object for\n    // a repeat visit is indistinguishable after JSON.stringify.\n    const cached = state.memo.get(value as object);\n    if (cached !== undefined) return cached;\n\n    seen.add(value as object);\n    const truncationsBefore = state.truncations;\n    const memoize = (result: unknown): unknown => {\n        // Only cache a result that nothing was cut from.\n        if (result !== undefined && state.truncations === truncationsBefore) {\n            state.memo.set(value as object, result);\n        }\n        return result;\n    };\n\n    try {\n        if (Array.isArray(value)) {\n            const items = value\n                .map(item => toSerializable(item, seen, depth + 1, state))\n                .filter(item => item !== undefined);\n            // A container that had content, none of which can be represented, is\n            // itself unrepresentable — see the note below.\n            return memoize(value.length > 0 && items.length === 0 ? undefined : items);\n        }\n\n        // A React element or component reference has no meaning to a client and\n        // will not survive JSON anyway.\n        if (\"$$typeof\" in (value as Record<string, unknown>)) return undefined;\n\n        const entries = Object.entries(value as Record<string, unknown>);\n        const out: Record<string, unknown> = {};\n        for (const [k, v] of entries) {\n            const converted = toSerializable(v, seen, depth + 1, state, k);\n            if (converted !== undefined) out[k] = converted;\n        }\n\n        // Drop a container whose entire content was dropped.\n        //\n        // `callbacks: { beforeSave() {…} }` would otherwise serialize to\n        // `callbacks: {}` — an empty husk that carries no information but is not\n        // *nothing*, so it lands in the payload and, worse, in the schema hash.\n        // Editing a hook would then change every client's schema version and\n        // report perfectly current SDKs as stale.\n        //\n        // A container that started empty stays empty: `properties: {}` is a\n        // deliberate statement, not a casualty.\n        if (entries.length > 0 && Object.keys(out).length === 0) return undefined;\n\n        return memoize(out);\n    } finally {\n        // Released so a collection referenced twice in different branches is\n        // emitted twice rather than being dropped as a false cycle.\n        seen.delete(value as object);\n    }\n}\n\n/**\n * Serialize collections for transport over the contract endpoint.\n *\n * Sorted by slug so the output — and therefore the schema hash computed from it\n * — does not depend on filesystem ordering.\n */\nexport function serializeCollections(collections: CollectionConfig[]): unknown[] {\n    return [...collections]\n        .sort((a, b) => String(a.slug ?? \"\").localeCompare(String(b.slug ?? \"\")))\n        .map(collection => toSerializable(withoutAdminBlock(collection), new WeakSet(), 0, {\n            memo: new WeakMap(),\n            truncations: 0\n        }))\n        .filter((c): c is Record<string, unknown> => c !== undefined);\n}\n\n/**\n * Drop the admin block before the walk.\n *\n * Nothing downstream of serialization is an admin panel. The contract endpoint\n * feeds remote SDK generation, and `rebase build` writes the result into a bundle\n * manifest that only the backend runtime reads. The block would survive the walk\n * as a husk anyway — its React elements and component functions are dropped\n * individually — and that husk has two costs worth avoiding: it puts every custom\n * component's *file path* on an endpoint whose job is to describe data shapes, and\n * it grows a payload that is fetched and cached per project.\n *\n * Removing it here rather than at each call site means one chokepoint, so a future\n * consumer of `serializeCollections` cannot forget.\n *\n * Child collections carry their own block, so this recurses — stripping only the\n * top level was the mistake `stripNonClientFields` in the contract routes already\n * had to fix once for security rules.\n */\nfunction withoutAdminBlock(collection: CollectionConfig): CollectionConfig {\n    const { admin: _admin, ...rest } = collection as CollectionConfig & Record<string, unknown>;\n    const nested = rest as Record<string, unknown>;\n    if (Array.isArray(nested.subcollections)) {\n        nested.subcollections = nested.subcollections.map(\n            (child) => withoutAdminBlock(child as CollectionConfig)\n        );\n    }\n    return rest as CollectionConfig;\n}\n\n/**\n * Rebuild collections received from a contract endpoint.\n *\n * Relation refs become real thunks resolving through the returned set, so\n * downstream consumers — the SDK generator above all — see exactly the shape\n * they would have seen had the collections been imported from source.\n *\n * A ref naming a collection that is not in the payload resolves to `undefined`\n * rather than throwing: the generator already tolerates an unresolvable target\n * by falling back to a permissive key type, and a partial contract should still\n * produce a usable SDK.\n */\nexport function deserializeCollections(payload: unknown[]): CollectionConfig[] {\n    const collections = payload\n        .filter((c): c is Record<string, unknown> => typeof c === \"object\" && c !== null)\n        .map(c => ({ ...c })) as unknown as CollectionConfig[];\n\n    const bySlug = new Map<string, CollectionConfig>();\n    for (const collection of collections) {\n        const ref = refFor(collection);\n        if (ref) bySlug.set(ref, collection);\n    }\n\n    const rehydrate = (value: unknown, depth: number): void => {\n        if (depth > MAX_DEPTH || !value || typeof value !== \"object\") return;\n\n        if (Array.isArray(value)) {\n            for (const item of value) rehydrate(item, depth + 1);\n            return;\n        }\n\n        const record = value as Record<string, unknown>;\n        for (const [key, child] of Object.entries(record)) {\n            if (key === \"target\" && isSerializedCollectionRef(child)) {\n                const slug = child.__collectionRef;\n                record.target = () => bySlug.get(slug);\n                continue;\n            }\n            rehydrate(child, depth + 1);\n        }\n    };\n\n    for (const collection of collections) rehydrate(collection, 0);\n    return collections;\n}\n","import type { CollectionConfig } from \"./collections\";\nimport { serializeCollections } from \"./collection_contract\";\n\n/**\n * The schema version stamp.\n *\n * One function, used in three places that must agree or the whole drift-detection\n * story is noise: `rebase build` writes it into a bundle manifest, the runtime\n * serves it from the contract endpoint, and a generated SDK records the value it\n * was built from. If any two of those computed it differently, every client would\n * look permanently out of date.\n *\n * It covers **collections only** — the client's contract is the shape of the\n * data, so editing a hook or a server function must not invalidate every SDK in\n * every repository. That is a deliberate narrowing, not an oversight.\n */\n\n/** Stable stringify: object keys sorted at every level, so key order cannot alter the hash. */\nfunction canonicalize(value: unknown): string {\n    if (value === null || typeof value !== \"object\") {\n        return JSON.stringify(value) ?? \"null\";\n    }\n    if (Array.isArray(value)) {\n        return `[${value.map(canonicalize).join(\",\")}]`;\n    }\n    const entries = Object.entries(value as Record<string, unknown>)\n        .filter(([, v]) => v !== undefined)\n        .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));\n    return `{${entries.map(([k, v]) => `${JSON.stringify(k)}:${canonicalize(v)}`).join(\",\")}}`;\n}\n\n/**\n * Reduce a collection to the parts a generated client is actually built from.\n *\n * The version answers one question — \"is this SDK stale?\" — so it must change\n * exactly when the generated types could change, and never otherwise. Hashing a\n * whole collection fails both halves of that:\n *\n * - Security rules, callbacks, icons, groups and UI settings do not appear in a\n *   generated client, so including them reports perfectly current SDKs as stale.\n * - Worse, they are not stable *inputs*. The runtime applies default security\n *   rules when it loads collections, so the same source hashed before and after\n *   loading produced two different answers — a build-time stamp that could never\n *   match the server that served it.\n *\n * Codegen reads the slug (for the `Database` key and type names), the properties,\n * and the relations. That is the projection.\n */\nfunction projectForCodegen(collection: CollectionConfig): Record<string, unknown> {\n    const source = collection as CollectionConfig & {\n        relations?: unknown;\n        subcollections?: CollectionConfig[];\n        path?: string;\n        engine?: unknown;\n        dataSource?: unknown;\n    };\n\n    return {\n        slug: collection.slug ?? source.path,\n        properties: collection.properties,\n        relations: source.relations,\n        // The engine decides whether relations are resolved at all: codegen asks\n        // `getDataSourceCapabilities(collection.engine).supportsRelations`, and an\n        // engine that answers no drops every foreign-key column from the\n        // generated Row/Insert/Update types. Moving a collection to such an\n        // engine is a real change to the generated types, so it has to move the\n        // version. `dataSource` is what resolves to `engine`, so it counts too.\n        engine: source.engine,\n        dataSource: source.dataSource,\n        subcollections: source.subcollections?.map(projectForCodegen)\n    };\n}\n\n/**\n * Compute the canonical string a schema version hashes.\n *\n * Exposed separately so the hashing itself can differ by environment: Node has\n * `crypto`, and callers without it can still compare canonical forms directly.\n */\nexport function canonicalSchemaPayload(collections: CollectionConfig[]): string {\n    const projected = serializeCollections(collections)\n        .map(collection => projectForCodegen(collection as CollectionConfig));\n    return canonicalize(projected);\n}\n\n/**\n * A short, non-cryptographic digest of the canonical payload.\n *\n * FNV-1a style, 64 bits, as two 32-bit halves. This is an identity, not a\n * security boundary: nothing trusts a schema version to prove anything, it only\n * answers \"is this the same schema as before\". A hand-rolled hash keeps this\n * module free of `node:crypto`, so the identical function runs in the browser,\n * in the CLI, and in the runtime — which is the property that actually matters.\n */\nexport function computeSchemaVersion(collections: CollectionConfig[]): string {\n    const payload = canonicalSchemaPayload(collections);\n\n    let h1 = 0x811c9dc5;\n    let h2 = 0x01000193;\n\n    for (let i = 0; i < payload.length; i++) {\n        const code = payload.charCodeAt(i);\n        h1 ^= code;\n        // Multiply by the FNV prime using shifts to stay in 32-bit integer math.\n        h1 = (h1 + ((h1 << 1) + (h1 << 4) + (h1 << 7) + (h1 << 8) + (h1 << 24))) >>> 0;\n        h2 ^= code + i;\n        h2 = (h2 + ((h2 << 1) + (h2 << 5) + (h2 << 9) + (h2 << 15) + (h2 << 24))) >>> 0;\n    }\n\n    const hex = (n: number): string => n.toString(16).padStart(8, \"0\");\n    return `v1:${hex(h1)}${hex(h2)}`;\n}\n","import type { CollectionRegistryController } from \"./collection_registry\";\nimport type { EntityStatus, EntityValues } from \"../types/entities\";\nimport type { CollectionConfig, FilterValues } from \"../types/collections\";\nimport type { RebaseCallContext } from \"../call_context\";\n\n\n/**\n * @internal\n */\nexport interface FetchOneProps<M extends Record<string, unknown> = Record<string, unknown>> {\n    path: string;\n    id: string | number;\n    databaseId?: string;\n    collection?: CollectionConfig<M>\n}\n\n/**\n * @internal\n */\nexport type ListenOneProps<M extends Record<string, unknown> = Record<string, unknown>> =\n    FetchOneProps<M>\n    & {\n        onUpdate: (row: Record<string, unknown> | null) => void,\n        onError?: (error: Error) => void,\n    }\n\n/**\n * Configuration for vector similarity search queries.\n * Vector search applies an ORDER BY distance expression and optionally\n * filters results by a distance threshold.\n */\nexport interface VectorSearchParams {\n    /** Property name containing the vector column */\n    property: string;\n    /** Query vector to compare against */\n    vector: number[];\n    /** Distance function (default: \"cosine\") */\n    distance?: \"cosine\" | \"l2\" | \"inner_product\";\n    /** Only return results within this distance threshold */\n    threshold?: number;\n}\n\n// ── List pagination bounds ────────────────────────────────────────────────\n//\n// Client-driven list reads (REST `GET /<collection>` and the WebSocket\n// `subscribe_collection` message) accept a client-supplied `limit`. Without\n// bounds, an ABSENT limit streams the entire table into memory — a trivial\n// OOM/DoS — and `limit=100000000` (or `limit=0`, historically an unlimited\n// bypass) is honoured verbatim. `resolveClientListLimit` is the single shared\n// enforcement point so every untrusted ingress behaves identically. Trusted\n// server-side callers build fetch options directly and are intentionally NOT\n// bounded here (migrations, admin exports, and CDC refetches may need the full\n// set).\n\n/** Rows returned for a plain / text-search list read when the client sends no `limit`. */\nexport const DEFAULT_LIST_LIMIT = 50;\n/** Rows returned for a vector-search list read when the client sends no `limit`. */\nexport const DEFAULT_VECTOR_LIST_LIMIT = 10;\n/** Hard ceiling clamped onto any client-supplied `limit`, on every surface. */\nexport const MAX_LIST_LIMIT = 1000;\n\n/** Overridable bounds for {@link resolveClientListLimit}. */\nexport interface ListLimitBounds {\n    /** Default page size for plain and text-search reads. */\n    defaultLimit?: number;\n    /** Default page size for vector-search reads. */\n    vectorDefaultLimit?: number;\n    /** Upper bound clamped onto any client-supplied limit. */\n    maxLimit?: number;\n}\n\n/**\n * Resolve a client-supplied list `limit` into a safe, always-defined value.\n *\n * - A provided limit is coerced to an integer and clamped to `[1, maxLimit]`,\n *   so `0`, negatives, and absurd values can never bypass the cap.\n * - An absent / blank / non-numeric limit falls back to the mode default:\n *   `vectorDefaultLimit` for a vector search, otherwise `defaultLimit`.\n *\n * The return is never `undefined` — no ingress that routes its client limit\n * through this can produce an unbounded read.\n */\nexport function resolveClientListLimit(\n    rawLimit: number | string | null | undefined,\n    opts: ListLimitBounds & { vectorSearch?: boolean } = {}\n): number {\n    const maxLimit = opts.maxLimit ?? MAX_LIST_LIMIT;\n    if (rawLimit != null && String(rawLimit).trim() !== \"\") {\n        const parsed = typeof rawLimit === \"number\" ? rawLimit : parseInt(String(rawLimit), 10);\n        if (Number.isFinite(parsed)) {\n            return Math.min(Math.max(1, Math.floor(parsed)), maxLimit);\n        }\n    }\n    return opts.vectorSearch\n        ? (opts.vectorDefaultLimit ?? DEFAULT_VECTOR_LIST_LIMIT)\n        : (opts.defaultLimit ?? DEFAULT_LIST_LIMIT);\n}\n\n/**\n * @internal\n */\nexport interface FetchCollectionProps<M extends Record<string, unknown> = Record<string, unknown>> {\n    path: string;\n    collection?: CollectionConfig<M>;\n    filter?: FilterValues<Extract<keyof M, string>>,\n    limit?: number;\n    offset?: number;\n    startAfter?: unknown;\n    orderBy?: string;\n    searchString?: string;\n    order?: \"desc\" | \"asc\";\n    /** Vector similarity search configuration */\n    vectorSearch?: VectorSearchParams;\n}\n\n/**\n * @internal\n */\nexport type ListenCollectionProps<M extends Record<string, unknown> = Record<string, unknown>> =\n    FetchCollectionProps<M> &\n    {\n        onUpdate: (rows: Record<string, unknown>[]) => void;\n        onError?: (error: Error) => void;\n    };\n\n/**\n * @internal\n */\nexport interface SaveProps<M extends Record<string, unknown> = Record<string, unknown>> {\n    path: string;\n    values: Partial<EntityValues<M>>;\n    id?: string | number; // can be empty for new entities\n    previousValues?: Partial<EntityValues<M>>;\n    collection?: CollectionConfig<M>;\n    status: EntityStatus;\n    /**\n     * Write the row with INSERT ... ON CONFLICT DO UPDATE on the primary key\n     * instead of choosing between insert and update up front.\n     *\n     * One statement, so it does not lose the race a read-then-write can, and it\n     * succeeds whether or not the row is already there — what a re-runnable\n     * import needs. Requires every primary key column to be present; without\n     * them there is no conflict target and the row is inserted normally.\n     */\n    upsert?: boolean;\n}\n\n/**\n * @internal\n */\nexport interface SaveManyProps<M extends Record<string, unknown> = Record<string, unknown>> {\n    path: string;\n    /**\n     * The rows to write. A row carrying its primary key updates (or, with\n     * `upsert`, inserts-or-updates) that row; one without inserts.\n     */\n    rows: Partial<EntityValues<M>>[];\n    collection?: CollectionConfig<M>;\n    /** Apply every row as INSERT ... ON CONFLICT DO UPDATE. See {@link SaveProps.upsert}. */\n    upsert?: boolean;\n}\n\n/**\n * @internal\n */\nexport interface DeleteProps<M extends Record<string, unknown> = Record<string, unknown>> {\n    row: { id: string | number; path: string; values?: Partial<EntityValues<M>> };\n    collection?: CollectionConfig<M>;\n}\n\nexport type FilterCombinationValidProps = {\n    path: string;\n    databaseId?: string;\n    collection: CollectionConfig;\n    filterValues: FilterValues<string>;\n    sortBy?: [string, \"asc\" | \"desc\"];\n};\n\n/**\n * The integration SPI for plugging a data backend into Rebase.\n *\n * Implement this interface to connect a custom backend (or use a built-in\n * driver such as the Firestore one) and register it on\n * `<Rebase dataSources>`. Rebase wraps drivers via `buildRebaseData` and\n * routes collections to them by their `dataSource` key.\n *\n * For *consuming* data in application code, use `RebaseData` /\n * `context.data` instead — this interface is only for providing it.\n *\n * @group Datasource\n */\nexport interface DataDriver {\n\n    /**\n     * Key that identifies this driver\n     */\n    key?: string;\n\n    /**\n     * If the driver has been initialised\n     */\n    initialised?: boolean;\n\n    /**\n     * Fetch data from a collection\n     * @param props\n     * @return Promise of flat rows\n     */\n    fetchCollection<M extends Record<string, unknown> = Record<string, unknown>>(props: FetchCollectionProps<M>): Promise<Record<string, unknown>[]>;\n\n    /**\n     * Listen to a collection in a given path. If you don't implement this method\n     * `fetchCollection` will be used instead, with no real time updates.\n     * @param props\n     * @return Function to cancel subscription\n     */\n    listenCollection?<M extends Record<string, unknown> = Record<string, unknown>>(props: ListenCollectionProps<M>): () => void;\n\n    /**\n     * Retrieve a single row given a path and a collection\n     * @param props\n     */\n    fetchOne<M extends Record<string, unknown> = Record<string, unknown>>(props: FetchOneProps<M>): Promise<Record<string, unknown> | undefined>;\n\n    /**\n     * Get realtime updates on one row.\n     * @param props\n     * @return Function to cancel subscription\n     */\n    listenOne?<M extends Record<string, unknown> = Record<string, unknown>>(props: ListenOneProps<M>): () => void;\n\n    /**\n     * Save a row to the specified path\n     * @param props\n     */\n    save<M extends Record<string, unknown> = Record<string, unknown>>(props: SaveProps<M>): Promise<Record<string, unknown>>;\n\n    /**\n     * Save many rows as one unit of work.\n     *\n     * Every row runs the same pipeline as {@link save} — callbacks, relations\n     * and row-level security all still apply — but they share a single\n     * transaction, so the batch either lands whole or not at all. That, and the\n     * single round trip, is what makes importing tens of thousands of rows\n     * viable without dropping to raw SQL.\n     *\n     * Optional: drivers that cannot do this leave it undefined and callers fall\n     * back to `save` per row.\n     */\n    saveMany?<M extends Record<string, unknown> = Record<string, unknown>>(props: SaveManyProps<M>): Promise<Record<string, unknown>[]>;\n\n    /**\n     * Delete a entity\n     * @param props\n     * @return was the whole deletion flow successful\n     */\n    delete<M extends Record<string, unknown> = Record<string, unknown>>(props: DeleteProps<M>): Promise<void>;\n\n    /**\n     * Delete all entities from a collection.\n     * @param path Collection path\n     */\n    deleteAll?(path: string): Promise<void>;\n\n    /**\n     * Check if the given property is unique in the given collection\n     * @param path Collection path\n     * @param name of the property\n     * @param value\n     * @param id\n     * @param collection\n     * @return `true` if there are no other fields besides the given entity\n     */\n    checkUniqueField(\n        path: string,\n        name: string,\n        value: unknown,\n        id?: string | number,\n        collection?: CollectionConfig\n    ): Promise<boolean>;\n\n    /**\n     * Count the number of entities in a collection\n     */\n    count?<M extends Record<string, unknown> = Record<string, unknown>>(props: FetchCollectionProps<M>): Promise<number>;\n\n    /**\n     * Check if the given filter combination is valid\n     * @param props\n     */\n    isFilterCombinationValid?(props: Omit<FilterCombinationValidProps, \"collection\"> & {\n        databaseId?: string\n    }): boolean;\n\n    /**\n     * Get the object to generate the current time in the driver\n     */\n    currentTime?: () => unknown;\n\n    delegateToCMSModel?: (data: unknown) => unknown;\n\n    cmsToDelegateModel?: (data: unknown) => unknown;\n\n    initTextSearch?: (props: {\n        context: RebaseCallContext,\n        path: string,\n        databaseId?: string,\n        collection: CollectionConfig,\n        parentCollectionSlugs?: string[];\n        parentEntityIds?: string[];\n    }) => Promise<boolean>;\n\n    /**\n     * Flag to indicate if the driver has requested the initialization of the text search index\n     */\n    needsInitTextSearch?: boolean;\n\n    // ── REST fetch capabilities ─────────────────────────────────────────\n\n    /**\n     * Optional REST-optimised fetch service. When present, the REST API\n     * generator uses these methods instead of the generic `fetchOne` /\n     * `fetchCollection` pipeline, enabling include-aware eager-loading.\n     */\n    restFetchService?: RestFetchService;\n\n    // ── Admin capabilities ─────────────────────────────────────────────\n    //\n    // Admin operations are now modelled as capability-specific interfaces\n    // (SQLAdmin, DocumentAdmin, SchemaAdmin) in `@rebasepro/types/backend`.\n    //\n    // Drivers that support admin features should expose them here.\n    // Consumers should use the `isSQLAdmin()`, `isSchemaAdmin()` etc.\n    // type guards to safely narrow the type before calling methods.\n\n    /**\n     * Return the admin capabilities of this driver.\n     * @see SQLAdmin\n     * @see DocumentAdmin\n     * @see SchemaAdmin\n     */\n    admin?: import(\"../types/backend\").DatabaseAdmin;\n\n}\n\n/**\n * REST-optimised fetch service exposed by drivers that support\n * eager-loading of relations via `include`.\n *\n * The methods return flattened rows — exactly the table's columns, under their\n * own names and with the types the database returned — and included relations\n * inlined as plain nested rows. This is the shape served to app developers\n * through the REST API / SDK client.\n *\n * No synthesized `id`: identity is a primary key, which may be named anything\n * and span several columns, so an address is derived by whoever needs one (see\n * `buildCompositeId`) rather than written into the row on top of the data.\n *\n * @group DataDriver\n */\nexport interface RestFetchService {\n    /**\n     * Fetch a collection of flattened entities with optional relation includes.\n     */\n    fetchCollectionForRest(\n        collectionPath: string,\n        options?: {\n            filter?: FilterValues<string>;\n            orderBy?: string;\n            order?: \"desc\" | \"asc\";\n            limit?: number;\n            offset?: number;\n            startAfter?: Record<string, unknown>;\n            searchString?: string;\n            databaseId?: string;\n            vectorSearch?: VectorSearchParams;\n        },\n        include?: string[]\n    ): Promise<Record<string, unknown>[]>;\n\n    /**\n     * Fetch a single flattened entity with optional relation includes.\n     */\n    fetchOneForRest(\n        collectionPath: string,\n        id: string | number,\n        include?: string[],\n        databaseId?: string\n    ): Promise<Record<string, unknown> | null>;\n}\n","/**\n * Path prefix that marks an object as **public**. Files stored under this\n * prefix are served without any auth token via a stable, permanent,\n * CDN-cacheable URL (see {@link StorageSource.getSignedUrl}). Shared by the\n * client SDK and the backend so both agree on which objects are public.\n *\n * @group Models\n */\nexport const PUBLIC_STORAGE_PREFIX = \"public/\";\n\n/**\n * True when a storage key/path points at a public object (lives under\n * {@link PUBLIC_STORAGE_PREFIX}). The check is applied to the key *within the\n * bucket* — strip any `bucket/` and `scheme://` prefixes first.\n *\n * @group Models\n */\nexport function isPublicStoragePath(path: string | null | undefined): boolean {\n    if (!path) return false;\n    let p = path;\n    const scheme = p.indexOf(\"://\");\n    if (scheme !== -1) p = p.substring(scheme + 3);\n    p = p.replace(/^\\/+/, \"\");\n\n    // Defense-in-depth: a path containing traversal segments is never public,\n    // so an attacker can't reach a private object via `public/../secret`.\n    if (p.split(\"/\").some((seg) => seg === \"..\")) return false;\n\n    // Public iff the object **key** starts with the public prefix. A single\n    // leading `default/` bucket segment is tolerated (the default bucket).\n    // A substring match is deliberately NOT used — a private object under a\n    // folder literally named `public` (e.g. `reports/public/q3.pdf`) must stay\n    // private. Named buckets: pass the key (not `bucket/key`) so the prefix is\n    // anchored; otherwise it falls back to a private, token-scoped URL (safe).\n    return p.startsWith(PUBLIC_STORAGE_PREFIX) || p.startsWith(`default/${PUBLIC_STORAGE_PREFIX}`);\n}\n\n/**\n * @group Models\n */\nexport interface UploadFileProps {\n    file: File,\n    key: string,\n    metadata?: Record<string, unknown>,\n    bucket?: string,\n    /**\n     * Store this object as **public**: it is placed under\n     * {@link PUBLIC_STORAGE_PREFIX} and served via a stable, token-less,\n     * permanent URL (safe to persist in a database and cache on a CDN).\n     * Defaults to `false` (private, short-lived signed URLs).\n     */\n    public?: boolean\n}\n\n/**\n * @group Models\n */\nexport interface UploadFileResult {\n    /**\n     * Storage key including the file name where the file was uploaded.\n     */\n    key: string;\n    /**\n     * Bucket where the file was uploaded\n     */\n    bucket: string;\n\n    /**\n     * Fully qualified storage URL for the uploaded file.\n     *\n     * For example: `s3://my-bucket/path/to/file.png`.\n     *\n     * This is optional for backwards compatibility.\n     */\n    storageUrl?: string;\n}\n\n/**\n * @group Models\n */\nexport interface DownloadConfig {\n    /**\n     * Temporal url that can be used to download the file\n     */\n    url: string | null;\n\n    metadata?: DownloadMetadata;\n\n    fileNotFound?: boolean;\n}\n\n/**\n * The full set of object metadata, including read-only properties.\n * @public\n */\nexport declare interface DownloadMetadata {\n    /**\n     * The bucket this object is contained in.\n     */\n    bucket: string;\n    /**\n     * The full path of this object.\n     */\n    fullPath: string;\n    /**\n     * The short name of this object, which is the last component of the full path.\n     * For example, if path is 'full/path/image.png', name is 'image.png'.\n     */\n    name: string;\n    /**\n     * The size of this object, in bytes.\n     */\n    size: number;\n    /**\n     * Type of the uploaded file\n     * e.g. \"image/jpeg\"\n     */\n    contentType: string;\n\n    customMetadata: Record<string, unknown>;\n    /**\n     * Optional short-lived download token (for local/server-mediated storage).\n     * Absent for public objects, which need no token.\n     */\n    token?: string;\n    /**\n     * Optional remaining lifetime of the token, in seconds.\n     */\n    tokenExpiresIn?: number;\n    /**\n     * True when this object is public: it is served without a token via a\n     * stable, permanent, CDN-cacheable URL. When set, the client builds a\n     * token-less URL and caches it indefinitely.\n     */\n    public?: boolean;\n}\n\n/**\n * @group Models\n */\nexport interface StorageSource {\n    /**\n     * Upload an object, specifying a key\n     * @param file\n     * @param key\n     * @param metadata\n     * @param bucket\n     */\n    putObject: ({\n                     file,\n                     key,\n                     metadata,\n                     bucket\n                 }: UploadFileProps) => Promise<UploadFileResult>;\n\n    /**\n     * Convert a storage key or URL into a download configuration (signed URL equivalent)\n     * @param keyOrUrl\n     * @param bucket\n     */\n    getSignedUrl: (keyOrUrl: string, bucket?: string) => Promise<DownloadConfig>;\n\n    /**\n     * Get an object from a storage key.\n     * It returns null if the object does not exist.\n     * @param key\n     * @param bucket\n     */\n    getObject: (key: string, bucket?: string) => Promise<File | null>;\n\n    /**\n     * Delete an object.\n     * @param key\n     * @param bucket\n     */\n    deleteObject: (key: string, bucket?: string) => Promise<void>;\n\n    /**\n     * List the contents of a prefix.\n     * @param prefix\n     * @param options\n     */\n    listObjects: (prefix: string, options?: {\n        bucket?: string,\n        maxResults?: number,\n        pageToken?: string\n    }) => Promise<StorageListResult>;\n\n}\n\n/**\n * Result returned by list().\n * @public\n */\nexport declare interface StorageListResult {\n    /**\n     * References to prefixes (sub-folders). You can call list() on them to\n     * get its contents.\n     *\n     * Folders are implicit based on '/' in the object paths.\n     * For example, if a bucket has two objects '/a/b/1' and '/a/b/2', list('/a')\n     * will return '/a/b' as a prefix.\n     */\n    prefixes: StorageReference[];\n    /**\n     * Objects in this directory.\n     * You can call getMetadata() and getDownloadUrl() on them.\n     */\n    items: StorageReference[];\n    /**\n     * If set, there might be more results for this list. Use this token to resume the list.\n     */\n    nextPageToken?: string;\n}\n\n/**\n * Represents a reference to an S3-compatible storage object. Developers can\n * upload, download, and delete objects, as well as get/set object metadata.\n * @public\n */\nexport declare interface StorageReference {\n    /**\n     * Returns a s3:// URL for this object in the form\n     *   `s3://<bucket>/<path>/<to>/<object>`\n     * @returns The s3:// URL.\n     */\n    toString(): string;\n\n    /**\n     * A reference to the root of this object's bucket.\n     */\n    root: StorageReference;\n    /**\n     * The name of the bucket containing this reference's object.\n     */\n    bucket: string;\n    /**\n     * The full path of this object.\n     */\n    fullPath: string;\n    /**\n     * The short name of this object, which is the last component of the full path.\n     * For example, if path is 'full/path/image.png', name is 'image.png'.\n     */\n    name: string;\n\n    /**\n     * A reference pointing to the parent location of this reference, or null if\n     * this reference is the root.\n     */\n    parent: StorageReference | null;\n}\n"],"mappings":"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"}
+{"version":3,"file":"index.es.js","names":[],"sources":["../src/errors.ts","../src/types/entities.ts","../src/types/filter-operators.ts","../src/types/admin_block.ts","../src/types/data_source.ts","../src/types/collections.ts","../src/types/relations.ts","../src/types/policy.ts","../src/types/backend.ts","../src/types/channel_bus.ts","../src/types/storage_source.ts","../src/types/component_ref.ts","../src/types/project_manifest.ts","../src/types/collection_contract.ts","../src/types/schema_version.ts","../src/controllers/data_driver.ts","../src/controllers/storage.ts"],"sourcesContent":["/**\n * Structured initializer for {@link RebaseApiError}.\n *\n * @group Errors\n */\nexport interface RebaseErrorInit {\n    /**\n     * HTTP status code, when the error originated from an HTTP response.\n     * Left `undefined` for realtime/WebSocket, network, and client-side\n     * logic errors that have no HTTP status.\n     */\n    status?: number;\n    /** Stable, machine-readable error code (e.g. `\"NOT_FOUND\"`, `\"BAD_REQUEST\"`). */\n    code?: string;\n    /** Structured error payload returned by the server, when present. */\n    details?: unknown;\n    /** The underlying error this one wraps, if any. */\n    cause?: unknown;\n}\n\n/**\n * The single error type thrown across the entire Rebase client surface —\n * HTTP data/control-plane calls, realtime/WebSocket operations, and\n * client-side logic errors (e.g. an unknown collection accessor). A `catch`\n * block only ever needs to check for this one class:\n *\n * ```ts\n * import { RebaseApiError } from \"@rebasepro/client\"; // re-exported\n *\n * try {\n *   await client.data.products.update(id, { price: 9 });\n * } catch (e) {\n *   if (e instanceof RebaseApiError) {\n *     if (e.status === 404) { ... }   // HTTP failures carry a status\n *     console.error(e.code, e.details);\n *   }\n * }\n * ```\n *\n * `status` is present for HTTP failures and `undefined` otherwise, so its\n * presence distinguishes transport-level errors from realtime/logic errors.\n *\n * @group Errors\n */\nexport class RebaseApiError extends Error {\n    /** HTTP status code, or `undefined` for non-HTTP errors. */\n    readonly status?: number;\n    /** Stable machine-readable error code, when the server supplied one. */\n    readonly code?: string;\n    /** Structured error payload from the server, when present. */\n    readonly details?: unknown;\n\n    constructor(message: string, init: RebaseErrorInit = {}) {\n        super(message);\n        this.name = \"RebaseApiError\";\n        this.status = init.status;\n        this.code = init.code;\n        this.details = init.details;\n        if (init.cause !== undefined) {\n            // `cause` is standard on Error but not always in the lib target's type.\n            (this as { cause?: unknown }).cause = init.cause;\n        }\n    }\n}\n\n/**\n * Client-side logic error — raised before any request is made (e.g. accessing\n * an unknown collection accessor when a typed dictionary is configured).\n *\n * A subclass of {@link RebaseApiError} (with no `status`), so a single\n * `catch (e) { if (e instanceof RebaseApiError) ... }` handles it too.\n *\n * @group Errors\n */\nexport class RebaseClientError extends RebaseApiError {\n    constructor(message: string) {\n        super(message);\n        this.name = \"RebaseClientError\";\n    }\n}\n","/**\n * New or existing status\n * @group Models\n */\nexport type EntityStatus = \"new\" | \"existing\" | \"copy\";\n\n/**\n * Representation of a entity fetched from the driver\n * @group Models\n */\nexport interface Entity<M extends Record<string, unknown> = Record<string, unknown>> {\n\n    /**\n     * ID of the entity\n     */\n    id: string | number;\n\n    /**\n     * A string representing the path of the referenced document (relative\n     * to the root of the database).\n     */\n    path: string;\n\n    /**\n     * Current values\n     */\n    values: EntityValues<M>;\n\n    /**\n     * Which driver this entity belongs to (e.g., 'postgres', 'firestore').\n     * If not specified, the default driver is assumed.\n     */\n    driver?: string;\n\n    /**\n     * Which database within the driver (e.g., for Firestore multi-database).\n     * If not specified, the default database of the driver is used.\n     */\n    databaseId?: string;\n}\n\n/**\n * This type represents a record of key value pairs as described in an\n * entity collection.\n * @group Models\n */\nexport type EntityValues<M extends Record<string, unknown>> = M;\n\n/**\n * Props for creating a EntityReference\n */\nexport interface EntityReferenceProps {\n    /** ID of the entity */\n    id: string;\n    /** Path of the collection (relative to the root of the database) */\n    path: string;\n    /** Which driver (e.g., 'postgres', 'firestore'). Defaults to \"(default)\" */\n    driver?: string;\n    /** Which database within the driver. Defaults to \"(default)\" */\n    databaseId?: string;\n}\n\n/**\n * Class used to create a reference to a entity in a different path.\n *\n * @example\n * // Simple reference (most common case - single driver, single db)\n * new EntityReference({ id: \"123\", path: \"users\" })\n *\n * // Reference to a different driver (e.g., Firestore)\n * new EntityReference({ id: \"123\", path: \"analytics\", driver: \"firestore\" })\n *\n * // Reference to a specific database within a driver\n * new EntityReference({ id: \"123\", path: \"orders\", driver: \"postgres\", databaseId: \"orders_db\" })\n */\nexport class EntityReference {\n\n    readonly __type = \"reference\";\n    /**\n     * ID of the entity\n     */\n    readonly id: string;\n    /**\n     * A string representing the path of the referenced document (relative\n     * to the root of the database).\n     */\n    readonly path: string;\n\n    /**\n     * Which driver (e.g., 'postgres', 'firestore').\n     * Defaults to \"(default)\" if not specified.\n     */\n    readonly driver?: string;\n\n    /**\n     * Which database within the driver.\n     * Defaults to \"(default)\" if not specified.\n     */\n    readonly databaseId?: string;\n\n    /**\n     * Create a reference to a entity.\n     *\n     * @example\n     * // Simple reference (most common case)\n     * new EntityReference({ id: \"123\", path: \"users\" })\n     *\n     * // With driver\n     * new EntityReference({ id: \"123\", path: \"analytics\", driver: \"firestore\" })\n     */\n    constructor(props: EntityReferenceProps) {\n        this.id = props.id;\n        this.path = props.path;\n        this.driver = props.driver;\n        this.databaseId = props.databaseId;\n    }\n\n    get pathWithId() {\n        return `${this.path}/${this.id}`;\n    }\n\n    /**\n     * Get the full path including driver and database prefixes if specified.\n     * For the common case (single driver, single db), this just returns pathWithId.\n     */\n    get fullPath() {\n        const parts: string[] = [];\n\n        // Add driver prefix if not default\n        if (this.driver && this.driver !== \"(default)\") {\n            parts.push(this.driver);\n        }\n\n        // Add database prefix if specified\n        if (this.databaseId && this.databaseId !== \"(default)\") {\n            parts.push(this.databaseId);\n        }\n\n        if (parts.length > 0) {\n            return `${parts.join(\":\")}:::${this.path}/${this.id}`;\n        }\n        return this.pathWithId;\n    }\n\n    isEntityReference() {\n        return true;\n    }\n}\n\n/**\n * Class used to create a reference to a entity in a different path\n */\nexport class EntityRelation {\n\n    readonly __type = \"relation\";\n    /**\n     * ID of the entity\n     */\n    readonly id: string | number;\n    /**\n     * A string representing the path of the referenced document (relative\n     * to the root of the database).\n     */\n    readonly path: string;\n\n    /**\n     * Pre-fetched data payload to eliminate N+1 queries.\n     * When present, clients can use this directly instead of fetching.\n     */\n    readonly data?: Record<string, unknown>;\n\n    constructor(id: string | number, path: string, data?: Record<string, unknown>) {\n        this.id = id;\n        this.path = path;\n        this.data = data;\n    }\n\n    get pathWithId() {\n        return `${this.path}/${this.id}`;\n    }\n\n    isEntityReference() {\n        return false;\n    }\n\n    isEntityRelation() {\n        return true;\n    }\n}\n\nexport class GeoPoint {\n\n    /**\n     * The latitude of this GeoPoint instance.\n     */\n    readonly latitude: number;\n    /**\n     * The longitude of this GeoPoint instance.\n     */\n    readonly longitude: number;\n\n    constructor(latitude: number, longitude: number) {\n        this.latitude = latitude;\n        this.longitude = longitude;\n    }\n}\n\nexport class Vector {\n    readonly value: number[];\n\n    constructor(value: number[]) {\n        this.value = value;\n    }\n}\n","/**\n * Canonical filter operators and REST wire-format mappings.\n *\n * `WhereFilterOp` is THE operator type used at every layer — from React\n * components through the SDK, server, and down to the database driver.\n *\n * PostgREST short-codes (`eq`, `gt`, `cs`, …) exist **only** at the\n * HTTP wire boundary, handled by `serializeFilter` / `deserializeFilter`\n * in `@rebasepro/common`.\n *\n * ┌──────────────────────┬───────────────┬──────────────────────────────┐\n * │ Canonical            │ REST short    │ Meaning                      │\n * ├──────────────────────┼───────────────┼──────────────────────────────┤\n * │ \"==\"                 │ \"eq\"          │ Equal                        │\n * │ \"!=\"                 │ \"neq\"         │ Not equal                    │\n * │ \">\"                  │ \"gt\"          │ Greater than                 │\n * │ \">=\"                 │ \"gte\"         │ Greater than or equal        │\n * │ \"<\"                  │ \"lt\"          │ Less than                    │\n * │ \"<=\"                 │ \"lte\"         │ Less than or equal           │\n * │ \"in\"                 │ \"in\"          │ Value in list                │\n * │ \"not-in\"             │ \"nin\"         │ Value not in list            │\n * │ \"array-contains\"     │ \"cs\"          │ Array contains element       │\n * │ \"array-contains-any\" │ \"csa\"         │ Array contains any of        │\n * │ \"like\"               │ \"like\"        │ SQL LIKE (case-sensitive)    │\n * │ \"ilike\"              │ \"ilike\"       │ SQL ILIKE (case-insensitive) │\n * │ \"not-like\"           │ \"nlike\"       │ NOT LIKE (case-sensitive)    │\n * │ \"not-ilike\"          │ \"nilike\"      │ NOT ILIKE (case-insensitive) │\n * │ \"is-null\"            │ \"isnull\"      │ Field IS NULL                │\n * │ \"is-not-null\"        │ \"notnull\"     │ Field IS NOT NULL            │\n * └──────────────────────┴───────────────┴──────────────────────────────┘\n *\n * Pattern matching (`like`/`ilike`) uses SQL wildcard syntax: `%` matches any\n * sequence of characters, `_` matches a single character. On MongoDB these are\n * translated to anchored regular expressions; Firestore has no native pattern\n * matching and rejects these operators (use `searchString` instead).\n *\n * @module\n */\n\n/**\n * Canonical sort representation: `[fieldName, direction]`.\n *\n * Used in `FindParams.orderBy`, `collection.sort`, and `FilterPreset.sort`.\n * The colon-string form (`\"field:direction\"`) exists only at the HTTP wire\n * boundary, handled by `serializeOrderBy` / `deserializeOrderBy` in\n * `@rebasepro/common`.\n *\n * Design note: the natural extension for multi-column sort is\n * `OrderByTuple[]` — not implemented yet (server consumes only the first).\n *\n * @group Models\n */\nexport type OrderByTuple<Key extends string = string> = [Key, \"asc\" | \"desc\"];\n\n/**\n * Canonical filter operators supported across all database backends.\n * Each DB driver translates these to its native query format.\n *\n * @group Models\n */\nexport type WhereFilterOp =\n    | \"<\"\n    | \"<=\"\n    | \"==\"\n    | \"!=\"\n    | \">=\"\n    | \">\"\n    | \"array-contains\"\n    | \"in\"\n    | \"not-in\"\n    | \"array-contains-any\"\n    | \"like\"\n    | \"ilike\"\n    | \"not-like\"\n    | \"not-ilike\"\n    | \"is-null\"\n    | \"is-not-null\";\n\n/**\n * Used to define filters applied in collections.\n *\n * A single condition is a tuple `[operator, value]`.\n * Multiple conditions on the same field use an array of tuples.\n *\n * @example\n * // Single condition per field\n * { status: [\"==\", \"active\"], price: [\">=\", 9.99] }\n *\n * // Multiple conditions on one field\n * { age: [[\">=\", 18], [\"<\", 65]] }\n *\n * // Array operators\n * { role: [\"in\", [\"admin\", \"editor\"]] }\n * { tags: [\"array-contains\", \"featured\"] }\n *\n * // Pattern matching (SQL wildcards: % and _)\n * { name: [\"ilike\", \"%john%\"] }\n * { slug: [\"like\", \"post-%\"] }\n *\n * // Null checks (the value is ignored; `null` is conventional)\n * { deleted_at: [\"is-null\", null] }\n * { published_at: [\"is-not-null\", null] }\n *\n * @group Models\n */\nexport type FilterValues<Key extends string> =\n    Partial<Record<Key, [WhereFilterOp, unknown] | [WhereFilterOp, unknown][]>>;\n\n/**\n * The field names a query may address on a row type: every column, plus a\n * dotted path reaching inside one.\n *\n * Only the **root** of a dotted path is checked. `\"meta.tag\"` requires a `meta`\n * column and says nothing about what is under it, because what is under it is a\n * `map`/jsonb value whose shape the row type does not describe — and rejecting\n * paths we cannot verify would make jsonb columns unqueryable.\n *\n * When `M` is left at its default `Record<string, unknown>`, `keyof M` is\n * `string` and a template literal over `string` is itself assignable to\n * `string`, so this collapses to `string` and every query stays permissive.\n * That is what keeps an untyped `createRebaseClient()` behaving exactly as it\n * did before the row type was threaded through.\n *\n * @group Models\n */\nexport type FieldPath<M extends Record<string, unknown> = Record<string, unknown>> =\n    | Extract<keyof M, string>\n    | `${Extract<keyof M, string>}.${string}`;\n\n/**\n * Relaxed filter type that also accepts pre-serialized PostgREST strings.\n * **Internal only** — used at the wire-format boundary\n * (`serializeFilter` / `deserializeFilter` in `@rebasepro/common`).\n *\n * Application code, UI components, and SDK consumers should use\n * {@link FilterValues} instead.\n *\n * @internal\n */\nexport type WireFilterValues<Key extends string> =\n    Partial<Record<Key, [WhereFilterOp, unknown] | [WhereFilterOp, unknown][] | string>>;\n\n/**\n * A pre-defined filter preset for quick access in the collection toolbar.\n * Users can select a preset to instantly apply a set of filters and\n * optionally a sort order.\n *\n * @group Models\n */\nexport interface FilterPreset<Key extends string = string> {\n    /**\n     * Display label shown in the preset menu.\n     * If omitted, a summary is auto-generated from the filter keys.\n     */\n    label?: string;\n\n    /**\n     * The filter values to apply when this preset is selected.\n     */\n    filterValues: FilterValues<Key>;\n\n    /**\n     * Optional sort override to apply alongside the filter values.\n     */\n    sort?: OrderByTuple<Key>;\n}\n\n/**\n * PostgREST short-code operators. Wire format only — these never appear\n * in application code. Used by `serializeFilter`/`deserializeFilter`\n * in `@rebasepro/common`.\n */\nexport type RestFilterOp =\n    | \"eq\" | \"neq\"\n    | \"gt\" | \"gte\"\n    | \"lt\" | \"lte\"\n    | \"in\" | \"nin\"\n    | \"cs\" | \"csa\"\n    | \"like\" | \"ilike\"\n    | \"nlike\" | \"nilike\"\n    | \"isnull\" | \"notnull\";\n\n/** Maps canonical operators to their REST short-code equivalents. */\nexport const CANONICAL_TO_REST: Readonly<Record<WhereFilterOp, RestFilterOp>> = {\n    \"==\": \"eq\",\n    \"!=\": \"neq\",\n    \">\": \"gt\",\n    \">=\": \"gte\",\n    \"<\": \"lt\",\n    \"<=\": \"lte\",\n    \"in\": \"in\",\n    \"not-in\": \"nin\",\n    \"array-contains\": \"cs\",\n    \"array-contains-any\": \"csa\",\n    \"like\": \"like\",\n    \"ilike\": \"ilike\",\n    \"not-like\": \"nlike\",\n    \"not-ilike\": \"nilike\",\n    \"is-null\": \"isnull\",\n    \"is-not-null\": \"notnull\"\n};\n\n/** Maps REST short-code operators to their canonical equivalents. */\nexport const REST_TO_CANONICAL: Readonly<Record<RestFilterOp, WhereFilterOp>> = {\n    \"eq\": \"==\",\n    \"neq\": \"!=\",\n    \"gt\": \">\",\n    \"gte\": \">=\",\n    \"lt\": \"<\",\n    \"lte\": \"<=\",\n    \"in\": \"in\",\n    \"nin\": \"not-in\",\n    \"cs\": \"array-contains\",\n    \"csa\": \"array-contains-any\",\n    \"like\": \"like\",\n    \"ilike\": \"ilike\",\n    \"nlike\": \"not-like\",\n    \"nilike\": \"not-ilike\",\n    \"isnull\": \"is-null\",\n    \"notnull\": \"is-not-null\"\n};\n\n/**\n * Operators that test for null/not-null and therefore ignore their value.\n * Codecs normalize the value of these conditions to `null`.\n */\nexport const NULL_OPS: ReadonlySet<WhereFilterOp> = new Set<WhereFilterOp>([\n    \"is-null\", \"is-not-null\"\n]);\n\n/**\n * Every canonical operator, in a stable order. Useful for engine capability\n * declarations ({@link DataSourceCapabilities.filterOperators}) and for\n * building operator subsets.\n * @group Models\n */\nexport const ALL_WHERE_FILTER_OPS: readonly WhereFilterOp[] = [\n    \"<\", \"<=\", \"==\", \"!=\", \">=\", \">\",\n    \"in\", \"not-in\",\n    \"array-contains\", \"array-contains-any\",\n    \"like\", \"ilike\", \"not-like\", \"not-ilike\",\n    \"is-null\", \"is-not-null\"\n];\n\n/** All canonical operator strings for runtime validation. */\nconst CANONICAL_OPS: ReadonlySet<string> = new Set<WhereFilterOp>(ALL_WHERE_FILTER_OPS);\n\n/**\n * Resolve any operator string (canonical or REST short-code) to its\n * canonical `WhereFilterOp` form. Returns `undefined` for unknown operators.\n *\n * @example\n * toCanonicalOp(\"==\")   // \"==\"\n * toCanonicalOp(\"eq\")   // \"==\"\n * toCanonicalOp(\"cs\")   // \"array-contains\"\n * toCanonicalOp(\"xyz\")  // undefined\n */\nexport function toCanonicalOp(op: string): WhereFilterOp | undefined {\n    if (CANONICAL_OPS.has(op)) return op as WhereFilterOp;\n    return (REST_TO_CANONICAL as Record<string, WhereFilterOp | undefined>)[op];\n}\n","/**\n * The keys of a collection's admin block, as data.\n *\n * There is no *type* for the block in this package any more, and that is the point:\n * `admin` is not declared on `BaseCollectionConfig` or on any property here, so a\n * BaaS install cannot even write one. `@rebasepro/admin-types` adds the field back by\n * declaration merging, which is why installing it is what makes the admin surface\n * appear.\n *\n * The *list* still has to live here, because three runtime consumers need it and two\n * of them are core — see below.\n */\n\n/**\n * Every key that belongs inside a collection's `admin` block, as data.\n *\n * The type that describes these fields is `AdminCollectionOptions` in\n * `@rebasepro/admin-types`, and it is erased at build time — but three runtime\n * consumers need the list, and two of them are core:\n *\n * - `serializeCollections`, to drop the block from the contract\n * - the ts-morph schema editor in `@rebasepro/server`, which rewrites collection\n *   files on disk from the admin panel and has to know where each key goes. A key\n *   missing from this list gets written to the *top level* of the file, where the\n *   backend ignores it and the panel never finds it again.\n * - the `collections-admin-block` codemod\n *\n * `@rebasepro/admin-types` re-exports this and asserts it names only real option\n * keys; the count is pinned by a test there.\n *\n * @group Models\n */\nexport const ADMIN_COLLECTION_KEYS = [\n    \"Actions\",\n    \"additionalFields\",\n    \"alwaysApplyDefaultValues\",\n    \"components\",\n    \"defaultEntityAction\",\n    \"defaultFilter\",\n    \"defaultSelectedView\",\n    \"defaultSize\",\n    \"defaultViewMode\",\n    \"disableDefaultActions\",\n    \"enabledViews\",\n    \"entityActions\",\n    \"entityViews\",\n    \"exportable\",\n    \"filterPresets\",\n    \"fixedFilter\",\n    \"formAutoSave\",\n    \"formView\",\n    \"group\",\n    \"hideFromNavigation\",\n    \"hideIdFromCollection\",\n    \"hideIdFromForm\",\n    \"icon\",\n    \"includeJsonView\",\n    \"inlineEditing\",\n    \"kanban\",\n    \"listProperties\",\n    \"localChangesBackup\",\n    \"openEntityMode\",\n    \"orderProperty\",\n    \"pagination\",\n    \"previewProperties\",\n    \"propertiesOrder\",\n    \"selectionController\",\n    \"selectionEnabled\",\n    \"sideDialogWidth\",\n    \"sort\",\n    \"titleProperty\"\n] as const;\n\n/** A key of a collection's `admin` block. @group Models */\nexport type AdminCollectionKey = typeof ADMIN_COLLECTION_KEYS[number];\n\n/**\n * Every key that belongs inside a *property's* `admin` block, as data.\n *\n * The union of `AdminPropertyOptions` and its per-type extensions\n * (`AdminStringOptions`, `AdminArrayOptions`, …) in `@rebasepro/admin-types`.\n * It lives here for the same reason {@link ADMIN_COLLECTION_KEYS} does: the\n * runtime consumers are core packages that the BaaS guard forbids from\n * importing `@rebasepro/admin-types`. Here it is the boot-time collection\n * validator in `@rebasepro/server`, which has to tell \"you left `readOnly` at\n * the top of the property, where nothing reads it\" apart from \"you invented a\n * key we have never heard of\".\n *\n * `@rebasepro/admin-types` re-exports this and asserts it names only real\n * option keys.\n *\n * @group Models\n */\nexport const ADMIN_PROPERTY_KEYS = [\n    \"canAddElements\",\n    \"clearable\",\n    \"columnWidth\",\n    \"customProps\",\n    \"disabled\",\n    \"expanded\",\n    \"Field\",\n    \"Filter\",\n    \"filterOperators\",\n    \"fixedFilter\",\n    \"hideFromCollection\",\n    \"includeEntityLink\",\n    \"includeId\",\n    \"markdown\",\n    \"minimalistView\",\n    \"multiline\",\n    \"Preview\",\n    \"previewAsTag\",\n    \"previewProperties\",\n    \"readOnly\",\n    \"sortable\",\n    \"spreadChildren\",\n    \"urlPreview\",\n    \"widget\",\n    \"widthPercentage\"\n] as const;\n\n/** A key of a property's `admin` block. @group Models */\nexport type AdminPropertyKey = typeof ADMIN_PROPERTY_KEYS[number];\n","import { ALL_WHERE_FILTER_OPS, WhereFilterOp } from \"./filter-operators\";\n\n/**\n * Describes the capabilities and features supported by a data source (driver).\n *\n * Each driver (Postgres, Firebase, MongoDB, etc.) declares which features it\n * supports. The admin uses this descriptor to:\n * - Show/hide editor tabs (e.g. Relations for SQL, Subcollections for Firebase)\n * - Filter the property type picker (e.g. `relation` for SQL, `reference` for Firebase)\n * - Toggle driver-specific form controls (e.g. `columnType` for SQL)\n *\n * @group Models\n */\nexport interface DataSourceCapabilities {\n    /** Unique driver key (e.g. \"postgres\", \"firestore\", \"mongodb\") */\n    key: string;\n\n    /** Human-readable label for the UI (e.g. \"PostgreSQL\", \"Firebase / Firestore\") */\n    label: string;\n\n    // ── Feature flags ─────────────────────────────────────────────────\n    /** Does this source support SQL-style relations (JOINs)? */\n    supportsRelations: boolean;\n\n    /** Does this source support nested subcollections? */\n    supportsSubcollections: boolean;\n\n    /** Does this source support Row Level Security policies? */\n    supportsRLS: boolean;\n\n    /** Does this source support document references (Firebase-style)? */\n    supportsReferences: boolean;\n\n    /** Does this source support SQL column type annotations? */\n    supportsColumnTypes: boolean;\n\n    /** Does this source support real-time listeners? */\n    supportsRealtime: boolean;\n\n    /**\n     * Does this source store vectors natively?\n     *\n     * `VectorProperty` carries a `dimensions` and is pgvector-shaped. It was\n     * the one driver-specific property kind with no flag to gate it, so unlike\n     * every other field in this descriptor there was not even a runtime answer\n     * to appeal to — a Firestore collection could declare an embedding column\n     * and no driver would do anything with it.\n     */\n    supportsVectors: boolean;\n\n    /**\n     * Canonical filter operators this engine can execute.\n     *\n     * The admin UI intersects this set with the property-type defaults and\n     * any per-property narrowing (`property.ui.filterOperators`) to decide\n     * which operators to offer in filter fields — so an engine that cannot\n     * run `ilike` (e.g. Firestore) never shows a \"Contains\" filter that\n     * would throw at query time.\n     */\n    filterOperators: readonly WhereFilterOp[];\n\n    /**\n     * Relation kinds this engine's driver can compile into a filter.\n     *\n     * Only `belongsTo` puts a column on the row being filtered; the others are\n     * answered with a correlated subquery over the junction or the target\n     * table, which not every driver can build. An engine with no relations at\n     * all declares none.\n     *\n     * The admin uses this to decide whether a relation column offers a filter\n     * control. Offering one an engine cannot answer is not cosmetic: a driver\n     * that drops the key it cannot resolve *widens* the read to every row, and\n     * one that fails closed answers a control the admin itself put on screen\n     * with a 400.\n     *\n     * Optional, so a third-party driver registered before this existed still\n     * compiles. Omitted means {@link DEFAULT_FILTERABLE_RELATION_KINDS} — the\n     * one kind that is a plain column comparison, which every relational\n     * driver can do. The subquery kinds are a real capability and have to be\n     * claimed rather than assumed: assuming them wrongly is the widening.\n     */\n    filterableRelationKinds?: readonly string[];\n\n    // ── Admin capability flags ───────────────────────────────────────\n    /** Does this source support SQL admin operations (SQL editor, EXPLAIN, etc.)? */\n    supportsSQLAdmin: boolean;\n\n    /** Does this source support document admin operations (aggregation, stats)? */\n    supportsDocumentAdmin: boolean;\n\n    /** Does this source support schema admin (unmapped tables, table metadata)? */\n    supportsSchemaAdmin: boolean;\n}\n\n/**\n * Subset of DataSourceCapabilities containing only feature flags.\n * Useful when you only need to check capabilities without UI metadata.\n * @group Models\n */\nexport type DataSourceFeatures = Omit<DataSourceCapabilities, \"key\" | \"label\">;\n\n/**\n * The default data-source key, used when a collection does not name a\n * `dataSource`. Shared by the frontend router and the backend driver\n * registry so both agree on \"the default database\".\n * @group Models\n */\nexport const DEFAULT_DATA_SOURCE_KEY = \"(default)\";\n\n/**\n * How the *frontend* reaches a data source.\n *\n * - `\"server\"` — through the Rebase backend (the `RebaseClient`). The backend\n *   holds the actual database adapter and routes by data-source key. This is\n *   the default and covers Postgres, MongoDB, and any other server-mediated\n *   engine.\n * - `\"direct\"` — straight from the client to the external backend via its own\n *   SDK driver (e.g. Firestore). The Rebase backend is not in the data path.\n * - `\"custom\"` — a developer-supplied {@link DataDriver}, transport unspecified.\n *\n * @group Models\n */\nexport type DataSourceTransport = \"server\" | \"direct\" | \"custom\";\n\n/**\n * Declarative definition of a data source — a named place data lives.\n *\n * Declared once and shared front and back: the frontend uses it to decide\n * transport (client vs direct driver), the backend uses the same `key` to\n * resolve a database adapter, and the editor derives capabilities from\n * `engine`. Collections reference a definition by its `key` via\n * `collection.dataSource`.\n *\n * @group Models\n */\nexport interface DataSourceDefinition {\n    /**\n     * Unique identifier for this data source. Collections point at it via\n     * `dataSource`. Defaults to {@link DEFAULT_DATA_SOURCE_KEY}.\n     */\n    key: string;\n\n    /**\n     * The engine backing this data source (e.g. `\"postgres\"`, `\"mongodb\"`,\n     * `\"firestore\"`, or a custom id). Determines the\n     * {@link DataSourceCapabilities} surfaced in the editor.\n     */\n    engine: string;\n\n    /**\n     * How the frontend reaches this source. Optional — when omitted it is\n     * inferred: `\"direct\"` if the definition carries a client-side driver,\n     * `\"server\"` otherwise.\n     */\n    transport?: DataSourceTransport;\n\n    /**\n     * The physical database/schema/Firestore-database within the engine.\n     * Threaded to drivers/adapters as the existing `databaseId` runtime\n     * parameter. Defaults to the engine's own default.\n     */\n    databaseId?: string;\n\n    /** Human-readable label for the UI. */\n    label?: string;\n}\n\n/**\n * The resolved data source for a collection: the single source of truth that\n * the frontend router, backend registry, and editor all derive from.\n * Produced by `resolveDataSource(collection, registry)`.\n *\n * @group Models\n */\nexport interface ResolvedDataSource {\n    /** Data-source key (routing key, shared front + back). */\n    key: string;\n    /** Engine backing the source (drives capabilities). */\n    engine: string;\n    /** Frontend transport. */\n    transport: DataSourceTransport;\n    /** Within-engine instance, if any (the `databaseId` runtime param). */\n    databaseId?: string;\n    /** Capabilities derived from {@link engine}. */\n    capabilities: DataSourceCapabilities;\n}\n\n/**\n * Relation kinds assumed filterable when a driver does not say.\n *\n * `belongsTo` alone: its filter is a comparison on a column of the row being\n * filtered, the one shape that needs no query construction a driver might not\n * have. Everything else is a correlated subquery over another table.\n *\n * @group Models\n */\nexport const DEFAULT_FILTERABLE_RELATION_KINDS: readonly string[] = [\"belongsTo\"];\n\n// ── Built-in driver capabilities ─────────────────────────────────────\n\n/** @group Models */\nexport const POSTGRES_CAPABILITIES: DataSourceCapabilities = {\n    key: \"postgres\",\n    label: \"PostgreSQL\",\n    supportsRelations: true,\n    supportsSubcollections: false,\n    supportsRLS: true,\n    supportsReferences: false,\n    supportsColumnTypes: true,\n    supportsRealtime: true,\n    supportsVectors: true,\n    filterOperators: ALL_WHERE_FILTER_OPS,\n    // `via` is absent: its join path is authored source → target with no\n    // stated inverse, so the driver has nothing to reverse into a filter.\n    filterableRelationKinds: [\"belongsTo\", \"manyToMany\", \"hasMany\", \"hasOne\"],\n    supportsSQLAdmin: true,\n    supportsDocumentAdmin: false,\n    supportsSchemaAdmin: true\n};\n\n/** @group Models */\nexport const FIREBASE_CAPABILITIES: DataSourceCapabilities = {\n    key: \"firestore\",\n    label: \"Firebase / Firestore\",\n    supportsRelations: false,\n    supportsSubcollections: true,\n    supportsRLS: false,\n    supportsReferences: true,\n    supportsColumnTypes: false,\n    supportsRealtime: true,\n    supportsVectors: false,\n    // Firestore has no SQL pattern matching — the driver throws on the LIKE\n    // family, so the UI must never offer it.\n    filterOperators: ALL_WHERE_FILTER_OPS.filter(op =>\n        op !== \"like\" && op !== \"ilike\" && op !== \"not-like\" && op !== \"not-ilike\"),\n    // No relations at all — a document store links by reference.\n    filterableRelationKinds: [],\n    supportsSQLAdmin: false,\n    supportsDocumentAdmin: false,\n    supportsSchemaAdmin: false\n};\n\n/** @group Models */\nexport const MONGODB_CAPABILITIES: DataSourceCapabilities = {\n    key: \"mongodb\",\n    label: \"MongoDB\",\n    supportsRelations: false,\n    supportsSubcollections: true,\n    supportsRLS: false,\n    supportsReferences: true,\n    supportsColumnTypes: false,\n    supportsRealtime: false,\n    supportsVectors: false,\n    filterOperators: ALL_WHERE_FILTER_OPS,\n    filterableRelationKinds: [],\n    supportsSQLAdmin: false,\n    supportsDocumentAdmin: true,\n    supportsSchemaAdmin: true\n};\n\n/**\n * Fallback capabilities when the driver is unknown.\n * Enables everything so nothing is hidden unexpectedly.\n * @group Models\n */\nexport const DEFAULT_CAPABILITIES: DataSourceCapabilities = {\n    key: \"(default)\",\n    label: \"Default\",\n    supportsRelations: true,\n    supportsSubcollections: true,\n    supportsRLS: true,\n    supportsReferences: true,\n    supportsColumnTypes: true,\n    supportsRealtime: true,\n    supportsVectors: true,\n    filterOperators: ALL_WHERE_FILTER_OPS,\n    // The exception to this descriptor's \"enable everything\" rule. The other\n    // flags hide a tab or a picker when they are wrong; this one decides\n    // whether a query is sent that an unknown driver may answer by dropping\n    // the condition — which returns every row rather than none.\n    filterableRelationKinds: DEFAULT_FILTERABLE_RELATION_KINDS,\n    supportsSQLAdmin: true,\n    supportsDocumentAdmin: true,\n    supportsSchemaAdmin: true\n};\n\nconst CAPABILITIES_REGISTRY: Record<string, DataSourceCapabilities> = {\n    postgres: POSTGRES_CAPABILITIES,\n    firestore: FIREBASE_CAPABILITIES,\n    mongodb: MONGODB_CAPABILITIES,\n    \"(default)\": DEFAULT_CAPABILITIES\n};\n\n/**\n * Look up capabilities for a given engine key.\n * If `engine` is undefined or not found, returns `DEFAULT_CAPABILITIES`.\n * @group Models\n */\nexport function getDataSourceCapabilities(engine?: string): DataSourceCapabilities {\n    if (!engine) return POSTGRES_CAPABILITIES; // postgres is the default engine\n    return CAPABILITIES_REGISTRY[engine] ?? DEFAULT_CAPABILITIES;\n}\n\n/**\n * Register custom capabilities for a third-party driver.\n * @group Models\n */\nexport function registerDataSourceCapabilities(capabilities: DataSourceCapabilities): void {\n    CAPABILITIES_REGISTRY[capabilities.key] = capabilities;\n}\n","import type { CollectionCallbacks } from \"./entity_callbacks\";\n\nimport type { EnumValues, Properties, PostgresProperties, FirebaseProperties, MongoProperties } from \"./properties\";\n\nimport type { User } from \"../users\";\nimport type { Relation } from \"./relations\";\nimport type { SecurityRule } from \"./security_rules\";\nimport { getDataSourceCapabilities } from \"./data_source\";\nimport type { WhereFilterOp, FilterValues, FilterPreset } from \"./filter-operators\";\n\n/**\n * Base interface containing all driver-agnostic collection properties.\n * Use {@link PostgresCollectionConfig} or {@link FirebaseCollectionConfig} for\n * driver-specific type safety, or {@link CollectionConfig} when you\n * need to handle any collection regardless of backend.\n *\n * @group Models\n */\nexport interface BaseCollectionConfig<M extends Record<string, unknown> = Record<string, unknown>, USER extends User = User> {\n\n    /**\n     * You can set an alias that will be used internally instead of the collection name.\n     * The `slug` value will be used to determine the URL of the collection.\n     * Note that you can use this value in reference properties too.\n     */\n    slug: string;\n\n    /**\n     * Name of the collection, typically plural.\n     * E.g. `Products`, `Blog`\n     */\n    name: string;\n\n    /**\n     * Singular name of an entry in this collection\n     * E.g. `Product`, `Blog entry`\n     */\n    singularName?: string;\n\n    /**\n     * Optional description of this view. You can use Markdown.\n     */\n    description?: string;\n\n    /**\n     * Child collections nested under entities of this collection.\n     * Populated automatically during normalization from driver-specific fields\n     * (e.g. Firebase `subcollections`, Postgres `relations` with many-cardinality).\n     *\n     * Custom drivers can set this directly to expose child collections to the UI.\n     */\n    childCollections?: () => CollectionConfig<Record<string, unknown>>[];\n\n\n    /**\n     * The data source this collection belongs to — the routing key shared by\n     * the frontend router and the backend driver registry. It points at a\n     * {@link DataSourceDefinition} registered on `<Rebase dataSources>` (front)\n     * and `initializeRebaseBackend({ dataSources })` (back).\n     *\n     * If not specified, the default data source `\"(default)\"` is used, which\n     * for a standard Rebase app is the server-mediated Postgres backend.\n     *\n     * @example\n     * // Default data source (server-mediated Postgres)\n     * { slug: \"products\" }\n     *\n     * // A direct-transport Firestore data source registered as \"analytics\"\n     * { slug: \"events\", dataSource: \"analytics\" }\n     */\n    dataSource?: string;\n\n    /**\n     * The database engine backing this collection (`\"postgres\"`, `\"firestore\"`,\n     * `\"mongodb\"`, or a custom id).\n     *\n     * On concrete collection types ({@link PostgresCollectionConfig},\n     * {@link FirebaseCollectionConfig}, {@link MongoDBCollectionConfig}) this is a literal\n     * discriminant. On the base type it is optional and gets stamped\n     * automatically during collection normalization from the registered\n     * {@link DataSourceDefinition}.\n     *\n     * Prefer setting {@link dataSource} and letting the engine be resolved.\n     */\n    engine?: string;\n\n    /**\n     * Which database within the engine.\n     * - For Firestore: The Firestore database ID (e.g., for multi-database projects)\n     * - For PostgreSQL: Schema or database name\n     * - For MongoDB: Database name\n     *\n     * If not specified, the default database of the engine is used. Resolved\n     * from the collection's {@link DataSourceDefinition} when omitted here.\n     */\n    databaseId?: string;\n\n    /**\n     * Set of properties that compose a entity\n     */\n    properties: Properties;\n\n\n\n\n\n\n\n\n\n\n\n\n    /**\n     * Mark this collection as an authentication collection.\n     * When true, this collection is used for user management, login, password hashing, and invitation flows.\n     */\n    auth?: boolean | AuthCollectionConfig;\n\n\n\n\n\n\n\n    /**\n     * Row-level authorization rules for this collection.\n     *\n     * Driver-agnostic on purpose, unlike `disableDefaultPolicies`, `table` and\n     * `relations`, which are declared on {@link PostgresCollectionConfig} only.\n     * The rules are a *contract* — who may read or write which rows — and each\n     * engine enforces it its own way:\n     *\n     * - **Postgres** compiles them to real `CREATE POLICY` statements and lets\n     *   the database enforce them (see {@link PostgresCollectionConfig.securityRules},\n     *   which narrows this with the raw-SQL details).\n     * - **MongoDB** translates them into a query filter it AND-s into every\n     *   read and write, honouring `access`, `ownerField`, `roles`, `mode` and\n     *   the `operation`/`operations` selectors, and making a best effort at raw\n     *   `using`/`withCheck` SQL.\n     * - **Firestore** does not implement them at all; its own rules language is\n     *   evaluated by Google, not from here. `supportsRLS` on\n     *   {@link DataSourceCapabilities} reports which engines generate policies,\n     *   which is not the same question as whether an engine honours a rule.\n     */\n    securityRules?: readonly SecurityRule[];\n\n    /**\n     * This interface defines all the callbacks that can be used when a entity\n     * is being created, updated or deleted.\n     * Useful for adding your own logic or blocking the execution of the operation.\n     */\n    readonly callbacks?: CollectionCallbacks<M, USER>;\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n    /**\n     * User id of the owner of this collection. This is used only by plugins, or if you\n     * are writing custom code\n     */\n    ownerId?: string;\n\n    /**\n     * Arbitrary key-value metadata for external consumers.\n     * Not interpreted by Rebase — passed through serialization unchanged.\n     * Used by domain apps to store custom per-collection config.\n     */\n    metadata?: Record<string, unknown>;\n\n\n\n\n    /**\n     * If set to true, changes to the entity will be saved in a subcollection.\n     * This prop has no effect if the history plugin is not enabled\n     */\n    history?: boolean;\n\n    /**\n     * Whether a write naming a field this collection does not declare is\n     * rejected with a 400. Defaults to `true`.\n     *\n     * Set to `false` to let unknown keys through to the database, which is what\n     * happened before this existed: a typo reached the INSERT and came back as\n     * a Postgres error about a column, or — where a column really does exist\n     * that the config never declared, populated by a trigger or a default —\n     * quietly worked. The second case is the reason for the escape hatch.\n     */\n    strictWrites?: boolean;\n\n\n\n\n\n\n\n\n}\n\n// ── Driver-specific collection types ──────────────────────────────────\n\n/**\n * A collection backed by PostgreSQL (or any SQL database).\n * Adds support for SQL-style relations (JOINs) and Row Level Security.\n *\n * Use this type instead of {@link CollectionConfig} when you want\n * compile-time safety that only SQL-relevant fields appear.\n *\n * @group Models\n */\nexport interface PostgresCollectionConfig<M extends Record<string, unknown> = Record<string, unknown>, USER extends User = User>\n    extends BaseCollectionConfig<M, USER> {\n    properties: PostgresProperties;\n\n    /**\n     * The database engine for this collection. For Postgres collections this\n     * can be omitted (Postgres is the default) or set to `\"postgres\"`.\n     */\n    engine?: \"postgres\" | undefined;\n\n    /**\n     * The PostgreSQL table name for this collection.\n     */\n    table: string;\n\n    /**\n     * The PostgreSQL schema name for this table.\n     * E.g. \"public\", \"rebase\", \"auth\".\n     * If not specified, \"public\" is used (or the default search path).\n     */\n    schema?: string;\n\n    /**\n     * For SQL databases, you can define the relations between collections here.\n     * Relations describe JOINs, foreign keys, and junction tables.\n     */\n    relations?: Relation[];\n\n    /**\n     * Security rules for this collection (PostgreSQL Row Level Security).\n     * When defined, the schema generator will enable RLS on the table and\n     * create the corresponding PostgreSQL policies.\n     *\n     * Supports three levels of expressiveness:\n     * 1. **Convenience shortcuts** — `ownerField`, `access`, `roles`\n     * 2. **Raw SQL** — `using` and `withCheck` for full PostgreSQL power\n     * 3. **Combined** — mix shortcuts with `roles` for common patterns\n     *\n     * The authenticated user context is available in raw SQL via:\n     * - `auth.uid()`   — the current user's ID\n     * - `auth.roles()` — comma-separated app role IDs\n     * - `auth.jwt()`   — full JWT claims as JSONB\n     */\n    securityRules?: readonly SecurityRule[];\n\n    /**\n     * Opt out of the framework's default Row Level Security policies.\n     *\n     * The schema generator automatically injects, for every collection, a\n     * baseline SELECT policy granting the trusted server context and the\n     * `admin` role read access (reads run under a restricted role, so RLS\n     * default-denies without it). For auth collections it additionally injects\n     * a self-read policy (`id = auth.uid()`) and an admin-only write gate\n     * (INSERT/UPDATE/DELETE require the `admin` role or the trusted server\n     * context), making privileged columns such as `roles` safe by default.\n     *\n     * Author-defined `securityRules` are permissive and broaden access on top\n     * of these defaults. Set this flag to `true` to remove the defaults\n     * entirely and take full responsibility for the collection's RLS.\n     *\n     * @default false\n     */\n    disableDefaultPolicies?: boolean;\n}\n\n/**\n * A collection backed by Firebase / Firestore.\n * Adds support for subcollections (nested document collections).\n *\n * Use this type instead of {@link CollectionConfig} when you want\n * compile-time safety that only Firestore-relevant fields appear.\n *\n * @group Models\n */\nexport interface FirebaseCollectionConfig<M extends Record<string, unknown> = Record<string, unknown>, USER extends User = User>\n    extends BaseCollectionConfig<M, USER> {\n    /**\n     * The database engine for this collection. Must be set to `\"firestore\"`.\n     */\n    engine: \"firestore\";\n\n    /**\n     * Set of properties that compose a entity.\n     * Firestore collections support `reference` properties but not `relation`.\n     */\n    properties: FirebaseProperties;\n\n    /**\n     * The Firestore collection path to query. Defaults to `slug` if not set.\n     * Use this when the Firestore path differs from the slug\n     * (e.g., when a PostgreSQL collection already uses the same slug).\n     *\n     * @example\n     * ```typescript\n     * const fsCustomer: FirebaseCollectionConfig = {\n     *     slug: \"fs_customer\",        // URL: /c/fs_customer\n     *     path: \"customer\",           // Firestore path: customer\n     *     name: \"Customers (Firestore)\",\n     *     engine: \"firestore\",\n     *     properties: { ... }\n     * };\n     * ```\n     */\n    path?: string;\n\n    /**\n     * You can add subcollections to your entity in the same way you define the root\n     * collections. The collections added here will be displayed when opening\n     * the side dialog of a entity.\n     */\n    subcollections?: () => CollectionConfig<Record<string, unknown>>[];\n}\n\n/**\n * A collection backed by MongoDB.\n *\n * Use this type instead of {@link CollectionConfig} when you want\n * compile-time safety that only MongoDB-relevant fields appear.\n *\n * @group Models\n */\nexport interface MongoDBCollectionConfig<M extends Record<string, unknown> = Record<string, unknown>, USER extends User = User>\n    extends BaseCollectionConfig<M, USER> {\n\n    /**\n     * The database engine for this collection. Must be set to `\"mongodb\"`.\n     */\n    engine: \"mongodb\";\n\n    /**\n     * Set of properties that compose a entity.\n     * MongoDB collections support `reference` properties but not `relation`.\n     */\n    properties: MongoProperties;\n\n    /**\n     * The MongoDB collection name to use. Defaults to `slug` if not set.\n     * Use this when the MongoDB collection name differs from the slug\n     * (e.g., when a PostgreSQL collection already uses the same slug).\n     *\n     * @example\n     * ```typescript\n     * const mongoCustomer: MongoDBCollectionConfig = {\n     *     slug: \"mongo_customer\",      // URL: /c/mongo_customer\n     *     path: \"customer\",            // MongoDB collection: customer\n     *     name: \"Customers (MongoDB)\",\n     *     engine: \"mongodb\",\n     *     properties: { ... }\n     * };\n     * ```\n     */\n    path?: string;\n}\n\n/**\n * A collection backed by any data source.\n * This is a discriminated union — use {@link PostgresCollectionConfig},\n * {@link FirebaseCollectionConfig}, or {@link MongoDBCollectionConfig} for\n * driver-specific type safety.\n *\n * @group Models\n */\nexport type CollectionConfig<M extends Record<string, unknown> = Record<string, unknown>, USER extends User = User> =\n    | PostgresCollectionConfig<M, USER>\n    | FirebaseCollectionConfig<M, USER>\n    | MongoDBCollectionConfig<M, USER>;\n\n/**\n * A collection of *any* row type.\n *\n * `CollectionConfig` is **invariant** in `M`: `callbacks` both consumes `M`\n * (`AfterReadProps<M>`) and produces it, so neither direction of assignment\n * holds. `CollectionConfig<SomeRow>` is therefore not assignable to a bare\n * `CollectionConfig`, whose `M` defaults to `Record<string, unknown>`.\n *\n * That matters wherever a collection is merely *referred to* rather than read\n * from. `defineCollection` returns a config whose `M` is inferred from the\n * properties — the whole point of it — so a field typed `() => CollectionConfig`\n * rejects every collection the builder produces, and `target: () => otherCollection`\n * (the documented way to point a relation at its other end) does not compile in\n * any project that uses the builder.\n *\n * `any` is deliberate and is what it is for here: these positions never read the\n * target's rows, they only identify which collection is meant, so there is no\n * type safety to preserve and invariance is pure obstruction.\n *\n * @group Models\n */\nexport type AnyCollectionConfig = CollectionConfig<any, any>;\n\n/**\n * Type guard for PostgreSQL collections.\n * Returns true if the collection uses the Postgres engine (or the default engine).\n *\n * Generic over the *input* type, and narrows by intersection rather than\n * replacement. Narrowing to a bare `PostgresCollectionConfig` discarded whatever\n * the caller actually had — most visibly the admin panel's view model, whose\n * flattened presentation fields vanished the moment a collection passed through\n * one of these guards.\n *\n * @group Models\n */\nexport function isPostgresCollectionConfig<C extends CollectionConfig<any, any>>(\n    collection: C\n): collection is C & PostgresCollectionConfig<any, any> {\n    return !collection.engine || collection.engine === \"postgres\";\n}\n\n/**\n * Narrows to the SQL collection fields — `table`, `relations`,\n * `disableDefaultPolicies` — by asking the engine's declared capabilities\n * rather than by naming Postgres.\n *\n * The two halves of this already existed and were never joined. The engine\n * split (`PostgresCollectionConfig` / `FirebaseCollectionConfig` /\n * `MongoDBCollectionConfig`) said which fields belong to which engine at the\n * type level; {@link DataSourceCapabilities} said the same thing at runtime,\n * down to a `supportsRelations` flag. So call sites guarded on the capability\n * and then read a field the base type had to declare for them — which is why\n * those fields were on the base, and why a MongoDB collection could be written\n * with a `table`.\n *\n * Prefer this over {@link isPostgresCollectionConfig} wherever the question is\n * \"does this collection live in a SQL table\", so a custom SQL engine\n * registered through `registerDataSourceCapabilities` is included.\n *\n * @group Models\n */\nexport function isRelationalCollectionConfig<C extends CollectionConfig<any, any>>(\n    collection: C\n): collection is C & PostgresCollectionConfig<any, any> {\n    return getDataSourceCapabilities(collection.engine).supportsRelations;\n}\n\n/**\n * Type guard for Firebase / Firestore collections.\n * @group Models\n */\nexport function isFirebaseCollectionConfig<C extends CollectionConfig<any, any>>(\n    collection: C\n): collection is C & FirebaseCollectionConfig<any, any> {\n    return collection.engine === \"firestore\";\n}\n\n/**\n * Type guard for MongoDB collections.\n * @group Models\n */\nexport function isMongoDBCollectionConfig<C extends CollectionConfig<any, any>>(\n    collection: C\n): collection is C & MongoDBCollectionConfig<any, any> {\n    return collection.engine === \"mongodb\";\n}\n\n/**\n * Returns the data path for a collection.\n * For Firestore or MongoDB collections with a `path`, returns that value;\n * otherwise falls back to `slug`.\n */\nexport function getCollectionDataPath<M extends Record<string, unknown> = Record<string, unknown>, USER extends User = User>(\n    collection: CollectionConfig<M, USER>\n): string {\n    if (isFirebaseCollectionConfig(collection) && collection.path) {\n        return collection.path;\n    }\n    if (isMongoDBCollectionConfig(collection) && collection.path) {\n        return collection.path;\n    }\n    return collection.slug;\n}\n\n/**\n * Reads a collection's driver-declared subcollections thunk (the `subcollections`\n * field) independent of engine identity, so engine-agnostic code doesn't have to\n * type-guard against a specific driver. Returns `undefined` when the collection\n * declares none.\n *\n * Pair with `getDataSourceCapabilities(engine).supportsSubcollections` to decide\n * whether the engine honours subcollections at all before reading them.\n * @group Models\n */\nexport function getDeclaredSubcollections<M extends Record<string, unknown> = Record<string, unknown>, USER extends User = User>(\n    collection: CollectionConfig<M, USER>\n): (() => CollectionConfig<Record<string, unknown>>[]) | undefined {\n    return (collection as FirebaseCollectionConfig<M, USER>).subcollections;\n}\n\n/**\n * Where the rows in an {@link EntityChildView} come from.\n *\n * The two are not the same thing, and conflating them is what made a Postgres\n * relation borrow Firestore's addressing:\n *\n * - `subcollection` is **containment**. The rows live under the parent; the\n *   path is their identity, and they cannot exist without it. This is what\n *   Firestore has natively.\n * - `relation` is a **link**. The rows are an ordinary collection, narrowed to\n *   those the parent reaches. `owned` means the child carries the parent's\n *   foreign key and belongs to it alone; `linked` means the row is shared\n *   through a junction, so what the parent controls is the link, not the row.\n *\n * @group Models\n */\nexport type ChildViewSource =\n    | { kind: \"subcollection\" }\n    | {\n        kind: \"relation\";\n        relationKey: string;\n        mode: \"owned\" | \"linked\";\n        /**\n         * Slug of the collection the rows actually live in.\n         *\n         * Distinct from the view's `key`, which is the relation. A `linked` view\n         * needs both: the key addresses the parent's set, and this addresses the\n         * whole collection to pick an existing row out of.\n         */\n        targetSlug: string;\n    };\n\n/**\n * A list of rows rendered inside an entity view — the tab under a record.\n *\n * This is a *presentation* descriptor, which is the whole point: rendering a\n * related list as a tab used to require minting a child `CollectionConfig` with\n * its own slug, which dragged a URL grammar, a path resolver and a second\n * read/write pipeline along with it. A tab needs a key, a collection to list,\n * and to know where its rows come from.\n *\n * @group Models\n */\nexport interface EntityChildView<M extends Record<string, unknown> = Record<string, unknown>> {\n    /**\n     * Stable identifier for this view: the tab id and the path segment.\n     *\n     * For a relation this is the **relation key** — the name the backend\n     * resolves a nested path segment by — not the target collection's slug.\n     * Those differ whenever a relation is named, which is every inline relation\n     * property, and the mismatch is why such a tab used to open onto an error.\n     */\n    key: string;\n\n    /** The collection whose rows this view lists, with any overrides applied. */\n    collection: CollectionConfig<M>;\n\n    source: ChildViewSource;\n}\n\n\nexport type { WhereFilterOp, FilterValues, WireFilterValues, FilterPreset } from \"./filter-operators\";\n\n\nexport type InferCollectionConfigType<S extends CollectionConfig> = S extends CollectionConfig<infer M> ? M : never;\n\n/**\n * Configuration for authentication collections.\n *\n * Controls what happens when admins create users, reset passwords,\n * and which entity actions are auto-injected.\n *\n * Use `auth: true` as sugar for `{ enabled: true }` with all defaults.\n *\n * @example Override user creation\n * ```ts\n * auth: {\n *     enabled: true,\n *     onCreateUser: async (values, ctx) => {\n *         const hash = await ctx.hashPassword(\"welcome123\");\n *         return {\n *             values: { ...values, passwordHash: hash, emailVerified: true },\n *             temporaryPassword: \"welcome123\",\n *         };\n *     },\n * }\n * ```\n *\n * @example Disable the reset-password entity action\n * ```ts\n * auth: {\n *     enabled: true,\n *     actions: { resetPassword: false },\n * }\n * ```\n *\n * @group Models\n */\nexport interface AuthCollectionConfig {\n    /** Set to true to mark this collection as the authentication collection. */\n    enabled: boolean;\n\n    /**\n     * Called when an admin creates a user via the collection REST API.\n     *\n     * Default: generate password → hash → normalize email → save →\n     *          send invitation email (or return temp password if no email configured).\n     *\n     * Override to implement custom invitation flows, LDAP sync, etc.\n     */\n    onCreateUser?: (\n        values: Record<string, unknown>,\n        ctx: AuthCollectionContext\n    ) => Promise<AuthCollectionCreateResult>;\n\n    /**\n     * Called when an admin resets a user's password via the admin panel.\n     *\n     * Default: generate reset token → send email (or generate + return temp password).\n     * Override for custom reset flows.\n     */\n    onResetPassword?: (\n        uid: string,\n        ctx: AuthCollectionContext\n    ) => Promise<AuthCollectionResetResult>;\n\n    /**\n     * Control which auth-specific entity actions are auto-injected.\n     *\n     * Default: `{ resetPassword: true }` — the framework auto-injects\n     * the built-in `resetPasswordAction` into the collection's entity actions.\n     *\n     * Set to `false` to disable, or pass a custom `EntityAction` to replace the UI.\n     *\n     * The object form is an `EntityAction` from `@rebasepro/admin-types`, typed\n     * here as `object` because it is a React component with admin controllers in\n     * its props and nothing on the server reads it — only whether the built-in\n     * action is injected, which is the boolean.\n     */\n    actions?: {\n        resetPassword?: boolean | object;\n    };\n}\n\n/**\n * Context provided to collection-level auth hooks.\n *\n * This is a simplified facade over the server internals —\n * it exposes only what's needed for custom auth flows without\n * coupling collection config to internal interfaces.\n *\n * @group Models\n */\nexport interface AuthCollectionContext {\n    /** Hash a password using the configured algorithm (scrypt by default). */\n    hashPassword: (password: string) => Promise<string>;\n    /** Send an email. Only available when email service is configured. */\n    sendEmail?: (options: { to: string; subject: string; html: string; text?: string }) => Promise<void>;\n    /** Whether the email service is configured and available. */\n    emailConfigured: boolean;\n    /** The app name from email config (for templates). */\n    appName: string;\n    /** The base URL for password reset links. */\n    resetPasswordUrl: string;\n}\n\n/**\n * Result of a collection-level `onCreateUser` hook.\n * @group Models\n */\nexport interface AuthCollectionCreateResult {\n    /** Processed values to persist (must include passwordHash, NOT raw password). */\n    values: Record<string, unknown>;\n    /** If set, shown to the admin in the creation result dialog. */\n    temporaryPassword?: string;\n    /** Whether an invitation email was sent. */\n    invitationSent?: boolean;\n}\n\n/**\n * Result of a collection-level `onResetPassword` hook.\n * @group Models\n */\nexport interface AuthCollectionResetResult {\n    /** If set, shown to the admin. */\n    temporaryPassword?: string;\n    /** Whether a reset email was sent. */\n    invitationSent?: boolean;\n}\n","import type { AnyCollectionConfig } from \"./collections\";\n\n/**\n * @group Models\n */\nexport type OnAction = \"cascade\" | \"restrict\" | \"no action\" | \"set null\" | \"set default\";\n\n/**\n * What kind of link a relation is.\n *\n * The discriminant. Every other field a relation carries belongs to exactly one\n * of these, which is the point: a relation used to be a single open interface\n * where `cardinality`, `direction`, `localKey`, `foreignKeyOnTarget`, `through`\n * and `joinPath` were all optional and any combination typechecked. Which link\n * you meant then had to be *inferred* from which fields you happened to set,\n * and the inference was ~200 lines that guessed, fell back on naming\n * conventions, and swallowed its own failures.\n *\n * Most of that guessing produced bugs rather than convenience. A `many`\n * relation carrying a `localKey` — a combination the old type permitted — made\n * the write path stamp the parent's own foreign key onto the child row. Under\n * these kinds that state cannot be written down.\n *\n * @group Models\n */\nexport type RelationKind = \"belongsTo\" | \"hasOne\" | \"hasMany\" | \"manyToMany\" | \"via\";\n\n/** Fields every relation carries, whatever its kind. @group Models */\nexport interface RelationBase {\n    /**\n     * The name this link is addressed by: the key in `include`, the tab in the\n     * admin panel, and the path segment of a nested URL.\n     *\n     * Defaults to the declaring property's key, or to the target's slug for an\n     * entry in `relations`.\n     */\n    relationName?: string;\n\n    /** The collection on the other end. */\n    target: () => AnyCollectionConfig;\n\n    onUpdate?: OnAction;\n    onDelete?: OnAction;\n\n    /** Presentation overrides applied when this relation is rendered as a tab. */\n    overrides?: Partial<AnyCollectionConfig>;\n\n    validation?: {\n        required?: boolean;\n    };\n}\n\n/**\n * This collection holds the foreign key. One target row per source row.\n *\n * ```ts\n * author: { kind: \"belongsTo\", target: () => authors, localKey: \"author_id\" }\n * ```\n * @group Models\n */\nexport interface BelongsToRelation extends RelationBase {\n    kind: \"belongsTo\";\n    /**\n     * Column on **this** collection's table holding the target's key.\n     * Defaults to `<relationName>_id`.\n     */\n    localKey?: string;\n}\n\n/**\n * The target holds the foreign key, and at most one target row points back.\n *\n * ```ts\n * profile: { kind: \"hasOne\", target: () => profiles, foreignKeyOnTarget: \"user_id\" }\n * ```\n * @group Models\n */\nexport interface HasOneRelation extends RelationBase {\n    kind: \"hasOne\";\n    /**\n     * Column on the **target's** table holding this collection's key.\n     * Defaults to `<thisCollection>_id`.\n     */\n    foreignKeyOnTarget?: string;\n}\n\n/**\n * The target holds the foreign key, and many target rows point back. The\n * children belong to this parent alone — deleting one deletes a row.\n *\n * ```ts\n * posts: { kind: \"hasMany\", target: () => posts, foreignKeyOnTarget: \"author_id\" }\n * ```\n * @group Models\n */\nexport interface HasManyRelation extends RelationBase {\n    kind: \"hasMany\";\n    /**\n     * Column on the **target's** table holding this collection's key.\n     * Defaults to `<thisCollection>_id`.\n     */\n    foreignKeyOnTarget?: string;\n}\n\n/**\n * Both sides hold many, through a junction table. The target rows are shared,\n * so this collection owns the *link* and not the row: removing one removes a\n * junction row and leaves the target alone.\n *\n * Declared the same way from either side — there is no owning and inverse\n * version. Swap `sourceColumn` and `targetColumn` to describe the other\n * direction.\n *\n * ```ts\n * tags: { kind: \"manyToMany\", target: () => tags }\n * ```\n * @group Models\n */\nexport interface ManyToManyRelation extends RelationBase {\n    kind: \"manyToMany\";\n    /**\n     * The junction table and its two key columns. Every part defaults: the\n     * table to both table names sorted and joined, the columns to\n     * `<collection>_id` and `<relationName>_id`.\n     */\n    through?: {\n        table?: string;\n        /** Junction column holding **this** collection's key. */\n        sourceColumn?: string;\n        /** Junction column holding the **target's** key. */\n        targetColumn?: string;\n    };\n}\n\n/**\n * An explicit chain of joins, for links the four shapes above cannot express:\n * multi-hop paths, composite keys, or a join whose condition is not a plain\n * foreign key.\n *\n * Read-only. Rebase will not infer how to write through an arbitrary join\n * chain, and guessing is what this type exists to stop.\n *\n * ```ts\n * permissions: {\n *     kind: \"via\",\n *     target: () => permissions,\n *     cardinality: \"many\",\n *     joinPath: [\n *         { table: \"user_roles\",       on: { from: \"id\",            to: \"user_id\" } },\n *         { table: \"role_permissions\", on: { from: \"role_id\",       to: \"role_id\" } },\n *         { table: \"permissions\",      on: { from: \"permission_id\", to: \"id\" } }\n *     ]\n * }\n * ```\n * @group Models\n */\nexport interface ViaRelation extends RelationBase {\n    kind: \"via\";\n    /** Whether the chain yields one row or many. Cannot be derived from a join chain. */\n    cardinality: \"one\" | \"many\";\n    joinPath: JoinStep[];\n}\n\n/**\n * A link from one collection to another, as authored.\n *\n * A closed union: pick the kind that describes the link and the type offers\n * exactly the fields that kind needs. See {@link ResolvedRelation} for the form\n * the runtime works with, which has every default filled in.\n *\n * @group Models\n */\nexport type Relation =\n    | BelongsToRelation\n    | HasOneRelation\n    | HasManyRelation\n    | ManyToManyRelation\n    | ViaRelation;\n\n/**\n * A relation with every default filled in — the form the runtime works with.\n *\n * The authored {@link Relation} and this are deliberately different types.\n * They used to be one, which meant no reader could tell which fields had been\n * supplied and which had been guessed, and so every consumer re-derived what it\n * needed with its own chain of `if (through) … else if (localKey) …` fallbacks.\n * Those chains disagreed with each other; that disagreement is what produced\n * silently wrong reads and corrupt writes.\n *\n * Here each variant carries exactly its own fields, all required. A consumer\n * switches on `kind` and gets what it needs without a fallback, and the cases\n * it forgot are a compile error rather than a wrong answer at runtime.\n *\n * @group Models\n */\nexport type ResolvedRelation =\n    | ResolvedBelongsTo\n    | ResolvedHasOne\n    | ResolvedHasMany\n    | ResolvedManyToMany\n    | ResolvedVia;\n\n/** Fields present on every resolved relation. @group Models */\nexport interface ResolvedRelationBase {\n    /** Always set: defaulted during resolution if the author omitted it. */\n    relationName: string;\n    target: () => AnyCollectionConfig;\n    /** The target's slug, resolved once so consumers need not call `target()`. */\n    targetSlug: string;\n    onUpdate?: OnAction;\n    onDelete?: OnAction;\n    overrides?: Partial<AnyCollectionConfig>;\n    validation?: { required?: boolean };\n    /**\n     * Whether one row or many come back. Derived from `kind` — kept because it\n     * is what most consumers actually branch on, and because `via` is the one\n     * kind where it is authored rather than implied.\n     */\n    cardinality: \"one\" | \"many\";\n    /**\n     * Whether Rebase knows how to write through this link. False only for\n     * {@link ResolvedVia}, whose join chain it will not invent a write for.\n     */\n    writable: boolean;\n    /**\n     * Whether the target rows are shared with other parents. True for\n     * many-to-many and for multi-hop `via`: what the parent owns is the link,\n     * so removing one must not delete the row.\n     */\n    shared: boolean;\n}\n\n/** @group Models */\nexport interface ResolvedBelongsTo extends ResolvedRelationBase {\n    kind: \"belongsTo\";\n    cardinality: \"one\";\n    writable: true;\n    shared: false;\n    /** Column on this collection's table. */\n    localKey: string;\n}\n\n/** @group Models */\nexport interface ResolvedHasOne extends ResolvedRelationBase {\n    kind: \"hasOne\";\n    cardinality: \"one\";\n    writable: true;\n    shared: false;\n    /** Column on the target's table. */\n    foreignKeyOnTarget: string;\n}\n\n/** @group Models */\nexport interface ResolvedHasMany extends ResolvedRelationBase {\n    kind: \"hasMany\";\n    cardinality: \"many\";\n    writable: true;\n    shared: false;\n    /** Column on the target's table. */\n    foreignKeyOnTarget: string;\n}\n\n/** @group Models */\nexport interface ResolvedManyToMany extends ResolvedRelationBase {\n    kind: \"manyToMany\";\n    cardinality: \"many\";\n    writable: true;\n    shared: true;\n    through: {\n        table: string;\n        sourceColumn: string;\n        targetColumn: string;\n    };\n}\n\n/** @group Models */\nexport interface ResolvedVia extends ResolvedRelationBase {\n    kind: \"via\";\n    writable: false;\n    joinPath: JoinStep[];\n}\n\n// ── Narrowing helpers ────────────────────────────────────────────────\n//\n// Consumers that only care about one axis — \"does this list many rows\",\n// \"is there a column on the target\" — should ask that question rather\n// than enumerate kinds, so adding a kind later does not silently skip them.\n\n/** Relations whose target row carries this collection's key. @group Models */\nexport type ResolvedForeignKeyOnTarget = ResolvedHasOne | ResolvedHasMany;\n\n/** @group Models */\nexport function hasForeignKeyOnTarget(relation: ResolvedRelation): relation is ResolvedForeignKeyOnTarget {\n    return relation.kind === \"hasOne\" || relation.kind === \"hasMany\";\n}\n\n/** @group Models */\nexport function isManyToMany(relation: ResolvedRelation): relation is ResolvedManyToMany {\n    return relation.kind === \"manyToMany\";\n}\n\n/** @group Models */\nexport function isToMany(relation: ResolvedRelation): boolean {\n    return relation.cardinality === \"many\";\n}\n\n/**\n * Defines a single, explicit step in a multi-join path.\n *\n * Each step represents one JOIN operation in the sequence. The `from` columns\n * refer to the previous table in the chain (or the source table for the first step),\n * and the `to` columns refer to the current table being joined.\n *\n * @example Single column join:\n * ```typescript\n * {\n *   table: \"authors\",\n *   on: {\n *     from: \"author_id\",  // Column from previous table (e.g., posts.author_id)\n *     to: \"id\"           // Column from current table (authors.id)\n *   }\n * }\n * ```\n *\n * @example Multi-column composite key join:\n * ```typescript\n * {\n *   table: \"order_items\",\n *   on: {\n *     from: [\"order_id\", \"store_id\"],    // Multiple columns from previous table\n *     to: [\"order_id\", \"store_id\"]       // Corresponding columns in current table\n *   }\n * }\n * ```\n */\nexport interface JoinStep {\n    /**\n     * The database table name to join TO in this step.\n     * This is the table you're joining into, not the table you're joining from.\n     *\n     * @example \"authors\", \"user_roles\", \"product_categories\"\n     */\n    table: string;\n\n    /**\n     * The join condition for this step. Defines how the previous table\n     * connects to the current table.\n     *\n     * - `from`: Column name(s) on the PREVIOUS table in the join chain\n     * - `to`: Column name(s) on the CURRENT table (specified in `table`)\n     *\n     * For the first step, `from` refers to the source collection's table.\n     * For subsequent steps, `from` refers to the table from the previous step.\n     *\n     * Both `from` and `to` support:\n     * - Single column: `\"user_id\"`\n     * - Multiple columns: `[\"company_id\", \"region_id\"]` for composite keys\n     *\n     * When using arrays, both `from` and `to` must have the same length,\n     * and columns are matched by position (index 0 with index 0, etc.).\n     */\n    on: {\n        from: string | string[];\n        to: string | string[];\n    };\n}\n","/**\n * Structured, engine-agnostic policy expressions.\n *\n * A {@link PolicyExpression} is the single source of truth for a row-level\n * security condition. It is compiled to Postgres `USING`/`WITH CHECK` SQL\n * (authoritative enforcement) and independently evaluated in JavaScript (to\n * drive the admin UI, and — in future — to enforce on engines without native\n * RLS such as MongoDB). Because both the SQL and the JS decision derive from\n * the *same* expression, the UI matches database enforcement by construction —\n * no drift between two hand-written implementations.\n *\n * The only escape hatch that cannot be evaluated client-side is the\n * {@link RawPolicyExpression} node (`{ kind: \"raw\" }`): it preserves full\n * PostgreSQL power but, being arbitrary SQL, is treated as *unknown* by the\n * JavaScript evaluator (never silently allowed) and reflected exactly in the UI\n * via server-computed capability flags.\n *\n * @group Models\n */\nexport type PolicyExpression =\n    | TruePolicyExpression\n    | FalsePolicyExpression\n    | AndPolicyExpression\n    | OrPolicyExpression\n    | NotPolicyExpression\n    | ComparePolicyExpression\n    | RolesOverlapPolicyExpression\n    | RolesContainPolicyExpression\n    | AuthenticatedPolicyExpression\n    | ServerContextPolicyExpression\n    | ExistsInPolicyExpression\n    | RawPolicyExpression;\n\n/**\n * The id a request without a logged-in user reports as `auth.uid()`.\n *\n * A user-context request always sets `app.uid`: blank would read back as\n * `NULL`, and `NULL` is how the trusted server context is recognised, so an\n * anonymous visitor would be promoted to server privileges. The driver\n * therefore substitutes this sentinel at the single chokepoint where the GUC\n * is set.\n *\n * The consequence for policy authors is that **`auth.uid() IS NOT NULL` is a\n * tautology on the user path** — it is true for anonymous visitors too. Use\n * {@link policy.authenticated} (or `auth.uid() <> 'anonymous'`) to mean \"signed\n * in\", and {@link policy.serverContext} to mean \"the trusted server context\".\n *\n * @group Models\n */\nexport const ANONYMOUS_USER_ID = \"anonymous\";\n\n/** Always allows. Compiles to `true`. @group Models */\nexport interface TruePolicyExpression {\n    kind: \"true\";\n}\n\n/** Always denies. Compiles to `false`. @group Models */\nexport interface FalsePolicyExpression {\n    kind: \"false\";\n}\n\n/** Logical AND — every operand must pass. @group Models */\nexport interface AndPolicyExpression {\n    kind: \"and\";\n    operands: readonly PolicyExpression[];\n}\n\n/** Logical OR — at least one operand must pass. @group Models */\nexport interface OrPolicyExpression {\n    kind: \"or\";\n    operands: readonly PolicyExpression[];\n}\n\n/** Logical negation. @group Models */\nexport interface NotPolicyExpression {\n    kind: \"not\";\n    operand: PolicyExpression;\n}\n\n/** Comparison operators available to {@link ComparePolicyExpression}. @group Models */\nexport type PolicyCompareOperator = \"eq\" | \"neq\" | \"lt\" | \"lte\" | \"gt\" | \"gte\";\n\n/**\n * Compares two operands, e.g. `owner_id = auth.uid()`.\n * @group Models\n */\nexport interface ComparePolicyExpression {\n    kind: \"compare\";\n    op: PolicyCompareOperator;\n    left: PolicyOperand;\n    right: PolicyOperand;\n}\n\n/**\n * True when the user holds *at least one* of the given application roles.\n * Compiles to `string_to_array(auth.roles(), ',') && ARRAY[...]`.\n * @group Models\n */\nexport interface RolesOverlapPolicyExpression {\n    kind: \"rolesOverlap\";\n    roles: readonly string[];\n}\n\n/**\n * True when the user holds *all* of the given application roles.\n * Compiles to `string_to_array(auth.roles(), ',') @> ARRAY[...]`.\n * @group Models\n */\nexport interface RolesContainPolicyExpression {\n    kind: \"rolesContain\";\n    roles: readonly string[];\n}\n\n/**\n * True when a signed-in user is making the request. Compiles to\n * `auth.uid() IS NOT NULL AND auth.uid() <> 'anonymous'`.\n *\n * Both halves are load-bearing. `IS NOT NULL` excludes the server context;\n * the {@link ANONYMOUS_USER_ID} comparison excludes anonymous visitors, who\n * *do* carry a non-null `auth.uid()`. Checking only `IS NOT NULL` grants to\n * everyone — see {@link ANONYMOUS_USER_ID}.\n *\n * `policy.not(policy.authenticated())` therefore means \"anonymous visitor or\n * the server context\". To single out the server context, use\n * {@link ServerContextPolicyExpression}.\n * @group Models\n */\nexport interface AuthenticatedPolicyExpression {\n    kind: \"authenticated\";\n}\n\n/**\n * True only in the trusted **server context** — the built-in flows that run\n * without a user (signup, migrations, `dataAsAdmin`) set no user GUC, so\n * `auth.uid()` is `NULL` for them and only for them. Compiles to\n * `auth.uid() IS NULL`.\n *\n * This is what lets the owner connection satisfy a policy even under FORCE RLS.\n * It is deliberately a primitive rather than `not(authenticated())`: the two\n * meant the same thing while `authenticated` ignored {@link ANONYMOUS_USER_ID},\n * and conflating them is what turns a server-only grant into an anonymous one.\n *\n * The JavaScript evaluator always returns `false` for this node — a client is\n * never the server context.\n * @group Models\n */\nexport interface ServerContextPolicyExpression {\n    kind: \"serverContext\";\n}\n\n/**\n * Membership / relational access: true when at least one row exists in another\n * collection (a join/membership table) matching `where`. This is what lets you\n * scope reads to \"rows whose team the caller belongs to\" without an N+1\n * per-row lookup — it compiles to a single correlated `EXISTS` subquery.\n *\n * Inside `where`, {@link FieldPolicyOperand} (`policy.field`) references a column\n * of the joined collection, while {@link OuterFieldPolicyOperand}\n * (`policy.outerField`) references a column of the row being checked (the outer\n * table under RLS). Combine with {@link AuthUidPolicyOperand} to correlate to\n * the caller.\n *\n * @example\n * ```ts\n * // documents visible only to members of the document's team:\n * policy.existsIn({\n *   collection: \"team_members\",\n *   where: policy.and(\n *     policy.compare(policy.field(\"team_id\"), \"eq\", policy.outerField(\"team_id\")),\n *     policy.compare(policy.field(\"user_id\"), \"eq\", policy.authUid()),\n *   ),\n * })\n * // → EXISTS (SELECT 1 FROM team_members _ex0\n * //           WHERE _ex0.team_id = documents.team_id AND _ex0.user_id = auth.uid())\n * ```\n *\n * Postgres-authoritative: like {@link RawPolicyExpression}, the JavaScript\n * evaluator treats it as *unknown* (it cannot run a subquery client-side), so\n * enforcement is always the database's.\n * @group Models\n */\nexport interface ExistsInPolicyExpression {\n    kind: \"existsIn\";\n    /** Slug of the collection to search (the join / membership table). */\n    collection: string;\n    /** Condition evaluated against the joined collection's rows. */\n    where: PolicyExpression;\n}\n\n/**\n * A raw PostgreSQL boolean expression — the full-power escape hatch.\n *\n * Columns can be referenced as `{column_name}`. This is Postgres-only and\n * **server-authoritative**: the JavaScript evaluator cannot evaluate arbitrary\n * SQL, so it treats this node as *unknown* rather than guessing.\n * @group Models\n */\nexport interface RawPolicyExpression {\n    kind: \"raw\";\n    sql: string;\n}\n\n/**\n * An operand referenced by a {@link ComparePolicyExpression}.\n * @group Models\n */\nexport type PolicyOperand =\n    | FieldPolicyOperand\n    | OuterFieldPolicyOperand\n    | LiteralPolicyOperand\n    | AuthUidPolicyOperand\n    | AuthRolesPolicyOperand;\n\n/** A column value on the row being evaluated. @group Models */\nexport interface FieldPolicyOperand {\n    kind: \"field\";\n    /** The property/column name (resolved to its DB column when compiled). */\n    name: string;\n}\n\n/**\n * A column value on the *outer* row when used inside {@link ExistsInPolicyExpression}\n * — i.e. the row the RLS policy is being evaluated for, referenced from within the\n * subquery. Outside an `existsIn` it is equivalent to {@link FieldPolicyOperand}.\n * @group Models\n */\nexport interface OuterFieldPolicyOperand {\n    kind: \"outerField\";\n    /** The property/column name on the outer collection. */\n    name: string;\n}\n\n/** A constant value. @group Models */\nexport interface LiteralPolicyOperand {\n    kind: \"literal\";\n    value: string | number | boolean | null;\n}\n\n/** The current user's id — compiles to `auth.uid()`. @group Models */\nexport interface AuthUidPolicyOperand {\n    kind: \"authUid\";\n}\n\n/**\n * The current user's roles as an array — compiles to\n * `string_to_array(auth.roles(), ',')`.\n * @group Models\n */\nexport interface AuthRolesPolicyOperand {\n    kind: \"authRoles\";\n}\n\n// ── Constructor helpers ──────────────────────────────────────────────\n// Small, dependency-free builders so callers (and the desugaring in\n// `@rebasepro/common`) can assemble expressions without object-literal noise.\n\n/** @group Models */\nexport const policy = {\n    true: (): TruePolicyExpression => ({ kind: \"true\" }),\n    false: (): FalsePolicyExpression => ({ kind: \"false\" }),\n    and: (...operands: readonly PolicyExpression[]): AndPolicyExpression => ({ kind: \"and\",\noperands: operands as PolicyExpression[] }),\n    or: (...operands: readonly PolicyExpression[]): OrPolicyExpression => ({ kind: \"or\",\noperands: operands as PolicyExpression[] }),\n    not: (operand: PolicyExpression): NotPolicyExpression => ({ kind: \"not\",\noperand }),\n    compare: (left: PolicyOperand, op: PolicyCompareOperator, right: PolicyOperand): ComparePolicyExpression =>\n        ({ kind: \"compare\",\nop,\nleft,\nright }),\n    rolesOverlap: (roles: readonly string[]): RolesOverlapPolicyExpression => ({ kind: \"rolesOverlap\",\nroles: roles as string[] }),\n    rolesContain: (roles: readonly string[]): RolesContainPolicyExpression => ({ kind: \"rolesContain\",\nroles: roles as string[] }),\n    authenticated: (): AuthenticatedPolicyExpression => ({ kind: \"authenticated\" }),\n    serverContext: (): ServerContextPolicyExpression => ({ kind: \"serverContext\" }),\n    existsIn: (args: { collection: string; where: PolicyExpression }): ExistsInPolicyExpression =>\n        ({ kind: \"existsIn\",\ncollection: args.collection,\nwhere: args.where }),\n    raw: (sql: string): RawPolicyExpression => ({ kind: \"raw\",\nsql }),\n    field: (name: string): FieldPolicyOperand => ({ kind: \"field\",\nname }),\n    outerField: (name: string): OuterFieldPolicyOperand => ({ kind: \"outerField\",\nname }),\n    literal: (value: string | number | boolean | null): LiteralPolicyOperand => ({ kind: \"literal\",\nvalue }),\n    authUid: (): AuthUidPolicyOperand => ({ kind: \"authUid\" }),\n    authRoles: (): AuthRolesPolicyOperand => ({ kind: \"authRoles\" })\n};\n","import type { CollectionConfig, FilterValues, WhereFilterOp } from \"./collections\";\nimport type { AuthAdapter } from \"./auth_adapter\";\nimport type { HistoryConfig } from \"../controllers/client\";\nimport type { ChannelBusSetting } from \"./channel_bus\";\n\n// =============================================================================\n// DATABASE CONNECTION INTERFACES\n// =============================================================================\n\n/**\n * Abstract database connection interface.\n * Represents a connection to any database system.\n */\nexport interface DatabaseConnection {\n    /**\n     * Type identifier for this database (e.g., 'postgres', 'mongodb', 'mysql')\n     */\n    readonly type: string;\n\n    /**\n     * Whether the connection is currently active\n     */\n    readonly isConnected?: boolean;\n\n    /**\n     * Close the database connection and release resources.\n     */\n    close?(): Promise<void>;\n}\n\n// =============================================================================\n// QUERY BUILDING INTERFACES\n// =============================================================================\n\n/**\n * A single filter condition for database queries\n */\nexport interface QueryFilter {\n    field: string;\n    operator: WhereFilterOp;\n    value: unknown;\n}\n\n/**\n * Options for fetching a collection of entities\n */\nexport interface FetchCollectionOptions<M extends Record<string, unknown> = Record<string, unknown>> {\n    filter?: FilterValues<Extract<keyof M, string>>;\n    orderBy?: string;\n    order?: \"desc\" | \"asc\";\n    limit?: number;\n    offset?: number;\n    startAfter?: unknown;\n    searchString?: string;\n    databaseId?: string;\n    collection?: CollectionConfig;\n}\n\n/**\n * Options for searching entities\n */\nexport interface SearchOptions<M extends Record<string, unknown> = Record<string, unknown>> {\n    filter?: FilterValues<Extract<keyof M, string>>;\n    orderBy?: string;\n    order?: \"desc\" | \"asc\";\n    limit?: number;\n    databaseId?: string;\n    collection?: CollectionConfig;\n}\n\n/**\n * Options for counting entities\n */\nexport interface CountOptions<M extends Record<string, unknown> = Record<string, unknown>> {\n    filter?: FilterValues<Extract<keyof M, string>>;\n    searchString?: string;\n    databaseId?: string;\n}\n\n/**\n * Abstract condition builder interface.\n * Implementations translate Rebase filter conditions to database-specific queries.\n *\n * Note: This interface can be implemented as instance methods or as a class with static methods.\n * For static implementations (like DrizzleConditionBuilder), use the ConditionBuilderStatic type.\n *\n * @template T The type of condition returned by the builder (e.g., SQL for PostgreSQL, Filter<Document> for MongoDB)\n */\nexport interface ConditionBuilder<T = unknown> {\n    /**\n     * Build filter conditions from Rebase FilterValues\n     */\n    buildFilterConditions<M extends Record<string, unknown>>(\n        filter: FilterValues<Extract<keyof M, string>>,\n        collectionPath: string,\n        ...args: unknown[]\n    ): T[];\n\n    /**\n     * Build search conditions for text search\n     */\n    buildSearchConditions(\n        searchString: string,\n        properties: Record<string, unknown>,\n        ...args: unknown[]\n    ): T[];\n\n    /**\n     * Combine multiple conditions with AND operator\n     */\n    combineConditionsWithAnd(conditions: T[]): T | undefined;\n\n    /**\n     * Combine multiple conditions with OR operator\n     */\n    combineConditionsWithOr(conditions: T[]): T | undefined;\n}\n\n/**\n * Static condition builder type for implementations using static methods.\n * Use this type when the class provides static methods rather than instance methods.\n *\n * @example\n * // DrizzleConditionBuilder satisfies this type\n * const builder: ConditionBuilderStatic<SQL> = DrizzleConditionBuilder;\n */\nexport type ConditionBuilderStatic<T = unknown> = {\n    buildFilterConditions<M extends Record<string, unknown>>(\n        filter: FilterValues<Extract<keyof M, string>>,\n        ...args: unknown[]\n    ): T[];\n    buildSearchConditions(\n        searchString: string,\n        properties: Record<string, unknown>,\n        ...args: unknown[]\n    ): T[];\n    combineConditionsWithAnd(conditions: T[]): T | undefined;\n    combineConditionsWithOr(conditions: T[]): T | undefined;\n};\n\n// =============================================================================\n// ENTITY REPOSITORY INTERFACES\n// =============================================================================\n\n/**\n * Abstract entity repository interface.\n * Handles all CRUD operations for entities in the database.\n *\n * Implementations should handle:\n * - Entity serialization/deserialization\n * - Relation resolution\n * - ID generation and conversion\n */\nexport interface DataRepository {\n    /**\n     * Fetch a single entity by ID\n     */\n    fetchOne<M extends Record<string, unknown>>(\n        collectionPath: string,\n        id: string | number,\n        databaseId?: string\n    ): Promise<Record<string, unknown> | undefined>;\n\n    /**\n     * Fetch a collection of entities with optional filtering, ordering, and pagination\n     */\n    fetchCollection<M extends Record<string, unknown>>(\n        collectionPath: string,\n        options?: FetchCollectionOptions<M>\n    ): Promise<Record<string, unknown>[]>;\n\n    /**\n     * Search entities by text\n     */\n    searchRows<M extends Record<string, unknown>>(\n        collectionPath: string,\n        searchString: string,\n        options?: SearchOptions<M>\n    ): Promise<Record<string, unknown>[]>;\n\n    /**\n     * Count entities in a collection\n     */\n    count<M extends Record<string, unknown>>(\n        collectionPath: string,\n        options?: CountOptions<M>\n    ): Promise<number>;\n\n    /**\n     * Save a entity (create or update)\n     */\n    save<M extends Record<string, unknown>>(\n        collectionPath: string,\n        values: Partial<M>,\n        id?: string | number,\n        databaseId?: string\n    ): Promise<Record<string, unknown>>;\n\n    /**\n     * Delete a entity by ID\n     */\n    delete(\n        collectionPath: string,\n        id: string | number,\n        databaseId?: string\n    ): Promise<void>;\n\n    /**\n     * Check if a field value is unique in a collection\n     */\n    checkUniqueField(\n        collectionPath: string,\n        fieldName: string,\n        value: unknown,\n        excludeEntityId?: string,\n        databaseId?: string\n    ): Promise<boolean>;\n\n}\n\n// =============================================================================\n// REALTIME INTERFACES\n// =============================================================================\n\n/**\n * Configuration for subscribing to a collection\n */\nexport interface CollectionSubscriptionConfig {\n    clientId: string;\n    path: string;\n    filter?: unknown;\n    orderBy?: string;\n    order?: \"desc\" | \"asc\";\n    limit?: number;\n    startAfter?: unknown;\n    databaseId?: string;\n    searchString?: string;\n}\n\n/**\n * Configuration for subscribing to a single entity\n */\nexport interface SingleSubscriptionConfig {\n    clientId: string;\n    path: string;\n    id: string | number;\n}\n\n/**\n * Opt-in retention for one set of broadcast channels.\n *\n * Retention is configured on the server and nowhere else. A channel is created\n * by whoever names it, so letting a client ask for its own history depth would\n * let any visitor commit the backend to unbounded storage; and presence-only or\n * notification-only channels — the overwhelming majority — must not pay for a\n * feature they never use. With no rules configured nothing is written, no table\n * is created, and broadcast behaves exactly as it did before history existed.\n */\nexport interface ChannelRetentionRule {\n    /**\n     * Channel name to match. Either exact (`\"doc:42\"`) or a trailing-`*` prefix\n     * (`\"doc:*\"`). Deliberately not a full glob or RegExp: this decides what\n     * gets written to disk, and a rule whose blast radius is not obvious at a\n     * glance is the wrong shape for that.\n     */\n    match: string;\n    /** Keep at most this many of the most recent messages per channel. */\n    limit?: number;\n    /**\n     * Keep messages for at most this long. Accepts a millisecond count or a\n     * short duration string (`\"30s\"`, `\"15m\"`, `\"24h\"`, `\"7d\"`).\n     */\n    ttl?: number | string;\n}\n\n/**\n * Server-side realtime options.\n *\n * The channel bus contract and its config live in `./channel_bus` so that a\n * transport shipped as its own package depends on the contract alone.\n */\nexport interface RealtimeChannelsConfig {\n    /**\n     * Retention rules, most specific first — the first match wins. Omitted or\n     * empty means no channel retains anything.\n     */\n    channels?: ChannelRetentionRule[];\n    /**\n     * How channel broadcast and presence reach other backend instances.\n     * Defaults to `{ type: \"memory\" }` — i.e. they don't.\n     */\n    bus?: ChannelBusSetting;\n}\n\n/**\n * Abstract realtime provider interface.\n * Handles real-time subscriptions and notifications for entity changes.\n */\nexport interface RealtimeProvider {\n    /**\n     * Subscribe to collection changes\n     */\n    subscribeToCollection(\n        subscriptionId: string,\n        config: CollectionSubscriptionConfig,\n        callback?: (rows: Record<string, unknown>[]) => void\n    ): void;\n\n    /**\n     * Subscribe to single entity changes\n     */\n    subscribeToOne(\n        subscriptionId: string,\n        config: SingleSubscriptionConfig,\n        callback?: (row: Record<string, unknown> | null) => void\n    ): void;\n\n    /**\n     * Unsubscribe from a subscription\n     */\n    unsubscribe(subscriptionId: string): void;\n\n    /**\n     * Notify all relevant subscribers of a entity update\n     */\n    notifyUpdate(\n        path: string,\n        id: string,\n        row: Record<string, unknown> | null,\n        databaseId?: string\n    ): Promise<void>;\n\n    /**\n     * Called when the HTTP server is ready and listening.\n     * Useful for providers that need the server address for callbacks.\n     */\n    onServerReady?(serverInfo: { port: number; hostname?: string }): void;\n\n    /**\n     * Gracefully shut down the realtime provider.\n     * Called during server shutdown to clean up resources.\n     */\n    destroy?(): Promise<void>;\n\n    /**\n     * Stop the internal LISTEN client (e.g., PostgreSQL LISTEN/NOTIFY).\n     * Called during graceful shutdown before closing database connections.\n     */\n    stopListening?(): Promise<void>;\n}\n\n// =============================================================================\n// COLLECTION REGISTRY INTERFACES\n// =============================================================================\n\n/**\n * Abstract collection registry interface.\n * Manages registration and lookup of entity collections.\n */\nexport interface CollectionRegistryInterface {\n    /**\n     * Register a collection\n     */\n    register(collection: CollectionConfig): void;\n\n    /**\n     * Get a collection by its path\n     */\n    getCollectionByPath(path: string): CollectionConfig | undefined;\n\n    /**\n     * Get all registered collections\n     */\n    getCollections(): CollectionConfig[];\n\n    /**\n     * Get the currently registered global callbacks, if any.\n     */\n    getGlobalCallbacks(): any | undefined;\n}\n\n// =============================================================================\n// DATA TRANSFORMER INTERFACES\n// =============================================================================\n\n/**\n * Abstract data transformer interface.\n * Handles serialization/deserialization between frontend and database formats.\n */\nexport interface DataTransformer {\n    /**\n     * Transform entity data for storage in the database\n     */\n    serializeToDatabase<M extends Record<string, unknown>>(\n        entity: M,\n        collection: CollectionConfig\n    ): Record<string, unknown>;\n\n    /**\n     * Transform database data back to entity format\n     */\n    deserializeFromDatabase<M extends Record<string, unknown>>(\n        data: Record<string, unknown>,\n        collection: CollectionConfig\n    ): Promise<M>;\n}\n\n// =============================================================================\n// DATABASE ADMIN — CAPABILITY-SPECIFIC INTERFACES (1.3)\n// =============================================================================\n\n/**\n * Administrative operations for SQL-based databases (PostgreSQL, MySQL, etc.).\n * Used by the SQL Editor, RLS Editor, and schema browser.\n *\n * @group Admin\n */\nexport interface SQLAdmin {\n    /**\n     * Execute raw SQL against the database.\n     */\n    executeSql(sql: string, options?: { database?: string; role?: string; params?: unknown[] }): Promise<Record<string, unknown>[]>;\n\n    /**\n     * Fetch the available databases on the server.\n     */\n    fetchAvailableDatabases?(): Promise<string[]>;\n\n    /**\n     * Fetch the available *native PostgreSQL* database roles (from `pg_roles`).\n     *\n     * These are connection-level roles — what the SQL editor can `SET ROLE` to,\n     * and what `SecurityRule.pgRoles` targets. They are NOT application roles;\n     * for those use {@link fetchApplicationRoles}.\n     */\n    fetchAvailableRoles?(): Promise<string[]>;\n\n    /**\n     * Fetch the *application-level* roles in use in this project.\n     *\n     * These are the strings stored on the users table's `roles` column and\n     * exposed to policies as `auth.roles()` — what `SecurityRule.roles`\n     * matches against. Distinct from {@link fetchAvailableRoles}; the two are\n     * not interchangeable.\n     */\n    fetchApplicationRoles?(): Promise<string[]>;\n\n    /**\n     * Fetch the current database name.\n     */\n    fetchCurrentDatabase?(): Promise<string | undefined>;\n}\n\n/**\n * Administrative operations for document-based databases (MongoDB, Firestore, etc.).\n * Used by future document administration tools.\n *\n * @group Admin\n */\nexport interface DocumentAdmin {\n    /**\n     * Execute an aggregation pipeline or equivalent query.\n     */\n    executeAggregate?(pipeline: Record<string, unknown>[]): Promise<Record<string, unknown>[]>;\n\n    /**\n     * Fetch statistics for a collection (document count, size, etc.).\n     */\n    fetchCollectionStats?(collectionName: string): Promise<{ count: number; sizeBytes?: number }>;\n}\n\n/**\n * Administrative operations for schema management.\n * Shared across SQL and document databases.\n *\n * @group Admin\n */\nexport interface SchemaAdmin {\n    /**\n     * Fetch database tables/collections not yet mapped to a Rebase collection.\n     */\n    fetchUnmappedTables?(mappedPaths?: string[]): Promise<string[]>;\n\n    /**\n     * Fetch column/field metadata for a single table/collection.\n     * The return type is generic — SQL backends return TableMetadata,\n     * document backends may return a different shape.\n     */\n    fetchTableMetadata?(tableName: string): Promise<unknown>;\n}\n\n/**\n * Metadata for a database branch.\n * @group Admin\n */\nexport interface BranchInfo {\n    /** Branch name (without prefix). */\n    name: string;\n    /** The database this branch was created from. */\n    parentDatabase: string;\n    /** When the branch was created. */\n    createdAt: Date;\n    /** Size in bytes, if available from the server. */\n    sizeBytes?: number;\n}\n\n/**\n * Administrative operations for database branching.\n * Allows creating isolated database copies for development/preview workflows.\n *\n * @group Admin\n */\nexport interface BranchAdmin {\n    /** Create a new branch (database copy) from the current or specified source database. */\n    createBranch(name: string, options?: { source?: string }): Promise<BranchInfo>;\n\n    /** Delete a branch database. Cannot delete the main/default database. */\n    deleteBranch(name: string): Promise<void>;\n\n    /** List all branches (databases that were created via branching). */\n    listBranches(): Promise<BranchInfo[]>;\n\n    /** Get info about a specific branch. */\n    getBranchInfo(name: string): Promise<BranchInfo | undefined>;\n}\n\n/**\n * Union type for all admin capabilities.\n * A backend may implement any combination of these interfaces.\n *\n * Use type guards (`isSQLAdmin`, `isDocumentAdmin`, `isSchemaAdmin`, `isBranchAdmin`)\n * to safely narrow the type before calling methods.\n *\n * @group Admin\n */\nexport type DatabaseAdmin = Partial<SQLAdmin> & Partial<DocumentAdmin> & Partial<SchemaAdmin> & Partial<BranchAdmin>;\n\n/**\n * Type guard: does this admin support SQL operations?\n * @group Admin\n */\nexport function isSQLAdmin(admin: DatabaseAdmin | undefined): admin is SQLAdmin {\n    return !!admin && typeof (admin as SQLAdmin).executeSql === \"function\";\n}\n\n/**\n * Type guard: does this admin support document operations?\n * @group Admin\n */\nexport function isDocumentAdmin(admin: DatabaseAdmin | undefined): admin is DocumentAdmin {\n    return !!admin && (\n        typeof (admin as DocumentAdmin).executeAggregate === \"function\" ||\n        typeof (admin as DocumentAdmin).fetchCollectionStats === \"function\"\n    );\n}\n\n/**\n * Type guard: does this admin support schema management?\n * @group Admin\n */\nexport function isSchemaAdmin(admin: DatabaseAdmin | undefined): admin is SchemaAdmin {\n    return !!admin && (\n        typeof (admin as SchemaAdmin).fetchUnmappedTables === \"function\" ||\n        typeof (admin as SchemaAdmin).fetchTableMetadata === \"function\"\n    );\n}\n\n/**\n * Type guard: does this admin support database branching?\n * @group Admin\n */\nexport function isBranchAdmin(admin: DatabaseAdmin | undefined): admin is BranchAdmin {\n    return !!admin && typeof (admin as BranchAdmin).createBranch === \"function\";\n}\n\n// =============================================================================\n// LIFECYCLE INTERFACES (1.4)\n// =============================================================================\n\n/**\n * Health check result returned by `healthCheck()`.\n * @group Lifecycle\n */\nexport interface HealthCheckResult {\n    /** Whether the backend is healthy and able to serve requests. */\n    healthy: boolean;\n    /** Round-trip latency to the database in milliseconds. */\n    latencyMs: number;\n    /** Optional details (e.g., pool stats, replication lag). */\n    details?: Record<string, unknown>;\n}\n\n/**\n * Lifecycle contract for backend components that hold resources\n * (database connections, WebSocket pools, timers, etc.).\n *\n * All methods are optional — simple backends (e.g., in-memory) can skip them.\n * @group Lifecycle\n */\nexport interface BackendLifecycle {\n    /**\n     * Initialize the backend: open connections, run migrations, seed data.\n     * Called once during startup. Idempotent.\n     */\n    initialize?(): Promise<void>;\n\n    /**\n     * Check whether the backend is healthy and reachable.\n     * Should be fast (< 1 s) and safe to call frequently.\n     */\n    healthCheck?(): Promise<HealthCheckResult>;\n\n    /**\n     * Gracefully shut down: close connections, flush buffers, cancel timers.\n     * After calling `destroy()`, no other methods should be called.\n     */\n    destroy?(): Promise<void>;\n}\n\n// =============================================================================\n// BACKEND FACTORY INTERFACES\n// =============================================================================\n\n/**\n * Configuration for creating a database backend\n */\nexport interface BackendConfig {\n    /**\n     * Type of database backend\n     */\n    type: string;\n\n    /**\n     * Database connection (implementation-specific)\n     */\n    connection: unknown;\n\n    /**\n     * Schema definition (implementation-specific, e.g., Drizzle schema for PostgreSQL)\n     */\n    schema?: unknown;\n}\n\n/**\n * A complete backend instance with all required services.\n *\n * Now includes optional lifecycle management and admin capabilities.\n */\nexport interface BackendInstance extends BackendLifecycle {\n    /**\n     * Entity repository for CRUD operations\n     */\n    entityRepository: DataRepository;\n\n    /**\n     * Realtime provider for subscriptions\n     */\n    realtimeProvider: RealtimeProvider;\n\n    /**\n     * Collection registry\n     */\n    collectionRegistry: CollectionRegistryInterface;\n\n    /**\n     * The underlying database connection\n     */\n    connection: DatabaseConnection;\n\n    /**\n     * Administrative operations (SQL, schema, documents).\n     * What's available depends on the backend type — use type guards\n     * (`isSQLAdmin`, `isSchemaAdmin`, etc.) to narrow.\n     */\n    admin?: DatabaseAdmin;\n}\n\n/**\n * Factory function type for creating backend instances\n */\nexport type BackendFactory<TConfig extends BackendConfig = BackendConfig> =\n    (config: TConfig) => BackendInstance;\n\n// =============================================================================\n// BACKEND BOOTSTRAPPER (1.2)\n// =============================================================================\n\n/**\n * A `BackendBootstrapper` encapsulates all driver-specific initialization logic.\n *\n * Instead of hard-coding Postgres setup into `initializeRebaseBackend()`,\n * each database backend provides its own bootstrapper that knows how to:\n * - Create the DataDriver from a config object\n * - Optionally initialize auth tables\n * - Optionally create a realtime service\n * - Mount driver-specific API routes\n *\n * The main `initializeRebaseBackend()` becomes a **coordinator** that iterates\n * registered bootstrappers, calls their hooks, and wires the results together.\n *\n * @group Backend\n *\n * @example\n * ```typescript\n * // Third-party MySQL bootstrapper\n * const mysqlBootstrapper: BackendBootstrapper = {\n *   type: \"mysql\",\n *   initializeDriver: async (config) => new MySQLDataDriver(config.connection),\n *   initializeRealtime: async (config) => new MySQLChangeStreamRealtime(config.connection),\n * };\n *\n * initializeRebaseBackend({\n *   ...config,\n *   bootstrappers: [postgresBootstrapper, mysqlBootstrapper]\n * });\n * ```\n */\nexport interface BackendBootstrapper {\n    /**\n     * Which driver type this bootstrapper handles.\n     * Must match the `type` field on the driver config object\n     * (e.g., `\"postgres\"`, `\"mongodb\"`, `\"mysql\"`).\n     */\n    type: string;\n\n    /**\n     * Unique identifier for this bootstrapper instance.\n     * Used to register the driver in the driver registry.\n     * Defaults to `type` if not set.\n     */\n    id?: string;\n\n    /**\n     * Whether this bootstrapper provides the default driver.\n     * When true, the coordinator uses this driver as the primary one.\n     */\n    isDefault?: boolean;\n\n    /**\n     * Run database migrations for this driver.\n     * Called by the coordinator after all drivers are initialized.\n     */\n    runMigrations?(config: unknown, driverResult: InitializedDriver): Promise<void>;\n\n    /**\n     * Create a DataDriver from the given config.\n     * This is the only **required** method.\n     */\n    initializeDriver(config: unknown): Promise<InitializedDriver>;\n\n    /**\n     * Initialize auth tables / services if this driver supports them.\n     * Return undefined if auth is not supported by this backend.\n     */\n    initializeAuth?(config: unknown, driverResult: InitializedDriver): Promise<BootstrappedAuth | undefined>;\n\n    /**\n     * Initialize history tables / services if this driver supports them.\n     * Return undefined if history is not supported by this backend.\n     */\n    initializeHistory?(config: HistoryConfig, driverResult: InitializedDriver): Promise<{ historyService: unknown } | undefined>;\n\n    /**\n     * Create a realtime provider for this driver.\n     * Return undefined if the driver does not support realtime.\n     */\n    initializeRealtime?(config: unknown, driverResult: InitializedDriver): Promise<RealtimeProvider | undefined>;\n\n    /**\n     * Mount any driver-specific HTTP routes (e.g., custom admin endpoints).\n     * Called after all drivers are initialized.\n     */\n    mountRoutes?(app: unknown, basePath: string, driverResult: InitializedDriver): void;\n\n    /**\n     * Return admin capabilities for this driver.\n     */\n    getAdmin?(driverResult: InitializedDriver): DatabaseAdmin | undefined;\n\n    /**\n     * Bring the database's collection tables up to date, additively.\n     *\n     * Optional because it is only meaningful for schema-ful drivers. A managed\n     * runtime boots a compiled project against a database it has never seen; auth\n     * tables are ensured on boot but collection tables were created by nothing,\n     * so every data request answered 500 on a missing relation. The CLI's `db\n     * push` cannot fill the gap — it needs Atlas, and the runtime image ships no\n     * CLI.\n     *\n     * Implementations MUST be additive-only: create missing tables, columns and\n     * enum types, and never drop, narrow or rewrite anything. This runs\n     * unattended against live customer data with nobody reading a diff, so the\n     * destructive half stays a deliberate migration.\n     */\n    ensureCollectionSchema?(\n        collections: unknown[],\n        driverResult: InitializedDriver,\n        log?: (message: string) => void\n    ): Promise<{ applied: number }>;\n\n    /**\n     * Initialize WebSocket server for realtime operations.\n     */\n    initializeWebsockets?(server: unknown, realtimeService: RealtimeProvider, driver: import(\"../controllers/data_driver\").DataDriver, config?: unknown, authAdapter?: AuthAdapter): Promise<void> | void;\n}\n\n/**\n * Result of `BackendBootstrapper.initializeDriver()`.\n * @group Backend\n */\nexport interface InitializedDriver {\n    /** The DataDriver instance, ready for use. */\n    driver: import(\"../controllers/data_driver\").DataDriver;\n\n    /** The realtime service, if the driver created one during init. */\n    realtimeProvider?: RealtimeProvider;\n\n    /** A collection registry to register schema / tables into. */\n    collectionRegistry?: CollectionRegistryInterface;\n\n    /**\n     * Collections the driver derived from the live database schema.\n     *\n     * Set by drivers that introspect in `baas` mode; the server serves these\n     * instead of collections loaded from config files.\n     */\n    collections?: import(\"./collections\").CollectionConfig[];\n\n    /** The underlying database connection (for lifecycle management). */\n    connection?: DatabaseConnection;\n\n    /**\n     * Opaque handle that the bootstrapper can use in subsequent hooks\n     * (e.g., `initializeAuth`, `mountRoutes`) to access driver internals.\n     * Not used by the coordinator.\n     */\n    internals?: unknown;\n}\n\n/**\n * Result of `BackendBootstrapper.initializeAuth()`.\n * @group Backend\n */\nexport interface BootstrappedAuth {\n    /** User management service. */\n    userService: unknown;\n    /** Role management service (optional, roles are now simple strings). */\n    roleService?: unknown;\n    /** Email service (optional). */\n    emailService?: unknown;\n    /** Combined Auth Repository for unified token and user management. */\n    authRepository?: unknown;\n    /**\n     * Whether the auth schema in the database is one this runtime can serve.\n     *\n     * Folded into `healthCheck()` so a schema mismatch shows up as a degraded\n     * health response. Without it, a server whose auth is entirely broken still\n     * reports healthy — the database connection it probes is fine, and the\n     * mismatch is only discovered one failed login at a time.\n     */\n    schemaHealthCheck?(): Promise<AuthSchemaHealth>;\n}\n\n/**\n * Result of {@link BootstrappedAuth.schemaHealthCheck}.\n * @group Lifecycle\n */\nexport interface AuthSchemaHealth {\n    /** False when this runtime cannot be trusted to serve auth against this database. */\n    healthy: boolean;\n    /** Human-readable descriptions of each mismatch found. Empty when healthy. */\n    problems: string[];\n    /** Auth schema version recorded in the database, when it records one. */\n    databaseVersion?: number | null;\n    /** Auth schema version this runtime expects. */\n    runtimeVersion?: number;\n}\n","/**\n * The cross-instance transport for channel broadcast and presence, and the\n * contract anyone implementing one has to meet.\n *\n * These types live in `@rebasepro/types` rather than in the Postgres adapter on\n * purpose: a transport package should depend on the contract, not on the\n * database driver that happens to ship the default implementation. A\n * `@rebasepro/channel-bus-<something>` package needs this file and nothing else.\n *\n * Why a transport exists at all: entity/collection realtime already spans\n * instances (CDC, or per-mutation LISTEN/NOTIFY). Channel broadcast and presence\n * did not — they fanned out from per-process maps, so two clients served by\n * different replicas could not see each other, and nothing errored. The bus is\n * the missing hop, and deliberately *only* that hop: which local clients receive\n * a frame stays in the realtime service, so a transport never has to know what a\n * subscription, a WebSocket or a presence roster is.\n */\n\n/**\n * A frame in flight between instances.\n *\n * `sid` identifies the publishing instance. The realtime service drops frames\n * carrying its own `sid` on arrival — local fan-out already happened before the\n * publish — so a transport that echoes a publisher's own messages back to it is\n * still correct, merely wasteful.\n *\n * Keys are spelled out rather than abbreviated. The one shipped transport with a\n * size limit has a pointer path for anything that would approach it, so shaving\n * bytes off key names buys nothing worth the opacity.\n */\nexport type ChannelBusFrame =\n    /** A broadcast carrying its payload. */\n    | {\n        kind: \"broadcast\";\n        sid: string;\n        channel: string;\n        event: string;\n        /** Originating client, echoed so receivers can skip it if it is theirs. */\n        from?: string;\n        /** Sequence number, present only on retained channels. */\n        seq?: number;\n        payload: unknown;\n    }\n    /**\n     * A broadcast too large for the transport to carry inline: the body is\n     * already durable in `rebase.channel_messages`, so the frame carries only\n     * its address and each receiver reads it back. Only ever emitted for\n     * retained channels, and only by a transport with a finite\n     * {@link ChannelBus.maxFrameBytes}.\n     */\n    | {\n        kind: \"broadcast_ref\";\n        sid: string;\n        channel: string;\n        from?: string;\n        seq: number;\n    }\n    /** A presence join/leave/update, small by construction. */\n    | {\n        kind: \"presence_diff\";\n        sid: string;\n        channel: string;\n        joins: Record<string, Record<string, unknown>>;\n        leaves: Record<string, Record<string, unknown>>;\n    };\n\n/** Receives frames published by *other* instances. */\nexport type ChannelBusHandler = (frame: ChannelBusFrame) => void | Promise<void>;\n\n/**\n * A cross-instance transport.\n *\n * ## What an implementation must guarantee\n *\n * - **`start()` rejects if the transport is unusable.** The caller falls back to\n *   in-process delivery when it does. Resolving while disconnected produces a\n *   cluster that believes it is connected and silently is not, which is the\n *   exact failure this whole mechanism exists to remove.\n * - **`publish()` reaches every *other* instance, or rejects.** Delivery back to\n *   the publisher is permitted but pointless (see {@link ChannelBusFrame.sid}).\n * - **`stop()` is idempotent** and releases everything, including anything\n *   holding the event loop open.\n * - **A malformed message never throws out of the transport.** Parsing happens\n *   inside the implementation; drop and log what you cannot understand, so one\n *   bad frame cannot take the listener down.\n *\n * ## What it does *not* have to guarantee\n *\n * - **Ordering.** Retained channels carry `seq`, and the client SDK orders by\n *   it. Unsequenced broadcasts are cursor-grade traffic where order is not\n *   meaningful.\n * - **Durability.** A frame lost in transit is a missed live update; retained\n *   channels repair themselves through the client's `channel_history` replay.\n * - **Exactly-once.** Duplicates are tolerated — retained frames are deduped by\n *   `seq`, and presence diffs are idempotent by construction.\n */\nexport interface ChannelBus {\n    /**\n     * Identifies the transport in logs and in `getChannelBusKind()`. Use your\n     * own name; the framework only compares against `\"memory\"` to decide\n     * whether publishing is worth attempting at all.\n     */\n    readonly kind: string;\n\n    /**\n     * Largest frame this transport will carry, in bytes of encoded JSON, or\n     * `Infinity` when there is no meaningful ceiling.\n     *\n     * A broadcast that exceeds it is published as a `broadcast_ref` pointer when\n     * the channel is retained, and refused with an error to the sender when it\n     * is not. Implementations with no limit should return `Infinity` rather than\n     * a large number, so the pointer path is never taken needlessly.\n     */\n    readonly maxFrameBytes: number;\n\n    /** Connect and begin delivering remote frames to `handler`. */\n    start(handler: ChannelBusHandler): Promise<void>;\n\n    /** Publish a frame to the other instances. */\n    publish(frame: ChannelBusFrame): Promise<void>;\n\n    /** Disconnect and release resources. Idempotent. */\n    stop(): Promise<void>;\n}\n\n/**\n * Which transport to use, for the two that ship with the Postgres adapter.\n *\n * To use one that does not ship here — a Redis package, or your own class —\n * pass the {@link ChannelBus} instance itself instead of a config object.\n *\n * There are deliberately only two built in, and neither adds a service to a\n * deployment. Rebase deploys as Postgres + backend + frontend; a bus that\n * required a message broker would put a second stateful service into every\n * `docker-compose.yml` the CLI scaffolds, for a feature most applications never\n * use. Measured across two backend instances against one Postgres container,\n * the Postgres bus carried ~10k cross-instance messages/second with no losses,\n * and stayed flat out to eight instances — comfortably past what live-cursor\n * collaboration generates. The extension point below is the answer for anyone\n * who does outgrow it.\n */\nexport type ChannelBusConfig =\n    /**\n     * In-process only — the historical behaviour. Broadcast and presence reach\n     * the clients connected to *this* instance and no further.\n     */\n    | { type: \"memory\" }\n    /**\n     * Postgres LISTEN/NOTIFY, reusing infrastructure the deployment already has.\n     *\n     * `pg_notify` caps a payload at 8000 bytes, so a broadcast larger than that\n     * is delivered cross-instance only on a *retained* channel, where the\n     * notification carries a pointer (`seq`) instead of the message and each\n     * receiver reads the body back from `rebase.channel_messages`. An oversized\n     * broadcast on an ephemeral channel is refused rather than silently\n     * delivered to half the cluster.\n     *\n     * NOTE: `LISTEN` needs a session-mode connection. Behind PgBouncer in\n     * transaction mode this must point at the database directly\n     * (`DATABASE_DIRECT_URL`), not at the pooler.\n     */\n    | {\n        type: \"postgres\";\n        /** Direct connection for the LISTEN client. Defaults to `DATABASE_DIRECT_URL`. */\n        connectionString?: string;\n        /**\n         * How long to coalesce outgoing frames into a single notification, in\n         * milliseconds. Defaults to 10.\n         *\n         * A notify is a query on your primary database, so under load this is\n         * the difference between one query per message and one per window. The\n         * window is leading-edge: a frame arriving when none is open goes out\n         * immediately, so an idle channel pays no added latency and only a\n         * sustained stream is batched.\n         *\n         * Set to 0 to disable coalescing and send every frame on its own.\n         */\n        batchWindowMs?: number;\n    };\n\n/**\n * What `realtime.bus` accepts: a built-in transport by name, or any\n * {@link ChannelBus} instance.\n *\n * ```typescript\n * realtime: { bus: { type: \"postgres\" } }        // shipped\n * realtime: { bus: new MyRedisChannelBus(url) }  // a separate package, or your own\n * ```\n */\nexport type ChannelBusSetting = ChannelBusConfig | ChannelBus;\n\n/**\n * Whether `setting` is an already-constructed transport rather than a request\n * for a built-in one.\n *\n * Structural rather than nominal so that an instance from a *different copy* of\n * `@rebasepro/types` — an entirely normal outcome of a separately versioned\n * transport package — is still recognised.\n */\nexport function isChannelBusInstance(setting: ChannelBusSetting | undefined): setting is ChannelBus {\n    return typeof (setting as ChannelBus | undefined)?.publish === \"function\";\n}\n","/**\n * Describes a named storage backend — a place files live.\n *\n * Declared once and shared front + back: the frontend uses it to decide\n * transport (HTTP proxy vs direct SDK), the backend uses the same `key`\n * to resolve a StorageController, and collection properties reference\n * a definition by its `key` via `StorageConfig.storageSource`.\n *\n * This mirrors the {@link DataSourceDefinition} pattern used for databases.\n *\n * @group Models\n */\n\n/**\n * The default storage source key, used when a property does not specify\n * a `storageSource`. Shared by the frontend and backend registries so\n * both agree on \"the default storage backend\".\n * @group Models\n */\nexport const DEFAULT_STORAGE_SOURCE_KEY = \"(default)\";\n\n/**\n * How the *frontend* reaches a storage backend.\n *\n * - `\"server\"` — through the Rebase backend REST API (`/api/storage`).\n *   The backend holds the actual `StorageController` and routes by\n *   storage-source key. This is the default and covers Local, S3, GCS,\n *   and any other server-mediated engine.\n * - `\"direct\"` — straight from the client to the external backend via\n *   its own SDK (e.g. Firebase Storage via `@firebase/storage`).\n *   The Rebase backend is **not** in the upload/download path.\n *\n * @group Models\n */\nexport type StorageSourceTransport = \"server\" | \"direct\";\n\n/**\n * Declarative definition of a storage source — a named place files live.\n *\n * Declared once and shared front and back: the frontend uses it to decide\n * transport (client HTTP proxy vs direct provider SDK), the backend uses\n * the same `key` to resolve a `StorageController`, and collection\n * properties reference a definition by its `key` via\n * `StorageConfig.storageSource`.\n *\n * @group Models\n */\nexport interface StorageSourceDefinition {\n    /**\n     * Unique identifier for this storage source. Collection properties\n     * point at it via `StorageConfig.storageSource`.\n     * Defaults to {@link DEFAULT_STORAGE_SOURCE_KEY}.\n     */\n    key: string;\n\n    /**\n     * The engine backing this storage source (e.g. `\"local\"`, `\"s3\"`,\n     * `\"gcs\"`, `\"firebase\"`, `\"azure\"`, or a custom id).\n     */\n    engine: string;\n\n    /**\n     * How the frontend reaches this storage. Defaults to `\"server\"`.\n     *\n     * When `\"direct\"`, the client uses a provider-specific SDK\n     * (e.g. `@firebase/storage`) and the backend does not proxy\n     * upload/download traffic for this source.\n     */\n    transport: StorageSourceTransport;\n\n    /** Human-readable label for the UI (e.g. \"Firebase Storage\", \"S3 Media\"). */\n    label?: string;\n}\n\n/**\n * A resolved storage source: the single source of truth that the frontend\n * router and backend registry both derive from.\n *\n * @group Models\n */\nexport interface ResolvedStorageSource {\n    /** Storage source key (routing key, shared front + back). */\n    key: string;\n    /** Engine backing the source. */\n    engine: string;\n    /** Frontend transport. */\n    transport: StorageSourceTransport;\n    /** Human-readable label. */\n    label?: string;\n}\n\n/**\n * The environment-variable suffix for a storage or data source key.\n *\n * `\"\"` for the default source — so a single-bucket project keeps configuring\n * plain `S3_BUCKET` — and `__<KEY>` for every named one, uppercased with\n * non-alphanumerics collapsed to underscores: `media-cdn` → `S3_BUCKET__MEDIA_CDN`.\n *\n * The rule derives the variable name from the declared key rather than\n * discovering keys by scanning the environment. Scanning would have to guess how\n * `S3_BUCKET__MEDIA_CDN` splits into a key; deriving cannot be ambiguous, and a\n * typo surfaces as a missing source at boot instead of a silently ignored\n * variable.\n *\n * It lives in this package, with no dependencies, because four things must agree\n * on it exactly: the CLI (validating a build), the runtime (reading its own\n * environment), the control plane (writing a tenant's Secret), and the docs. A\n * second implementation of a naming convention is a second chance to disagree.\n *\n * @group Models\n */\nexport function storageEnvSuffix(key: string, defaultKey: string = DEFAULT_STORAGE_SOURCE_KEY): string {\n    if (!key || key === defaultKey) return \"\";\n    const normalized = key\n        .replace(/[^A-Za-z0-9]+/g, \"_\")\n        .replace(/^_+|_+$/g, \"\")\n        .toUpperCase();\n    if (!normalized) {\n        throw new Error(\n            `Source key \"${key}\" cannot be turned into an environment variable name. ` +\n            \"Use a key containing at least one letter or digit.\"\n        );\n    }\n    return `__${normalized}`;\n}\n\n/**\n * Two distinct keys that collapse onto the same variable name, or `null`.\n *\n * `media-cdn` and `media_cdn` are different source keys but the same suffix, so\n * without this one of them silently reads the other's configuration. Returns the\n * offending pair rather than throwing, so each caller can raise it in its own\n * idiom — a `BundleError` at boot, a build failure in the CLI, a rejected deploy\n * in a control plane.\n *\n * @group Models\n */\nexport function findStorageSuffixCollision(\n    keys: string[],\n    defaultKey: string = DEFAULT_STORAGE_SOURCE_KEY\n): { a: string; b: string; suffix: string } | null {\n    const seen = new Map<string, string>();\n    for (const key of keys) {\n        const suffix = storageEnvSuffix(key, defaultKey);\n        const existing = seen.get(suffix);\n        if (existing !== undefined && existing !== key) {\n            return { a: existing, b: key, suffix };\n        }\n        seen.set(suffix, key);\n    }\n    return null;\n}\n\n/** The `storage` block of `rebase.json`, structurally. */\nexport type DeclaredStorageSources = Record<string, {\n    engine: string;\n    transport?: StorageSourceTransport;\n    label?: string;\n}>;\n\n/**\n * Merge the two places a project may declare storage sources into one list.\n *\n * `rebase.json` is authoritative for every field it states. Config code may add\n * sources it does not mention and fill in fields it left out, but may not\n * contradict it: the manifest is what a host reads to decide which buckets need\n * configuring, and a runtime that quietly disagreed with it would put the\n * console back to describing a topology the tenant does not have — the exact\n * failure this whole mechanism exists to end.\n *\n * Note what is *not* here: no default source is invented when both inputs are\n * empty. That decision belongs to the resolver, which knows whether declaring\n * nothing means \"one plain bucket\" (it does) or \"no storage at all\".\n *\n * @group Models\n */\nexport function normalizeStorageSources(\n    declared: DeclaredStorageSources | StorageSourceDefinition[] | undefined,\n    exported: StorageSourceDefinition[] | undefined\n): StorageSourceDefinition[] {\n    const merged = new Map<string, StorageSourceDefinition>();\n\n    // Two shapes, one meaning. `rebase.json` states sources as a record keyed by\n    // source key, which is how JSON expresses a set of named things; the bundle\n    // manifest stores the already-resolved array. Accepting both is what lets the\n    // CLI and the runtime call this with what each of them happens to hold.\n    const declaredEntries: [string, { engine: string; transport?: StorageSourceTransport; label?: string }][] =\n        Array.isArray(declared)\n            ? declared.filter(d => d?.key).map(d => [d.key, d])\n            : Object.entries(declared ?? {});\n\n    for (const [key, config] of declaredEntries) {\n        merged.set(key, {\n            key,\n            engine: config.engine,\n            transport: config.transport ?? \"server\",\n            ...(config.label !== undefined ? { label: config.label } : {})\n        });\n    }\n\n    for (const definition of exported ?? []) {\n        if (!definition?.key) continue;\n        const existing = merged.get(definition.key);\n        if (!existing) {\n            merged.set(definition.key, {\n                key: definition.key,\n                engine: definition.engine,\n                transport: definition.transport ?? \"server\",\n                ...(definition.label !== undefined ? { label: definition.label } : {})\n            });\n            continue;\n        }\n        // Fill gaps only. `rebase.json` stated these; code does not overrule it.\n        if (existing.label === undefined && definition.label !== undefined) {\n            existing.label = definition.label;\n        }\n    }\n\n    return Array.from(merged.values());\n}\n","/**\n * How a collection points at a UI component without the backend learning about React.\n *\n * This file is the hinge the BaaS/admin split turns on. `ComponentRef` is named\n * by `properties.ts` (`ui.Field`, `ui.Preview`, `ui.Filter`), and `properties.ts`\n * must stay in the React-free core because every backend subsystem — validation,\n * the drizzle schema generator, the OpenAPI generator, the SDK codegen — reads\n * property definitions. If `ComponentRef` needed `React.ComponentType`, the whole\n * property model would have to move to the admin layer with it.\n *\n * So the React types are described structurally instead of imported. Every form\n * a React component takes is assignable to {@link ComponentLike}:\n *\n * - a function component is `(props: P) => ReactNode`\n * - a class component satisfies the construct signature (`Component` has `render`)\n * - `memo` and `forwardRef` return exotic components, which are callable\n *\n * The cost is that the return type is `unknown` rather than `ReactNode`, so a\n * function that returns something React could not render is accepted here.\n * `@rebasepro/admin-types` re-exports a `ReactComponentRef<P>` narrowed against\n * the real `React.ComponentType` for authoring and for the admin's internals,\n * which restores that check where it can be enforced.\n */\n\n/**\n * Structural stand-in for `React.ComponentType<P>`.\n *\n * Deliberately not `Function` or `unknown`: those would accept anything and the\n * resolver's runtime heuristics ({@link ComponentRef} form 3) would be all that\n * stood between a typo and a blank screen.\n */\nexport type ComponentLike<P = any> =\n    | ((props: P) => unknown)\n    | (new (props: P, context?: unknown) => { render(): unknown });\n\n/**\n * Internal marker for a lazily-loaded component reference.\n * Created by the Vite transform plugin when converting string paths\n * to deferred `import()` calls. Users should NOT create these manually.\n *\n * @internal\n */\nexport interface LazyComponentRef<P = unknown> {\n    readonly __rebaseLazy: true;\n    readonly load: () => Promise<{ default: ComponentLike<P> }>;\n}\n\n/**\n * A reference to a UI component that can be provided in three forms:\n *\n * 1. **String path** (recommended for collection configs):\n *    ```ts\n *    Field: \"../../frontend/src/components/MyField\"\n *    ```\n *    The Vite plugin transforms this into a `LazyComponentRef` at build time.\n *    On the backend, the string stays inert and is never evaluated.\n *\n * 2. **Lazy import function**:\n *    ```ts\n *    Field: () => import(\"../../frontend/src/components/MyField\")\n *    ```\n *    Standard ES dynamic import. Backend never calls the function.\n *\n * 3. **Direct component reference** (use only in frontend-only code):\n *    ```ts\n *    Field: MyFieldComponent\n *    ```\n *    Importing a component at the top level will pull React into the\n *    backend runtime — only safe in code that the backend never imports.\n *    `pnpm check:headless` fails on a collection file that does this.\n *\n * @group Types\n */\nexport type ComponentRef<P = any> =\n    | string\n    | LazyComponentRef<P>\n    | (() => Promise<{ default: ComponentLike<P> }>)\n    | ComponentLike<P>;\n\n/**\n * Type guard: checks if a value is a `LazyComponentRef` produced by the\n * Vite transform plugin.\n */\nexport function isLazyComponentRef<P = unknown>(ref: unknown): ref is LazyComponentRef<P> {\n    return (\n        typeof ref === \"object\" &&\n        ref !== null &&\n        \"__rebaseLazy\" in ref &&\n        (ref as Record<string, unknown>).__rebaseLazy === true\n    );\n}\n","/**\n * The project manifest (`rebase.json`) and the build artifacts derived from it.\n *\n * Three separate documents live in this file, and keeping them distinct matters:\n *\n * 1. {@link RebaseProjectManifest} — `rebase.json`. **Authored** by the developer,\n *    committed to the repository. Declares topology only: which runtime major the\n *    project targets, and which apps *this repository* contributes to the project.\n *    Schema, security rules, hooks and functions stay in TypeScript under the\n *    config package — nothing that needs a type system belongs here.\n *\n * 2. {@link RebaseProjectLink} — the per-checkout link (`.rebase/cloud.json`).\n *    **Not committed**, because it is per-developer like a git remote. Says which\n *    deployed project this working copy points at, whether that is a Rebase Cloud\n *    project or the base URL of a self-hosted backend.\n *\n * 3. {@link RebaseBundleManifest} — `manifest.json` inside a built bundle.\n *    **Generated**, never hand-edited. It is the lockfile analogue: the exact\n *    contract a built artifact claims to satisfy, which the runtime validates\n *    before it boots and a control plane validates before it deploys.\n *\n * A repository declares only the apps it contains. The set of apps belonging to a\n * project is held by the project itself, which is what makes multi-repo projects\n * work: two repositories never need to know about each other, only about the\n * project.\n */\n\nimport type { StorageSourceDefinition } from \"./storage_source\";\n\n/**\n * Which kind of thing an app is.\n *\n * - `backend` — the collections/hooks/functions that define the project's API.\n *   Exactly one per *project* (not per repository); the registry enforces it.\n * - `static`  — a pre-built client bundle (SPA, static site), served from the\n *   backend process at its declared `path` or from a CDN. The admin panel is\n *   one of these: it is an app in the user's repository like any other.\n *\n * That is the whole list. Ownership of the server process is a property of the\n * backend app ({@link RebaseBackendAppConfig.runtime}), not an app type.\n */\nexport type RebaseAppType = \"backend\" | \"static\";\n\n/**\n * The backend app: the project's API surface.\n *\n * Paths are relative to the directory holding `rebase.json`. The defaults match\n * the layout `rebase init` scaffolds, so a stock project may declare simply\n * `{ \"type\": \"backend\", \"runtime\": \"managed\" }`.\n */\nexport interface RebaseBackendAppConfig {\n    type: \"backend\";\n    /**\n     * Who owns the process this backend runs in.\n     *\n     * - `managed` — the platform's runtime image boots this project's bundle.\n     *   You supply collections, functions, crons and schema; Rebase supplies the\n     *   server.\n     * - `custom` — this repository builds its own image and entrypoint. The\n     *   escape hatch: full control, no managed-runtime guarantees.\n     *\n     * Independent of *where* it runs. Both run on Rebase Cloud and both\n     * self-host — the destination lives in `.rebase/cloud.json`, not here. See\n     * `docker/docker-compose.selfhost.yml`, which boots a managed bundle on a\n     * developer's own Docker host.\n     *\n     * This is authored rather than inferred on purpose. It is the single most\n     * consequential fact about a deployment, and inferring it is what used to\n     * land projects on the custom runtime without anyone choosing it.\n     */\n    runtime: \"managed\" | \"custom\";\n    /** Directory of the config package (collections + index). Default `config`. */\n    config?: string;\n    /** Directory of server functions. Default `backend/functions`. */\n    functions?: string;\n    /** Directory of cron job definitions. Default `backend/crons` when present. */\n    crons?: string;\n    /**\n     * Path to the generated Drizzle schema module (tables/enums/relations).\n     * Default `backend/src/schema.generated.ts`.\n     */\n    schema?: string;\n    /**\n     * Module path (relative to `config`) exporting the auth users collection as\n     * its default export. Default `collections/users`.\n     */\n    usersCollection?: string;\n\n    /**\n     * `runtime: \"custom\"` only. Dockerfile path relative to the repository root.\n     * Default `Dockerfile`.\n     */\n    dockerfile?: string;\n    /** `runtime: \"custom\"` only. Build context relative to the root. Default `.`. */\n    context?: string;\n    /** `runtime: \"custom\"` only. Port the container listens on. Default 8080. */\n    port?: number;\n}\n\n/**\n * A static client bundle — SPA or static site — built here and served at `path`.\n */\nexport interface RebaseStaticAppConfig {\n    type: \"static\";\n    /** Package directory containing the client sources. */\n    root: string;\n    /** Command that produces `output`. Run from the repository root. */\n    build?: string;\n    /** Directory of built assets, relative to the repository root. */\n    output: string;\n    /**\n     * Public base path this app is served under. Default `/`.\n     *\n     * Several static apps run in one process, each at its own path — the API at\n     * `/api`, a site at `/`, the admin at `/admin` — which is what keeps a\n     * self-hosted deployment a single container.\n     *\n     * **This is a build-time input, not only a serving concern.** An app mounted\n     * at `/admin` must be *built* for `/admin` (Vite's `base`), or `index.html`\n     * loads and every asset 404s: a blank page with no server error. `rebase\n     * build` passes it as `REBASE_APP_BASE` and asserts the emitted HTML honours\n     * it. Changing this value requires rebuilding the app.\n     */\n    path?: string;\n    /**\n     * Serve `index.html` for unmatched paths under `path` (client-side routing).\n     * Default `true` — the overwhelmingly common case for a client app, and a\n     * static *site* generator emits real files for its routes anyway.\n     */\n    spa?: boolean;\n}\n\nexport type RebaseAppConfig = RebaseBackendAppConfig | RebaseStaticAppConfig;\n\n/**\n * One declared storage source, as authored in `rebase.json`.\n *\n * The key comes from the enclosing record, so this is\n * {@link StorageSourceDefinition} minus its `key` — the same document the\n * runtime registry and the frontend router consume, expressed the way a JSON\n * object naturally expresses \"a set of named things\".\n */\nexport interface RebaseStorageSourceConfig {\n    /** Engine backing this source: `local`, `s3`, `gcs`, or a custom id. */\n    engine: string;\n    /**\n     * How the frontend reaches it. Default `server` (proxied through\n     * `/api/storage`). `direct` means a provider SDK talks to the bucket and the\n     * backend is not in the upload path.\n     */\n    transport?: \"server\" | \"direct\";\n    /** Human-readable label for the console and the admin UI. */\n    label?: string;\n}\n\n/**\n * `rebase.json` — the authored project manifest.\n */\nexport interface RebaseProjectManifest {\n    /** JSON Schema URL, for editor completion. Ignored by the tooling. */\n    $schema?: string;\n    /**\n     * The runtime contract **major** this project targets, as a semver range\n     * (e.g. `^1`, `~1.4`, or an exact `1.4.2` to pin).\n     *\n     * The platform upgrades patches and minors underneath a project without\n     * asking; it never crosses a major. See {@link RUNTIME_CONTRACT_VERSION}.\n     *\n     * Named `rebase` rather than `runtime` so that `runtime` means exactly one\n     * thing — {@link RebaseBackendAppConfig.runtime}, who owns the process. It\n     * reads like `engines` in a `package.json`, which is what it is.\n     */\n    rebase: string;\n    /**\n     * Apps this repository contributes, keyed by app name. The key is the app's\n     * identity within the project: it is what `rebase deploy <app>` names, what\n     * client credentials are issued against, and what a second repository must\n     * not collide with.\n     */\n    apps: Record<string, RebaseAppConfig>;\n    /**\n     * Storage sources this project uses, keyed by source key.\n     *\n     * **Topology only — never credentials.** Which buckets exist is a property of\n     * the project and belongs in the repository; how to reach each one is a\n     * property of the deployment and lives in the environment, read per source\n     * from `<BASE>__<KEY>` (`S3_BUCKET__MEDIA` for a source keyed `media`). The\n     * default source takes no suffix, so a single-bucket project configured with\n     * plain `S3_BUCKET` keeps working having declared nothing at all.\n     *\n     * Declared here rather than only in the config package because this file is\n     * the one artifact a host can read *before* running a build. That is what\n     * lets a console show \"this project wants a `media` bucket, and it has none\"\n     * on a project's first deploy, and it is why the managed and custom runtimes\n     * can present the same list — a custom build emits no bundle manifest, so a\n     * declaration that lived only in compiled config would leave every custom\n     * project invisible.\n     *\n     * Omitted entirely means one default source, which is the overwhelmingly\n     * common project and must not be required to say so.\n     */\n    storage?: Record<string, RebaseStorageSourceConfig>;\n}\n\n/**\n * The per-checkout project link.\n *\n * Deliberately separate from `rebase.json`: the manifest is committed and shared,\n * while the link is per-developer. Keeping them in one file would mean either\n * committing someone's project id or gitignoring the topology.\n */\nexport interface RebaseProjectLink {\n    /**\n     * A Rebase Cloud project id, or the base URL of any running Rebase backend\n     * (`https://api.example.com`). Both are first-class: every command that\n     * accepts a project reference accepts either, so a self-hosted project has\n     * the same tooling as a cloud one.\n     */\n    project: string;\n    /** Organization slug. Cloud projects only. */\n    org?: string;\n    /** Explicit API base URL, when it differs from the project's default. */\n    apiUrl?: string;\n}\n\n/**\n * Whether a project can run on the managed runtime, and if not, precisely why.\n *\n * The reasons are returned rather than summarised so tooling can print something\n * a developer can act on. \"Not eligible\" is never a dead end — it selects the\n * custom-runtime path, which still deploys.\n */\nexport interface ManagedCompatibility {\n    eligible: boolean;\n    reasons: string[];\n}\n\n// ─────────────────────────────────────────────────────────────────────────────\n// Bundle\n// ─────────────────────────────────────────────────────────────────────────────\n\n/**\n * Version of the bundle *format* itself.\n *\n * Bumped only when the on-disk layout changes in a way an older runtime could\n * not read. A runtime accepts any bundle whose `bundleFormat` is less than or\n * equal to its own — old bundles keep booting on new runtimes, which is the\n * whole point of separating the artifact from the engine.\n *\n * - **1** — `mode: \"cms\" | \"baas\" | \"static\"`, `entry.static` a single directory\n *   string, `entry.admin` for a bundled admin panel.\n * - **2** — `kind: \"backend\" | \"static\"`, `entry.static` a list of\n *   {@link RebaseBundleStatic}, `entry.admin` removed. A format-1 runtime reading\n *   one of these would find no `mode` and an array where it expects a string, so\n *   the bump is what turns that into a refusal to boot instead of a bundle that\n *   starts and serves nothing.\n */\nexport const BUNDLE_FORMAT_VERSION = 2;\n\n/**\n * The runtime contract major.\n *\n * Distinct from the `@rebasepro/server` package version: the package may release\n * any number of minors and patches while this stays put. It changes only when\n * the bundle/runtime contract breaks compatibility, and a project's\n * `manifest.runtime` range is matched against *this*.\n */\nexport const RUNTIME_CONTRACT_VERSION = 1;\n\n/** Where the runtime finds each part of the bundle. Paths are bundle-relative. */\nexport interface RebaseBundleEntrypoints {\n    /** Compiled config package directory (collections live under it). */\n    config?: string;\n    /** Compiled collections directory, when it differs from `<config>/collections`. */\n    collections?: string;\n    /** Compiled functions directory. */\n    functions?: string;\n    /** Compiled crons directory. */\n    crons?: string;\n    /** Compiled Drizzle schema module. */\n    schema?: string;\n    /** Module exporting the auth users collection (default export). */\n    usersCollection?: string;\n    /**\n     * Built static apps to serve from this process, in declaration order.\n     *\n     * A list rather than a single directory because one process serves several\n     * apps at different paths — a site at `/` and the admin at `/admin`. The\n     * runtime mounts them longest-path-first so the `/`-rooted app's catch-all\n     * does not claim its siblings' URLs.\n     */\n    static?: RebaseBundleStatic[];\n}\n\n/** One built static app inside a bundle. */\nexport interface RebaseBundleStatic {\n    /** Public base path, e.g. `/` or `/admin`. */\n    path: string;\n    /** Bundle-relative directory holding the built assets. */\n    dir: string;\n    /** Serve `index.html` for unmatched paths under `path`. */\n    spa: boolean;\n}\n\n/**\n * A native module found in the dependency closure.\n *\n * Recorded rather than merely counted so a rejection can name the offending\n * package instead of saying \"something here is native\".\n */\nexport interface NativeDependency {\n    name: string;\n    /** Why it was flagged — a `.node` binary, a gyp build, or an install script. */\n    reason: string;\n}\n\n/**\n * `manifest.json` — generated, and the document the runtime and control plane\n * both validate against.\n */\nexport interface RebaseBundleManifest {\n    /** @see BUNDLE_FORMAT_VERSION */\n    bundleFormat: number;\n    runtime: {\n        /** The `runtime` range copied from `rebase.json`. */\n        range: string;\n        /** Exact `@rebasepro/server` version this bundle was built against. */\n        builtAgainst: string;\n        /** Runtime contract major this bundle requires. */\n        contract: number;\n    };\n    /**\n     * Hash of the compiled collection definitions.\n     *\n     * This is the contract stamp. A generated SDK records the value it was built\n     * from, a client sends it back, and a mismatch is what lets the platform say\n     * \"this app was built against an older schema\" instead of failing mysteriously\n     * at the first request. It covers collections only — a hook edit does not\n     * change a client's contract, so it must not invalidate every SDK.\n     */\n    schemaVersion: string;\n    /** Which app in `rebase.json` this bundle was built from. */\n    app: string;\n    /**\n     * What the runtime does with this bundle.\n     *\n     * - `backend` — boot the full server: database, auth and the data API, plus\n     *   any static apps in `entry.static`.\n     * - `static` — no backend at all: serve `entry.static` and nothing else. No\n     *   database, no auth, no data sources. This is how a static app runs on the\n     *   same image as the backend.\n     *\n     * Replaces an earlier `mode: \"cms\" | \"baas\" | \"static\"`. The cms/baas\n     * distinction was never a third kind of thing — it is simply whether\n     * `entry.config` is present, so it is derived rather than declared.\n     */\n    kind: \"backend\" | \"static\";\n    entry: RebaseBundleEntrypoints;\n    /** Collection slugs contained in the bundle, for quick inspection. */\n    collections?: string[];\n    hooks: {\n        /**\n         * Whether the dependency closure contains native code.\n         *\n         * The managed runtime refuses these: a prebuilt binary cannot be run on\n         * an image the platform did not build it for, and the honest failure is\n         * at deploy time rather than at 3am in a crash loop.\n         */\n        native: boolean;\n        nativeModules?: NativeDependency[];\n    };\n    /**\n     * What the bundle's config says about storage access control.\n     *\n     * Storage is not under RLS and its keys share one flat namespace, so a\n     * deployment with file storage enabled and no access model serves every\n     * user's files to every signed-in user. The runtime refuses to boot in that\n     * state — which, on a hosted platform that enables storage from the *console*\n     * rather than from the bundle, surfaces as a crash loop the developer cannot\n     * read.\n     *\n     * Recording it here lets a host reject the deploy with the reason instead.\n     * Absent on bundles built before this field existed.\n     */\n    storage?: {\n        /** Whether the config package exports a `storageAuthorize` hook. */\n        authorize: boolean;\n        /**\n         * Every storage source this bundle expects, resolved at build time from\n         * `rebase.json`'s `storage` block merged with any `storageSources` the\n         * config package exports.\n         *\n         * Recorded so the runtime does not have to import user code to learn its\n         * own topology, and so a host can tell — from the artifact alone, before\n         * starting anything — which buckets need configuring. Absent on bundles\n         * built before this field existed, which means one default source.\n         */\n        sources?: StorageSourceDefinition[];\n    };\n    deps: {\n        /** Runtime dependencies of user code, as declared. */\n        declared: Record<string, string>;\n    };\n    build: {\n        /** `@rebasepro/cli` version that produced this bundle. */\n        cli: string;\n        /** Node major the bundle was compiled on. */\n        node: string;\n        /** ISO-8601. */\n        createdAt: string;\n    };\n}\n\n/** The contract a running backend serves at `GET /api/meta/contract`. */\nexport interface RebaseProjectContract {\n    /** Matches {@link RebaseBundleManifest.schemaVersion}. */\n    schemaVersion: string;\n    runtime: {\n        /** `@rebasepro/server` version currently running. */\n        version: string;\n        contract: number;\n    };\n    /** Full collection definitions, serialized — the input to SDK generation. */\n    collections: unknown[];\n    /** Collection slugs, for cheap inspection without parsing the definitions. */\n    collectionSlugs: string[];\n    generatedAt: string;\n}\n\n/** Header carrying the schema version an SDK was generated from. */\nexport const SCHEMA_VERSION_HEADER = \"x-rebase-schema\";\n","import type { CollectionConfig } from \"./collections\";\n\n/**\n * Serializing collections so they survive a network hop.\n *\n * A collection definition is not plain data. Relations point at their target\n * with a *function* (`target: () => usersCollection`) so two collections can\n * reference each other without an import cycle, and collections also carry\n * callbacks, custom views and component references. `JSON.stringify` silently\n * drops every one of those, which matters because the SDK generator *calls*\n * `relation.target()` to decide whether a foreign key is a string or a number.\n * Serialize naively and remote SDK generation produces subtly wrong types\n * instead of failing — the worst possible outcome.\n *\n * So relation targets are resolved to a slug reference on the way out and\n * rebuilt into functions on the way in. Everything else that cannot cross a wire\n * is dropped deliberately: an SDK is generated from the *shape* of the data, and\n * server-side behaviour is neither useful to a client nor safe to publish.\n */\n\n/** Marker replacing a relation's `target` function in serialized form. */\nexport interface SerializedCollectionRef {\n    __collectionRef: string;\n}\n\nexport function isSerializedCollectionRef(value: unknown): value is SerializedCollectionRef {\n    return typeof value === \"object\"\n        && value !== null\n        && typeof (value as SerializedCollectionRef).__collectionRef === \"string\";\n}\n\n/** Depth limit for the walk — deep enough for real configs, finite for cyclic ones. */\nconst MAX_DEPTH = 64;\n\n/**\n * Resolve whatever a `target` thunk returns down to a collection.\n *\n * A target may be the collection, a module namespace (when the authoring file\n * used `import * as`), or a default-export wrapper. All three appear in real\n * projects, and the SDK generator already unwraps them the same way.\n */\nfunction unwrapTarget(value: unknown): CollectionConfig | undefined {\n    if (!value || typeof value !== \"object\") return undefined;\n    const candidate = value as { default?: unknown; __esModule?: boolean; properties?: unknown };\n    if (candidate.default || candidate.__esModule) {\n        const inner = candidate.default;\n        if (inner && typeof inner === \"object\") return inner as CollectionConfig;\n    }\n    if (candidate.properties) return value as CollectionConfig;\n    return undefined;\n}\n\n/** The identity a serialized reference uses. Slug first — it is the routing key. */\nfunction refFor(collection: CollectionConfig | undefined): string | undefined {\n    if (!collection) return undefined;\n    const withPath = collection as CollectionConfig & { path?: string };\n    return collection.slug || withPath.path || collection.name;\n}\n\n/**\n * Deep-copy a value into something JSON can carry.\n *\n * `target` keys are special-cased into refs. Other functions vanish, cycles are\n * cut, and everything else is copied structurally.\n */\n/** Shared walk state: the memo, plus a count of depth-cap hits. */\ninterface WalkState {\n    memo: WeakMap<object, unknown>;\n    /**\n     * How many times the walk has truncated a subtree — by hitting the depth\n     * cap, or by cutting a cycle.\n     *\n     * Either kind of truncation makes a result valid only at the *position* it\n     * was produced at, so caching it and serving it elsewhere silently drops\n     * content that would have been included. Comparing this counter before and\n     * after a node's children tells us whether its result is position-\n     * independent and therefore safe to memoize.\n     *\n     * The cycle case is the subtle one: with `a.b = b` and `b.a = a`, serializing\n     * `{ first: b, second: a }` visits `a` beneath `b` — where the cycle back to\n     * `b` is cut — and would then reuse that truncated `a` for `second`, where\n     * nothing needed cutting.\n     */\n    truncations: number;\n}\n\nfunction toSerializable(\n    value: unknown,\n    seen: WeakSet<object>,\n    depth: number,\n    state: WalkState,\n    key?: string\n): unknown {\n    if (depth > MAX_DEPTH) {\n        state.truncations++;\n        return undefined;\n    }\n\n    if (typeof value === \"function\") {\n        // Only a relation target carries information a client needs. Calling it\n        // is safe here — this runs on the server, where the target module is\n        // already loaded — and a throwing target simply yields no reference,\n        // which degrades the generated FK type rather than failing the request.\n        if (key === \"target\") {\n            try {\n                const resolved = unwrapTarget((value as () => unknown)());\n                const ref = refFor(resolved);\n                return ref ? { __collectionRef: ref } : undefined;\n            } catch {\n                return undefined;\n            }\n        }\n        return undefined;\n    }\n\n    if (value === null || typeof value !== \"object\") {\n        return value;\n    }\n\n    if (value instanceof Date) return value.toISOString();\n    if (value instanceof RegExp) return value.source;\n\n    if (seen.has(value as object)) {\n        state.truncations++;\n        return undefined;\n    }\n\n    // A shared (non-cyclic) subgraph is reachable by many paths, and `seen` is a\n    // *path* set — released in the `finally` below so a node referenced twice in\n    // different branches is emitted twice rather than dropped as a false cycle.\n    // Without memoization that makes the walk exponential in depth: a diamond\n    // graph 20 levels deep took ~400ms, and each further level doubled it. The\n    // result is a plain data tree, so handing back the same converted object for\n    // a repeat visit is indistinguishable after JSON.stringify.\n    const cached = state.memo.get(value as object);\n    if (cached !== undefined) return cached;\n\n    seen.add(value as object);\n    const truncationsBefore = state.truncations;\n    const memoize = (result: unknown): unknown => {\n        // Only cache a result that nothing was cut from.\n        if (result !== undefined && state.truncations === truncationsBefore) {\n            state.memo.set(value as object, result);\n        }\n        return result;\n    };\n\n    try {\n        if (Array.isArray(value)) {\n            const items = value\n                .map(item => toSerializable(item, seen, depth + 1, state))\n                .filter(item => item !== undefined);\n            // A container that had content, none of which can be represented, is\n            // itself unrepresentable — see the note below.\n            return memoize(value.length > 0 && items.length === 0 ? undefined : items);\n        }\n\n        // A React element or component reference has no meaning to a client and\n        // will not survive JSON anyway.\n        if (\"$$typeof\" in (value as Record<string, unknown>)) return undefined;\n\n        const entries = Object.entries(value as Record<string, unknown>);\n        const out: Record<string, unknown> = {};\n        for (const [k, v] of entries) {\n            const converted = toSerializable(v, seen, depth + 1, state, k);\n            if (converted !== undefined) out[k] = converted;\n        }\n\n        // Drop a container whose entire content was dropped.\n        //\n        // `callbacks: { beforeSave() {…} }` would otherwise serialize to\n        // `callbacks: {}` — an empty husk that carries no information but is not\n        // *nothing*, so it lands in the payload and, worse, in the schema hash.\n        // Editing a hook would then change every client's schema version and\n        // report perfectly current SDKs as stale.\n        //\n        // A container that started empty stays empty: `properties: {}` is a\n        // deliberate statement, not a casualty.\n        if (entries.length > 0 && Object.keys(out).length === 0) return undefined;\n\n        return memoize(out);\n    } finally {\n        // Released so a collection referenced twice in different branches is\n        // emitted twice rather than being dropped as a false cycle.\n        seen.delete(value as object);\n    }\n}\n\n/**\n * Serialize collections for transport over the contract endpoint.\n *\n * Sorted by slug so the output — and therefore the schema hash computed from it\n * — does not depend on filesystem ordering.\n */\nexport function serializeCollections(collections: CollectionConfig[]): unknown[] {\n    return [...collections]\n        .sort((a, b) => String(a.slug ?? \"\").localeCompare(String(b.slug ?? \"\")))\n        .map(collection => toSerializable(withoutAdminBlock(collection), new WeakSet(), 0, {\n            memo: new WeakMap(),\n            truncations: 0\n        }))\n        .filter((c): c is Record<string, unknown> => c !== undefined);\n}\n\n/**\n * Drop the admin block before the walk.\n *\n * Nothing downstream of serialization is an admin panel. The contract endpoint\n * feeds remote SDK generation, and `rebase build` writes the result into a bundle\n * manifest that only the backend runtime reads. The block would survive the walk\n * as a husk anyway — its React elements and component functions are dropped\n * individually — and that husk has two costs worth avoiding: it puts every custom\n * component's *file path* on an endpoint whose job is to describe data shapes, and\n * it grows a payload that is fetched and cached per project.\n *\n * Removing it here rather than at each call site means one chokepoint, so a future\n * consumer of `serializeCollections` cannot forget.\n *\n * Child collections carry their own block, so this recurses — stripping only the\n * top level was the mistake `stripNonClientFields` in the contract routes already\n * had to fix once for security rules.\n */\nfunction withoutAdminBlock(collection: CollectionConfig): CollectionConfig {\n    const { admin: _admin, ...rest } = collection as CollectionConfig & Record<string, unknown>;\n    const nested = rest as Record<string, unknown>;\n    if (Array.isArray(nested.subcollections)) {\n        nested.subcollections = nested.subcollections.map(\n            (child) => withoutAdminBlock(child as CollectionConfig)\n        );\n    }\n    return rest as CollectionConfig;\n}\n\n/**\n * Rebuild collections received from a contract endpoint.\n *\n * Relation refs become real thunks resolving through the returned set, so\n * downstream consumers — the SDK generator above all — see exactly the shape\n * they would have seen had the collections been imported from source.\n *\n * A ref naming a collection that is not in the payload resolves to `undefined`\n * rather than throwing: the generator already tolerates an unresolvable target\n * by falling back to a permissive key type, and a partial contract should still\n * produce a usable SDK.\n */\nexport function deserializeCollections(payload: unknown[]): CollectionConfig[] {\n    const collections = payload\n        .filter((c): c is Record<string, unknown> => typeof c === \"object\" && c !== null)\n        .map(c => ({ ...c })) as unknown as CollectionConfig[];\n\n    const bySlug = new Map<string, CollectionConfig>();\n    for (const collection of collections) {\n        const ref = refFor(collection);\n        if (ref) bySlug.set(ref, collection);\n    }\n\n    const rehydrate = (value: unknown, depth: number): void => {\n        if (depth > MAX_DEPTH || !value || typeof value !== \"object\") return;\n\n        if (Array.isArray(value)) {\n            for (const item of value) rehydrate(item, depth + 1);\n            return;\n        }\n\n        const record = value as Record<string, unknown>;\n        for (const [key, child] of Object.entries(record)) {\n            if (key === \"target\" && isSerializedCollectionRef(child)) {\n                const slug = child.__collectionRef;\n                record.target = () => bySlug.get(slug);\n                continue;\n            }\n            rehydrate(child, depth + 1);\n        }\n    };\n\n    for (const collection of collections) rehydrate(collection, 0);\n    return collections;\n}\n","import type { CollectionConfig } from \"./collections\";\nimport { serializeCollections } from \"./collection_contract\";\n\n/**\n * The schema version stamp.\n *\n * One function, used in three places that must agree or the whole drift-detection\n * story is noise: `rebase build` writes it into a bundle manifest, the runtime\n * serves it from the contract endpoint, and a generated SDK records the value it\n * was built from. If any two of those computed it differently, every client would\n * look permanently out of date.\n *\n * It covers **collections only** — the client's contract is the shape of the\n * data, so editing a hook or a server function must not invalidate every SDK in\n * every repository. That is a deliberate narrowing, not an oversight.\n */\n\n/** Stable stringify: object keys sorted at every level, so key order cannot alter the hash. */\nfunction canonicalize(value: unknown): string {\n    if (value === null || typeof value !== \"object\") {\n        return JSON.stringify(value) ?? \"null\";\n    }\n    if (Array.isArray(value)) {\n        return `[${value.map(canonicalize).join(\",\")}]`;\n    }\n    const entries = Object.entries(value as Record<string, unknown>)\n        .filter(([, v]) => v !== undefined)\n        .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));\n    return `{${entries.map(([k, v]) => `${JSON.stringify(k)}:${canonicalize(v)}`).join(\",\")}}`;\n}\n\n/**\n * Reduce a collection to the parts a generated client is actually built from.\n *\n * The version answers one question — \"is this SDK stale?\" — so it must change\n * exactly when the generated types could change, and never otherwise. Hashing a\n * whole collection fails both halves of that:\n *\n * - Security rules, callbacks, icons, groups and UI settings do not appear in a\n *   generated client, so including them reports perfectly current SDKs as stale.\n * - Worse, they are not stable *inputs*. The runtime applies default security\n *   rules when it loads collections, so the same source hashed before and after\n *   loading produced two different answers — a build-time stamp that could never\n *   match the server that served it.\n *\n * Codegen reads the slug (for the `Database` key and type names), the properties,\n * and the relations. That is the projection.\n */\nfunction projectForCodegen(collection: CollectionConfig): Record<string, unknown> {\n    const source = collection as CollectionConfig & {\n        relations?: unknown;\n        subcollections?: CollectionConfig[];\n        path?: string;\n        engine?: unknown;\n        dataSource?: unknown;\n    };\n\n    return {\n        slug: collection.slug ?? source.path,\n        properties: collection.properties,\n        relations: source.relations,\n        // The engine decides whether relations are resolved at all: codegen asks\n        // `getDataSourceCapabilities(collection.engine).supportsRelations`, and an\n        // engine that answers no drops every foreign-key column from the\n        // generated Row/Insert/Update types. Moving a collection to such an\n        // engine is a real change to the generated types, so it has to move the\n        // version. `dataSource` is what resolves to `engine`, so it counts too.\n        engine: source.engine,\n        dataSource: source.dataSource,\n        subcollections: source.subcollections?.map(projectForCodegen)\n    };\n}\n\n/**\n * Compute the canonical string a schema version hashes.\n *\n * Exposed separately so the hashing itself can differ by environment: Node has\n * `crypto`, and callers without it can still compare canonical forms directly.\n */\nexport function canonicalSchemaPayload(collections: CollectionConfig[]): string {\n    const projected = serializeCollections(collections)\n        .map(collection => projectForCodegen(collection as CollectionConfig));\n    return canonicalize(projected);\n}\n\n/**\n * A short, non-cryptographic digest of the canonical payload.\n *\n * FNV-1a style, 64 bits, as two 32-bit halves. This is an identity, not a\n * security boundary: nothing trusts a schema version to prove anything, it only\n * answers \"is this the same schema as before\". A hand-rolled hash keeps this\n * module free of `node:crypto`, so the identical function runs in the browser,\n * in the CLI, and in the runtime — which is the property that actually matters.\n */\nexport function computeSchemaVersion(collections: CollectionConfig[]): string {\n    const payload = canonicalSchemaPayload(collections);\n\n    let h1 = 0x811c9dc5;\n    let h2 = 0x01000193;\n\n    for (let i = 0; i < payload.length; i++) {\n        const code = payload.charCodeAt(i);\n        h1 ^= code;\n        // Multiply by the FNV prime using shifts to stay in 32-bit integer math.\n        h1 = (h1 + ((h1 << 1) + (h1 << 4) + (h1 << 7) + (h1 << 8) + (h1 << 24))) >>> 0;\n        h2 ^= code + i;\n        h2 = (h2 + ((h2 << 1) + (h2 << 5) + (h2 << 9) + (h2 << 15) + (h2 << 24))) >>> 0;\n    }\n\n    const hex = (n: number): string => n.toString(16).padStart(8, \"0\");\n    return `v1:${hex(h1)}${hex(h2)}`;\n}\n","import type { CollectionRegistryController } from \"./collection_registry\";\nimport type { EntityStatus, EntityValues } from \"../types/entities\";\nimport type { CollectionConfig, FilterValues } from \"../types/collections\";\nimport type { RebaseCallContext } from \"../call_context\";\n\n\n/**\n * @internal\n */\nexport interface FetchOneProps<M extends Record<string, unknown> = Record<string, unknown>> {\n    path: string;\n    id: string | number;\n    databaseId?: string;\n    collection?: CollectionConfig<M>\n}\n\n/**\n * @internal\n */\nexport type ListenOneProps<M extends Record<string, unknown> = Record<string, unknown>> =\n    FetchOneProps<M>\n    & {\n        onUpdate: (row: Record<string, unknown> | null) => void,\n        onError?: (error: Error) => void,\n    }\n\n/**\n * Configuration for vector similarity search queries.\n * Vector search applies an ORDER BY distance expression and optionally\n * filters results by a distance threshold.\n */\nexport interface VectorSearchParams {\n    /** Property name containing the vector column */\n    property: string;\n    /** Query vector to compare against */\n    vector: number[];\n    /** Distance function (default: \"cosine\") */\n    distance?: \"cosine\" | \"l2\" | \"inner_product\";\n    /** Only return results within this distance threshold */\n    threshold?: number;\n}\n\n// ── List pagination bounds ────────────────────────────────────────────────\n//\n// Client-driven list reads (REST `GET /<collection>` and the WebSocket\n// `subscribe_collection` message) accept a client-supplied `limit`. Without\n// bounds, an ABSENT limit streams the entire table into memory — a trivial\n// OOM/DoS — and `limit=100000000` (or `limit=0`, historically an unlimited\n// bypass) is honoured verbatim. `resolveClientListLimit` is the single shared\n// enforcement point so every untrusted ingress behaves identically. Trusted\n// server-side callers build fetch options directly and are intentionally NOT\n// bounded here (migrations, admin exports, and CDC refetches may need the full\n// set).\n\n/** Rows returned for a plain / text-search list read when the client sends no `limit`. */\nexport const DEFAULT_LIST_LIMIT = 50;\n/** Rows returned for a vector-search list read when the client sends no `limit`. */\nexport const DEFAULT_VECTOR_LIST_LIMIT = 10;\n/** Hard ceiling clamped onto any client-supplied `limit`, on every surface. */\nexport const MAX_LIST_LIMIT = 1000;\n\n/** Overridable bounds for {@link resolveClientListLimit}. */\nexport interface ListLimitBounds {\n    /** Default page size for plain and text-search reads. */\n    defaultLimit?: number;\n    /** Default page size for vector-search reads. */\n    vectorDefaultLimit?: number;\n    /** Upper bound clamped onto any client-supplied limit. */\n    maxLimit?: number;\n}\n\n/**\n * Resolve a client-supplied list `limit` into a safe, always-defined value.\n *\n * - A provided limit is coerced to an integer and clamped to `[1, maxLimit]`,\n *   so `0`, negatives, and absurd values can never bypass the cap.\n * - An absent / blank / non-numeric limit falls back to the mode default:\n *   `vectorDefaultLimit` for a vector search, otherwise `defaultLimit`.\n *\n * The return is never `undefined` — no ingress that routes its client limit\n * through this can produce an unbounded read.\n */\nexport function resolveClientListLimit(\n    rawLimit: number | string | null | undefined,\n    opts: ListLimitBounds & { vectorSearch?: boolean } = {}\n): number {\n    const maxLimit = opts.maxLimit ?? MAX_LIST_LIMIT;\n    if (rawLimit != null && String(rawLimit).trim() !== \"\") {\n        const parsed = typeof rawLimit === \"number\" ? rawLimit : parseInt(String(rawLimit), 10);\n        if (Number.isFinite(parsed)) {\n            return Math.min(Math.max(1, Math.floor(parsed)), maxLimit);\n        }\n    }\n    return opts.vectorSearch\n        ? (opts.vectorDefaultLimit ?? DEFAULT_VECTOR_LIST_LIMIT)\n        : (opts.defaultLimit ?? DEFAULT_LIST_LIMIT);\n}\n\n/**\n * @internal\n */\nexport interface FetchCollectionProps<M extends Record<string, unknown> = Record<string, unknown>> {\n    path: string;\n    collection?: CollectionConfig<M>;\n    filter?: FilterValues<Extract<keyof M, string>>,\n    limit?: number;\n    offset?: number;\n    startAfter?: unknown;\n    orderBy?: string;\n    searchString?: string;\n    order?: \"desc\" | \"asc\";\n    /** Vector similarity search configuration */\n    vectorSearch?: VectorSearchParams;\n}\n\n/**\n * @internal\n */\nexport type ListenCollectionProps<M extends Record<string, unknown> = Record<string, unknown>> =\n    FetchCollectionProps<M> &\n    {\n        onUpdate: (rows: Record<string, unknown>[]) => void;\n        onError?: (error: Error) => void;\n    };\n\n/**\n * @internal\n */\nexport interface SaveProps<M extends Record<string, unknown> = Record<string, unknown>> {\n    path: string;\n    values: Partial<EntityValues<M>>;\n    id?: string | number; // can be empty for new entities\n    previousValues?: Partial<EntityValues<M>>;\n    collection?: CollectionConfig<M>;\n    status: EntityStatus;\n    /**\n     * Write the row with INSERT ... ON CONFLICT DO UPDATE on the primary key\n     * instead of choosing between insert and update up front.\n     *\n     * One statement, so it does not lose the race a read-then-write can, and it\n     * succeeds whether or not the row is already there — what a re-runnable\n     * import needs. Requires every primary key column to be present; without\n     * them there is no conflict target and the row is inserted normally.\n     */\n    upsert?: boolean;\n}\n\n/**\n * @internal\n */\nexport interface SaveManyProps<M extends Record<string, unknown> = Record<string, unknown>> {\n    path: string;\n    /**\n     * The rows to write. A row carrying its primary key updates (or, with\n     * `upsert`, inserts-or-updates) that row; one without inserts.\n     */\n    rows: Partial<EntityValues<M>>[];\n    collection?: CollectionConfig<M>;\n    /** Apply every row as INSERT ... ON CONFLICT DO UPDATE. See {@link SaveProps.upsert}. */\n    upsert?: boolean;\n}\n\n/**\n * @internal\n */\nexport interface DeleteProps<M extends Record<string, unknown> = Record<string, unknown>> {\n    row: { id: string | number; path: string; values?: Partial<EntityValues<M>> };\n    collection?: CollectionConfig<M>;\n}\n\nexport type FilterCombinationValidProps = {\n    path: string;\n    databaseId?: string;\n    collection: CollectionConfig;\n    filterValues: FilterValues<string>;\n    sortBy?: [string, \"asc\" | \"desc\"];\n};\n\n/**\n * The integration SPI for plugging a data backend into Rebase.\n *\n * Implement this interface to connect a custom backend (or use a built-in\n * driver such as the Firestore one) and register it on\n * `<Rebase dataSources>`. Rebase wraps drivers via `buildRebaseData` and\n * routes collections to them by their `dataSource` key.\n *\n * For *consuming* data in application code, use `RebaseData` /\n * `context.data` instead — this interface is only for providing it.\n *\n * @group Datasource\n */\nexport interface DataDriver {\n\n    /**\n     * Key that identifies this driver\n     */\n    key?: string;\n\n    /**\n     * If the driver has been initialised\n     */\n    initialised?: boolean;\n\n    /**\n     * Fetch data from a collection\n     * @param props\n     * @return Promise of flat rows\n     */\n    fetchCollection<M extends Record<string, unknown> = Record<string, unknown>>(props: FetchCollectionProps<M>): Promise<Record<string, unknown>[]>;\n\n    /**\n     * Listen to a collection in a given path. If you don't implement this method\n     * `fetchCollection` will be used instead, with no real time updates.\n     * @param props\n     * @return Function to cancel subscription\n     */\n    listenCollection?<M extends Record<string, unknown> = Record<string, unknown>>(props: ListenCollectionProps<M>): () => void;\n\n    /**\n     * Retrieve a single row given a path and a collection\n     * @param props\n     */\n    fetchOne<M extends Record<string, unknown> = Record<string, unknown>>(props: FetchOneProps<M>): Promise<Record<string, unknown> | undefined>;\n\n    /**\n     * Get realtime updates on one row.\n     * @param props\n     * @return Function to cancel subscription\n     */\n    listenOne?<M extends Record<string, unknown> = Record<string, unknown>>(props: ListenOneProps<M>): () => void;\n\n    /**\n     * Save a row to the specified path\n     * @param props\n     */\n    save<M extends Record<string, unknown> = Record<string, unknown>>(props: SaveProps<M>): Promise<Record<string, unknown>>;\n\n    /**\n     * Save many rows as one unit of work.\n     *\n     * Every row runs the same pipeline as {@link save} — callbacks, relations\n     * and row-level security all still apply — but they share a single\n     * transaction, so the batch either lands whole or not at all. That, and the\n     * single round trip, is what makes importing tens of thousands of rows\n     * viable without dropping to raw SQL.\n     *\n     * Optional: drivers that cannot do this leave it undefined and callers fall\n     * back to `save` per row.\n     */\n    saveMany?<M extends Record<string, unknown> = Record<string, unknown>>(props: SaveManyProps<M>): Promise<Record<string, unknown>[]>;\n\n    /**\n     * Delete a entity\n     * @param props\n     * @return was the whole deletion flow successful\n     */\n    delete<M extends Record<string, unknown> = Record<string, unknown>>(props: DeleteProps<M>): Promise<void>;\n\n    /**\n     * Delete all entities from a collection.\n     * @param path Collection path\n     */\n    deleteAll?(path: string): Promise<void>;\n\n    /**\n     * Check if the given property is unique in the given collection\n     * @param path Collection path\n     * @param name of the property\n     * @param value\n     * @param id\n     * @param collection\n     * @return `true` if there are no other fields besides the given entity\n     */\n    checkUniqueField(\n        path: string,\n        name: string,\n        value: unknown,\n        id?: string | number,\n        collection?: CollectionConfig\n    ): Promise<boolean>;\n\n    /**\n     * Count the number of entities in a collection\n     */\n    count?<M extends Record<string, unknown> = Record<string, unknown>>(props: FetchCollectionProps<M>): Promise<number>;\n\n    /**\n     * Check if the given filter combination is valid\n     * @param props\n     */\n    isFilterCombinationValid?(props: Omit<FilterCombinationValidProps, \"collection\"> & {\n        databaseId?: string\n    }): boolean;\n\n    /**\n     * Get the object to generate the current time in the driver\n     */\n    currentTime?: () => unknown;\n\n    delegateToCMSModel?: (data: unknown) => unknown;\n\n    cmsToDelegateModel?: (data: unknown) => unknown;\n\n    initTextSearch?: (props: {\n        context: RebaseCallContext,\n        path: string,\n        databaseId?: string,\n        collection: CollectionConfig,\n        parentCollectionSlugs?: string[];\n        parentEntityIds?: string[];\n    }) => Promise<boolean>;\n\n    /**\n     * Flag to indicate if the driver has requested the initialization of the text search index\n     */\n    needsInitTextSearch?: boolean;\n\n    // ── REST fetch capabilities ─────────────────────────────────────────\n\n    /**\n     * Optional REST-optimised fetch service. When present, the REST API\n     * generator uses these methods instead of the generic `fetchOne` /\n     * `fetchCollection` pipeline, enabling include-aware eager-loading.\n     */\n    restFetchService?: RestFetchService;\n\n    // ── Admin capabilities ─────────────────────────────────────────────\n    //\n    // Admin operations are now modelled as capability-specific interfaces\n    // (SQLAdmin, DocumentAdmin, SchemaAdmin) in `@rebasepro/types/backend`.\n    //\n    // Drivers that support admin features should expose them here.\n    // Consumers should use the `isSQLAdmin()`, `isSchemaAdmin()` etc.\n    // type guards to safely narrow the type before calling methods.\n\n    /**\n     * Return the admin capabilities of this driver.\n     * @see SQLAdmin\n     * @see DocumentAdmin\n     * @see SchemaAdmin\n     */\n    admin?: import(\"../types/backend\").DatabaseAdmin;\n\n}\n\n/**\n * REST-optimised fetch service exposed by drivers that support\n * eager-loading of relations via `include`.\n *\n * The methods return flattened rows — exactly the table's columns, under their\n * own names and with the types the database returned — and included relations\n * inlined as plain nested rows. This is the shape served to app developers\n * through the REST API / SDK client.\n *\n * No synthesized `id`: identity is a primary key, which may be named anything\n * and span several columns, so an address is derived by whoever needs one (see\n * `buildCompositeId`) rather than written into the row on top of the data.\n *\n * @group DataDriver\n */\nexport interface RestFetchService {\n    /**\n     * Fetch a collection of flattened entities with optional relation includes.\n     */\n    fetchCollectionForRest(\n        collectionPath: string,\n        options?: {\n            filter?: FilterValues<string>;\n            orderBy?: string;\n            order?: \"desc\" | \"asc\";\n            limit?: number;\n            offset?: number;\n            startAfter?: Record<string, unknown>;\n            searchString?: string;\n            databaseId?: string;\n            vectorSearch?: VectorSearchParams;\n        },\n        include?: string[]\n    ): Promise<Record<string, unknown>[]>;\n\n    /**\n     * Fetch a single flattened entity with optional relation includes.\n     */\n    fetchOneForRest(\n        collectionPath: string,\n        id: string | number,\n        include?: string[],\n        databaseId?: string\n    ): Promise<Record<string, unknown> | null>;\n}\n","/**\n * Path prefix that marks an object as **public**. Files stored under this\n * prefix are served without any auth token via a stable, permanent,\n * CDN-cacheable URL (see {@link StorageSource.getSignedUrl}). Shared by the\n * client SDK and the backend so both agree on which objects are public.\n *\n * @group Models\n */\nexport const PUBLIC_STORAGE_PREFIX = \"public/\";\n\n/**\n * True when a storage key/path points at a public object (lives under\n * {@link PUBLIC_STORAGE_PREFIX}). The check is applied to the key *within the\n * bucket* — strip any `bucket/` and `scheme://` prefixes first.\n *\n * @group Models\n */\nexport function isPublicStoragePath(path: string | null | undefined): boolean {\n    if (!path) return false;\n    let p = path;\n    const scheme = p.indexOf(\"://\");\n    if (scheme !== -1) p = p.substring(scheme + 3);\n    p = p.replace(/^\\/+/, \"\");\n\n    // Defense-in-depth: a path containing traversal segments is never public,\n    // so an attacker can't reach a private object via `public/../secret`.\n    if (p.split(\"/\").some((seg) => seg === \"..\")) return false;\n\n    // Public iff the object **key** starts with the public prefix. A single\n    // leading `default/` bucket segment is tolerated (the default bucket).\n    // A substring match is deliberately NOT used — a private object under a\n    // folder literally named `public` (e.g. `reports/public/q3.pdf`) must stay\n    // private. Named buckets: pass the key (not `bucket/key`) so the prefix is\n    // anchored; otherwise it falls back to a private, token-scoped URL (safe).\n    return p.startsWith(PUBLIC_STORAGE_PREFIX) || p.startsWith(`default/${PUBLIC_STORAGE_PREFIX}`);\n}\n\n/**\n * @group Models\n */\nexport interface UploadFileProps {\n    file: File,\n    key: string,\n    metadata?: Record<string, unknown>,\n    bucket?: string,\n    /**\n     * Store this object as **public**: it is placed under\n     * {@link PUBLIC_STORAGE_PREFIX} and served via a stable, token-less,\n     * permanent URL (safe to persist in a database and cache on a CDN).\n     * Defaults to `false` (private, short-lived signed URLs).\n     */\n    public?: boolean\n}\n\n/**\n * @group Models\n */\nexport interface UploadFileResult {\n    /**\n     * Storage key including the file name where the file was uploaded.\n     */\n    key: string;\n    /**\n     * Bucket where the file was uploaded\n     */\n    bucket: string;\n\n    /**\n     * Fully qualified storage URL for the uploaded file.\n     *\n     * For example: `s3://my-bucket/path/to/file.png`.\n     *\n     * This is optional for backwards compatibility.\n     */\n    storageUrl?: string;\n}\n\n/**\n * @group Models\n */\nexport interface DownloadConfig {\n    /**\n     * Temporal url that can be used to download the file\n     */\n    url: string | null;\n\n    metadata?: DownloadMetadata;\n\n    fileNotFound?: boolean;\n}\n\n/**\n * The full set of object metadata, including read-only properties.\n * @public\n */\nexport declare interface DownloadMetadata {\n    /**\n     * The bucket this object is contained in.\n     */\n    bucket: string;\n    /**\n     * The full path of this object.\n     */\n    fullPath: string;\n    /**\n     * The short name of this object, which is the last component of the full path.\n     * For example, if path is 'full/path/image.png', name is 'image.png'.\n     */\n    name: string;\n    /**\n     * The size of this object, in bytes.\n     */\n    size: number;\n    /**\n     * Type of the uploaded file\n     * e.g. \"image/jpeg\"\n     */\n    contentType: string;\n\n    customMetadata: Record<string, unknown>;\n    /**\n     * Optional short-lived download token (for local/server-mediated storage).\n     * Absent for public objects, which need no token.\n     */\n    token?: string;\n    /**\n     * Optional remaining lifetime of the token, in seconds.\n     */\n    tokenExpiresIn?: number;\n    /**\n     * True when this object is public: it is served without a token via a\n     * stable, permanent, CDN-cacheable URL. When set, the client builds a\n     * token-less URL and caches it indefinitely.\n     */\n    public?: boolean;\n}\n\n/**\n * @group Models\n */\nexport interface StorageSource {\n    /**\n     * Upload an object, specifying a key\n     * @param file\n     * @param key\n     * @param metadata\n     * @param bucket\n     */\n    putObject: ({\n                     file,\n                     key,\n                     metadata,\n                     bucket\n                 }: UploadFileProps) => Promise<UploadFileResult>;\n\n    /**\n     * Convert a storage key or URL into a download configuration (signed URL equivalent)\n     * @param keyOrUrl\n     * @param bucket\n     */\n    getSignedUrl: (keyOrUrl: string, bucket?: string) => Promise<DownloadConfig>;\n\n    /**\n     * Get an object from a storage key.\n     * It returns null if the object does not exist.\n     * @param key\n     * @param bucket\n     */\n    getObject: (key: string, bucket?: string) => Promise<File | null>;\n\n    /**\n     * Delete an object.\n     * @param key\n     * @param bucket\n     */\n    deleteObject: (key: string, bucket?: string) => Promise<void>;\n\n    /**\n     * List the contents of a prefix.\n     * @param prefix\n     * @param options\n     */\n    listObjects: (prefix: string, options?: {\n        bucket?: string,\n        maxResults?: number,\n        pageToken?: string\n    }) => Promise<StorageListResult>;\n\n}\n\n/**\n * Result returned by list().\n * @public\n */\nexport declare interface StorageListResult {\n    /**\n     * References to prefixes (sub-folders). You can call list() on them to\n     * get its contents.\n     *\n     * Folders are implicit based on '/' in the object paths.\n     * For example, if a bucket has two objects '/a/b/1' and '/a/b/2', list('/a')\n     * will return '/a/b' as a prefix.\n     */\n    prefixes: StorageReference[];\n    /**\n     * Objects in this directory.\n     * You can call getMetadata() and getDownloadUrl() on them.\n     */\n    items: StorageReference[];\n    /**\n     * If set, there might be more results for this list. Use this token to resume the list.\n     */\n    nextPageToken?: string;\n}\n\n/**\n * Represents a reference to an S3-compatible storage object. Developers can\n * upload, download, and delete objects, as well as get/set object metadata.\n * @public\n */\nexport declare interface StorageReference {\n    /**\n     * Returns a s3:// URL for this object in the form\n     *   `s3://<bucket>/<path>/<to>/<object>`\n     * @returns The s3:// URL.\n     */\n    toString(): string;\n\n    /**\n     * A reference to the root of this object's bucket.\n     */\n    root: StorageReference;\n    /**\n     * The name of the bucket containing this reference's object.\n     */\n    bucket: string;\n    /**\n     * The full path of this object.\n     */\n    fullPath: string;\n    /**\n     * The short name of this object, which is the last component of the full path.\n     * For example, if path is 'full/path/image.png', name is 'image.png'.\n     */\n    name: string;\n\n    /**\n     * A reference pointing to the parent location of this reference, or null if\n     * this reference is the root.\n     */\n    parent: StorageReference | null;\n}\n"],"mappings":"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"}

package/dist/types/cron.d.ts

@@ -26,6 +26,37 @@ export interface CronJobDefinition {
      * considered timed-out. Default: 300 (5 min).
      */
     timeoutSeconds?: number;
+    /**
+     * How far back to look, on startup, for a slot that elapsed while no
+     * instance was holding a timer for it. Off by default.
+     *
+     * The scheduler drives jobs with in-process `setTimeout` and computes the
+     * next slot from *now* on every boot, so a slot only fires if some instance
+     * happened to be alive and ticking when it came round. That is not a
+     * scale-to-zero problem: a platform that recycles containers — Cloud Run
+     * rotating an instance under `--min-instances 1`, a rolling deploy, a crash
+     * loop — drops any slot that falls inside the changeover, and the
+     * replacement schedules the slot *after* it. The run is skipped in silence.
+     *
+     * Set this to a window comfortably wider than a restart (a few minutes for
+     * a frequent job; an hour or more for a daily one) and startup will run a
+     * slot it finds unclaimed inside that window.
+     *
+     * Two deliberate limits:
+     *
+     * - **Only the most recent missed slot runs.** Booting after a six-hour
+     *   outage catches an hourly job up once, not six times. Catch-up exists to
+     *   stop a run going missing, not to replay history.
+     * - **A claims-capable store is required.** Catch-up is skipped entirely
+     *   when the store has no `tryClaimRun` (or no store is attached), because
+     *   the claim is the only thing that distinguishes "this slot never ran"
+     *   from "this slot already ran on the instance I am replacing". Without
+     *   it, an instance recycled every 30 minutes would re-run the same hourly
+     *   job every time it booted.
+     *
+     * @example catchUpWindowSeconds: 3600  // daily job: tolerate an hour of downtime
+     */
+    catchUpWindowSeconds?: number;
     /**
      * The handler function executed on each tick.
      * Receives a context object with the data driver and logger.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@rebasepro/types",
   "type": "module",
-  "version": "0.12.0",
+  "version": "0.12.1-canary.gdfba2a1",
   "description": "Rebase type definitions — shared interfaces and controller types",
   "funding": {
     "url": "https://github.com/sponsors/rebaseco"
@@ -39,14 +39,14 @@
   },
   "devDependencies": {
     "@types/jest": "^30.0.0",
-    "@types/node": "^25.9.3",
+    "@types/node": "^26.1.2",
     "@types/object-hash": "^3.0.6",
     "@types/react-measure": "^2.0.12",
     "hono": "^4.12.27",
     "jest": "^30.4.2",
-    "ts-jest": "^29.4.11",
+    "ts-jest": "^29.4.12",
     "typescript": "^6.0.3",
-    "vite": "^8.0.16"
+    "vite": "^8.1.5"
   },
   "peerDependencies": {
     "hono": "^4.12.27"

package/src/types/cron.ts

@@ -38,6 +38,38 @@ export interface CronJobDefinition {
      */
     timeoutSeconds?: number;
 
+    /**
+     * How far back to look, on startup, for a slot that elapsed while no
+     * instance was holding a timer for it. Off by default.
+     *
+     * The scheduler drives jobs with in-process `setTimeout` and computes the
+     * next slot from *now* on every boot, so a slot only fires if some instance
+     * happened to be alive and ticking when it came round. That is not a
+     * scale-to-zero problem: a platform that recycles containers — Cloud Run
+     * rotating an instance under `--min-instances 1`, a rolling deploy, a crash
+     * loop — drops any slot that falls inside the changeover, and the
+     * replacement schedules the slot *after* it. The run is skipped in silence.
+     *
+     * Set this to a window comfortably wider than a restart (a few minutes for
+     * a frequent job; an hour or more for a daily one) and startup will run a
+     * slot it finds unclaimed inside that window.
+     *
+     * Two deliberate limits:
+     *
+     * - **Only the most recent missed slot runs.** Booting after a six-hour
+     *   outage catches an hourly job up once, not six times. Catch-up exists to
+     *   stop a run going missing, not to replay history.
+     * - **A claims-capable store is required.** Catch-up is skipped entirely
+     *   when the store has no `tryClaimRun` (or no store is attached), because
+     *   the claim is the only thing that distinguishes "this slot never ran"
+     *   from "this slot already ran on the instance I am replacing". Without
+     *   it, an instance recycled every 30 minutes would re-run the same hourly
+     *   job every time it booted.
+     *
+     * @example catchUpWindowSeconds: 3600  // daily job: tolerate an hour of downtime
+     */
+    catchUpWindowSeconds?: number;
+
     /**
      * The handler function executed on each tick.
      * Receives a context object with the data driver and logger.