@rebasepro/types 0.16.1-canary.gef08a6e → 0.17.0

package/dist/types/admin_block.d.ts

@@ -3,7 +3,7 @@
  *
  * There is no *type* for the block in this package any more, and that is the point:
  * `admin` is not declared on `BaseCollectionConfig` or on any property here, so a
- * BaaS install cannot even write one. `@rebasepro/admin-types` adds the field back by
+ * BaaS install cannot even write one. `@rebasepro/cms-types` adds the field back by
  * declaration merging, which is why installing it is what makes the admin surface
  * appear.
  *
@@ -14,7 +14,7 @@
  * Every key that belongs inside a collection's `admin` block, as data.
  *
  * The type that describes these fields is `AdminCollectionOptions` in
- * `@rebasepro/admin-types`, and it is erased at build time — but three runtime
+ * `@rebasepro/cms-types`, and it is erased at build time — but three runtime
  * consumers need the list, and two of them are core:
  *
  * - `serializeCollections`, to drop the block from the contract
@@ -24,7 +24,7 @@
  *   backend ignores it and the panel never finds it again.
  * - the `collections-admin-block` codemod
  *
- * `@rebasepro/admin-types` re-exports this and asserts it names only real option
+ * `@rebasepro/cms-types` re-exports this and asserts it names only real option
  * keys; the count is pinned by a test there.
  *
  * @group Models
@@ -36,15 +36,15 @@ export type AdminCollectionKey = typeof ADMIN_COLLECTION_KEYS[number];
  * Every key that belongs inside a *property's* `admin` block, as data.
  *
  * The union of `AdminPropertyOptions` and its per-type extensions
- * (`AdminStringOptions`, `AdminArrayOptions`, …) in `@rebasepro/admin-types`.
+ * (`AdminStringOptions`, `AdminArrayOptions`, …) in `@rebasepro/cms-types`.
  * It lives here for the same reason {@link ADMIN_COLLECTION_KEYS} does: the
  * runtime consumers are core packages that the BaaS guard forbids from
- * importing `@rebasepro/admin-types`. Here it is the boot-time collection
+ * importing `@rebasepro/cms-types`. Here it is the boot-time collection
  * validator in `@rebasepro/server`, which has to tell "you left `readOnly` at
  * the top of the property, where nothing reads it" apart from "you invented a
  * key we have never heard of".
  *
- * `@rebasepro/admin-types` re-exports this and asserts it names only real
+ * `@rebasepro/cms-types` re-exports this and asserts it names only real
  * option keys.
  *
  * @group Models
@@ -65,7 +65,7 @@ export type AdminPropertyKey = typeof ADMIN_PROPERTY_KEYS[number];
  * in favour of the value the user changed away from.
  *
  * This lives here, next to the key lists, because it had two implementations —
- * `toAdminCollectionConfig` in `@rebasepro/admin-types` and `nestAdminKeys` in
+ * `toAdminCollectionConfig` in `@rebasepro/cms-types` and `nestAdminKeys` in
  * `@rebasepro/server`'s schema editor — that agreed on everything except that
  * precedence, which is the only part that decides whether a save is visible.
  *

package/dist/types/collections.d.ts

@@ -5,6 +5,7 @@ import type { EmailSendResult } from "../controllers/email.js";
 import type { Relation } from "./relations.js";
 import type { SecurityRule } from "./security_rules.js";
 import type { SearchConfig } from "./search.js";
+import type { CollectionIndex } from "./indexes.js";
 /**
  * Base interface containing all driver-agnostic collection properties.
  * Use {@link PostgresCollectionConfig} or {@link FirebaseCollectionConfig} for
@@ -248,6 +249,23 @@ export interface PostgresCollectionConfig<M extends Record<string, unknown> = Re
      * @see SearchConfig
      */
     search?: SearchConfig;
+    /**
+     * Ordinary indexes on this collection's table.
+     *
+     * Collection-level, not per-property, because an index over two columns
+     * has no single property to hang on and a partial index has none at all —
+     * and because a second declaration site for the single-column case would
+     * put the same object in two places. An index's identity is a column list
+     * in an order; the single-column case is a degenerate one, not a special
+     * one.
+     *
+     * `VectorProperty.index` stays where it is: an ANN structure is a property
+     * of the column's type, not of a query.
+     *
+     * Postgres-only, like {@link SearchConfig}: refused on another engine
+     * rather than silently ignored.
+     */
+    indexes?: readonly CollectionIndex<Extract<keyof M, string>>[];
 }
 /**
  * A collection backed by Firebase / Firestore.
@@ -537,7 +555,7 @@ export interface AuthCollectionConfig {
      *
      * Set to `false` to disable, or pass a custom `EntityAction` to replace the UI.
      *
-     * The object form is an `EntityAction` from `@rebasepro/admin-types`, typed
+     * The object form is an `EntityAction` from `@rebasepro/cms-types`, typed
      * here as `object` because it is a React component with admin controllers in
      * its props and nothing on the server reads it — only whether the built-in
      * action is injected, which is the boolean.

package/dist/types/component_ref.d.ts

@@ -18,7 +18,7 @@
  *
  * The cost is that the return type is `unknown` rather than `ReactNode`, so a
  * function that returns something React could not render is accepted here.
- * `@rebasepro/admin-types` re-exports a `ReactComponentRef<P>` narrowed against
+ * `@rebasepro/cms-types` re-exports a `ReactComponentRef<P>` narrowed against
  * the real `React.ComponentType` for authoring and for the admin's internals,
  * which restores that check where it can be enforced.
  */

package/dist/types/index.d.ts

@@ -5,6 +5,7 @@ export * from "./properties.js";
 export * from "./admin_block.js";
 export * from "./collections.js";
 export * from "./search.js";
+export * from "./indexes.js";
 export * from "./relations.js";
 export * from "./policy.js";
 export * from "./rls-functions.js";

package/dist/types/indexes.d.ts

@@ -0,0 +1,179 @@
+/**
+ * Ordinary indexes, declared on a collection.
+ *
+ * Distinct from the two index-shaped things Rebase already builds. A `search`
+ * block builds a GIN index over a generated `tsvector`, and a `vector`
+ * property builds an ANN index over an embedding; both are structures the
+ * *feature* owns and neither is a query the developer wrote. This is the plain
+ * case — the btree behind a `where` clause — which had no declaration site at
+ * all, so the only way to have one was to write it by hand, where the next
+ * `rebase db push` planned it away.
+ *
+ * Every form here is core Postgres, deliberately. See {@link CollectionIndex}.
+ */
+/**
+ * A key column of an index whose access method has no ordering.
+ *
+ * `gin` and `brin` reject `ASC`/`DESC`/`NULLS` outright — Postgres answers
+ * `access method "gin" does not support ASC/DESC options` — so those methods
+ * take this narrower shape and the combination is unrepresentable rather than
+ * refused at build time.
+ */
+export interface UnorderedIndexKey<Keys extends string = string> {
+    /**
+     * A property key on this collection — never a column name.
+     *
+     * Which column that resolves to depends on the property, and the two
+     * differ in exactly the case an index is most often wanted for: a
+     * `belongsTo` relation compiles to its resolved `localKey`
+     * (`primaryCategory` → `primary_category_id`), not to the snake-cased
+     * property key. Anything else resolves through `columnName`, or the
+     * snake-case default when it declares none.
+     *
+     * Writing the column name here would work for most properties and quietly
+     * index nothing for a foreign key, which is the one people reach for.
+     */
+    prop: Keys | (string & {});
+}
+/**
+ * A key column of an index, when its order matters.
+ *
+ * `direction` and `nulls` earn their place only when a query's `ORDER BY`
+ * mixes directions. A lone `DESC` index is redundant with its `ASC` twin —
+ * Postgres scans a btree backwards just as fast — and declaring both is
+ * refused.
+ *
+ * Writing the Postgres default down explicitly is free: the derived name
+ * hashes the *effective* order, so adding `direction: "asc"` to a column that
+ * was already ascending is not a redefinition and rebuilds nothing.
+ */
+export interface IndexKey<Keys extends string = string> extends UnorderedIndexKey<Keys> {
+    direction?: "asc" | "desc";
+    /** Postgres's own default: `last` under `asc`, `first` under `desc`. */
+    nulls?: "first" | "last";
+}
+/**
+ * The rows a partial index covers.
+ *
+ * Structure rather than a SQL string, and this is the most load-bearing choice
+ * in the type. A string would be replayed verbatim by Atlas in a scratch
+ * database, would be the one place a caller reaches for an extension operator
+ * class or a subquery, could not be checked against the collection's
+ * properties, and could not be fingerprinted — its own text would have to go
+ * into the derived name, so reformatting it would rename a live index.
+ *
+ * Structure keeps every reference resolvable at build time, keeps literals
+ * going through the same quoting as the rest of the DDL, and keeps the name
+ * stable under any rendering change.
+ *
+ * There is no `or`. An OR predicate almost always means the index should not
+ * be partial at all; a caller who genuinely needs one declares two indexes.
+ */
+export type IndexPredicate<Keys extends string = string> = {
+    prop: Keys | (string & {});
+    op: "=";
+    value: string | number | boolean;
+} | {
+    prop: Keys | (string & {});
+    op: "!=" | "<" | "<=" | ">" | ">=";
+    value: string | number;
+} | {
+    prop: Keys | (string & {});
+    op: "is null" | "is not null";
+}
+/**
+ * A non-empty list, enforced in the type. An empty `IN` is a predicate
+ * matching nothing: it builds an index over zero rows and reports success,
+ * which is the silent-empty-condition shape this codebase has been bitten
+ * by before.
+ */
+ | {
+    prop: Keys | (string & {});
+    op: "in";
+    value: readonly [string | number, ...(string | number)[]];
+} | {
+    and: readonly [IndexPredicate<Keys>, ...IndexPredicate<Keys>[]];
+};
+interface BaseCollectionIndex<Keys extends string = string> {
+    /**
+     * The key columns, in order. This *is* the index's identity.
+     *
+     * Postgres can only use a leading subset, so `["ownerId", "createdAt"]`
+     * serves a query filtering on `ownerId`, and one filtering on both, and
+     * never one filtering on `createdAt` alone.
+     *
+     * Capped at five keys. Postgres allows thirty-two; past four the trailing
+     * columns are dead weight on every write, and the declaration is usually
+     * someone hoping a query gets faster by accretion. Payload columns that
+     * are not searched belong in `include`, which does not count against this.
+     */
+    on: readonly [Keys | IndexKey<Keys>, ...(Keys | IndexKey<Keys>)[]];
+    where?: IndexPredicate<Keys>;
+    /**
+     * Why this index exists, in one line. Required, and the only required
+     * field carrying no SQL.
+     *
+     * An index is the only thing a Rebase config can declare that costs money
+     * forever and whose benefit is invisible from the config. `rebase doctor`
+     * prints this beside "0 scans in 34 days, 412 MB", which is the one moment
+     * anyone is in a position to decide whether to delete it. Without it
+     * nobody can decide, so nobody does, and the table accretes indexes for
+     * the life of the product.
+     */
+    reason: string;
+}
+/**
+ * The default. Answers equality, range, `ORDER BY`, and uniqueness.
+ */
+export interface BtreeIndex<Keys extends string = string> extends BaseCollectionIndex<Keys> {
+    using?: "btree";
+    /**
+     * A composite uniqueness guarantee.
+     *
+     * Single-column uniqueness is `validation.unique` on the property, and
+     * declaring it here is refused rather than accepted as a synonym.
+     * `validation.unique` compiles to an inline `UNIQUE` whose backing index
+     * Postgres — not Rebase — names `<table>_<column>_key`. That name is in
+     * every deployed database, appears in no contract file, and no release can
+     * reach in and rename it.
+     */
+    unique?: boolean;
+    /**
+     * Payload columns carried in the leaf pages, for index-only scans. Not
+     * searchable and not ordered — they save a heap fetch at the cost of a
+     * fatter index. May not overlap `on`.
+     */
+    include?: readonly (Keys | (string & {}))[];
+}
+/**
+ * Containment over an `array` property or a JSONB `map`, using core operator
+ * classes only. Trigram and full-text search are `search:`, not this.
+ */
+export interface GinIndex<Keys extends string = string> extends BaseCollectionIndex<Keys> {
+    using: "gin";
+    on: readonly [Keys | UnorderedIndexKey<Keys>, ...(Keys | UnorderedIndexKey<Keys>)[]];
+}
+/**
+ * A naturally-ordered column on an append-only table — tiny, and useless the
+ * moment rows arrive out of order.
+ */
+export interface BrinIndex<Keys extends string = string> extends BaseCollectionIndex<Keys> {
+    using: "brin";
+    on: readonly [Keys | UnorderedIndexKey<Keys>, ...(Keys | UnorderedIndexKey<Keys>)[]];
+}
+/**
+ * An index on a collection's table.
+ *
+ * No `gist` and no `hash`: every interesting gist operator class ships in an
+ * extension, and hash indexes cannot be unique, composite, or ordered.
+ *
+ * The restriction to core Postgres is not conservatism, it is what keeps the
+ * whole model on the Atlas path. `rebase db push` materialises the desired
+ * state in a bare scratch database to plan against, `--exclude` does not
+ * suppress that replay, and `CREATE EXTENSION` cannot be put in the file — so
+ * an index needing `gin_trgm_ops` or `vector_cosine_ops` is refused at build
+ * time rather than emitted to fail later against a database the author has
+ * never heard of. Trigram search is `search:`; ANN is a `vector` property.
+ */
+export type CollectionIndex<Keys extends string = string> = BtreeIndex<Keys> | GinIndex<Keys> | BrinIndex<Keys>;
+export {};

package/dist/types/postgres_introspection.d.ts

@@ -9,7 +9,7 @@
  * They were spread across three places that had nothing to do with each other:
  * the `Table*` shapes sat in `websockets.ts`, next to the WebSocket frame types
  * they share no relationship with, and `PostgresPolicy` was declared twice — in
- * `@rebasepro/admin`'s RLS tab and again in `@rebasepro/studio`'s RLS editor,
+ * `@rebasepro/cms`'s RLS tab and again in `@rebasepro/studio`'s RLS editor,
  * the second with a comment explaining it was inline "to avoid depending on
  * @rebasepro/studio". Neither had to: this package is already a dependency of
  * both.

package/dist/types/properties.d.ts

@@ -625,7 +625,7 @@ export interface MapProperty extends BaseProperty {
      * rest of the map's presentation options: `sortProperties` in
      * `@rebasepro/common` reads it recursively, and `@rebasepro/firebase` calls
      * that when it builds collections. A core package cannot read the admin
-     * block — the field exists only once `@rebasepro/admin-types` is installed.
+     * block — the field exists only once `@rebasepro/cms-types` is installed.
      */
     propertiesOrder?: string[];
     /**

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@rebasepro/types",
   "type": "module",
-  "version": "0.16.1-canary.gef08a6e",
+  "version": "0.17.0",
   "description": "Rebase type definitions — shared interfaces and controller types",
   "funding": {
     "url": "https://github.com/sponsors/rebaseco"

package/src/types/admin_block.ts

@@ -3,7 +3,7 @@
  *
  * There is no *type* for the block in this package any more, and that is the point:
  * `admin` is not declared on `BaseCollectionConfig` or on any property here, so a
- * BaaS install cannot even write one. `@rebasepro/admin-types` adds the field back by
+ * BaaS install cannot even write one. `@rebasepro/cms-types` adds the field back by
  * declaration merging, which is why installing it is what makes the admin surface
  * appear.
  *
@@ -15,7 +15,7 @@
  * Every key that belongs inside a collection's `admin` block, as data.
  *
  * The type that describes these fields is `AdminCollectionOptions` in
- * `@rebasepro/admin-types`, and it is erased at build time — but three runtime
+ * `@rebasepro/cms-types`, and it is erased at build time — but three runtime
  * consumers need the list, and two of them are core:
  *
  * - `serializeCollections`, to drop the block from the contract
@@ -25,7 +25,7 @@
  *   backend ignores it and the panel never finds it again.
  * - the `collections-admin-block` codemod
  *
- * `@rebasepro/admin-types` re-exports this and asserts it names only real option
+ * `@rebasepro/cms-types` re-exports this and asserts it names only real option
  * keys; the count is pinned by a test there.
  *
  * @group Models
@@ -81,15 +81,15 @@ export type AdminCollectionKey = typeof ADMIN_COLLECTION_KEYS[number];
  * Every key that belongs inside a *property's* `admin` block, as data.
  *
  * The union of `AdminPropertyOptions` and its per-type extensions
- * (`AdminStringOptions`, `AdminArrayOptions`, …) in `@rebasepro/admin-types`.
+ * (`AdminStringOptions`, `AdminArrayOptions`, …) in `@rebasepro/cms-types`.
  * It lives here for the same reason {@link ADMIN_COLLECTION_KEYS} does: the
  * runtime consumers are core packages that the BaaS guard forbids from
- * importing `@rebasepro/admin-types`. Here it is the boot-time collection
+ * importing `@rebasepro/cms-types`. Here it is the boot-time collection
  * validator in `@rebasepro/server`, which has to tell "you left `readOnly` at
  * the top of the property, where nothing reads it" apart from "you invented a
  * key we have never heard of".
  *
- * `@rebasepro/admin-types` re-exports this and asserts it names only real
+ * `@rebasepro/cms-types` re-exports this and asserts it names only real
  * option keys.
  *
  * @group Models
@@ -138,7 +138,7 @@ export type AdminPropertyKey = typeof ADMIN_PROPERTY_KEYS[number];
  * in favour of the value the user changed away from.
  *
  * This lives here, next to the key lists, because it had two implementations —
- * `toAdminCollectionConfig` in `@rebasepro/admin-types` and `nestAdminKeys` in
+ * `toAdminCollectionConfig` in `@rebasepro/cms-types` and `nestAdminKeys` in
  * `@rebasepro/server`'s schema editor — that agreed on everything except that
  * precedence, which is the only part that decides whether a save is visible.
  *

package/src/types/collections.ts

@@ -9,6 +9,7 @@ import type { SecurityRule } from "./security_rules";
 import { getDataSourceCapabilities } from "./data_source";
 import type { WhereFilterOp, FilterValues, FilterPreset } from "./filter-operators";
 import type { SearchConfig } from "./search";
+import type { CollectionIndex } from "./indexes";
 
 /**
  * Base interface containing all driver-agnostic collection properties.
@@ -323,6 +324,24 @@ export interface PostgresCollectionConfig<M extends Record<string, unknown> = Re
      * @see SearchConfig
      */
     search?: SearchConfig;
+
+    /**
+     * Ordinary indexes on this collection's table.
+     *
+     * Collection-level, not per-property, because an index over two columns
+     * has no single property to hang on and a partial index has none at all —
+     * and because a second declaration site for the single-column case would
+     * put the same object in two places. An index's identity is a column list
+     * in an order; the single-column case is a degenerate one, not a special
+     * one.
+     *
+     * `VectorProperty.index` stays where it is: an ANN structure is a property
+     * of the column's type, not of a query.
+     *
+     * Postgres-only, like {@link SearchConfig}: refused on another engine
+     * rather than silently ignored.
+     */
+    indexes?: readonly CollectionIndex<Extract<keyof M, string>>[];
 }
 
 /**
@@ -681,7 +700,7 @@ export interface AuthCollectionConfig {
      *
      * Set to `false` to disable, or pass a custom `EntityAction` to replace the UI.
      *
-     * The object form is an `EntityAction` from `@rebasepro/admin-types`, typed
+     * The object form is an `EntityAction` from `@rebasepro/cms-types`, typed
      * here as `object` because it is a React component with admin controllers in
      * its props and nothing on the server reads it — only whether the built-in
      * action is injected, which is the boolean.

package/src/types/component_ref.ts

@@ -18,7 +18,7 @@
  *
  * The cost is that the return type is `unknown` rather than `ReactNode`, so a
  * function that returns something React could not render is accepted here.
- * `@rebasepro/admin-types` re-exports a `ReactComponentRef<P>` narrowed against
+ * `@rebasepro/cms-types` re-exports a `ReactComponentRef<P>` narrowed against
  * the real `React.ComponentType` for authoring and for the admin's internals,
  * which restores that check where it can be enforced.
  */

package/src/types/index.ts

@@ -6,6 +6,7 @@ export * from "./properties";
 export * from "./admin_block";
 export * from "./collections";
 export * from "./search";
+export * from "./indexes";
 export * from "./relations";
 export * from "./policy";
 export * from "./rls-functions";

package/src/types/indexes.ts

@@ -0,0 +1,180 @@
+/**
+ * Ordinary indexes, declared on a collection.
+ *
+ * Distinct from the two index-shaped things Rebase already builds. A `search`
+ * block builds a GIN index over a generated `tsvector`, and a `vector`
+ * property builds an ANN index over an embedding; both are structures the
+ * *feature* owns and neither is a query the developer wrote. This is the plain
+ * case — the btree behind a `where` clause — which had no declaration site at
+ * all, so the only way to have one was to write it by hand, where the next
+ * `rebase db push` planned it away.
+ *
+ * Every form here is core Postgres, deliberately. See {@link CollectionIndex}.
+ */
+
+/**
+ * A key column of an index whose access method has no ordering.
+ *
+ * `gin` and `brin` reject `ASC`/`DESC`/`NULLS` outright — Postgres answers
+ * `access method "gin" does not support ASC/DESC options` — so those methods
+ * take this narrower shape and the combination is unrepresentable rather than
+ * refused at build time.
+ */
+export interface UnorderedIndexKey<Keys extends string = string> {
+    /**
+     * A property key on this collection — never a column name.
+     *
+     * Which column that resolves to depends on the property, and the two
+     * differ in exactly the case an index is most often wanted for: a
+     * `belongsTo` relation compiles to its resolved `localKey`
+     * (`primaryCategory` → `primary_category_id`), not to the snake-cased
+     * property key. Anything else resolves through `columnName`, or the
+     * snake-case default when it declares none.
+     *
+     * Writing the column name here would work for most properties and quietly
+     * index nothing for a foreign key, which is the one people reach for.
+     */
+    prop: Keys | (string & {});
+}
+
+/**
+ * A key column of an index, when its order matters.
+ *
+ * `direction` and `nulls` earn their place only when a query's `ORDER BY`
+ * mixes directions. A lone `DESC` index is redundant with its `ASC` twin —
+ * Postgres scans a btree backwards just as fast — and declaring both is
+ * refused.
+ *
+ * Writing the Postgres default down explicitly is free: the derived name
+ * hashes the *effective* order, so adding `direction: "asc"` to a column that
+ * was already ascending is not a redefinition and rebuilds nothing.
+ */
+export interface IndexKey<Keys extends string = string> extends UnorderedIndexKey<Keys> {
+    direction?: "asc" | "desc";
+    /** Postgres's own default: `last` under `asc`, `first` under `desc`. */
+    nulls?: "first" | "last";
+}
+
+/**
+ * The rows a partial index covers.
+ *
+ * Structure rather than a SQL string, and this is the most load-bearing choice
+ * in the type. A string would be replayed verbatim by Atlas in a scratch
+ * database, would be the one place a caller reaches for an extension operator
+ * class or a subquery, could not be checked against the collection's
+ * properties, and could not be fingerprinted — its own text would have to go
+ * into the derived name, so reformatting it would rename a live index.
+ *
+ * Structure keeps every reference resolvable at build time, keeps literals
+ * going through the same quoting as the rest of the DDL, and keeps the name
+ * stable under any rendering change.
+ *
+ * There is no `or`. An OR predicate almost always means the index should not
+ * be partial at all; a caller who genuinely needs one declares two indexes.
+ */
+export type IndexPredicate<Keys extends string = string> =
+    | { prop: Keys | (string & {}); op: "="; value: string | number | boolean }
+    | { prop: Keys | (string & {}); op: "!=" | "<" | "<=" | ">" | ">="; value: string | number }
+    | { prop: Keys | (string & {}); op: "is null" | "is not null" }
+    /**
+     * A non-empty list, enforced in the type. An empty `IN` is a predicate
+     * matching nothing: it builds an index over zero rows and reports success,
+     * which is the silent-empty-condition shape this codebase has been bitten
+     * by before.
+     */
+    | { prop: Keys | (string & {}); op: "in"; value: readonly [string | number, ...(string | number)[]] }
+    | { and: readonly [IndexPredicate<Keys>, ...IndexPredicate<Keys>[]] };
+
+interface BaseCollectionIndex<Keys extends string = string> {
+    /**
+     * The key columns, in order. This *is* the index's identity.
+     *
+     * Postgres can only use a leading subset, so `["ownerId", "createdAt"]`
+     * serves a query filtering on `ownerId`, and one filtering on both, and
+     * never one filtering on `createdAt` alone.
+     *
+     * Capped at five keys. Postgres allows thirty-two; past four the trailing
+     * columns are dead weight on every write, and the declaration is usually
+     * someone hoping a query gets faster by accretion. Payload columns that
+     * are not searched belong in `include`, which does not count against this.
+     */
+    on: readonly [Keys | IndexKey<Keys>, ...(Keys | IndexKey<Keys>)[]];
+
+    where?: IndexPredicate<Keys>;
+
+    /**
+     * Why this index exists, in one line. Required, and the only required
+     * field carrying no SQL.
+     *
+     * An index is the only thing a Rebase config can declare that costs money
+     * forever and whose benefit is invisible from the config. `rebase doctor`
+     * prints this beside "0 scans in 34 days, 412 MB", which is the one moment
+     * anyone is in a position to decide whether to delete it. Without it
+     * nobody can decide, so nobody does, and the table accretes indexes for
+     * the life of the product.
+     */
+    reason: string;
+}
+
+/**
+ * The default. Answers equality, range, `ORDER BY`, and uniqueness.
+ */
+export interface BtreeIndex<Keys extends string = string> extends BaseCollectionIndex<Keys> {
+    using?: "btree";
+
+    /**
+     * A composite uniqueness guarantee.
+     *
+     * Single-column uniqueness is `validation.unique` on the property, and
+     * declaring it here is refused rather than accepted as a synonym.
+     * `validation.unique` compiles to an inline `UNIQUE` whose backing index
+     * Postgres — not Rebase — names `<table>_<column>_key`. That name is in
+     * every deployed database, appears in no contract file, and no release can
+     * reach in and rename it.
+     */
+    unique?: boolean;
+
+    /**
+     * Payload columns carried in the leaf pages, for index-only scans. Not
+     * searchable and not ordered — they save a heap fetch at the cost of a
+     * fatter index. May not overlap `on`.
+     */
+    include?: readonly (Keys | (string & {}))[];
+}
+
+/**
+ * Containment over an `array` property or a JSONB `map`, using core operator
+ * classes only. Trigram and full-text search are `search:`, not this.
+ */
+export interface GinIndex<Keys extends string = string> extends BaseCollectionIndex<Keys> {
+    using: "gin";
+    on: readonly [Keys | UnorderedIndexKey<Keys>, ...(Keys | UnorderedIndexKey<Keys>)[]];
+}
+
+/**
+ * A naturally-ordered column on an append-only table — tiny, and useless the
+ * moment rows arrive out of order.
+ */
+export interface BrinIndex<Keys extends string = string> extends BaseCollectionIndex<Keys> {
+    using: "brin";
+    on: readonly [Keys | UnorderedIndexKey<Keys>, ...(Keys | UnorderedIndexKey<Keys>)[]];
+}
+
+/**
+ * An index on a collection's table.
+ *
+ * No `gist` and no `hash`: every interesting gist operator class ships in an
+ * extension, and hash indexes cannot be unique, composite, or ordered.
+ *
+ * The restriction to core Postgres is not conservatism, it is what keeps the
+ * whole model on the Atlas path. `rebase db push` materialises the desired
+ * state in a bare scratch database to plan against, `--exclude` does not
+ * suppress that replay, and `CREATE EXTENSION` cannot be put in the file — so
+ * an index needing `gin_trgm_ops` or `vector_cosine_ops` is refused at build
+ * time rather than emitted to fail later against a database the author has
+ * never heard of. Trigram search is `search:`; ANN is a `vector` property.
+ */
+export type CollectionIndex<Keys extends string = string> =
+    | BtreeIndex<Keys>
+    | GinIndex<Keys>
+    | BrinIndex<Keys>;

package/src/types/postgres_introspection.ts

@@ -9,7 +9,7 @@
  * They were spread across three places that had nothing to do with each other:
  * the `Table*` shapes sat in `websockets.ts`, next to the WebSocket frame types
  * they share no relationship with, and `PostgresPolicy` was declared twice — in
- * `@rebasepro/admin`'s RLS tab and again in `@rebasepro/studio`'s RLS editor,
+ * `@rebasepro/cms`'s RLS tab and again in `@rebasepro/studio`'s RLS editor,
  * the second with a comment explaining it was inline "to avoid depending on
  * @rebasepro/studio". Neither had to: this package is already a dependency of
  * both.

package/src/types/properties.ts

@@ -712,7 +712,7 @@ export interface MapProperty extends BaseProperty {
      * rest of the map's presentation options: `sortProperties` in
      * `@rebasepro/common` reads it recursively, and `@rebasepro/firebase` calls
      * that when it builds collections. A core package cannot read the admin
-     * block — the field exists only once `@rebasepro/admin-types` is installed.
+     * block — the field exists only once `@rebasepro/cms-types` is installed.
      */
     propertiesOrder?: string[];
     /**