@rebasepro/server-postgres 0.12.1-canary.g4e7bcbf → 0.12.1-canary.g52d71ee

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.
  */

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

@@ -0,0 +1,119 @@
+/**
+ * The catalog queries introspection runs, and the shape they produce.
+ *
+ * These live apart from {@link ./introspect-db.ts} (the CLI entry point) on
+ * purpose: the fixture-capture script and the live e2e read a database through
+ * this module too, so what the tests see is what the CLI sees. A query that
+ * only exists inside the CLI's `main()` can only be tested by running the CLI.
+ *
+ * No side effects beyond `SELECT`. Introspection reads a database it does not
+ * own — it must never `ANALYZE`, create a temp table, or otherwise write.
+ */
+import type { SchemaMetadata } from "./introspect-db-logic";
+/** The subset of `pg.Client` this module needs, so tests can pass a fake. */
+export interface QueryableClient {
+    query<R = Record<string, unknown>>(text: string, values?: unknown[]): Promise<{
+        rows: R[];
+    }>;
+}
+/**
+ * Base tables, excluding partitions.
+ *
+ * `relispartition` is the reason this reads `pg_class` rather than
+ * `information_schema.tables`, which reports every partition as a base table of
+ * its own. Pagila partitions `payment` by month; introspected through
+ * information_schema it yields `payment` plus 26 near-identical
+ * `payment_p2022_*` collections, each with its own nav entry.
+ *
+ * `relkind = 'p'` (the partitioned parent) is included and `'r'` partitions are
+ * dropped, which is the right way round: the parent is the queryable table.
+ */
+export declare const TABLES_QUERY = "\n    SELECT c.relname AS table_name,\n           c.relkind = 'p' AS is_partitioned\n    FROM pg_class c\n    JOIN pg_namespace n ON n.oid = c.relnamespace\n    WHERE n.nspname = $1\n      AND c.relkind IN ('r', 'p')\n      AND NOT c.relispartition\n      AND c.relname NOT LIKE 'drizzle_%'\n      AND c.relname NOT LIKE 'rebase_%'\n    ORDER BY c.relname\n";
+/**
+ * Columns, with the catalog facts that say a column is not the user's to edit.
+ *
+ * `is_generated`/`is_identity` are read for that reason: a generated column
+ * rejects any write, so a form that offers it is offering a field that always
+ * errors. `character_maximum_length` is the declared `varchar(n)` bound —
+ * already enforced by the database, and free to surface as validation.
+ */
+export declare const COLUMNS_QUERY = "\n    SELECT\n        c.table_name,\n        c.column_name,\n        c.data_type,\n        c.udt_name,\n        c.is_nullable,\n        c.column_default,\n        c.ordinal_position,\n        c.is_generated,\n        c.is_identity,\n        c.identity_generation,\n        c.character_maximum_length,\n        c.numeric_precision,\n        c.numeric_scale,\n        (SELECT a.atttypmod FROM pg_attribute a\n         JOIN pg_class pc ON a.attrelid = pc.oid\n         WHERE pc.relname = c.table_name\n           AND a.attname = c.column_name\n           AND pc.relnamespace = (SELECT oid FROM pg_namespace WHERE nspname = c.table_schema)) as atttypmod\n    FROM information_schema.columns c\n    WHERE c.table_schema = $1\n    ORDER BY c.table_name, c.ordinal_position\n";
+export declare const ENUMS_QUERY = "\n    SELECT t.typname AS enum_name,\n           e.enumlabel AS enum_value,\n           e.enumsortorder AS sort_order\n    FROM pg_type t\n    JOIN pg_enum e ON t.oid = e.enumtypid\n    JOIN pg_namespace n ON t.typnamespace = n.oid\n    WHERE n.nspname = $1\n    ORDER BY t.typname, e.enumsortorder\n";
+/**
+ * Primary key columns, in key order.
+ *
+ * `ORDER BY k.ord` matters for composite keys: the position of a column inside
+ * the key is what tells a two-column PK made of two foreign keys apart from an
+ * ordinary composite key, and `= ANY(i.indkey)` (the shape this replaced)
+ * returns catalog order instead.
+ */
+export declare const PRIMARY_KEYS_QUERY = "\n    SELECT t.relname AS table_name,\n           a.attname AS column_name\n    FROM pg_index i\n    JOIN pg_class t ON t.oid = i.indrelid\n    JOIN pg_namespace n ON n.oid = t.relnamespace\n    CROSS JOIN LATERAL unnest(i.indkey) WITH ORDINALITY AS k(attnum, ord)\n    JOIN pg_attribute a ON a.attrelid = i.indrelid AND a.attnum = k.attnum\n    WHERE i.indisprimary AND n.nspname = $1\n    ORDER BY t.relname, k.ord\n";
+/**
+ * Foreign keys, one row per referencing column, with the delete rule.
+ *
+ * Read from `pg_constraint` rather than through
+ * `information_schema.constraint_column_usage`, which does not preserve the
+ * pairing on a composite foreign key: it reports the cross product of the
+ * constraint's columns, so a two-column FK comes back as four rows, two of them
+ * pairing the wrong columns. `unnest(...) WITH ORDINALITY` on both sides joined
+ * on the ordinal keeps each referencing column with the column it references.
+ *
+ * `confdeltype` is carried because `ON DELETE CASCADE` is the schema author
+ * saying, in the database, that the child cannot outlive the parent — the one
+ * unambiguous declaration of ownership a schema contains.
+ *
+ * Constraints declared on a *partition* are attributed to the partition root,
+ * because that is the table this run generates a collection for. Pagila declares
+ * `payment`'s three foreign keys on each monthly partition and none on the
+ * parent, so reading `pg_constraint` at face value gives the `payment`
+ * collection no relations at all. `pick = 1` then keeps one row per logical key,
+ * preferring the root's own constraint when it has one, so a schema that
+ * declares the key on the parent *and* inherits it onto 26 partitions does not
+ * yield 27 copies of the same relation.
+ */
+export declare const FOREIGN_KEYS_QUERY = "\n    WITH fk AS (\n        SELECT con.oid,\n               con.conname,\n               con.conrelid,\n               con.confrelid,\n               con.conkey,\n               con.confkey,\n               con.confdeltype,\n               COALESCE(pg_partition_root(con.conrelid), con.conrelid) AS root_oid,\n               row_number() OVER (\n                   PARTITION BY COALESCE(pg_partition_root(con.conrelid), con.conrelid),\n                                con.confrelid, con.conkey, con.confkey\n                   ORDER BY (con.conrelid = COALESCE(pg_partition_root(con.conrelid), con.conrelid)) DESC,\n                            con.oid\n               ) AS pick\n        FROM pg_constraint con\n        JOIN pg_namespace n ON n.oid = con.connamespace\n        WHERE con.contype = 'f' AND n.nspname = $1\n    )\n    SELECT root.relname AS table_name,\n           sa.attname AS column_name,\n           tgt.relname AS foreign_table_name,\n           ta.attname AS foreign_column_name,\n           fk.conname AS constraint_name,\n           s.ord::int AS ordinal,\n           CASE fk.confdeltype\n               WHEN 'a' THEN 'NO ACTION'\n               WHEN 'r' THEN 'RESTRICT'\n               WHEN 'c' THEN 'CASCADE'\n               WHEN 'n' THEN 'SET NULL'\n               WHEN 'd' THEN 'SET DEFAULT'\n           END AS delete_rule\n    FROM fk\n    JOIN pg_class root ON root.oid = fk.root_oid\n    JOIN pg_class tgt ON tgt.oid = fk.confrelid\n    CROSS JOIN LATERAL unnest(fk.conkey) WITH ORDINALITY AS s(attnum, ord)\n    JOIN pg_attribute sa ON sa.attrelid = fk.conrelid AND sa.attnum = s.attnum\n    CROSS JOIN LATERAL unnest(fk.confkey) WITH ORDINALITY AS f(attnum, ord)\n    JOIN pg_attribute ta ON ta.attrelid = fk.confrelid AND ta.attnum = f.attnum\n    WHERE fk.pick = 1 AND s.ord = f.ord\n    ORDER BY root.relname, fk.conname, s.ord\n";
+/**
+ * Unique constraints and unique indexes, as ordered column lists.
+ *
+ * Indexes rather than constraints alone, because `CREATE UNIQUE INDEX` and
+ * `ADD CONSTRAINT ... UNIQUE` produce the same guarantee and schemas use both.
+ * Partial indexes (`indpred IS NOT NULL`) are excluded: they promise uniqueness
+ * only over the rows matching their predicate, which is not the promise a
+ * `validation: { unique: true }` field makes.
+ */
+export declare const UNIQUE_CONSTRAINTS_QUERY = "\n    SELECT t.relname AS table_name,\n           ic.relname AS constraint_name,\n           -- ::text, because the driver has no parser for an array of `name`\n           -- and hands back the raw `{a,b}` literal as a string. Every consumer\n           -- here indexes and compares it as an array, and a string of that\n           -- shape fails those silently rather than loudly.\n           array_agg(a.attname::text ORDER BY k.ord) AS column_names\n    FROM pg_index i\n    JOIN pg_class t ON t.oid = i.indrelid\n    JOIN pg_class ic ON ic.oid = i.indexrelid\n    JOIN pg_namespace n ON n.oid = t.relnamespace\n    CROSS JOIN LATERAL unnest(i.indkey) WITH ORDINALITY AS k(attnum, ord)\n    JOIN pg_attribute a ON a.attrelid = i.indrelid AND a.attnum = k.attnum\n    WHERE i.indisunique\n      AND NOT i.indisprimary\n      AND i.indpred IS NULL\n      AND n.nspname = $1\n      AND NOT t.relispartition\n    GROUP BY t.relname, ic.relname\n    ORDER BY t.relname, ic.relname\n";
+/**
+ * CHECK constraints, as the source text Postgres reproduces them from.
+ *
+ * `pg_get_constraintdef` output is normalized by the server — the parser in
+ * {@link ./introspect-db-constraints.ts} reads that normalized form, not
+ * whatever the author typed.
+ */
+export declare const CHECK_CONSTRAINTS_QUERY = "\n    SELECT DISTINCT\n           root.relname AS table_name,\n           con.conname AS constraint_name,\n           pg_get_constraintdef(con.oid) AS definition\n    FROM pg_constraint con\n    JOIN pg_namespace n ON n.oid = con.connamespace\n    JOIN pg_class root ON root.oid = COALESCE(pg_partition_root(con.conrelid), con.conrelid)\n    WHERE con.contype = 'c'\n      AND n.nspname = $1\n    ORDER BY root.relname, con.conname\n";
+/**
+ * `COMMENT ON TABLE` / `COMMENT ON COLUMN`, which is documentation the author
+ * already wrote and which nothing downstream has ever read.
+ */
+export declare const COMMENTS_QUERY = "\n    SELECT t.relname AS table_name,\n           a.attname AS column_name,\n           d.description AS comment\n    FROM pg_description d\n    JOIN pg_class t ON t.oid = d.objoid\n    JOIN pg_namespace n ON n.oid = t.relnamespace\n    LEFT JOIN pg_attribute a ON a.attrelid = t.oid AND a.attnum = d.objsubid\n    WHERE n.nspname = $1\n      AND t.relkind IN ('r', 'p')\n      AND (d.objsubid = 0 OR a.attname IS NOT NULL)\n    ORDER BY t.relname, d.objsubid\n";
+/**
+ * Counts a table's rows, stopping once the answer can only be "more than
+ * `limit`".
+ *
+ * Introspection asks this to tell a small reference table from a table that
+ * merely looks like one (see `classifyTables`). `reltuples` would answer for
+ * free but lies on a table that has never been analyzed — which is every table
+ * in a database restored from a dump, i.e. exactly the case introspection meets
+ * — and reports -1 there rather than an error, so the lie is silent.
+ *
+ * The subquery's LIMIT caps the work at `limit + 1` rows however large the
+ * table is, so this stays cheap on a table with a billion rows.
+ */
+export declare function countRowsUpTo(client: QueryableClient, schema: string, table: string, limit: number): Promise<number>;
+/**
+ * Reads everything the generator needs, in one pass.
+ *
+ * `rowCounts` is deliberately absent here: it costs a query per table and only
+ * a handful of tables can possibly need it. The caller fills it in for the
+ * candidates `lookupCandidates()` names.
+ */
+export declare function readSchemaMetadata(client: QueryableClient, schema: string): Promise<SchemaMetadata>;

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

@@ -0,0 +1,263 @@
+/**
+ * What a schema's *structure* says about the app on top of it.
+ *
+ * Introspection has always been a table mirror: one table in, one collection
+ * out, one nav entry each, every column a form field. A schema of thirty tables
+ * produces thirty sidebar entries, and a panel whose navigation is a list of
+ * table names reads as a database browser however good the fields are — which
+ * is the actual complaint about generated admin panels, and is structural, not
+ * cosmetic.
+ *
+ * Most of what separates the eight nouns a user navigates by from the thirty
+ * tables underneath them is written down in the schema already: which tables
+ * only exist to join two others, which are small referenced code lists, which
+ * rows cannot outlive a parent row. This module reads that.
+ *
+ * ## Structure only
+ *
+ * Nothing here looks at a column or table *name*. Name heuristics — `status`,
+ * `*_url`, `image`, `created_at` — are wrong exactly when a schema is not in
+ * English, or is domain-specific, or spells things differently, and they are
+ * wrong silently. Every rule below is a fact the database enforces: key
+ * composition, foreign-key direction and delete rule, uniqueness, nullability,
+ * declared type and length, generated-ness, row count.
+ *
+ * That constraint has a cost, and it is worth stating: a schema that declares
+ * nothing beyond `NOT NULL` gives this module very little to work with, and it
+ * returns `entity` for everything rather than guessing. Under-classifying is
+ * the intended failure mode. A table wrongly hidden from the navigation is a
+ * table the user cannot find; a table wrongly left in it is merely the status
+ * quo.
+ *
+ * Pure module: no I/O. Row counts come in on {@link SchemaMetadata.rowCounts},
+ * which the caller fills from {@link ./introspect-db-queries.countRowsUpTo} for
+ * the tables {@link lookupCandidates} names.
+ */
+import type { ForeignKeyRow, SchemaMetadata, TableColumn, TableMeta } from "./introspect-db-logic";
+import type { CheckFactsByTable } from "./introspect-db-constraints";
+/**
+ * The row count above which a referenced table is a real entity rather than a
+ * code list. Deliberately low: `pagila.category` has 16 rows and `language` 6,
+ * while `actor` has 200 and `country` 109 — the gap between "a fixed set
+ * somebody typed once" and "data the app accumulates" is wide, and picking a
+ * number in the middle of it costs nothing.
+ */
+export declare const LOOKUP_MAX_ROWS = 50;
+/**
+ * The most payload columns a code list may carry. A code list is an id, a
+ * label, and perhaps a sort key or a flag; past that it is a table with
+ * attributes, which is an entity.
+ */
+export declare const LOOKUP_MAX_PAYLOAD_COLUMNS = 3;
+/**
+ * The most enum values a board can usefully have as columns. A kanban with
+ * thirty columns is a horizontally scrolling table.
+ */
+export declare const KANBAN_MAX_VALUES = 12;
+/** Below this, a "board" is one or two columns — a filter, not a board. */
+export declare const KANBAN_MIN_VALUES = 2;
+/**
+ * How many columns a generated list view shows before it stops being readable.
+ * Only applied when a table has more properties than this; a six-column table
+ * gets no `listProperties` at all rather than a restatement of its own columns.
+ */
+export declare const LIST_PROPERTIES_CAP = 6;
+/**
+ * What a table *is*, structurally.
+ *
+ * - `entity` — a thing the app is about. Gets a collection and a nav entry.
+ * - `junction` — exists only to relate two other tables. Gets no collection at
+ *   all; it becomes a many-to-many relation on both sides.
+ * - `lookup` — a small, referenced, self-contained code list. Gets a collection,
+ *   grouped away from the entities rather than listed beside them.
+ * - `owned-child` — rows that belong to exactly one parent row and are reached
+ *   through it. Gets a collection (it is a real table with real rows, and the
+ *   API still serves it) but no nav entry: it already renders as a tab on its
+ *   parent.
+ */
+export type TableRole = "entity" | "junction" | "lookup" | "owned-child";
+/**
+ * Why a table was called someone's child, weakest last.
+ *
+ * Carried into the generated file as a comment. A reader who disagrees with the
+ * classification needs to see what it was based on to know which line to change.
+ */
+export type OwnershipEvidence = 
+/** The only foreign key declared `ON DELETE CASCADE`. */
+"cascade-delete"
+/** The only foreign key that is part of the table's primary key. */
+ | "identifying-key"
+/** The only foreign key that is `NOT NULL`. */
+ | "sole-required-key"
+/** First column of a composite primary key made entirely of foreign keys. */
+ | "leading-key-column";
+export interface JunctionShape {
+    sourceTable: string;
+    sourceColumn: string;
+    targetTable: string;
+    targetColumn: string;
+}
+export interface TableClassification {
+    table: string;
+    role: TableRole;
+    /** One line, in prose, for the generated file. */
+    reason: string;
+    /** Set when `role === "owned-child"`. */
+    owner?: {
+        table: string;
+        column: string;
+        evidence: OwnershipEvidence;
+    };
+    /** Set when `role === "junction"`. */
+    junction?: JunctionShape;
+}
+/**
+ * A timestamp the database maintains: a temporal column defaulting to the
+ * transaction clock.
+ *
+ * This is the structural stand-in for the `created_at`/`updated_at` name check.
+ * It is strictly better than the name: it catches `fecha_creacion` and
+ * `last_update` (pagila's spelling, which the name list misses), and it does not
+ * fire on a user-editable `created_at date` column that has no default and which
+ * the name check would wrongly make read-only.
+ */
+export declare function isAutoTimestamp(column: TableColumn): boolean;
+/** A key the database fills in: identity, serial, or a uuid-generating default. */
+export declare function isGeneratedKey(column: TableColumn): boolean;
+/** A column Postgres computes; writing to it is an error. */
+export declare function isGeneratedColumn(column: TableColumn): boolean;
+/**
+ * Types that exist to be searched or indexed, never to be typed into.
+ *
+ * A `tsvector` column is a derived search index — maintained by a trigger, a
+ * generated expression, or an application job — and its contents are lexeme
+ * positions, not text. Pagila's `film.fulltext` is one, and introspection used
+ * to emit it as an ordinary required string: a mandatory form field whose
+ * correct value no user can produce, on the sixth column of the list view.
+ */
+export declare function isDerivedIndexColumn(column: TableColumn): boolean;
+/** Anything the user cannot meaningfully edit, whatever the reason. */
+export declare function isReadOnlyColumn(column: TableColumn): boolean;
+/**
+ * A string column with a declared maximum length.
+ *
+ * `varchar(50)` and `text` are the same type to an application but not to the
+ * author: choosing a bound is a statement that the value is short and
+ * label-like, which is what makes this usable for picking a display column.
+ */
+export declare function isBoundedString(column: TableColumn): boolean;
+/**
+ * A column carrying data rather than structure: not a key, not a foreign key,
+ * not a database-maintained timestamp, not computed.
+ *
+ * The count of these is what tells a pure join table from an association that
+ * carries its own attributes — `northwind.order_details` has the key shape of a
+ * junction and three payload columns, so it is not one.
+ */
+export declare function isPayloadColumn(column: TableColumn, pks: string[], fkColumns: Set<string>): boolean;
+/** One foreign key, with its columns grouped back together. */
+export interface ForeignKeyConstraint {
+    name: string;
+    table: string;
+    columns: string[];
+    foreignTable: string;
+    foreignColumns: string[];
+    deleteRule?: string;
+}
+/**
+ * Groups per-column foreign key rows back into constraints.
+ *
+ * Rows arrive one per referencing column. A composite key looks exactly like two
+ * separate keys until they are grouped by constraint name, and the difference
+ * matters: two single-column keys to two tables can be a junction, one
+ * two-column key never is.
+ */
+export declare function groupForeignKeys(fks: ForeignKeyRow[]): ForeignKeyConstraint[];
+/**
+ * Names the tables whose classification depends on a row count.
+ *
+ * The caller counts these — and only these — before calling
+ * {@link classifyTables}. On a schema of any size this is a handful of tables,
+ * and the count itself is capped (see `countRowsUpTo`), so the whole extra cost
+ * is bounded regardless of how much data the database holds.
+ */
+export declare function lookupCandidates(metadata: SchemaMetadata, tables: Map<string, TableMeta>): string[];
+/**
+ * Classifies every table in the schema.
+ *
+ * Order matters: junction is the most specific and most consequential (the
+ * table disappears), so it is tested first; then lookup, which needs no
+ * ownership reasoning; then ownership. Anything unmatched is an entity, which
+ * is also what every rule falls back to when its evidence is ambiguous.
+ */
+export declare function classifyTables(metadata: SchemaMetadata, tables: Map<string, TableMeta>): Map<string, TableClassification>;
+/**
+ * The columns a property-level derivation needs, resolved once.
+ */
+export interface ColumnFacts {
+    column: TableColumn;
+    isPk: boolean;
+    isFk: boolean;
+    /** Covered by a single-column unique constraint or unique index. */
+    isUniqueAlone: boolean;
+    isAutoTimestamp: boolean;
+    isGenerated: boolean;
+    /** Allowed values, from a Postgres enum type or a readable CHECK. */
+    enumValues?: string[];
+    propType: string;
+}
+export declare function buildColumnFacts(meta: TableMeta, metadata: SchemaMetadata, enumMap: Map<string, string[]>, checkFacts: CheckFactsByTable): Map<string, ColumnFacts>;
+/**
+ * The column that identifies a row to a human.
+ *
+ * Structural, in three rungs, strongest first:
+ *
+ * 1. A single-column unique constraint on a required string. This is as close
+ *    as a schema comes to declaring "this is what a row is called": it is the
+ *    column a person looks a row up by, and the database guarantees it picks
+ *    out one row.
+ * 2. The first required string that declares a length, when the table also has
+ *    strings that do not. Choosing `varchar(n)` for one column and `text` for
+ *    another is the author distinguishing a label from prose.
+ * 3. The first required string in declaration order. Weak, but it is the same
+ *    rung the panel's own fallback stands on, and column order carries real
+ *    information — the identifying column of a table is written near the top of
+ *    it, in every schema, in every language.
+ *
+ * Deliberately not: a column called `name`, or `title`. That works on English
+ * schemas written by someone who read the same tutorial. This picks
+ * `film.title`, `actor.first_name` and `category.name` out of pagila without
+ * knowing what any of those words mean.
+ */
+export declare function deriveTitleProperty(facts: Map<string, ColumnFacts>): string | undefined;
+/**
+ * The enum column a board should have as its columns.
+ *
+ * A board needs a small, closed, always-present set of states. `NOT NULL` is
+ * required because a null has no column to sit in; the bounds keep out
+ * two-state flags (a filter, not a board) and long code lists (a scrolling
+ * table). The first qualifying column in declaration order wins, so the output
+ * is stable across runs.
+ */
+export declare function deriveKanbanProperty(facts: Map<string, ColumnFacts>): string | undefined;
+/**
+ * The column a list should be sorted by, newest first.
+ *
+ * Only when the table has exactly one database-maintained timestamp. With two —
+ * a created and an updated stamp — the two orderings differ and the schema does
+ * not say which the user means, so neither is chosen.
+ */
+export declare function deriveSort(facts: Map<string, ColumnFacts>): [string, "desc"] | undefined;
+/**
+ * The first `LIST_PROPERTIES_CAP` visible properties, or nothing.
+ *
+ * Returning nothing when the table is already narrow matters: `listProperties`
+ * that restates every column is config the reader has to check against the
+ * property list to discover it does nothing, and it silently stops new columns
+ * from appearing in the list view when someone adds one later.
+ *
+ * `hidden` names the properties already marked `hideFromCollection` — spending
+ * one of six columns on a value the list does not render is worse than not
+ * capping at all.
+ */
+export declare function deriveListProperties(propertiesOrder: string[], hidden?: ReadonlySet<string>): string[] | undefined;

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

@@ -0,0 +1,11 @@
+/**
+ * The PostgreSQL type → Rebase property type mapping.
+ *
+ * Split out of `introspect-db-logic` so that the structural analysis can use it
+ * without importing the generator, which imports the analysis. Re-exported from
+ * `introspect-db-logic` so existing callers keep their import path.
+ */
+/**
+ * Map a PostgreSQL data type to a Rebase property type.
+ */
+export declare function mapPgType(dataType: string): string;

package/dist/services/RelationService.d.ts

@@ -1,5 +1,5 @@
 import { DrizzleClient } from "../interfaces";
-import { CollectionConfig, FilterValues, ResolvedRelation, ResolvedManyToMany } from "@rebasepro/types";
+import { CollectionConfig, FilterValues, ResolvedRelation, ResolvedManyToMany, ResolvedHasMany, ResolvedHasOne } from "@rebasepro/types";
 import { type ResolvedVia } from "@rebasepro/types";
 import { PostgresCollectionRegistry } from "../collections/PostgresCollectionRegistry";
 import type { NestedPathHop } from "./nested-path";
@@ -56,6 +56,29 @@ export declare class RelationService {
      * hand a tenant's rows to its neighbour — say so instead.
      */
     private assertSingleKeyAddressable;
+    /**
+     * What the target's foreign key holds, for each of these parent rows.
+     *
+     * Ordinarily the parent's id, and then this is free. When the relation
+     * declares a `sourceKey` the two are different values, and the mapping
+     * between them lives in the source table — so it costs one SELECT, issued
+     * once for the whole batch rather than per parent.
+     *
+     * Both directions come back because both are needed and deriving one from
+     * the other by hand is how a batch loader ends up attributing a child to the
+     * wrong parent: reads translate id → key to build the WHERE, and then
+     * translate key → id to attribute each row that comes back.
+     */
+    /**
+     * The value a related row's foreign key must hold to belong to this parent.
+     *
+     * `undefined` when the parent's source key is null — which is not an error
+     * here, only in the callers that were about to write it. Exposed for
+     * {@link PersistService}, which stamps this onto a child created under a
+     * nested path and would otherwise write the id and lose the row.
+     */
+    parentKeyValue(parentCollection: CollectionConfig, relation: ResolvedHasOne | ResolvedHasMany, parentId: string | number, db?: DrizzleClient): Promise<string | number | undefined>;
+    private resolveSourceKeys;
     /**
      * Fetch rows related to a parent row through a specific relation
      */

package/dist/services/channel-bus/index.d.ts

@@ -15,7 +15,7 @@
  * `types/channel_bus.ts` for the contract such a package implements.
  */
 import { NodePgDatabase } from "drizzle-orm/node-postgres";
-import { type ChannelBus, type ChannelBusConfig, type ChannelBusSetting } from "@rebasepro/types";
+import { type ChannelBus, type ChannelBusSetting } from "@rebasepro/types";
 export * from "./ChannelBus";
 export { PostgresChannelBus, CHANNEL_BUS_NOTIFY_CHANNEL, PG_NOTIFY_MAX_PAYLOAD_BYTES, DEFAULT_BATCH_WINDOW_MS, parseChannelBusFrame, parseChannelBusPayload } from "./PostgresChannelBus";
 export interface ChannelBusDeps {
@@ -37,12 +37,6 @@ export interface ChannelBusDeps {
  * mean silently discarding the object the application handed us.
  */
 export declare function resolveChannelBusSetting(configured?: ChannelBusSetting): ChannelBusSetting;
-/**
- * @deprecated Use {@link resolveChannelBusSetting}, which also accepts a
- * supplied {@link ChannelBus} instance. Kept as a narrow alias so existing
- * config-only callers keep their exact types.
- */
-export declare function resolveChannelBusConfig(configured?: ChannelBusConfig): ChannelBusConfig;
 /**
  * Produce the bus a setting asks for.
  *