@facilis.dev/db 0.0.0-stage → 0.1.0

package/dist/schema-digest.d.ts

@@ -0,0 +1,97 @@
+import type { LiveSchemaSnapshot } from "./live-schema.js";
+import type { SchemaSnapshot } from "./snapshot.js";
+/**
+ * Canonical schema digest (docs/MIGRATION-PLAN.md §3.1, ADR D-159).
+ *
+ * The declared snapshot (`schemaSnapshot`, from `db/schema.ts`) and the live snapshot
+ * (`liveSchemaSnapshot`, from the Postgres catalogs) are projected onto one canonical
+ * form and hashed. A release artifact carries these digests as `fromDigest`/`toDigest`;
+ * the deploy uses them to check that the database is where the ledger says it is.
+ *
+ * Equality is fail-closed by construction: only the normalization described below is
+ * applied, everything else is a difference, so two different schemas cannot share a
+ * digest and a declared schema and the catalog it produces can.
+ *
+ * Digest scope v1 — the first segment of the digest string is the version:
+ * - table: name, `rlsEnabled`;
+ * - column: name, canonical SQL type (`canonicalColumnType`), `notNull`, canonical
+ *   default (`normalizeDefault`), `isPrimaryKey`;
+ * - policy: name, command upper-cased, restrictive flag, normalized USING and WITH CHECK
+ *   predicates (`normalizePolicySql`, shared with `diffSchemaSnapshots`).
+ *
+ * NOT in v1: foreign keys, indexes, unique/check constraints, enum types, scope columns,
+ * policy roles and the table's schema (framework tables live in the connection's current
+ * schema, i.e. `public`). They join the projection in v2, which changes the digest string
+ * prefix too, so a v1 digest is never compared with a v2 one.
+ *
+ * Framework bookkeeping tables never reach the projection: `liveSchemaSnapshot` filters
+ * the migration tracking table and reads only the current schema, and declared snapshots
+ * contain only project tables.
+ */
+export declare const SCHEMA_DIGEST_VERSION = 1;
+export interface DigestColumn {
+    readonly name: string;
+    /** `canonicalColumnType` spelling, e.g. `varchar(120)` or `timestamp with time zone`. */
+    readonly type: string;
+    readonly notNull: boolean;
+    /** `normalizeDefault` form; null means the column has no default. */
+    readonly default: string | null;
+    readonly isPrimaryKey: boolean;
+}
+export interface DigestPolicy {
+    readonly name: string;
+    /** SQL command, upper-cased: SELECT, INSERT, UPDATE, DELETE or ALL. */
+    readonly command: string;
+    /** RESTRICTIVE policies are AND-ed with the permissive set (D-008). */
+    readonly restrictive: boolean;
+    /** `normalizePolicySql` form; "" means the policy has no USING clause. */
+    readonly using: string;
+    /** `normalizePolicySql` form; "" means the policy has no WITH CHECK clause. */
+    readonly withCheck: string;
+}
+export interface DigestTable {
+    readonly name: string;
+    readonly rlsEnabled: boolean;
+    /** Sorted by name: `ordinal_position` is not part of the projection. */
+    readonly columns: readonly DigestColumn[];
+    /** Sorted by name. */
+    readonly policies: readonly DigestPolicy[];
+}
+export interface DigestSchema {
+    /** Projection version; part of the canonical JSON and of the digest string prefix. */
+    readonly digestVersion: number;
+    /** Sorted by name. */
+    readonly tables: readonly DigestTable[];
+}
+/** Project the declared (Drizzle) snapshot onto the canonical form. */
+export declare function declaredDigestSchema(snapshot: SchemaSnapshot): DigestSchema;
+/** Project the live (catalog) snapshot onto the same canonical form. */
+export declare function liveDigestSchema(snapshot: LiveSchemaSnapshot): DigestSchema;
+/**
+ * Canonical JSON: object keys sorted by code unit at every level, no whitespace, arrays in
+ * the order the projection produced (already sorted by their semantic key).
+ */
+export declare function canonicalDigestJson(schema: DigestSchema): string;
+/**
+ * sha256 of the canonical form, spelled `v<version>:sha256:<64 lowercase hex>`. The
+ * version prefix is part of the value on purpose: a digest computed under a different
+ * projection must not compare equal to this one.
+ */
+export declare function digestSchema(schema: DigestSchema): string;
+/**
+ * Normalize a column default onto the spelling both renderers agree on.
+ *
+ * Drizzle (`schemaSnapshot`) renders `'untitled'`, `false`, `now()`; `pg_get_expr`
+ * (`liveSchemaSnapshot`) renders `'untitled'::text`, `false`, `now()`. The differences
+ * are catalog-only noise: explicit casts, keyword case, redundant parentheses and
+ * whitespace. String-literal bodies are preserved verbatim, so `'Draft'` and `'draft'`
+ * stay different defaults (guessed normalization here would turn drift into a digest
+ * match). `CURRENT_TIMESTAMP` is folded onto `now` because Postgres stores both as
+ * `now()`.
+ *
+ * NOT normalized (documented v1 limitations): JSON object/array defaults (`{}` vs
+ * `'{}'::jsonb`), date values rendered as full ISO timestamps by Drizzle, array defaults
+ * and sequences of `serial` columns. P2's renderer owns producing catalog-compatible
+ * defaults; until then such a column is a digest difference, never a false match.
+ */
+export declare function normalizeDefault(value: string | null): string | null;

package/dist/schema-digest.js

@@ -0,0 +1,178 @@
+import { createHash } from "node:crypto";
+import { canonicalColumnType, isRestrictivePolicy, normalizePolicySql } from "./schema-drift.js";
+/**
+ * Canonical schema digest (docs/MIGRATION-PLAN.md §3.1, ADR D-159).
+ *
+ * The declared snapshot (`schemaSnapshot`, from `db/schema.ts`) and the live snapshot
+ * (`liveSchemaSnapshot`, from the Postgres catalogs) are projected onto one canonical
+ * form and hashed. A release artifact carries these digests as `fromDigest`/`toDigest`;
+ * the deploy uses them to check that the database is where the ledger says it is.
+ *
+ * Equality is fail-closed by construction: only the normalization described below is
+ * applied, everything else is a difference, so two different schemas cannot share a
+ * digest and a declared schema and the catalog it produces can.
+ *
+ * Digest scope v1 — the first segment of the digest string is the version:
+ * - table: name, `rlsEnabled`;
+ * - column: name, canonical SQL type (`canonicalColumnType`), `notNull`, canonical
+ *   default (`normalizeDefault`), `isPrimaryKey`;
+ * - policy: name, command upper-cased, restrictive flag, normalized USING and WITH CHECK
+ *   predicates (`normalizePolicySql`, shared with `diffSchemaSnapshots`).
+ *
+ * NOT in v1: foreign keys, indexes, unique/check constraints, enum types, scope columns,
+ * policy roles and the table's schema (framework tables live in the connection's current
+ * schema, i.e. `public`). They join the projection in v2, which changes the digest string
+ * prefix too, so a v1 digest is never compared with a v2 one.
+ *
+ * Framework bookkeeping tables never reach the projection: `liveSchemaSnapshot` filters
+ * the migration tracking table and reads only the current schema, and declared snapshots
+ * contain only project tables.
+ */
+export const SCHEMA_DIGEST_VERSION = 1;
+/** Project the declared (Drizzle) snapshot onto the canonical form. */
+export function declaredDigestSchema(snapshot) {
+    return {
+        digestVersion: SCHEMA_DIGEST_VERSION,
+        tables: snapshot.tables.map(declaredDigestTable).toSorted(byName),
+    };
+}
+/** Project the live (catalog) snapshot onto the same canonical form. */
+export function liveDigestSchema(snapshot) {
+    return {
+        digestVersion: SCHEMA_DIGEST_VERSION,
+        tables: snapshot.tables.map(liveDigestTable).toSorted(byName),
+    };
+}
+function declaredDigestTable(table) {
+    return {
+        name: table.name,
+        rlsEnabled: table.rlsEnabled,
+        columns: table.columns.map(declaredDigestColumn).toSorted(byName),
+        policies: table.policies.map(declaredDigestPolicy).toSorted(byName),
+    };
+}
+function liveDigestTable(table) {
+    return {
+        name: table.name,
+        rlsEnabled: table.rlsEnabled,
+        columns: table.columns.map(liveDigestColumn).toSorted(byName),
+        policies: table.policies.map(liveDigestPolicy).toSorted(byName),
+    };
+}
+function declaredDigestColumn(column) {
+    return {
+        name: column.name,
+        type: canonicalColumnType(column.type),
+        notNull: column.notNull,
+        default: normalizeDefault(column.default),
+        isPrimaryKey: column.isPrimaryKey,
+    };
+}
+function liveDigestColumn(column) {
+    return {
+        name: column.name,
+        type: canonicalColumnType(column.type),
+        notNull: column.notNull,
+        default: normalizeDefault(column.default),
+        isPrimaryKey: column.isPrimaryKey,
+    };
+}
+function declaredDigestPolicy(policy) {
+    return {
+        name: policy.name,
+        command: policy.command.toUpperCase(),
+        restrictive: isRestrictivePolicy(policy),
+        using: normalizePolicySql(policy.using),
+        withCheck: normalizePolicySql(policy.withCheck),
+    };
+}
+function liveDigestPolicy(policy) {
+    return {
+        name: policy.name,
+        command: policy.command.toUpperCase(),
+        restrictive: policy.restrictive,
+        using: normalizePolicySql(policy.using),
+        withCheck: normalizePolicySql(policy.withCheck),
+    };
+}
+/**
+ * Canonical JSON: object keys sorted by code unit at every level, no whitespace, arrays in
+ * the order the projection produced (already sorted by their semantic key).
+ */
+export function canonicalDigestJson(schema) {
+    return JSON.stringify(sortKeys(schema));
+}
+/**
+ * sha256 of the canonical form, spelled `v<version>:sha256:<64 lowercase hex>`. The
+ * version prefix is part of the value on purpose: a digest computed under a different
+ * projection must not compare equal to this one.
+ */
+export function digestSchema(schema) {
+    const hash = createHash("sha256").update(canonicalDigestJson(schema), "utf8").digest("hex");
+    return `v${schema.digestVersion}:sha256:${hash}`;
+}
+/**
+ * Code-unit comparison, not `localeCompare`: the digest must not depend on the ICU locale
+ * of the machine (or browser) that computes it.
+ */
+function compareText(left, right) {
+    if (left === right)
+        return 0;
+    return left < right ? -1 : 1;
+}
+function byName(left, right) {
+    return compareText(left.name, right.name);
+}
+function sortKeys(value) {
+    if (Array.isArray(value))
+        return value.map(sortKeys);
+    if (value !== null && typeof value === "object") {
+        const record = value;
+        return Object.fromEntries(Object.keys(record)
+            .toSorted(compareText)
+            .map((key) => [key, sortKeys(record[key])]));
+    }
+    return value;
+}
+/** A cast suffix: the column type is already part of the projection, so casts are noise. */
+const TYPE_CAST = /::[a-z][a-z_ ]*(?:\([0-9, ]*\))?(?:\[\])?/g;
+/** Single-quoted SQL literal, including the doubled-quote escape (`''`). */
+const STRING_LITERAL = /'(?:[^']|'')*'/g;
+/**
+ * Normalize a column default onto the spelling both renderers agree on.
+ *
+ * Drizzle (`schemaSnapshot`) renders `'untitled'`, `false`, `now()`; `pg_get_expr`
+ * (`liveSchemaSnapshot`) renders `'untitled'::text`, `false`, `now()`. The differences
+ * are catalog-only noise: explicit casts, keyword case, redundant parentheses and
+ * whitespace. String-literal bodies are preserved verbatim, so `'Draft'` and `'draft'`
+ * stay different defaults (guessed normalization here would turn drift into a digest
+ * match). `CURRENT_TIMESTAMP` is folded onto `now` because Postgres stores both as
+ * `now()`.
+ *
+ * NOT normalized (documented v1 limitations): JSON object/array defaults (`{}` vs
+ * `'{}'::jsonb`), date values rendered as full ISO timestamps by Drizzle, array defaults
+ * and sequences of `serial` columns. P2's renderer owns producing catalog-compatible
+ * defaults; until then such a column is a digest difference, never a false match.
+ */
+export function normalizeDefault(value) {
+    if (value === null)
+        return null;
+    let normalized = "";
+    let cursor = 0;
+    for (const match of value.matchAll(STRING_LITERAL)) {
+        const start = match.index ?? 0;
+        normalized += normalizeDefaultFragment(value.slice(cursor, start));
+        normalized += match[0];
+        cursor = start + match[0].length;
+    }
+    normalized += normalizeDefaultFragment(value.slice(cursor));
+    return normalized;
+}
+function normalizeDefaultFragment(fragment) {
+    return fragment
+        .toLowerCase()
+        .replace(TYPE_CAST, "")
+        .replace(/[()]/g, "")
+        .replace(/\bcurrent_timestamp\b/g, "now")
+        .replace(/\s+/g, "");
+}

package/dist/schema-drift.d.ts

@@ -0,0 +1,43 @@
+import type { LiveSchemaSnapshot } from "./live-schema.js";
+import type { PolicySnapshot, SchemaSnapshot } from "./snapshot.js";
+/**
+ * Code↔live schema diff (SPEC §11.1): a pure comparison of the snapshot derived from
+ * `db/schema.ts` with the one read from the running database. The Studio renders the
+ * resulting entries; the release preview (SPEC §11.3) can reuse the same typed drift.
+ */
+export type SchemaDriftKind = "table_missing" | "table_extra" | "column_missing" | "column_extra" | "column_type" | "column_nullability" | "rls_disabled" | "policy_missing" | "policy_extra" | "policy_changed";
+/**
+ * One difference. `expected` is the code-side value and `actual` the live one, so a
+ * consumer never has to guess which side of the diff it is looking at.
+ */
+export interface SchemaDrift {
+    kind: SchemaDriftKind;
+    table: string;
+    column?: string;
+    policy?: string;
+    expected?: string | null;
+    actual?: string | null;
+}
+/** Compare the code schema against the live one, deterministically ordered. */
+export declare function diffSchemaSnapshots(code: SchemaSnapshot, live: LiveSchemaSnapshot): SchemaDrift[];
+/**
+ * Code-side permissiveness: `PolicySnapshot` keeps only the rendered SQL, so the flag is
+ * read from the `AS RESTRICTIVE` clause the generator emits (D-008).
+ */
+export declare function isRestrictivePolicy(policy: PolicySnapshot): boolean;
+/**
+ * Postgres re-renders a policy's qualifier (adds parentheses and explicit `::text`
+ * casts), so raw SQL text never matches the Drizzle rendering even when the policies are
+ * identical. Compare a normalized form instead: lower-case, casts removed, quotes and
+ * parentheses dropped, whitespace collapsed away.
+ *
+ * Exported so the canonical schema digest (./schema-digest.ts) normalizes the same way
+ * instead of carrying a second copy.
+ */
+export declare function normalizePolicySql(value: string | null): string;
+/**
+ * Normalize both renderers onto one spelling: Drizzle says `varchar(120)`/`serial`,
+ * `format_type()` says `character varying(120)`/`integer`. Without this every column
+ * would look like drift.
+ */
+export declare function canonicalColumnType(value: string): string;

package/dist/schema-drift.js

@@ -0,0 +1,176 @@
+/** Compare the code schema against the live one, deterministically ordered. */
+export function diffSchemaSnapshots(code, live) {
+    const liveTables = new Map(live.tables.map((table) => [table.name, table]));
+    const codeTables = new Set(code.tables.map((table) => table.name));
+    const drift = [];
+    for (const table of code.tables) {
+        const liveTable = liveTables.get(table.name);
+        if (liveTable === undefined) {
+            drift.push({ kind: "table_missing", table: table.name });
+            continue;
+        }
+        diffColumns(table, liveTable, drift);
+        // A scoped table without RLS is the one combo the security invariants forbid
+        // (SPEC §8.4.5); RLS off on an unscoped table is reported by the panel badge only.
+        if (table.scopeColumn !== undefined && !liveTable.rlsEnabled) {
+            drift.push({ kind: "rls_disabled", table: table.name });
+        }
+        diffPolicies(table, liveTable, drift);
+    }
+    for (const table of live.tables) {
+        if (!codeTables.has(table.name))
+            drift.push({ kind: "table_extra", table: table.name });
+    }
+    return drift.toSorted(compareDrift);
+}
+function diffColumns(table, liveTable, drift) {
+    const liveColumns = new Map(liveTable.columns.map((column) => [column.name, column]));
+    for (const column of table.columns) {
+        const liveColumn = liveColumns.get(column.name);
+        if (liveColumn === undefined) {
+            drift.push({ kind: "column_missing", table: table.name, column: column.name });
+            continue;
+        }
+        const expectedType = canonicalColumnType(column.type);
+        const actualType = canonicalColumnType(liveColumn.type);
+        if (expectedType !== actualType) {
+            drift.push({
+                kind: "column_type",
+                table: table.name,
+                column: column.name,
+                expected: column.type,
+                actual: liveColumn.type,
+            });
+        }
+        if (column.notNull !== liveColumn.notNull) {
+            drift.push({
+                kind: "column_nullability",
+                table: table.name,
+                column: column.name,
+                expected: nullability(column.notNull),
+                actual: nullability(liveColumn.notNull),
+            });
+        }
+    }
+    const codeColumns = new Set(table.columns.map((column) => column.name));
+    for (const liveColumn of liveTable.columns) {
+        if (!codeColumns.has(liveColumn.name)) {
+            drift.push({ kind: "column_extra", table: table.name, column: liveColumn.name });
+        }
+    }
+}
+function diffPolicies(table, liveTable, drift) {
+    const livePolicies = new Map(liveTable.policies.map((policy) => [policy.name, policy]));
+    const codePolicies = new Set(table.policies.map((policy) => policy.name));
+    for (const policy of table.policies) {
+        const livePolicy = livePolicies.get(policy.name);
+        if (livePolicy === undefined) {
+            drift.push({ kind: "policy_missing", table: table.name, policy: policy.name });
+            continue;
+        }
+        const expected = policySignature(policy);
+        const actual = livePolicySignature(livePolicy);
+        if (expected !== actual) {
+            drift.push({
+                kind: "policy_changed",
+                table: table.name,
+                policy: policy.name,
+                expected,
+                actual,
+            });
+        }
+    }
+    for (const livePolicy of liveTable.policies) {
+        if (!codePolicies.has(livePolicy.name)) {
+            drift.push({ kind: "policy_extra", table: table.name, policy: livePolicy.name });
+        }
+    }
+}
+function nullability(notNull) {
+    return notNull ? "not null" : "nullable";
+}
+/** Code-side signature: command + permissiveness + rendered predicates. */
+function policySignature(policy) {
+    return [
+        policy.command.toUpperCase(),
+        isRestrictivePolicy(policy) ? "RESTRICTIVE" : "PERMISSIVE",
+        normalizePolicySql(policy.using),
+        normalizePolicySql(policy.withCheck),
+    ].join("|");
+}
+function livePolicySignature(policy) {
+    return [
+        policy.command.toUpperCase(),
+        policy.restrictive ? "RESTRICTIVE" : "PERMISSIVE",
+        normalizePolicySql(policy.using),
+        normalizePolicySql(policy.withCheck),
+    ].join("|");
+}
+/**
+ * Code-side permissiveness: `PolicySnapshot` keeps only the rendered SQL, so the flag is
+ * read from the `AS RESTRICTIVE` clause the generator emits (D-008).
+ */
+export function isRestrictivePolicy(policy) {
+    return /\bas\s+restrictive\b/i.test(policy.sql);
+}
+/**
+ * Postgres re-renders a policy's qualifier (adds parentheses and explicit `::text`
+ * casts), so raw SQL text never matches the Drizzle rendering even when the policies are
+ * identical. Compare a normalized form instead: lower-case, casts removed, quotes and
+ * parentheses dropped, whitespace collapsed away.
+ *
+ * Exported so the canonical schema digest (./schema-digest.ts) normalizes the same way
+ * instead of carrying a second copy.
+ */
+export function normalizePolicySql(value) {
+    if (value === null)
+        return "";
+    return value
+        .toLowerCase()
+        .replace(/::(?:uuid|text|jsonb|json|integer|int4|int8|bigint|boolean|bool|numeric|date|timestamptz|timestamp(?: with(?:out)? time zone)?)\b/g, "")
+        .replace(/["'()]/g, "")
+        .replace(/\s+/g, "");
+}
+const TYPE_ALIASES = {
+    serial: "integer",
+    serial4: "integer",
+    bigserial: "bigint",
+    serial8: "bigint",
+    smallserial: "smallint",
+    serial2: "smallint",
+    int: "integer",
+    int4: "integer",
+    int8: "bigint",
+    int2: "smallint",
+    bool: "boolean",
+    float4: "real",
+    float8: "double precision",
+    decimal: "numeric",
+    bpchar: "char",
+};
+/**
+ * Normalize both renderers onto one spelling: Drizzle says `varchar(120)`/`serial`,
+ * `format_type()` says `character varying(120)`/`integer`. Without this every column
+ * would look like drift.
+ */
+export function canonicalColumnType(value) {
+    const array = value.trim().endsWith("[]") ? "[]" : "";
+    const bare = array === "[]" ? value.trim().slice(0, -2) : value.trim();
+    const type = bare
+        .toLowerCase()
+        .replace(/\bcharacter varying\b/g, "varchar")
+        .replace(/\bcharacter\b/g, "char")
+        // Only the "without" suffix is catalog-only: Drizzle renders no-tz columns as plain
+        // `timestamp`/`time`, while the catalog spells the default timezone out. Keeping
+        // "with time zone" makes a tz change a real type drift.
+        .replace(/\s+without\s+time zone\b/g, "")
+        .replace(/\s*,\s*/g, ",");
+    const base = /^([a-z][a-z0-9_]*)/.exec(type)?.[1] ?? type;
+    return (TYPE_ALIASES[base] ?? base) + type.slice(base.length) + array;
+}
+function compareDrift(left, right) {
+    return (left.table.localeCompare(right.table) ||
+        (left.column ?? "").localeCompare(right.column ?? "") ||
+        (left.policy ?? "").localeCompare(right.policy ?? "") ||
+        left.kind.localeCompare(right.kind));
+}

package/dist/snapshot-readers.d.ts

@@ -0,0 +1,3 @@
+import { PgTable } from "drizzle-orm/pg-core";
+import type { TableSnapshot } from "./snapshot.js";
+export declare function snapshotTable(table: PgTable, enums: Map<string, string[]>): TableSnapshot;

package/dist/snapshot-readers.js

@@ -0,0 +1,182 @@
+import { is, SQL } from "drizzle-orm";
+import { getTableConfig, PgDialect, PgTable } from "drizzle-orm/pg-core";
+import { DEFAULT_OWNER_COLUMNS, DEFAULT_TENANT_COLUMNS } from "./client.js";
+import { policyCreateSql } from "./rls.js";
+/**
+ * The read half of the declared snapshot: Drizzle's table config -> the public shapes in
+ * ./snapshot.ts. Kept separate so the contract file stays a contract.
+ */
+const dialect = new PgDialect();
+export function snapshotTable(table, enums) {
+    const config = getTableConfig(table);
+    const primaryKey = primaryKeyColumns(config);
+    const columns = config.columns.map((column) => snapshotColumn(column, primaryKey, enums));
+    const unsupported = [];
+    const indexes = config.indexes.map((index) => snapshotIndex(index, config.name, unsupported));
+    const snapshot = {
+        name: config.name,
+        rlsEnabled: config.enableRLS,
+        columns,
+        foreignKeys: config.foreignKeys.map((foreignKey) => {
+            const reference = foreignKey.reference();
+            const onDelete = toForeignKeyAction(foreignKey.onDelete);
+            const onUpdate = toForeignKeyAction(foreignKey.onUpdate);
+            return {
+                columns: reference.columns.map((column) => column.name),
+                targetTable: getTableConfig(reference.foreignTable).name,
+                targetColumns: reference.foreignColumns.map((column) => column.name),
+                ...(onDelete === undefined ? {} : { onDelete }),
+                ...(onUpdate === undefined ? {} : { onUpdate }),
+            };
+        }),
+        policies: config.policies.map((policy) => ({
+            name: policy.name,
+            command: (policy.for ?? "all").toUpperCase(),
+            using: policy.using === undefined ? null : dialect.sqlToQuery(policy.using).sql,
+            withCheck: policy.withCheck === undefined ? null : dialect.sqlToQuery(policy.withCheck).sql,
+            sql: policyCreateSql(config.name, policy),
+        })),
+        primaryKey,
+        indexes,
+        checks: config.checks.map((check) => ({
+            name: check.name,
+            expression: dialect.sqlToQuery(check.value).sql,
+        })),
+        uniqueConstraints: config.uniqueConstraints.map((constraint) => ({
+            name: constraint.name ?? constraint.getName() ?? derivedUniqueName(config.name, constraint.columns),
+            columns: constraint.columns.map((column) => column.name),
+        })),
+    };
+    if (unsupported.length > 0)
+        snapshot.unsupported = unsupported;
+    const scopeColumn = detectScopeColumn(columns.map((column) => column.name));
+    if (scopeColumn !== undefined)
+        snapshot.scopeColumn = scopeColumn;
+    return snapshot;
+}
+/** The table's ordered PK: a table-level `primaryKey()` wins over column-level `.primaryKey()`. */
+function primaryKeyColumns(config) {
+    const tableLevel = config.primaryKeys[0];
+    if (tableLevel !== undefined)
+        return tableLevel.columns.map((column) => column.name);
+    return config.columns.filter((column) => column.primary).map((column) => column.name);
+}
+function snapshotColumn(column, primaryKey, enums) {
+    const snapshot = {
+        name: column.name,
+        type: column.getSQLType(),
+        notNull: column.notNull,
+        default: renderDefault(column.default),
+        // A composite (table-level) PK is declared on the table, not on its columns, so
+        // `column.primary` alone would disagree with the live catalog's indisprimary view.
+        isPrimaryKey: column.primary || primaryKey.includes(column.name),
+        isUnique: column.isUnique,
+    };
+    if (column.generatedIdentity !== undefined)
+        snapshot.identity = column.generatedIdentity.type;
+    if (column.generated !== undefined)
+        snapshot.generated = true;
+    const enumValues = column.enumValues;
+    if (enumValues !== undefined && enumValues.length > 0) {
+        recordEnum(enums, column.getSQLType().replace(/\[\]$/, ""), enumValues);
+    }
+    return snapshot;
+}
+/**
+ * Enum columns expose their values and their SQL type is the enum name (`mood` or
+ * `mood[]`). Two columns of the same enum must agree; a conflict is a broken declaration,
+ * so it throws instead of picking one.
+ */
+function recordEnum(enums, name, values) {
+    const existing = enums.get(name);
+    if (existing === undefined) {
+        enums.set(name, [...values]);
+        return;
+    }
+    if (existing.length !== values.length || existing.some((value, index) => value !== values[index])) {
+        throw new Error(`schema declares enum "${name}" with conflicting values: [${existing.join(", ")}] vs [${values.join(", ")}]`);
+    }
+}
+/**
+ * Indexes are only representable when they are a plain (optionally unique) b-tree over
+ * plain columns; every other shape is recorded as unsupported rather than misrendered.
+ */
+function snapshotIndex(index, tableName, unsupported) {
+    const config = index.config;
+    const columns = config.columns.map(indexColumnName);
+    const name = config.name ??
+        `${tableName}_${columns.filter((column) => column !== null).join("_")}_${config.unique ? "unique_" : ""}idx`;
+    const unsupportedShape = config.concurrently === true ||
+        config.only === true ||
+        config.where !== undefined ||
+        config.with !== undefined ||
+        (config.method !== undefined && config.method !== "btree") ||
+        columns.some((column) => column === null);
+    if (unsupportedShape) {
+        unsupported.push({ construct: "index", name });
+        return { name, columns: [], unique: config.unique };
+    }
+    return {
+        name,
+        columns: columns.filter((column) => column !== null),
+        unique: config.unique,
+    };
+}
+/** An index member that is not a plain ordered column returns null (unsupported shape). */
+function indexColumnName(column) {
+    if (typeof column !== "object" || column === null)
+        return null;
+    const candidate = column;
+    if (typeof candidate.name !== "string" || candidate.name.length === 0)
+        return null;
+    const extra = candidate.indexConfig;
+    // Drizzle fills the ascending defaults explicitly (`asc`/`last`); anything else is a
+    // shape the plain-column rendering below would silently drop.
+    const unsupported = extra !== undefined &&
+        ((extra.order !== undefined && extra.order !== "asc") ||
+            (extra.nulls !== undefined && extra.nulls !== "last") ||
+            extra.opClass !== undefined);
+    return unsupported ? null : candidate.name;
+}
+function derivedUniqueName(tableName, columns) {
+    return `${tableName}_${columns.map((column) => column.name).join("_")}_unique`;
+}
+/**
+ * SPEC §7.3 does not model SQL's SET DEFAULT, and "no action" is Postgres' default, so
+ * both are omitted rather than invented or echoed as noise.
+ */
+function toForeignKeyAction(action) {
+    switch (action) {
+        case "cascade":
+        case "restrict":
+        case "set null":
+            return action;
+        default:
+            return undefined;
+    }
+}
+function renderDefault(value) {
+    if (value === undefined)
+        return null;
+    if (is(value, SQL))
+        return dialect.sqlToQuery(value).sql;
+    if (typeof value === "string")
+        return quoteLiteral(value);
+    if (value instanceof Date)
+        return quoteLiteral(value.toISOString());
+    if (typeof value === "object" && value !== null)
+        return JSON.stringify(value);
+    return String(value);
+}
+function detectScopeColumn(columnNames) {
+    const tenant = columnNames.find((name) => DEFAULT_TENANT_COLUMNS.includes(name));
+    if (tenant !== undefined)
+        return { name: tenant, kind: "tenant" };
+    const owner = columnNames.find((name) => DEFAULT_OWNER_COLUMNS.includes(name));
+    if (owner !== undefined)
+        return { name: owner, kind: "owner" };
+    return undefined;
+}
+function quoteLiteral(value) {
+    return `'${value.replaceAll("'", "''")}'`;
+}