@rebasepro/server-postgres 0.12.0 → 0.12.1-canary.g009ed95

package/src/schema/introspect-db-structure.ts

@@ -0,0 +1,670 @@
+/**
+ * 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,
+    UniqueConstraintRow
+} from "./introspect-db-logic";
+import { mapPgType } from "./introspect-db-types";
+import type { CheckFactsByTable } from "./introspect-db-constraints";
+
+// ── Thresholds ────────────────────────────────────────────────────────
+
+/**
+ * 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 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 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 const KANBAN_MAX_VALUES = 12;
+
+/** Below this, a "board" is one or two columns — a filter, not a board. */
+export 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 const LIST_PROPERTIES_CAP = 6;
+
+// ── Roles ─────────────────────────────────────────────────────────────
+
+/**
+ * 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;
+}
+
+// ── Column-level structural predicates ────────────────────────────────
+
+/**
+ * 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 function isAutoTimestamp(column: TableColumn): boolean {
+    if (mapPgType(column.data_type) !== "date") return false;
+    const columnDefault = (column.column_default ?? "").toLowerCase();
+    if (!columnDefault) return false;
+    return /\b(now\(\)|current_timestamp|current_date|current_time|localtimestamp|localtime|transaction_timestamp\(\)|statement_timestamp\(\)|clock_timestamp\(\))/.test(columnDefault);
+}
+
+/** A key the database fills in: identity, serial, or a uuid-generating default. */
+export function isGeneratedKey(column: TableColumn): boolean {
+    if (column.is_identity === "YES") return true;
+    const columnDefault = (column.column_default ?? "").toLowerCase();
+    if (!columnDefault) return false;
+    return columnDefault.includes("nextval(") ||
+        columnDefault.includes("gen_random_uuid") ||
+        columnDefault.includes("uuid_generate");
+}
+
+/** A column Postgres computes; writing to it is an error. */
+export function isGeneratedColumn(column: TableColumn): boolean {
+    return column.is_generated === "ALWAYS";
+}
+
+/**
+ * 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 function isDerivedIndexColumn(column: TableColumn): boolean {
+    return column.udt_name === "tsvector" || column.udt_name === "tsquery";
+}
+
+/** Anything the user cannot meaningfully edit, whatever the reason. */
+export function isReadOnlyColumn(column: TableColumn): boolean {
+    return isGeneratedColumn(column) || isDerivedIndexColumn(column);
+}
+
+/**
+ * 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 function isBoundedString(column: TableColumn): boolean {
+    return mapPgType(column.data_type) === "string" &&
+        typeof column.character_maximum_length === "number" &&
+        column.character_maximum_length > 0;
+}
+
+/**
+ * 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 function isPayloadColumn(column: TableColumn, pks: string[], fkColumns: Set<string>): boolean {
+    if (pks.includes(column.column_name)) return false;
+    if (fkColumns.has(column.column_name)) return false;
+    if (isAutoTimestamp(column)) return false;
+    if (isGeneratedColumn(column)) return false;
+    return true;
+}
+
+// ── Foreign-key topology ──────────────────────────────────────────────
+
+/** 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 function groupForeignKeys(fks: ForeignKeyRow[]): ForeignKeyConstraint[] {
+    const byName = new Map<string, ForeignKeyConstraint>();
+    for (const fk of fks) {
+        // Rows from older callers carry no constraint name. Falling back to a
+        // per-column key treats each as its own single-column constraint, which
+        // is what the generator assumed before names were available.
+        const key = `${fk.table_name}::${fk.constraint_name ?? `${fk.column_name}->${fk.foreign_table_name}`}`;
+        const existing = byName.get(key);
+        if (existing) {
+            existing.columns.push(fk.column_name);
+            existing.foreignColumns.push(fk.foreign_column_name);
+            continue;
+        }
+        byName.set(key, {
+            name: fk.constraint_name ?? `${fk.table_name}_${fk.column_name}_fkey`,
+            table: fk.table_name,
+            columns: [fk.column_name],
+            foreignTable: fk.foreign_table_name,
+            foreignColumns: [fk.foreign_column_name],
+            deleteRule: fk.delete_rule
+        });
+    }
+    return Array.from(byName.values());
+}
+
+/** Column sets that are unique in a table: its primary key and every unique index. */
+function uniqueColumnSets(table: string, pks: string[], uniques: UniqueConstraintRow[]): string[][] {
+    const sets: string[][] = [];
+    if (pks.length > 0) sets.push(pks);
+    for (const unique of uniques) {
+        if (unique.table_name === table) sets.push(unique.column_names);
+    }
+    return sets;
+}
+
+function sameColumnSet(a: string[], b: string[]): boolean {
+    if (a.length !== b.length) return false;
+    const left = [...a].sort();
+    const right = [...b].sort();
+    return left.every((value, index) => value === right[index]);
+}
+
+// ── Classification ────────────────────────────────────────────────────
+
+/** Everything classification needs, assembled once per run. */
+interface AnalysisContext {
+    tables: Map<string, TableMeta>;
+    constraintsByTable: Map<string, ForeignKeyConstraint[]>;
+    inboundByTable: Map<string, ForeignKeyConstraint[]>;
+    uniques: UniqueConstraintRow[];
+    rowCounts: Record<string, number>;
+}
+
+function buildContext(metadata: SchemaMetadata, tables: Map<string, TableMeta>): AnalysisContext {
+    const allConstraints = groupForeignKeys(metadata.fks);
+    const constraintsByTable = new Map<string, ForeignKeyConstraint[]>();
+    const inboundByTable = new Map<string, ForeignKeyConstraint[]>();
+
+    for (const constraint of allConstraints) {
+        const outbound = constraintsByTable.get(constraint.table) ?? [];
+        outbound.push(constraint);
+        constraintsByTable.set(constraint.table, outbound);
+
+        const inbound = inboundByTable.get(constraint.foreignTable) ?? [];
+        inbound.push(constraint);
+        inboundByTable.set(constraint.foreignTable, inbound);
+    }
+
+    return {
+        tables,
+        constraintsByTable,
+        inboundByTable,
+        uniques: metadata.uniques,
+        rowCounts: metadata.rowCounts
+    };
+}
+
+/**
+ * A table that exists only to relate two others.
+ *
+ * Requires all of:
+ * - exactly two single-column foreign keys, to two distinct columns;
+ * - that pair is unique — it is the primary key, or a unique index covers it.
+ *   Without this the table can hold the same pair twice, which is a list of
+ *   events between two things, not a set membership;
+ * - no payload columns. A join row that carries a quantity is an association
+ *   with attributes, and collapsing it into a many-to-many silently drops those
+ *   attributes from the UI entirely;
+ * - nothing references it. A junction with its own dependents is something rows
+ *   point *at*, so it needs an identity of its own.
+ */
+function classifyJunction(table: string, context: AnalysisContext): TableClassification | null {
+    const meta = context.tables.get(table);
+    if (!meta) return null;
+
+    const constraints = context.constraintsByTable.get(table) ?? [];
+    if (constraints.length !== 2) return null;
+    if (constraints.some((c) => c.columns.length !== 1)) return null;
+
+    const [first, second] = constraints;
+    if (first.columns[0] === second.columns[0]) return null;
+
+    if ((context.inboundByTable.get(table) ?? []).length > 0) return null;
+
+    const pair = [first.columns[0], second.columns[0]];
+    const uniqueSets = uniqueColumnSets(table, meta.pks, context.uniques);
+    if (!uniqueSets.some((set) => sameColumnSet(set, pair))) return null;
+
+    const fkColumns = new Set(pair);
+    const payload = meta.columns.filter((column) => isPayloadColumn(column, meta.pks, fkColumns));
+    if (payload.length > 0) return null;
+
+    return {
+        table,
+        role: "junction",
+        reason: `only relates ${first.foreignTable} to ${second.foreignTable}: two foreign keys, unique together, no other data`,
+        junction: {
+            sourceTable: first.foreignTable,
+            sourceColumn: first.columns[0],
+            targetTable: second.foreignTable,
+            targetColumn: second.columns[0]
+        }
+    };
+}
+
+/**
+ * A small, referenced, self-contained code list.
+ *
+ * Requires: something references it, it references nothing, it carries few and
+ * simple payload columns, and it is small — where "small" is a real count, not
+ * an estimate. `reltuples` is -1 on any table that has never been analyzed,
+ * which is every table in a freshly restored dump, so a count that is merely
+ * absent must not read as "small".
+ */
+function classifyLookup(table: string, context: AnalysisContext): TableClassification | null {
+    if (!isLookupCandidate(table, context)) return null;
+
+    const rowCount = context.rowCounts[table];
+    if (typeof rowCount !== "number") return null;
+    // An empty table is not a code list — there is nothing to look up, and a
+    // schema-only restore would otherwise classify half the database this way.
+    if (rowCount < 1 || rowCount > LOOKUP_MAX_ROWS) return null;
+
+    const referencedBy = (context.inboundByTable.get(table) ?? []).length;
+    return {
+        table,
+        role: "lookup",
+        reason: `a ${rowCount}-row code list: referenced by ${referencedBy} table(s), references none, ${LOOKUP_MAX_PAYLOAD_COLUMNS} or fewer simple columns`
+    };
+}
+
+/**
+ * The structural half of the lookup test — everything except the row count.
+ *
+ * Separate because the count costs a query per table, and the caller only wants
+ * to pay it for tables that could possibly qualify.
+ */
+function isLookupCandidate(table: string, context: AnalysisContext): boolean {
+    const meta = context.tables.get(table);
+    if (!meta) return false;
+
+    if ((context.constraintsByTable.get(table) ?? []).length > 0) return false;
+    if ((context.inboundByTable.get(table) ?? []).length === 0) return false;
+
+    const payload = meta.columns.filter((column) => isPayloadColumn(column, meta.pks, new Set()));
+    if (payload.length > LOOKUP_MAX_PAYLOAD_COLUMNS) return false;
+
+    // A code list holds labels and flags. Documents, arrays, files and dates are
+    // content, and content means the rows are worth browsing in their own right.
+    //
+    // Strings are allowed whether or not they declare a length. Requiring
+    // `varchar(n)` looked like a way to say "label, not prose", and it is —
+    // except that a schema written any time recently uses `text` for everything,
+    // which is the advice Postgres itself gives. Modern pagila is all `text`, so
+    // that rule classified nothing at all on it.
+    return payload.every((column) => {
+        const type = mapPgType(column.data_type);
+        return type === "boolean" || type === "number" || type === "string";
+    });
+}
+
+/**
+ * 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 function lookupCandidates(metadata: SchemaMetadata, tables: Map<string, TableMeta>): string[] {
+    const context = buildContext(metadata, tables);
+    return Array.from(tables.keys()).filter((table) => isLookupCandidate(table, context));
+}
+
+/**
+ * Rows that belong to one parent row and are reached through it.
+ *
+ * Requires nothing to reference the table — a table others point at has an
+ * identity of its own and belongs in the navigation — and an *unambiguous*
+ * owner among its foreign keys. The evidence ladder runs strongest first; each
+ * rung is only taken when exactly one key satisfies it, so a table with two
+ * equally plausible parents stays an entity rather than being filed under a
+ * coin-flip.
+ */
+function classifyOwnedChild(table: string, context: AnalysisContext): TableClassification | null {
+    const meta = context.tables.get(table);
+    if (!meta) return null;
+
+    const constraints = context.constraintsByTable.get(table) ?? [];
+    if (constraints.length === 0) return null;
+    if ((context.inboundByTable.get(table) ?? []).length > 0) return null;
+
+    const owner = pickOwner(meta, constraints);
+    if (!owner) return null;
+
+    return {
+        table,
+        role: "owned-child",
+        reason: `belongs to ${owner.constraint.foreignTable} (${describeEvidence(owner.evidence)}) and nothing else references it`,
+        owner: {
+            table: owner.constraint.foreignTable,
+            column: owner.constraint.columns[0],
+            evidence: owner.evidence
+        }
+    };
+}
+
+function describeEvidence(evidence: OwnershipEvidence): string {
+    switch (evidence) {
+        case "cascade-delete": return "its only ON DELETE CASCADE foreign key";
+        case "identifying-key": return "its only foreign key inside the primary key";
+        case "sole-required-key": return "its only NOT NULL foreign key";
+        case "leading-key-column": return "the leading column of a primary key made only of foreign keys";
+    }
+}
+
+function pickOwner(
+    meta: TableMeta,
+    constraints: ForeignKeyConstraint[]
+): { constraint: ForeignKeyConstraint; evidence: OwnershipEvidence } | null {
+    const singleColumn = constraints.filter((c) => c.columns.length === 1);
+    if (singleColumn.length === 0) return null;
+
+    const nullability = new Map(meta.columns.map((c) => [c.column_name, c.is_nullable === "NO"]));
+
+    const cascading = singleColumn.filter((c) => c.deleteRule === "CASCADE");
+    if (cascading.length === 1) return { constraint: cascading[0], evidence: "cascade-delete" };
+
+    const identifying = singleColumn.filter((c) => meta.pks.includes(c.columns[0]));
+    if (identifying.length === 1) return { constraint: identifying[0], evidence: "identifying-key" };
+
+    const required = singleColumn.filter((c) => nullability.get(c.columns[0]) === true);
+    if (required.length === 1) return { constraint: required[0], evidence: "sole-required-key" };
+
+    // Last resort, and the only rung that leans on an ordering convention rather
+    // than a guarantee: in a table whose whole primary key is foreign keys, the
+    // first key column is the parent the rows are filed under.
+    // `northwind.order_details` is keyed `(order_id, product_id)` — the rows are
+    // lines of an order, which is exactly what that ordering says.
+    if (identifying.length === meta.pks.length && meta.pks.length > 1) {
+        const leading = identifying.find((c) => c.columns[0] === meta.pks[0]);
+        if (leading) return { constraint: leading, evidence: "leading-key-column" };
+    }
+
+    return null;
+}
+
+/**
+ * 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 function classifyTables(
+    metadata: SchemaMetadata,
+    tables: Map<string, TableMeta>
+): Map<string, TableClassification> {
+    const context = buildContext(metadata, tables);
+    const result = new Map<string, TableClassification>();
+
+    for (const table of tables.keys()) {
+        const classification =
+            classifyJunction(table, context) ??
+            classifyLookup(table, context) ??
+            classifyOwnedChild(table, context) ?? {
+                table,
+                role: "entity" as const,
+                reason: "no structural evidence that it is a join table, a code list, or owned by another table"
+            };
+        result.set(table, classification);
+    }
+
+    return result;
+}
+
+// ── Presentation derived from structure ───────────────────────────────
+
+/**
+ * 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 function buildColumnFacts(
+    meta: TableMeta,
+    metadata: SchemaMetadata,
+    enumMap: Map<string, string[]>,
+    checkFacts: CheckFactsByTable
+): Map<string, ColumnFacts> {
+    const fkColumns = new Set(meta.fks.map((fk) => fk.column_name));
+    const singleColumnUniques = new Set(
+        metadata.uniques
+            .filter((u) => u.table_name === meta.name && u.column_names.length === 1)
+            .map((u) => u.column_names[0])
+    );
+    const tableChecks = checkFacts.get(meta.name);
+
+    const facts = new Map<string, ColumnFacts>();
+    for (const column of meta.columns) {
+        const pgEnum = column.data_type === "USER-DEFINED" ? enumMap.get(column.udt_name) : undefined;
+        const checkEnum = tableChecks?.get(column.column_name)?.enumValues;
+        facts.set(column.column_name, {
+            column,
+            isPk: meta.pks.includes(column.column_name),
+            isFk: fkColumns.has(column.column_name),
+            isUniqueAlone: singleColumnUniques.has(column.column_name),
+            isAutoTimestamp: isAutoTimestamp(column),
+            isGenerated: isGeneratedColumn(column),
+            enumValues: pgEnum ?? checkEnum,
+            propType: pgEnum ? "string" : mapPgType(column.data_type)
+        });
+    }
+    return facts;
+}
+
+/**
+ * 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 function deriveTitleProperty(facts: Map<string, ColumnFacts>): string | undefined {
+    const candidates = Array.from(facts.values()).filter((f) =>
+        !f.isPk && !f.isFk && !f.isGenerated &&
+        f.propType === "string" &&
+        !f.enumValues &&
+        f.column.is_nullable === "NO"
+    );
+    if (candidates.length === 0) return undefined;
+
+    const unique = candidates.find((f) => f.isUniqueAlone);
+    if (unique) return unique.column.column_name;
+
+    const bounded = candidates.filter((f) => isBoundedString(f.column));
+    if (bounded.length > 0 && bounded.length < candidates.length) {
+        return bounded[0].column.column_name;
+    }
+
+    return candidates[0].column.column_name;
+}
+
+/**
+ * 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 function deriveKanbanProperty(facts: Map<string, ColumnFacts>): string | undefined {
+    for (const fact of facts.values()) {
+        if (fact.isPk || fact.isFk || fact.isGenerated) continue;
+        if (!fact.enumValues) continue;
+        if (fact.column.is_nullable !== "NO") continue;
+        if (fact.enumValues.length < KANBAN_MIN_VALUES || fact.enumValues.length > KANBAN_MAX_VALUES) continue;
+        return fact.column.column_name;
+    }
+    return 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 function deriveSort(facts: Map<string, ColumnFacts>): [string, "desc"] | undefined {
+    const stamps = Array.from(facts.values()).filter((f) => f.isAutoTimestamp);
+    if (stamps.length !== 1) return undefined;
+    return [stamps[0].column.column_name, "desc"];
+}
+
+/**
+ * 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 function deriveListProperties(propertiesOrder: string[], hidden: ReadonlySet<string> = new Set()): string[] | undefined {
+    const visible = propertiesOrder.filter((key) => !hidden.has(key));
+    if (visible.length <= LIST_PROPERTIES_CAP) return undefined;
+    return visible.slice(0, LIST_PROPERTIES_CAP);
+}