@rebasepro/server-postgres 0.12.1-canary.gf5f1d39 → 0.13.1-canary.g18cfeb7

package/dist/schema/auth-users-columns.d.ts

@@ -0,0 +1,97 @@
+/**
+ * The one description of what an auth user table's columns must be.
+ *
+ * ## Why this exists
+ *
+ * Three different code paths create `rebase.users`, and before this module they
+ * disagreed about it:
+ *
+ * | column           | `db push` (generator) | `ensureAuthTablesExist` | `ensureCollectionTables` |
+ * |------------------|-----------------------|-------------------------|--------------------------|
+ * | `email`          | `TEXT UNIQUE NOT NULL`| `TEXT NOT NULL` + CHECK | `TEXT` (nullable)        |
+ * | `roles`          | `TEXT[]`              | `NOT NULL DEFAULT '{}'` | nullable, no default     |
+ * | `email_verified` | `BOOLEAN`             | `NOT NULL DEFAULT FALSE`| nullable                 |
+ * | `created_at`     | `DEFAULT now()`       | `NOT NULL DEFAULT NOW()`| no default               |
+ *
+ * They are all `CREATE TABLE IF NOT EXISTS` / `ADD COLUMN IF NOT EXISTS`, so
+ * whichever ran first decided the table and the other two silently no-op'd.
+ * Boot order therefore chose the constraints: a managed deploy (collection
+ * tables first) got a users table whose `email` was nullable and whose
+ * `email_verified` had no default, while the same project pushed from a
+ * checkout got the strict one. In the same table, `is_anonymous` came out
+ * `NOT NULL DEFAULT false` — because *that* column existed in only one of the
+ * three lists, so its owner's definition won by default.
+ *
+ * A second consequence was drift in the other direction. The scaffold's
+ * `users.ts` describes 12 columns; auth needs 14. `db push` is declarative and
+ * builds its desired state from the collection alone, so the two columns only
+ * auth knows about (`is_anonymous`, `tokens_valid_after`) read as unmanaged
+ * drift, and a push run after the server had booted once planned to DROP them.
+ *
+ * Both problems are the same problem: no single place said what this table is.
+ * This is that place. Every creator asks here first and only then falls back to
+ * the collection's own property definitions, so a column auth owns has one
+ * definition regardless of who gets there first, and a column the developer
+ * added to their users collection still behaves like any other field.
+ *
+ * ## What belongs here
+ *
+ * Only columns the auth services read or write. A developer's own additions to
+ * their users collection (`bio`, `stripe_customer_id`) are ordinary columns and
+ * must NOT be listed — they are generated from the collection like every other
+ * field, and listing them here would freeze a user's schema.
+ *
+ * `id` is deliberately absent: its type comes from the collection's id property
+ * (uuid / increment / text) and each creator already derives it.
+ *
+ * Keep in step with {@link AUTH_SCHEMA_VERSION} when a change here makes an
+ * older runtime unable to work against a migrated table.
+ */
+/**
+ * A column auth owns.
+ *
+ * Structured rather than one SQL string because the same facts are needed in
+ * three grammars — a `CREATE TABLE` column list, an `ADD COLUMN IF NOT EXISTS`,
+ * and a pair of `ALTER COLUMN … SET DEFAULT` / `SET NOT NULL` reconciles for a
+ * table that already exists with the wrong shape. Parsing a string back apart
+ * for the third of those is how the copies drifted in the first place.
+ */
+export interface AuthUsersColumn {
+    /** Physical column name. */
+    column: string;
+    /** Postgres type. */
+    type: string;
+    /** Default expression, verbatim, or absent for no default. */
+    default?: string;
+    /** Whether the column is NOT NULL. */
+    notNull?: boolean;
+}
+/**
+ * `email` is NOT NULL on purpose, and the anonymous sign-in route depends on it
+ * — it synthesizes `anon_<32 hex>@anonymous.local` rather than inserting NULL.
+ * The 320-char bound (RFC 5321) is a CHECK rather than a `VARCHAR(n)`, added
+ * separately by `ensureAuthTablesExist` so it can be `NOT VALID` on an adopted
+ * table that already holds a longer row.
+ */
+export declare const AUTH_USERS_COLUMNS: readonly AuthUsersColumn[];
+/** Type + inline constraints, as they appear after the column name. */
+export declare function authUsersColumnSql(spec: AuthUsersColumn): string;
+/**
+ * The auth-owned definition for a physical column name, or `undefined` when
+ * auth does not own it.
+ *
+ * Callers pass the RESOLVED column name (after `columnName` mapping), because
+ * that is the only name the three creators agree on: the scaffold's users
+ * collection spells the property `displayName` and the column `display_name`.
+ */
+export declare function authUsersColumnDefinition(column: string): string | undefined;
+/**
+ * Whether a collection is an auth collection, i.e. whether the definitions in
+ * this module apply to its table at all.
+ *
+ * Duplicated in shape from `@rebasepro/common`'s policy defaults on purpose:
+ * that one takes a `CollectionConfig`, this one is called from DDL code paths
+ * that hold looser objects, and both spellings must accept `auth: true` as well
+ * as `auth: { enabled: true }`.
+ */
+export declare function isAuthCollection(collection: unknown): boolean;

package/dist/schema/ensure-collection-policies.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Applying a bundle's RLS policies to a database at boot, idempotently.
+ *
+ * ## Why this exists
+ *
+ * {@link ensureCollectionTables} creates the collection *tables* a managed
+ * runtime boots against, but a table with row-level security disabled and no
+ * policies is not servable: authenticated requests run as the restricted
+ * `rebase_user` role, so a read with no `SELECT` policy returns nothing (a
+ * public collection answered 401) and a write with no `INSERT`/`UPDATE` policy
+ * is denied. The policies live in the collections' `securityRules`; nothing at
+ * boot applied them. `rebase db push` does — but it drives Atlas against a
+ * local `DATABASE_URL`, and a managed tenant's database is reachable only from
+ * inside the cluster, by the runtime that is already connected to it. So the
+ * runtime is the only thing that *can* apply them, and this is where it does.
+ *
+ * ## Why this is safe to run on every boot
+ *
+ * Every statement is idempotent: `ENABLE ROW LEVEL SECURITY` is a no-op once
+ * enabled, and each policy is a `DROP POLICY IF EXISTS` immediately followed by
+ * a `CREATE POLICY`, so re-applying asserts exactly the declared state. It adds
+ * and replaces; it never drops data. (It does not *reconcile* — a policy a
+ * previous push left behind under an old name is not removed here; that stays a
+ * `db push` / `db migrate` concern, alongside destructive schema changes.)
+ *
+ * Unlike table creation, a failure here is not fatal: RLS stays enabled, so a
+ * table whose policies could not be applied fails **closed** (denies) rather
+ * than leaking rows. One collection's policy failing (e.g. a rule that
+ * references a table a real migration has not created yet) must not crash-loop
+ * the whole deployment and take the other collections' working routes down with
+ * it. Failures are reported loudly and per-table so the operator can see
+ * exactly which collection is not yet servable and why.
+ */
+import { type CollectionConfig } from "@rebasepro/types";
+import { type Queryable } from "./ensure-collection-tables";
+export interface PolicyEnsureResult {
+    /** `CREATE POLICY` statements that ran successfully. */
+    policiesApplied: number;
+    /** Tables that had RLS enabled. */
+    tablesSecured: number;
+    /** Declared tables absent from the database — left to a real migration. */
+    skipped: {
+        table: string;
+        reason: string;
+    }[];
+    /** Tables whose RLS could not be fully applied (fail closed). */
+    failures: {
+        table: string;
+        error: string;
+    }[];
+}
+/**
+ * Bring the declared collections' RLS policies up to date. Returns what it did.
+ *
+ * Only tables that already exist are touched: the boot-time table creator runs
+ * first, so anything still missing is a table this additive path is not allowed
+ * to create (a junction, or a relation left to a migration). Enabling RLS on a
+ * non-existent table would error, so those are recorded as skipped, not failed.
+ */
+export declare function ensureCollectionPolicies(client: Queryable, collections: CollectionConfig[], log?: (message: string) => void): Promise<PolicyEnsureResult>;

package/dist/schema/ensure-collection-tables.d.ts

@@ -46,9 +46,17 @@ export interface ExistingSchema {
     tables: Map<string, Set<string>>;
     /** `schema.typename` of every enum type that already exists. */
     enums: Set<string>;
+    /**
+     * `schema.table.constraint` of every constraint that already exists.
+     *
+     * Optional so a caller that only cares about tables can still build one by
+     * hand; absent is read as "none known", which at worst re-attempts a
+     * constraint that then fails harmlessly as a duplicate.
+     */
+    constraints?: Set<string>;
 }
 export interface EnsureAction {
-    kind: "create-enum" | "create-table" | "add-column";
+    kind: "create-enum" | "create-table" | "add-column" | "add-constraint" | "rename-column";
     /** Qualified target, for logging: `public.posts` or `public.posts.title`. */
     target: string;
     sql: string;
@@ -57,6 +65,40 @@ export interface EnsurePlan {
     actions: EnsureAction[];
     /** Every statement, in dependency order. Empty when the schema is current. */
     statements: string[];
+    /**
+     * Relation columns this plan is about to create where the table already
+     * carries the same column under its pre-singularization name.
+     *
+     * The reason this is reported rather than silently handled: the ensure is
+     * additive, so it would add `category_id` beside a populated
+     * `categorie_id` and the relation would then read the new, empty one. No
+     * statement fails, no table is missing, and the only symptom is relations
+     * resolving to nothing — which is indistinguishable from having no data.
+     */
+    legacyForeignKeys: LegacyForeignKey[];
+}
+/** A relation column whose old and new spellings both plausibly apply. */
+export interface LegacyForeignKey {
+    /** `schema.table`. */
+    table: string;
+    /** The name the current rule derives, and what this plan would create. */
+    expected: string;
+    /** The name the old rule derived, which the table already has. */
+    legacy: string;
+}
+export interface EnsureOutcome extends EnsurePlan {
+    /**
+     * Constraints that could not be added — always non-fatal.
+     *
+     * A foreign key can only fail on data that already violates it, and the
+     * column it would police exists either way, so the collection still serves.
+     * Refusing to boot over one would turn a pre-existing data problem into an
+     * outage. Reported loudly instead.
+     */
+    failures: {
+        target: string;
+        error: string;
+    }[];
 }
 /**
  * Decide what to add. Pure — the caller supplies what exists and runs the result.
@@ -65,7 +107,7 @@ export interface EnsurePlan {
  * that reference them, tables before the columns added to other tables (a new
  * table may be the target of a relation), and nothing is emitted twice.
  */
-export declare function planCollectionSchemaEnsure(collections: CollectionConfig[], existing: ExistingSchema): EnsurePlan;
+export declare function planCollectionSchemaEnsure(allCollections: CollectionConfig[], existing: ExistingSchema): EnsurePlan;
 /** Read what the database has, for the schemas the collections live in. */
 export declare function readExistingSchema(client: Queryable, schemas: string[]): Promise<ExistingSchema>;
 /**
@@ -76,4 +118,4 @@ export declare function readExistingSchema(client: Queryable, schemas: string[])
  * cannot be added, say) should not roll back the tables that were created fine.
  * The error is surfaced with the statement that caused it.
  */
-export declare function ensureCollectionTables(client: Queryable, collections: CollectionConfig[], log?: (message: string) => void): Promise<EnsurePlan>;
+export declare function ensureCollectionTables(client: Queryable, collections: CollectionConfig[], log?: (message: string) => void): Promise<EnsureOutcome>;

package/dist/schema/generate-drizzle-schema-logic.d.ts

@@ -1,2 +1,2 @@
 import { CollectionConfig } from "@rebasepro/types";
-export declare const generateSchema: (collections: CollectionConfig[], stripPolicies?: boolean) => Promise<string>;
+export declare const generateSchema: (allCollections: CollectionConfig[], stripPolicies?: boolean) => Promise<string>;

package/dist/schema/generate-postgres-ddl-logic.d.ts

@@ -1,8 +1,142 @@
-import { CollectionConfig, Property } from "@rebasepro/types";
+import { CollectionConfig, Property, SecurityRule } from "@rebasepro/types";
 export declare const resolveColumnName: (propName: string, prop?: Property | null) => string;
+export declare const getPrimaryKeyProp: (collection: CollectionConfig) => {
+    name: string;
+    type: "string" | "number";
+    isUuid: boolean;
+};
+export declare const isNumericId: (collection: CollectionConfig) => boolean;
+export declare const getPrimaryKeyName: (collection: CollectionConfig) => string;
 export declare const isIdProperty: (propName: string, prop: Property, collection: CollectionConfig) => boolean;
+type ResolveCollection = (slug: string) => CollectionConfig | undefined;
+/**
+ * The individual SQL statements a single security rule compiles to: a
+ * `DROP POLICY IF EXISTS` / `CREATE POLICY` pair per operation, each a complete
+ * statement (terminated by `;`, no trailing newline).
+ *
+ * This is the primitive the boot-time RLS applier runs one statement at a time
+ * (the runtime's DB handle speaks the extended query protocol, which forbids
+ * multiple commands in one execute), while `db push` writes the joined string.
+ */
+export declare const generatePolicyStatements: (collection: CollectionConfig, rule: SecurityRule, resolveCollection: ResolveCollection) => string[];
+/**
+ * Single-quote escaping for a SQL string literal (PostgreSQL doubles the
+ * quote). Enum labels come straight from user-authored collection config, so a
+ * label like `it's` closes the literal early and the whole generated file stops
+ * parsing at the `CREATE TYPE`. Lives here rather than next to its other caller
+ * because ensure-collection-tables already imports from this module — the
+ * reverse would be a cycle.
+ */
+export declare const quoteSqlLiteral: (value: string) => string;
 export declare const getSqlColumnType: (propName: string, prop: Property, collection: CollectionConfig, collections: CollectionConfig[]) => string;
-export declare const generatePostgresDdl: (collections: CollectionConfig[], options?: {
+export declare const generatePostgresDdl: (allCollections: CollectionConfig[], options?: {
     includePolicies?: boolean;
 }) => Promise<string>;
-export declare const generatePostgresPoliciesDdl: (collections: CollectionConfig[]) => string;
+/** The RLS statements one declared collection's table needs, ready to run. */
+/**
+ * A foreign key, as both its parts and the statement that creates it.
+ *
+ * `ALTER TABLE … ADD CONSTRAINT` has no `IF NOT EXISTS`, so a caller applying
+ * these has to skip by name — hence the name is a field and not only a substring
+ * of the SQL.
+ */
+export interface ForeignKeyPlan {
+    constraintName: string;
+    schema: string;
+    /** Bare table name, no schema prefix. */
+    table: string;
+    column: string;
+    targetSchema: string;
+    targetTable: string;
+    targetColumn: string;
+    sql: string;
+}
+/** A column a `relation` or `reference` property owns on its own table. */
+export interface RelationalColumnPlan {
+    schema: string;
+    /** Bare table name, no schema prefix. */
+    table: string;
+    column: string;
+    /** Postgres type, exactly as the DDL generator declares it. */
+    type: string;
+    /** Absent when the target collection is not part of this bundle. */
+    foreignKey?: ForeignKeyPlan;
+    /**
+     * What this column would have been called before `generateForeignKeyName`
+     * learned to singularize — set only when the two differ and the column name
+     * is the derived default rather than one the author wrote.
+     *
+     * Carried so the boot-time ensure can notice a database provisioned under
+     * the old rule. It is never used to name anything.
+     */
+    legacyColumn?: string;
+}
+/** The table behind a many-to-many `through` relation. */
+export interface JunctionTablePlan {
+    schema: string;
+    /** Bare table name, no schema prefix. */
+    table: string;
+    columns: {
+        name: string;
+        type: string;
+        legacyName?: string;
+    }[];
+    /** Both endpoint columns plus the composite primary key. */
+    createTable: string;
+    foreignKeys: ForeignKeyPlan[];
+}
+/**
+ * The FK columns the declared collections own — one entry per `relation`
+ * (`belongsTo` side) or `reference` property.
+ *
+ * Split out of {@link generatePostgresDdl} so the boot-time schema ensure can
+ * create the same columns with the same names, types and constraints. Before
+ * this it skipped them outright, which was survivable only because `db push`
+ * always followed; on a managed tenant nothing follows, so a table arrived
+ * without the column its own collection reads and wrote 400 on every insert.
+ *
+ * A relation whose target is not in the bundle yields no column at all (the
+ * generator returns early on an unresolvable target); a `reference` whose target
+ * is unknown yields the column without a constraint. Both mirror the generator
+ * exactly — a divergence here is a schema fork between boot and `db push`.
+ */
+export declare const planRelationalColumns: (allCollections: CollectionConfig[]) => RelationalColumnPlan[];
+/**
+ * The junction tables a bundle's many-to-many relations imply.
+ *
+ * Derived from {@link resolveJunctionSpecs}, the same source the junction RLS
+ * comes from, so a table created here always has policies planned for it — a
+ * junction with row-level security left off is readable and writable by every
+ * signed-in user, which is why the two must ship together.
+ */
+export declare const planJunctionTables: (allCollections: CollectionConfig[]) => JunctionTablePlan[];
+export interface CollectionPolicyPlan {
+    /** The table's schema (e.g. `public`, `rebase`). */
+    schema: string;
+    /** The bare table name, no schema prefix. */
+    table: string;
+    /** `schema.table` — matches the keys `readExistingSchema` returns. */
+    qualified: string;
+    /** `ALTER TABLE … ENABLE ROW LEVEL SECURITY;` — locked by default. */
+    enableRls: string;
+    /** `DROP POLICY IF EXISTS` / `CREATE POLICY` statements, in order. */
+    policyStatements: string[];
+}
+/**
+ * The per-table RLS plan for the *declared* collections, as executable
+ * statements — what the managed runtime applies at boot so a freshly
+ * provisioned tenant database serves data instead of 401ing every read.
+ *
+ * Mirrors {@link generatePostgresPoliciesDdl} exactly (same
+ * `generatePolicyStatements`, same enable-RLS, same effective rules, same
+ * derived junction rules), so boot and `db push` produce identical policies from
+ * identical collections.
+ *
+ * Junction tables are included, and have to be: boot creates them now
+ * ({@link planJunctionTables}), and a junction with RLS left off is readable and
+ * writable by every signed-in user. A junction whose table is still absent is
+ * skipped by the applier, not planned away here.
+ */
+export declare const planCollectionPolicies: (allCollections: CollectionConfig[]) => CollectionPolicyPlan[];
+export declare const generatePostgresPoliciesDdl: (allCollections: CollectionConfig[]) => string;
+export {};

package/dist/schema/generated-schema-staleness.d.ts

@@ -0,0 +1,39 @@
+import { CollectionConfig } from "@rebasepro/types";
+/**
+ * Notice a generated Drizzle schema that a *library upgrade* invalidated.
+ *
+ * `rebase dev` already watches `config/collections` and warns when a collection
+ * file changes. That covers drift the developer caused. It cannot cover this one,
+ * because nothing the developer owns changed: 0.13 derives `category_id` where
+ * 0.12 derived `categorie_id`, from the same unedited collection. The watcher
+ * never fires, and `backend/src/schema.generated.ts` quietly stops describing the
+ * schema the runtime expects.
+ *
+ * The consequence is not cosmetic. Boot-ensure renames the column in the
+ * database, then relation validation reads the stale module and refuses to
+ * start — on that boot and every boot after it, because the rename is already
+ * applied and will not be attempted again.
+ *
+ * Deliberately narrow: this answers "does the generated schema name a foreign key
+ * the way the previous rule did", not "is this file what we would generate now".
+ * The wide question would report every whitespace change in the generator as a
+ * fatal staleness, and a check that cries wolf gets switched off.
+ */
+/** One column the generated schema names under the pre-0.13 rule. */
+export interface LegacyForeignKeyName {
+    /** Table whose column declaration is stale. */
+    table: string;
+    /** The name the generated schema declares. */
+    legacy: string;
+    /** The name this release derives, and which the database now carries. */
+    current: string;
+    /** `<collection>.<relation>` that derives it, for the message. */
+    relation: string;
+}
+/**
+ * @param generatedSource contents of `backend/src/schema.generated.ts`
+ * @param collections     the project's collections, as this release reads them
+ */
+export declare function findLegacyForeignKeyNames(generatedSource: string, collections: CollectionConfig[]): LegacyForeignKeyName[];
+/** One-line summary for a log or a CLI notice. */
+export declare function describeLegacyForeignKeyNames(found: LegacyForeignKeyName[]): string;

package/dist/schema/introspect-db-constraints.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Reading validation rules out of CHECK constraints.
+ *
+ * A CHECK constraint is the schema author stating a rule the database already
+ * enforces. Introspection has never read them, so a generated form let the user
+ * type a value the database was always going to reject — the rule was written
+ * down, in the schema, and the UI asked anyway.
+ *
+ * Everything here parses the *normalized* text `pg_get_constraintdef` produces,
+ * not what the author typed: Postgres re-renders the expression from its parse
+ * tree, so `CHECK (price > 0)` on a `numeric` column always comes back as
+ * `CHECK ((price > (0)::numeric))`. That normalization is what makes a
+ * string-level parser tractable — the input is generated, and the shapes are
+ * few.
+ *
+ * Constraints this cannot read are skipped in full. A partially-understood
+ * constraint is worse than an unread one: it would produce validation that
+ * *narrows* differently from the database, so a value the UI accepts still
+ * fails on write, or — worse — a value the database allows is refused in the
+ * form with no way to see why.
+ *
+ * Pure module: no I/O, no logging.
+ */
+import type { CheckConstraintRow } from "./introspect-db-logic";
+/** What a table's CHECK constraints say about one column. */
+export interface ColumnCheckFacts {
+    /** Allowed values, from `IN (…)` / `= ANY (ARRAY[…])` / `= 'literal'`. */
+    enumValues?: string[];
+    /** `x >= n` */
+    min?: number;
+    /** `x <= n` */
+    max?: number;
+    /** `x > n` */
+    moreThan?: number;
+    /** `x < n` */
+    lessThan?: number;
+    /** `length(x) >= n` */
+    lengthMin?: number;
+    /** `length(x) <= n` */
+    lengthMax?: number;
+}
+/** Per-table, per-column facts. */
+export type CheckFactsByTable = Map<string, Map<string, ColumnCheckFacts>>;
+/** Removes one layer of wrapping parentheses, repeatedly, when balanced. */
+export declare function unwrapParens(input: string): string;
+/** Drops trailing `::type` casts, including array and quoted forms. */
+export declare function stripCasts(input: string): string;
+/**
+ * Reads one constraint definition into per-column facts.
+ *
+ * Returns an empty map for anything not understood — including a constraint
+ * that is understood but spans two columns (`start_date < end_date`), which no
+ * per-property validation rule can express.
+ */
+export declare function parseCheckDefinition(definition: string): Map<string, ColumnCheckFacts>;
+/** Merges every readable CHECK in the schema into per-table, per-column facts. */
+export declare function parseCheckConstraints(rows: CheckConstraintRow[]): CheckFactsByTable;

package/dist/schema/introspect-db-logic.d.ts

@@ -1,5 +1,10 @@
+import { mapPgType } from "./introspect-db-types";
+import type { CheckFactsByTable } from "./introspect-db-constraints";
+import type { TableClassification } from "./introspect-db-structure";
 export interface TableRow {
     table_name: string;
+    /** True for the parent of a partitioned table (`relkind = 'p'`). */
+    is_partitioned?: boolean;
 }
 export interface TableColumn {
     table_name: string;
@@ -9,6 +14,18 @@ export interface TableColumn {
     is_nullable: string;
     column_default: string | null;
     atttypmod: number | null;
+    /** 1-based position in the table, as declared. */
+    ordinal_position?: number;
+    /** `"ALWAYS"` for a generated column, `"NEVER"` otherwise. */
+    is_generated?: string;
+    /** `"YES"` for an identity column. */
+    is_identity?: string;
+    /** `"ALWAYS"` or `"BY DEFAULT"` on an identity column. */
+    identity_generation?: string | null;
+    /** The declared `varchar(n)` / `char(n)` bound, if any. */
+    character_maximum_length?: number | null;
+    numeric_precision?: number | null;
+    numeric_scale?: number | null;
 }
 export interface EnumValue {
     enum_name: string;
@@ -24,6 +41,53 @@ export interface ForeignKeyRow {
     column_name: string;
     foreign_table_name: string;
     foreign_column_name: string;
+    /** Name of the FK constraint — the only way to tell composite keys apart. */
+    constraint_name?: string;
+    /** 1-based position of this column within its constraint. */
+    ordinal?: number;
+    /** `"CASCADE"`, `"RESTRICT"`, `"SET NULL"`, `"SET DEFAULT"`, `"NO ACTION"`. */
+    delete_rule?: string;
+}
+/** A unique constraint or unique index, as an ordered column list. */
+export interface UniqueConstraintRow {
+    table_name: string;
+    constraint_name: string;
+    column_names: string[];
+}
+/** A CHECK constraint, as `pg_get_constraintdef` renders it. */
+export interface CheckConstraintRow {
+    table_name: string;
+    constraint_name: string;
+    definition: string;
+}
+/** A `COMMENT ON TABLE` (null `column_name`) or `COMMENT ON COLUMN`. */
+export interface CommentRow {
+    table_name: string;
+    column_name: string | null;
+    comment: string;
+}
+/**
+ * Everything one introspection run reads from the database.
+ *
+ * Passed around as one value so a new signal means a new field here rather than
+ * a new parameter on every function between the query and the generator — the
+ * shape `generateCollectionFile` had grown to seven positional arguments by.
+ */
+export interface SchemaMetadata {
+    schema: string;
+    tables: TableRow[];
+    columns: TableColumn[];
+    enumValues: EnumValue[];
+    pks: PrimaryKeyRow[];
+    fks: ForeignKeyRow[];
+    uniques: UniqueConstraintRow[];
+    checks: CheckConstraintRow[];
+    comments: CommentRow[];
+    /**
+     * Row counts for the tables that needed one, capped — see `countRowsUpTo`.
+     * Absent for every table introspection never had a reason to count.
+     */
+    rowCounts: Record<string, number>;
 }
 export interface TableMeta {
     name: string;
@@ -38,12 +102,23 @@ export declare function singularize(word: string): string;
  */
 export declare function toCollectionVarName(tableName: string): string;
 export declare function getIconForTable(tableName: string): string;
-/**
- * Map a PostgreSQL data type to a Rebase property type.
- */
-export declare function mapPgType(dataType: string): string;
+export { mapPgType };
 export declare function buildEnumMap(enumValues: EnumValue[]): Map<string, string[]>;
 export declare function buildTablesMap(tables: TableRow[], columns: TableColumn[], pks: PrimaryKeyRow[], fks: ForeignKeyRow[]): Map<string, TableMeta>;
+/**
+ * Join tables, identified by column name.
+ *
+ * Superseded for the CLI by `classifyTables` in `./introspect-db-structure`,
+ * which asks the database instead: two single-column keys, unique together, no
+ * payload column, nothing referencing the table. This rule folds away
+ * `northwind.order_details` — which has the key shape and carries unit price,
+ * quantity and discount — because it recognises `id`, `created_at` and
+ * `updated_at` by name and calls everything else a foreign key.
+ *
+ * Still used by `./introspect-runtime`, which builds collections in memory from
+ * a narrower set of catalog queries and has no unique-constraint or row-count
+ * data to reason with.
+ */
 export declare function identifyJoinTables(tablesMap: Map<string, TableMeta>): Set<string>;
 /**
  * Property metadata used to compute display priority.
@@ -93,11 +168,25 @@ export interface GeneratedFile {
     fileName: string;
     content: string;
 }
+/**
+ * The structural analysis a run can hand the generator.
+ *
+ * Optional in full, and the generator degrades to exactly its previous output
+ * without it. That is not politeness towards old callers: three existing test
+ * suites and the `rebase init` scaffold path build a `TableMeta` by hand and
+ * have no database to read constraints or row counts from, and they must keep
+ * producing a valid collection.
+ */
+export interface GenerationContext {
+    metadata?: SchemaMetadata;
+    classifications?: Map<string, TableClassification>;
+    checkFacts?: CheckFactsByTable;
+}
 /**
  * Generate the full TypeScript file content for a single collection.
  * Pure function — no I/O.
  */
-export declare function generateCollectionFile(tableName: string, meta: TableMeta, allFks: ForeignKeyRow[], joinTables: Set<string>, tablesMap: Map<string, TableMeta>, enumMap: Map<string, string[]>, sampleData?: Record<string, unknown>[]): string;
+export declare function generateCollectionFile(tableName: string, meta: TableMeta, allFks: ForeignKeyRow[], joinTables: Set<string>, tablesMap: Map<string, TableMeta>, enumMap: Map<string, string[]>, sampleData?: Record<string, unknown>[], context?: GenerationContext): string;
 /**
  * Generate the content for an index.ts file that re-exports all collections.
  */