@segmentstream/ontology 0.0.0-stage → 0.92.1

package/dist/migrate/plan.js

@@ -0,0 +1,1856 @@
+import { isValueMatched, } from "../manifest.js";
+import { FEDERATION_TABLES, FEDERATION_TABLES_DDL } from "../runtime/federation-tables.js";
+import { EMAIL_LINK_FENCE_SQL, SEGMENTSTREAM_LINK_FENCE_SQL, USER_IDENTITY_ENTITY_ID, USER_IDENTITY_SYNC_SQL, } from "../runtime/user-identity-sql.js";
+import { AGENT_TASKS_DDL, AGENT_TASKS_TABLE, SIGN_IN_EMAILS_DDL, SIGN_IN_EMAILS_TABLE, ATTACHMENTS_TABLE, ATTACHMENT_TABLES_DDL, BLOB_TABLES_DDL, WORKFLOW_STARTS_DDL, WORKFLOW_STARTS_TABLE, } from "../storage/tables.js";
+import { SNAKE_CASE_NAME, isSystemProperty, toSnakeCase } from "../names.js";
+import { NO_RETAINED_STORAGE, retainedEntityManifest, } from "./model.js";
+import { ACTION_ATTRIBUTION_TABLE, ACTION_ATTRIBUTION_DDL, AGENT_TABLES, AGENT_TABLES_DDL, CATALOG_TABLE_DDL, MAX_IDENTIFIER_LENGTH, OAUTH_TABLES, OAUTH_TABLES_DDL, USER_TABLE, addConstraintStatement, columnName, columnDefinition, constraintDefinition, createEnumStatement, createIndexStatement, createTableStatement, defaultExpression, entityStorage, historyActivityIndex, enumTypeName, isStoredProperty, fieldColumnName, joinTable, propertyCheck, blobForeignKey, propertyColumn, propertyEnum, quoteIdentifier, quoteLiteral, relationshipColumn, relationshipColumnName, RUNTIME_TABLES_DDL, relationshipForeignKey, SYSTEM_COLUMNS, storedEntity, tableName, } from "./storage.js";
+const NO_MEMBERS = { properties: new Set(), relationships: new Set() };
+const GLOBAL_KINDS = new Set(["table", "type", "index"]);
+function step(input) {
+    return {
+        kind: input.kind,
+        classification: input.classification,
+        transactional: input.transactional ?? true,
+        validatesData: input.validatesData ?? false,
+        description: input.description,
+        sql: [...input.sql],
+    };
+}
+function refusal(code, path, message) {
+    return { code, path, message };
+}
+function alterTable(table, action) {
+    return `ALTER TABLE ${quoteIdentifier(table)} ${action}`;
+}
+/**
+ * Plans the migration from the applied manifest, the storage the catalog keeps and the observed
+ * storage to the target. It is pure: the same inputs give the same plan. An unchanged manifest can
+ * still need runtime storage upgrades.
+ */
+export function planMigration(input) {
+    const { current, target } = input;
+    const allowDrops = input.options?.allowDrops === true;
+    const draft = {
+        before: [],
+        catalog: [],
+        drops: [],
+        renames: [],
+        indexDrops: [],
+        changes: [],
+        creates: [],
+        additions: [],
+        joins: [],
+        runtimeTables: [],
+        foreignKeys: [],
+        indexes: [],
+        refusals: [],
+        rebuilds: 0,
+    };
+    const header = current === undefined ? {} : { currentHash: current.hash };
+    const retainedCurrent = input.retained ?? NO_RETAINED_STORAGE;
+    const retainedField = (next) => input.retained === undefined ? {} : { retained: { current: retainedCurrent, target: next } };
+    validateManifest(target, draft.refusals);
+    if (draft.refusals.length > 0) {
+        return {
+            ...header,
+            target,
+            steps: [],
+            refusals: draft.refusals,
+            ...retainedField(retainedCurrent),
+        };
+    }
+    for (const next of target.entities) {
+        const previous = current?.entities.find((entity) => entity.id === next.id);
+        if (previous && (previous.source !== undefined) !== (next.source !== undefined)) {
+            draft.refusals.push(refusal("type-change", next.name, "Stored and warehouse-backed entities cannot be converted in place."));
+        }
+    }
+    // A list has no column, so storage is planned from the properties that have one.
+    const storedTargets = target.entities
+        .filter((entity) => entity.source === undefined)
+        .map(storedEntity);
+    checkStorageNames(storedTargets, draft.refusals);
+    const currentEntities = (current?.entities ?? [])
+        .filter((entity) => entity.source === undefined)
+        .map(storedEntity);
+    const records = reconcileRetained({
+        retained: retainedCurrent,
+        current: currentEntities,
+        existing: input.existingStorage,
+    });
+    const pairs = matchEntities({
+        currentEntities,
+        records,
+        targetEntities: storedTargets,
+        refusals: draft.refusals,
+    });
+    // @legacy ontology.pre-upgrade-database-tolerance
+    // Upgrade the applied names before renaming anything, so old SDK databases can rename safely.
+    for (const pair of pairs) {
+        const index = historyActivityIndex(pair.current.name);
+        if (input.existingHistoryActivityIndexes?.has(index.name) === false) {
+            draft.before.push(step({
+                kind: "addIndex",
+                classification: "additive",
+                transactional: false,
+                description: `Add index ${index.name} (${index.origin}).`,
+                sql: [
+                    `DROP INDEX CONCURRENTLY IF EXISTS ${quoteIdentifier(index.name)}`,
+                    createIndexStatement(index, { concurrently: true }),
+                ],
+            }));
+        }
+    }
+    const pairedIds = new Set(pairs.map((pair) => pair.target.id));
+    const addedEntities = storedTargets.filter((entity) => !pairedIds.has(entity.id));
+    const removedEntities = currentEntities
+        .filter((entity) => !pairedIds.has(entity.id))
+        .map((entity) => declaredModel(entity, records));
+    const keptEntities = records
+        .filter((record) => record.removed && !pairedIds.has(record.id))
+        .map(keptModel);
+    if (current === undefined) {
+        draft.catalog.push(step({
+            kind: "createCatalog",
+            classification: "additive",
+            description: "Create the _ontology catalog table.",
+            sql: [CATALOG_TABLE_DDL],
+        }));
+        draft.runtimeTables.push(step({
+            kind: "createCatalog",
+            classification: "additive",
+            description: "Create the runtime's role assignment, API key, OAuth and agent tables.",
+            sql: RUNTIME_TABLES_DDL,
+        }));
+        draft.runtimeTables.push(step({
+            kind: "createCatalog",
+            classification: "additive",
+            description: "Create the table of the workflow starts action triggers decide.",
+            sql: WORKFLOW_STARTS_DDL,
+        }));
+        draft.runtimeTables.push(step({
+            kind: "createCatalog",
+            classification: "additive",
+            description: "Create the table of the tasks workflows hand the app's agent.",
+            sql: AGENT_TASKS_DDL,
+        }));
+        draft.runtimeTables.push(step({
+            kind: "createCatalog",
+            classification: "additive",
+            description: "Create the table of the sign-in links actions send.",
+            sql: SIGN_IN_EMAILS_DDL,
+        }));
+    }
+    else {
+        const methods = input.target.signIn?.browser?.methods;
+        if (current?.signIn?.browser && (!methods || target.version < 13)) {
+            draft.refusals.push(refusal("invalid-manifest", "signIn.browser", "browser_auth_declaration_required_after_adoption"));
+        }
+        // @legacy ontology.pre-upgrade-database-tolerance
+        // A database an earlier SDK migrated lacks the tables added since; each set arrives on its own.
+        const lacks = (tables) => tables.some((table) => input.existingTables?.has(table) === false);
+        if (lacks([ACTION_ATTRIBUTION_TABLE])) {
+            draft.runtimeTables.push(step({
+                kind: "createCatalog",
+                classification: "additive",
+                description: "Create the runtime's verified pipeline action attribution table.",
+                sql: ACTION_ATTRIBUTION_DDL,
+            }));
+        }
+        if (lacks(FEDERATION_TABLES) ||
+            (input.existingTables !== undefined &&
+                (input.current?.version ?? 13) < 13 &&
+                target.version >= 13)) {
+            draft.runtimeTables.push(step({
+                kind: "createCatalog",
+                classification: "additive",
+                description: "Create workspace identity links and federation sessions.",
+                sql: FEDERATION_TABLES_DDL,
+            }));
+        }
+        if (lacks(OAUTH_TABLES)) {
+            draft.runtimeTables.push(step({
+                kind: "createCatalog",
+                classification: "additive",
+                description: "Create the runtime's OAuth tables, which connect agents to the MCP server.",
+                sql: OAUTH_TABLES_DDL,
+            }));
+        }
+        if (lacks([WORKFLOW_STARTS_TABLE, "_workflow_admission"])) {
+            draft.runtimeTables.push(step({
+                kind: "createCatalog",
+                classification: "additive",
+                description: "Create the table of the workflow starts action triggers decide.",
+                sql: WORKFLOW_STARTS_DDL,
+            }));
+        }
+        if (lacks([AGENT_TASKS_TABLE])) {
+            draft.runtimeTables.push(step({
+                kind: "createCatalog",
+                classification: "additive",
+                description: "Create the table of the tasks workflows hand the app's agent.",
+                sql: AGENT_TASKS_DDL,
+            }));
+        }
+        if (lacks([SIGN_IN_EMAILS_TABLE])) {
+            draft.runtimeTables.push(step({
+                kind: "createCatalog",
+                classification: "additive",
+                description: "Create the table of the sign-in links actions send.",
+                sql: SIGN_IN_EMAILS_DDL,
+            }));
+        }
+        if (lacks(AGENT_TABLES)) {
+            draft.runtimeTables.push(step({
+                kind: "createCatalog",
+                classification: "additive",
+                description: "Create the runtime's agent tables, which pair channel accounts with members.",
+                sql: AGENT_TABLES_DDL,
+            }));
+        }
+        planBrowserMethodFences(target, methods, draft);
+    }
+    const storesFiles = storedTargets.some((entity) => entity.properties.some((property) => property.type === "blob"));
+    if (storesFiles &&
+        !current?.entities.some((entity) => entity.properties.some((property) => property.type === "blob"))) {
+        draft.runtimeTables.push(step({
+            kind: "createCatalog",
+            classification: "additive",
+            description: "Create the ontology's file revision, upload and agent attachment tables.",
+            sql: [...BLOB_TABLES_DDL, ...ATTACHMENT_TABLES_DDL],
+        }));
+    }
+    else if (storesFiles && input.existingTables?.has(ATTACHMENTS_TABLE) === false) {
+        // File storage an earlier SDK created lacks the agent's attachments, or their newer sources.
+        draft.runtimeTables.push(step({
+            kind: "createCatalog",
+            classification: "additive",
+            description: "Create the agent's temporary attachment table beside the file tables, or widen the " +
+                "sources it accepts.",
+            sql: ATTACHMENT_TABLES_DDL,
+        }));
+    }
+    planDrops({ pairs, removedEntities, addedEntities, allowDrops, draft });
+    // Everything the database stores once the drops ran, under the applied names.
+    const model = [
+        ...pairs.map((pair) => pairModel(pair, allowDrops)),
+        ...keptEntities,
+        ...(allowDrops
+            ? []
+            : removedEntities.map((removed) => ({ ...removed, detached: true, removed: true }))),
+    ];
+    const renamed = planRenames({ pairs, model, draft });
+    // Everything the database stores before the plan, which steps outside the transaction meet.
+    const accounted = [
+        ...currentEntities.map((entity) => declaredModel(entity, records)),
+        ...records.filter((record) => record.removed).map(keptModel),
+    ];
+    const appliedNames = new Set(storageObjects(accounted)
+        .filter((object) => GLOBAL_KINDS.has(object.kind))
+        .map((object) => object.name));
+    for (const pair of pairs) {
+        planEntityChanges({ pair, renamed, appliedNames, allowDrops, draft });
+    }
+    planNewEntities({ addedEntities, pairs, draft });
+    planJoinTables({ pairs, addedEntities, draft });
+    // The storage after the plan: the target's, beside the storage that stays kept.
+    const final = [
+        ...storedTargets.map((entity) => finalModel(entity, renamed)),
+        ...renamed.filter((stored) => stored.removed),
+    ];
+    checkKeptNames(final, draft.refusals);
+    if (input.existingStorage !== undefined) {
+        checkUnrecordedNames({
+            accounted,
+            final,
+            existing: input.existingStorage,
+            refusals: draft.refusals,
+        });
+    }
+    return {
+        ...header,
+        target,
+        steps: [
+            ...draft.before,
+            ...draft.catalog,
+            ...draft.drops,
+            ...draft.renames,
+            ...draft.indexDrops,
+            ...draft.changes,
+            ...draft.creates,
+            ...draft.additions,
+            ...draft.joins,
+            ...draft.runtimeTables,
+            ...draft.foreignKeys,
+            ...draft.indexes,
+        ],
+        refusals: draft.refusals,
+        ...retainedField(retainedAfter(renamed)),
+    };
+}
+/**
+ * A deploy that drops a browser sign-in method is refused while an active member would lose access:
+ * every established email member needs a SegmentStream identity to drop email, and every member with
+ * a SegmentStream identity an email sign-in to drop SegmentStream. They follow the runtime tables,
+ * which an earlier SDK's database may lack. A target with `user_identity` reads it, once the step
+ * before copied what the legacy stores hold; another reads the legacy stores, as SDKs before it did.
+ */
+function planBrowserMethodFences(target, methods, draft) {
+    const fences = [
+        ...(methods && !methods.includes("email")
+            ? [
+                {
+                    description: "Verify every established email member has a SegmentStream identity.",
+                    identities: SEGMENTSTREAM_LINK_FENCE_SQL,
+                    legacy: `DO $$ BEGIN
+          IF to_regclass('_user_identities') IS NULL THEN
+            IF EXISTS (SELECT 1 FROM "user" u WHERE u.kind = 'member' AND u.active = true
+              AND u.identity_provider = 'neon-auth' AND u.identity_subject IS NOT NULL)
+              THEN RAISE EXCEPTION 'browser_auth_segmentstream_link_required'; END IF;
+          ELSIF EXISTS (SELECT 1 FROM "user" u WHERE u.kind = 'member' AND u.active = true
+            AND u.identity_provider = 'neon-auth' AND u.identity_subject IS NOT NULL
+            AND NOT EXISTS (SELECT 1 FROM "_user_identities" i WHERE i.user_id = u.id))
+            THEN RAISE EXCEPTION 'browser_auth_segmentstream_link_required';
+          END IF;
+        END $$`,
+                },
+            ]
+            : []),
+        ...(methods && !methods.includes("segmentstream")
+            ? [
+                {
+                    description: "Verify every admitted OIDC member retains email authentication.",
+                    identities: EMAIL_LINK_FENCE_SQL,
+                    legacy: `DO $$ BEGIN
+          IF to_regclass('_user_identities') IS NOT NULL THEN
+            IF EXISTS (SELECT 1 FROM "user" u WHERE u.kind = 'member' AND u.active = true
+              AND EXISTS (SELECT 1 FROM "_user_identities" i WHERE i.user_id = u.id)
+              AND (u.identity_provider IS DISTINCT FROM 'neon-auth' OR u.identity_subject IS NULL))
+            THEN RAISE EXCEPTION 'browser_auth_email_link_required'; END IF;
+          END IF;
+        END $$`,
+                },
+            ]
+            : []),
+    ];
+    if (fences.length === 0) {
+        return;
+    }
+    const identities = target.entities.some((entity) => entity.id === USER_IDENTITY_ENTITY_ID);
+    if (identities) {
+        draft.runtimeTables.push(step({
+            kind: "createCatalog",
+            classification: "additive",
+            description: "Copy members' sign-in identities the legacy identity stores hold.",
+            sql: [USER_IDENTITY_SYNC_SQL],
+        }));
+    }
+    for (const fence of fences) {
+        draft.runtimeTables.push(step({
+            kind: "createCatalog",
+            classification: "additive",
+            validatesData: true,
+            description: fence.description,
+            sql: [identities ? fence.identities : fence.legacy],
+        }));
+    }
+}
+// Validation -------------------------------------------------------------------------------------
+function isValidDefault(property) {
+    if (!("default" in property) || property.default === undefined) {
+        return true;
+    }
+    const value = property.default;
+    switch (property.type) {
+        case "json":
+            return true;
+        case "integer":
+            return typeof value === "number" && Number.isInteger(value);
+        case "number":
+            return typeof value === "number" && Number.isFinite(value);
+        case "boolean":
+            return typeof value === "boolean";
+        case "select":
+            return (property.options ?? []).some((option) => option.value === value);
+        default:
+            return typeof value === "string";
+    }
+}
+/**
+ * The manifest was validated by `check` and decoded with the manifest schema; this only guards what
+ * the storage mapping relies on, so that a hand-built or damaged manifest is refused instead of
+ * producing broken SQL.
+ */
+function validateManifest(manifest, refusals) {
+    const invalid = (path, message) => {
+        refusals.push(refusal("invalid-manifest", path, message));
+    };
+    const entitiesByName = new Map();
+    const ids = new Set();
+    for (const entity of manifest.entities) {
+        if (!SNAKE_CASE_NAME.test(entity.name)) {
+            invalid(entity.name, "entity names are lowercase snake_case.");
+        }
+        if (entitiesByName.has(entity.name)) {
+            invalid(entity.name, `two entities are named ${entity.name}.`);
+        }
+        else {
+            entitiesByName.set(entity.name, entity);
+        }
+        if (ids.has(entity.id)) {
+            invalid(entity.name, `two entities have the id ${entity.id}.`);
+        }
+        ids.add(entity.id);
+    }
+    if (!entitiesByName.has(USER_TABLE)) {
+        invalid(USER_TABLE, "the built-in user entity is missing; every ontology includes it.");
+    }
+    for (const entity of manifest.entities) {
+        validateEntity({ entity, entitiesByName, invalid });
+    }
+}
+function validateEntity(input) {
+    const { entity, entitiesByName, invalid } = input;
+    for (const property of entity.properties) {
+        const path = `${entity.name}.properties.${property.name}`;
+        const values = (property.options ?? []).map((option) => option.value);
+        if (!SNAKE_CASE_NAME.test(property.name) || isSystemProperty(property.name)) {
+            invalid(path, "property names are lowercase snake_case and cannot be system properties.");
+        }
+        if (property.type === "select" &&
+            (values.length === 0 || values.some((value) => !SNAKE_CASE_NAME.test(value)))) {
+            invalid(path, "a select property needs at least one non-empty option.");
+        }
+        if (new Set(values).size !== values.length) {
+            invalid(path, "an option value is listed twice.");
+        }
+        if (!isValidDefault(property)) {
+            invalid(path, `the default ${JSON.stringify(property.default)} is not a ${property.type}.`);
+        }
+    }
+    for (const relationship of entity.relationships) {
+        const path = `${entity.name}.relationships.${relationship.name}`;
+        if (!SNAKE_CASE_NAME.test(relationship.name) || isSystemProperty(relationship.name)) {
+            invalid(path, "relationship names are lowercase snake_case and cannot be system properties.");
+        }
+        const target = entitiesByName.get(relationship.to);
+        if (target === undefined) {
+            invalid(path, `it points at ${relationship.to}, which is not an entity.`);
+        }
+        else if (isValueMatched(relationship) !== (entity.source !== undefined || target.source !== undefined)) {
+            // `on` is what keeps a relationship with a warehouse-backed end out of storage.
+            invalid(path, isValueMatched(relationship)
+                ? "a relationship between stored entities uses a key column and cannot declare on."
+                : "a relationship with a warehouse-backed end is matched by value and needs on.");
+        }
+        // A value-matched relationship has no foreign key, so no delete rule.
+        if (relationship.cardinality === "one" &&
+            !isValueMatched(relationship) &&
+            relationship.onDelete === undefined) {
+            invalid(path, "a rel.one relationship between stored entities needs onDelete.");
+        }
+        if (relationship.onDelete === "setNull" && relationship.optional !== true) {
+            invalid(path, 'onDelete "setNull" needs an optional relationship.');
+        }
+    }
+    entity.indexes.forEach((index, position) => {
+        const path = `${entity.name}.indexes[${position}]`;
+        if (index.properties.length === 0) {
+            invalid(path, "an index covers at least one field.");
+        }
+        for (const field of index.properties) {
+            if (fieldColumnName(entity, field) === undefined) {
+                invalid(path, `"${field}" is not a property, system property or rel.one of ${entity.name}.`);
+            }
+        }
+    });
+}
+// Storage names ----------------------------------------------------------------------------------
+function tableObjects(table, owner, path) {
+    return [
+        { kind: "table", name: table.name, table: table.name, owner, path },
+        {
+            kind: "index",
+            name: table.primaryKey.name,
+            table: table.name,
+            owner: `the primary key of ${table.name}`,
+            path,
+        },
+        ...table.indexes.map((index) => ({
+            kind: "index",
+            name: index.name,
+            table: table.name,
+            owner: `index ${index.name} (${index.origin})`,
+            path,
+        })),
+        ...table.columns.map((column) => ({
+            kind: "column",
+            name: column.name,
+            table: table.name,
+            owner: `column ${table.name}.${column.name}`,
+            path,
+        })),
+        ...table.constraints.map((constraint) => ({
+            kind: "constraint",
+            name: constraint.name,
+            table: table.name,
+            owner: `constraint ${constraint.name} of ${table.name}`,
+            path,
+        })),
+    ];
+}
+function declared(entity) {
+    return { entity, detached: false, kept: NO_MEMBERS, restoring: NO_MEMBERS, removed: false };
+}
+function keptProperties(stored) {
+    return stored.entity.properties.filter((property) => stored.kept.properties.has(property.name));
+}
+function keptRelationships(stored) {
+    return stored.entity.relationships.filter((relationship) => stored.kept.relationships.has(relationship.name));
+}
+/**
+ * What the database holds for an entity: its storage less the foreign keys of a detached entity,
+ * and less the foreign keys and indexes of its kept fields.
+ */
+function physicalStorage(stored) {
+    const { entity } = stored;
+    const storage = entityStorage(entity);
+    const properties = keptProperties(stored).filter(isStoredProperty);
+    const ones = keptRelationships(stored).filter((relationship) => relationship.cardinality === "one" && !isValueMatched(relationship));
+    const keptColumns = new Set([
+        ...properties.map((property) => columnName(property.name)),
+        ...ones.map((relationship) => relationshipColumnName(relationship.name)),
+    ]);
+    const keptKeys = new Set([
+        ...properties
+            .filter((property) => property.type === "blob")
+            .map((property) => blobForeignKey(entity.name, property).name),
+        ...ones.map((relationship) => relationshipForeignKey(entity.name, relationship).name),
+    ]);
+    const manys = entity.relationships.filter((relationship) => relationship.cardinality === "many");
+    return {
+        ...storage,
+        table: {
+            ...storage.table,
+            constraints: storage.table.constraints.filter((constraint) => constraint.kind !== "foreignKey" || (!stored.detached && !keptKeys.has(constraint.name))),
+            indexes: storage.table.indexes.filter((index) => !index.columns.some((column) => keptColumns.has(column))),
+        },
+        joins: storage.joins.map((join, position) => stored.detached || stored.kept.relationships.has(manys[position]?.name ?? "")
+            ? {
+                ...join,
+                constraints: join.constraints.filter((constraint) => constraint.kind !== "foreignKey"),
+            }
+            : join),
+    };
+}
+function keptEntityNote(entity) {
+    return (`The database keeps it for the removed entity ${entity.name}: entity ids never change, so ` +
+        `restore ${entity.id} to keep its records, or choose another name.`);
+}
+function keptFieldNote(entity, field) {
+    return (`The database keeps it for the removed field ${entity}.${field}: declare ${field} on ` +
+        `${entity} again to restore it, or choose another name.`);
+}
+/** Who each object of a declared entity's kept fields is kept for, by kind and name. */
+function keptFieldNotes(stored) {
+    const { entity, restoring } = stored;
+    const notes = new Map();
+    for (const property of keptProperties(stored).filter(isStoredProperty)) {
+        if (restoring.properties.has(property.name)) {
+            continue;
+        }
+        const note = keptFieldNote(entity.name, property.name);
+        const check = propertyCheck(entity.name, property);
+        notes.set(`column:${columnName(property.name)}`, note);
+        if (property.type === "select") {
+            notes.set(`type:${enumTypeName(entity.name, property.name)}`, note);
+        }
+        if (check !== undefined) {
+            notes.set(`constraint:${check.name}`, note);
+        }
+    }
+    for (const relationship of keptRelationships(stored)) {
+        if (restoring.relationships.has(relationship.name)) {
+            continue;
+        }
+        const note = keptFieldNote(entity.name, relationship.name);
+        notes.set(relationship.cardinality === "one"
+            ? `column:${relationshipColumnName(relationship.name)}`
+            : `join:${joinTable(entity.name, relationship).name}`, note);
+    }
+    return notes;
+}
+/** Every named object the entities store, in a deterministic order. */
+function storageObjects(models) {
+    return models.flatMap((stored) => {
+        const { entity } = stored;
+        const storage = physicalStorage(stored);
+        const manys = entity.relationships.filter((relationship) => relationship.cardinality === "many");
+        const entityNote = stored.removed ? keptEntityNote(entity) : undefined;
+        const fieldNotes = entityNote === undefined ? keptFieldNotes(stored) : new Map();
+        const objects = [
+            ...tableObjects(storage.table, `the table of entity ${entity.name}`, entity.name),
+            ...tableObjects(storage.history, `the history table of ${entity.name}`, entity.name),
+            ...storage.joins.flatMap((join, position) => tableObjects(join, `the join table of ${entity.name}.${manys[position]?.name ?? join.name}`, `${entity.name}.relationships.${manys[position]?.name ?? join.name}`)),
+            ...entity.properties
+                .filter((property) => property.type === "select")
+                .map((property) => ({
+                kind: "type",
+                name: enumTypeName(entity.name, property.name),
+                table: "",
+                owner: `the enum type of ${entity.name}.${property.name}`,
+                path: `${entity.name}.properties.${property.name}`,
+            })),
+        ];
+        return objects.map((object) => {
+            const note = entityNote ??
+                fieldNotes.get(`${object.kind}:${object.name}`) ??
+                fieldNotes.get(`join:${object.table}`);
+            return note === undefined ? object : { ...object, kept: note };
+        });
+    });
+}
+/** Tables, types and indexes share one namespace; columns and constraints are per table. */
+function scopeOf(object) {
+    return GLOBAL_KINDS.has(object.kind) ? "global" : `${object.kind}:${object.table}`;
+}
+function collisions(objects) {
+    const seen = new Map();
+    const found = [];
+    for (const object of objects) {
+        const key = `${scopeOf(object)}\u0000${object.name}`;
+        const first = seen.get(key);
+        if (first === undefined) {
+            seen.set(key, object);
+            continue;
+        }
+        found.push({ first, second: object });
+    }
+    return found;
+}
+function findCollisions(objects) {
+    return collisions(objects).map(({ first, second }) => refusal("name-collision", second.path, `"${second.name}" would name both ${first.owner} and ${second.owner}; rename one of them.`));
+}
+/** Collisions with kept storage: one refusal per kept entity or field, at its first collision. */
+function keptCollisionRefusals(found) {
+    const reported = new Set();
+    const refusals = [];
+    for (const { first, second } of found) {
+        const kept = first.kept === undefined ? second : first;
+        const other = kept === first ? second : first;
+        if (kept.kept === undefined || reported.has(kept.kept)) {
+            continue;
+        }
+        reported.add(kept.kept);
+        refusals.push(refusal("name-collision", other.path, `"${kept.name}" would name both ${other.owner} and ${kept.owner}. ${kept.kept}`));
+    }
+    return refusals;
+}
+function checkStorageNames(entities, refusals) {
+    const objects = storageObjects(entities.map(declared));
+    const reported = new Set();
+    for (const object of objects) {
+        if (object.name.length <= MAX_IDENTIFIER_LENGTH || reported.has(object.name)) {
+            continue;
+        }
+        reported.add(object.name);
+        refusals.push(refusal("identifier-too-long", object.path, `"${object.name}" (${object.owner}) is longer than Postgres' ${MAX_IDENTIFIER_LENGTH} ` +
+            "characters; shorten the entity or property name."));
+    }
+    refusals.push(...findCollisions(objects));
+}
+/** The target's storage cannot take a name its kept storage holds. */
+function checkKeptNames(final, refusals) {
+    // A refused rename already reported the collisions it would cause.
+    const reported = new Set(refusals.map((refusal) => `${refusal.path}\u0000${refusal.message}`));
+    refusals.push(...keptCollisionRefusals(collisions(storageObjects(final))).filter((refusal) => !reported.has(`${refusal.path}\u0000${refusal.message}`)));
+}
+const UNRECORDED = "already exists in the database, but neither the applied ontology nor the storage its catalog " +
+    "keeps accounts for it: storage an earlier SDK kept when something was removed, for example. Its " +
+    "definition is unknown, so it cannot be restored. Drop it from the database, or choose another name.";
+/** The member of an entity whose column has this name, for refusal paths. */
+function columnPath(entity, column) {
+    const property = entity.properties.find((candidate) => columnName(candidate.name) === column);
+    const relationship = entity.relationships.find((candidate) => candidate.cardinality === "one" && relationshipColumnName(candidate.name) === column);
+    return property !== undefined
+        ? `${entity.name}.properties.${property.name}`
+        : relationship !== undefined
+            ? `${entity.name}.relationships.${relationship.name}`
+            : entity.name;
+}
+function existingColumns(existing, table) {
+    return new Set(Object.hasOwn(existing.columns, table) ? existing.columns[table] : []);
+}
+/**
+ * The plan creates or renames into names the database already holds only where the applied
+ * ontology or its kept storage accounts for them: anything else would fail in SQL.
+ */
+function checkUnrecordedNames(input) {
+    const { accounted, final, existing, refusals } = input;
+    const physical = new Set(existing.names);
+    const known = new Set(storageObjects(accounted)
+        .filter((object) => GLOBAL_KINDS.has(object.kind))
+        .map((object) => object.name));
+    const reported = new Set();
+    // Indexes are left out: a failed concurrent build leaves an index the catalog does not record,
+    // which the next build drops first. Kept tables and columns are what carry unrecorded data.
+    for (const object of storageObjects(final)) {
+        if ((object.kind !== "table" && object.kind !== "type") ||
+            known.has(object.name) ||
+            !physical.has(object.name) ||
+            reported.has(object.name)) {
+            continue;
+        }
+        reported.add(object.name);
+        refusals.push(refusal("name-collision", object.path, `"${object.name}" (${object.owner}) ${UNRECORDED}`));
+    }
+    for (const stored of final) {
+        const before = accounted.find((candidate) => candidate.entity.id === stored.entity.id);
+        if (before === undefined) {
+            continue;
+        }
+        const table = tableName(before.entity.name);
+        const columns = new Set(physicalStorage(before).table.columns.map((column) => column.name));
+        const present = existingColumns(existing, table);
+        for (const column of physicalStorage(stored).table.columns) {
+            if (!columns.has(column.name) && present.has(column.name)) {
+                refusals.push(refusal("name-collision", columnPath(stored.entity, column.name), `Column "${column.name}" of ${table} ${UNRECORDED}`));
+            }
+        }
+    }
+}
+// Kept storage -----------------------------------------------------------------------------------
+/** A removed property as its column is kept: nullable, without a default or index. */
+function keptProperty(property) {
+    const kept = {
+        ...property,
+        optional: true,
+        unique: false,
+    };
+    delete kept.default;
+    return kept;
+}
+/** A removed relationship as its key column or join table is kept. */
+function keptRelationship(relationship) {
+    return relationship.cardinality === "one" ? { ...relationship, optional: true } : relationship;
+}
+function names(members) {
+    return new Set(members.map((member) => member.name));
+}
+/** A declared entity with the kept fields the catalog records for it. */
+function declaredModel(entity, records) {
+    const record = records.find((candidate) => candidate.id === entity.id && !candidate.removed);
+    if (record === undefined) {
+        return declared(entity);
+    }
+    return {
+        entity: {
+            ...entity,
+            properties: [...entity.properties, ...record.fields.properties],
+            relationships: [...entity.relationships, ...record.fields.relationships],
+        },
+        detached: false,
+        kept: {
+            properties: names(record.fields.properties),
+            relationships: names(record.fields.relationships),
+        },
+        restoring: NO_MEMBERS,
+        removed: false,
+    };
+}
+/** A removed entity whose storage is kept. */
+function keptModel(record) {
+    const entity = retainedEntityManifest(record);
+    return {
+        entity: {
+            ...entity,
+            properties: [...entity.properties, ...record.fields.properties],
+            relationships: [...entity.relationships, ...record.fields.relationships],
+        },
+        detached: true,
+        kept: {
+            properties: names(record.fields.properties),
+            relationships: names(record.fields.relationships),
+        },
+        restoring: NO_MEMBERS,
+        removed: true,
+    };
+}
+/**
+ * A matched entity's storage once the drops ran: its matched members, then the members this plan
+ * removes and keeps, then the kept fields that stay kept. Restored fields are still in the kept
+ * state; the plan declares them later.
+ */
+function pairModel(pair, allowDrops) {
+    const matched = {
+        ...pair.current,
+        properties: pair.properties.map(({ current }) => current),
+        relationships: pair.relationships.map(({ current }) => current),
+    };
+    const removedProperties = allowDrops ? [] : pair.removedProperties.map(keptProperty);
+    const removedRelationships = allowDrops ? [] : pair.removedRelationships.map(keptRelationship);
+    return {
+        entity: {
+            ...matched,
+            properties: [...matched.properties, ...removedProperties, ...pair.keptProperties],
+            relationships: [...matched.relationships, ...removedRelationships, ...pair.keptRelationships],
+            indexes: pair.current.indexes.filter((index) => index.properties.every((field) => fieldColumnName(pair.current, field) !== undefined)),
+        },
+        detached: pair.restored,
+        kept: {
+            properties: new Set([
+                ...pair.restoredFields.properties,
+                ...names(removedProperties),
+                ...names(pair.keptProperties),
+            ]),
+            relationships: new Set([
+                ...pair.restoredFields.relationships,
+                ...names(removedRelationships),
+                ...names(pair.keptRelationships),
+            ]),
+        },
+        restoring: pair.restoredFields,
+        removed: false,
+    };
+}
+/** A target entity with the kept fields that stay kept, under the target's names. */
+function finalModel(entity, renamed) {
+    const stored = renamed.find((candidate) => candidate.entity.id === entity.id && !candidate.removed);
+    if (stored === undefined) {
+        return declared(entity);
+    }
+    const properties = keptProperties(stored).filter((property) => !stored.restoring.properties.has(property.name));
+    const relationships = keptRelationships(stored).filter((relationship) => !stored.restoring.relationships.has(relationship.name));
+    return {
+        entity: {
+            ...entity,
+            properties: [...entity.properties, ...properties],
+            relationships: [...entity.relationships, ...relationships],
+        },
+        detached: false,
+        kept: { properties: names(properties), relationships: names(relationships) },
+        restoring: NO_MEMBERS,
+        removed: false,
+    };
+}
+/** What the catalog records after the plan: the renamed model's kept storage, by entity id. */
+function retainedAfter(model) {
+    const entities = model.flatMap((stored) => {
+        const { entity, kept, restoring } = stored;
+        const fields = {
+            properties: keptProperties(stored).filter((property) => !restoring.properties.has(property.name)),
+            relationships: keptRelationships(stored).filter((relationship) => !restoring.relationships.has(relationship.name)),
+        };
+        if (stored.removed) {
+            return [
+                {
+                    id: entity.id,
+                    name: entity.name,
+                    removed: true,
+                    properties: entity.properties.filter((property) => !kept.properties.has(property.name)),
+                    relationships: entity.relationships.filter((relationship) => !kept.relationships.has(relationship.name) && !isValueMatched(relationship)),
+                    indexes: entity.indexes,
+                    fields,
+                },
+            ];
+        }
+        return fields.properties.length + fields.relationships.length === 0
+            ? []
+            : [
+                {
+                    id: entity.id,
+                    name: entity.name,
+                    removed: false,
+                    properties: [],
+                    relationships: [],
+                    indexes: [],
+                    fields,
+                },
+            ];
+    });
+    return {
+        entities: entities.sort((left, right) => left.id < right.id ? -1 : left.id > right.id ? 1 : 0),
+    };
+}
+/**
+ * The catalog's kept storage that is still what it records. Without observed storage the record is
+ * trusted where it agrees with the applied manifest. With it, kept storage whose objects are gone,
+ * dropped by hand or renamed by an earlier SDK, is forgotten; what remains of it is unrecorded, so
+ * the plan cannot take its names.
+ */
+function reconcileRetained(input) {
+    const { current, existing } = input;
+    const declaredById = new Map(current.map((entity) => [entity.id, entity]));
+    const declaredNames = new Set(current.map((entity) => entity.name));
+    const physical = new Set(existing?.names ?? []);
+    const holds = (table) => physical.has(table.name) &&
+        table.columns.every((column) => existingColumns(existing, table.name).has(column.name));
+    const seen = new Set();
+    return input.retained.entities.flatMap((record) => {
+        if (seen.has(record.id)) {
+            return [];
+        }
+        seen.add(record.id);
+        if (record.removed) {
+            if (declaredById.has(record.id) || declaredNames.has(record.name)) {
+                return [];
+            }
+            if (existing === undefined) {
+                return [record];
+            }
+            const storage = physicalStorage(keptModel(record));
+            return [storage.table, storage.history, ...storage.joins].every(holds) &&
+                storage.enums.every((storage) => physical.has(storage.name))
+                ? [record]
+                : [];
+        }
+        const entity = declaredById.get(record.id);
+        if (entity === undefined || entity.name !== record.name) {
+            return [];
+        }
+        const table = tableName(entity.name);
+        const columns = existing === undefined ? undefined : existingColumns(existing, table);
+        const properties = record.fields.properties.filter((property) => !entity.properties.some((candidate) => candidate.name === property.name) &&
+            (columns === undefined ||
+                (columns.has(columnName(property.name)) &&
+                    (property.type !== "select" ||
+                        physical.has(enumTypeName(entity.name, property.name))))));
+        const relationships = record.fields.relationships.filter((relationship) => !entity.relationships.some((candidate) => candidate.name === relationship.name) &&
+            (columns === undefined ||
+                (relationship.cardinality === "one"
+                    ? columns.has(relationshipColumnName(relationship.name))
+                    : holds(joinTable(entity.name, relationship)))));
+        return properties.length + relationships.length === 0
+            ? []
+            : [{ ...record, fields: { properties, relationships } }];
+    });
+}
+// Matching ---------------------------------------------------------------------------------------
+function entityIdByName(entities, name) {
+    return entities.find((entity) => entity.name === name)?.id;
+}
+function matchProperties(current, target, kept) {
+    const byName = new Map(current.properties.map((property) => [property.name, property]));
+    const keptByName = new Map(kept.map((property) => [property.name, property]));
+    const claimed = new Set(target.properties.filter((property) => byName.has(property.name)).map(({ name }) => name));
+    const properties = [];
+    const addedProperties = [];
+    const restoredProperties = new Set();
+    for (const property of target.properties) {
+        const sameName = byName.get(property.name);
+        const source = property.renamedFrom === undefined
+            ? undefined
+            : (byName.get(property.renamedFrom) ?? byName.get(toSnakeCase(property.renamedFrom)));
+        const previous = source !== undefined && !claimed.has(source.name) ? source : undefined;
+        const match = sameName ?? previous;
+        if (match === undefined) {
+            const keptProperty = keptByName.get(property.name);
+            // A kept field is declared again under its own name.
+            if (keptProperty === undefined) {
+                addedProperties.push(property);
+            }
+            else {
+                restoredProperties.add(property.name);
+                properties.push({ current: keptProperty, target: property });
+            }
+            continue;
+        }
+        claimed.add(match.name);
+        properties.push({ current: match, target: property });
+    }
+    const removedProperties = current.properties.filter((property) => !claimed.has(property.name));
+    return {
+        properties,
+        addedProperties,
+        removedProperties,
+        restoredProperties,
+        keptProperties: kept.filter((property) => !restoredProperties.has(property.name)),
+    };
+}
+function matchEntities(input) {
+    const { currentEntities, records, targetEntities, refusals } = input;
+    const currentById = new Map(currentEntities.map((entity) => [entity.id, entity]));
+    const recordById = new Map(records.map((record) => [record.id, record]));
+    // Relationship targets resolve among everything the database stores, declared or kept.
+    const storedEntities = [
+        ...currentEntities,
+        ...records.filter((record) => record.removed).map(retainedEntityManifest),
+    ];
+    const pairs = [];
+    for (const target of targetEntities) {
+        const record = recordById.get(target.id);
+        const restored = !currentById.has(target.id) && record?.removed === true;
+        const current = currentById.get(target.id) ??
+            (restored && record !== undefined ? retainedEntityManifest(record) : undefined);
+        if (current === undefined) {
+            continue;
+        }
+        const keptRelationshipsByName = new Map((record?.fields.relationships ?? []).map((relationship) => [relationship.name, relationship]));
+        const relationships = [];
+        const addedRelationships = [];
+        const restoredRelationships = new Set();
+        const matched = new Set();
+        const changed = new Set();
+        for (const relationship of target.relationships) {
+            const declaredPrevious = current.relationships.find(({ name }) => name === relationship.name);
+            const keptPrevious = isValueMatched(relationship)
+                ? undefined
+                : keptRelationshipsByName.get(relationship.name);
+            const previous = declaredPrevious ?? keptPrevious;
+            if (previous === undefined) {
+                if (!isValueMatched(relationship)) {
+                    addedRelationships.push(relationship);
+                }
+                continue;
+            }
+            // Both lists hold stored entities only, so a warehouse-backed target has no id here.
+            const previousTarget = entityIdByName(storedEntities, previous.to);
+            const nextTarget = entityIdByName(targetEntities, relationship.to);
+            if (previous.cardinality !== relationship.cardinality ||
+                previousTarget !== nextTarget ||
+                isValueMatched(previous) !== isValueMatched(relationship)) {
+                changed.add(relationship.name);
+                refusals.push(refusal("relationship-change", `${target.name}.relationships.${relationship.name}`, declaredPrevious === undefined
+                    ? `was rel.${previous.cardinality} to ${previous.to} when it was removed, and the ` +
+                        "database keeps its links; it cannot come back as " +
+                        `rel.${relationship.cardinality} to ${relationship.to}. Declare it as it was to ` +
+                        "restore it, or choose another name."
+                    : `was rel.${previous.cardinality} to ${previous.to} and is now ` +
+                        `rel.${relationship.cardinality} to ${relationship.to}; a relationship keeps its ` +
+                        "target and cardinality. Declare a new relationship and drop this one instead."));
+                continue;
+            }
+            if (declaredPrevious === undefined) {
+                restoredRelationships.add(relationship.name);
+            }
+            else {
+                matched.add(relationship.name);
+            }
+            if (!isValueMatched(relationship)) {
+                relationships.push({ current: previous, target: relationship });
+            }
+        }
+        // A value-matched relationship is stored as the property its `on` names: adding, keeping or
+        // removing one plans no statement and drops nothing.
+        const removedRelationships = current.relationships.filter((relationship) => !matched.has(relationship.name) &&
+            !changed.has(relationship.name) &&
+            !isValueMatched(relationship));
+        const { restoredProperties, ...properties } = matchProperties(current, target, record?.fields.properties ?? []);
+        pairs.push({
+            current,
+            target,
+            restored,
+            ...properties,
+            relationships,
+            addedRelationships,
+            removedRelationships,
+            restoredFields: { properties: restoredProperties, relationships: restoredRelationships },
+            keptRelationships: [...keptRelationshipsByName.values()].filter((relationship) => !restoredRelationships.has(relationship.name)),
+        });
+    }
+    return pairs;
+}
+// Drops ------------------------------------------------------------------------------------------
+function planDrops(input) {
+    const { pairs, removedEntities, addedEntities, allowDrops, draft } = input;
+    for (const pair of pairs) {
+        const table = tableName(pair.current.name);
+        // A restored entity's foreign keys were detached when it was removed.
+        const attached = !pair.restored;
+        for (const relationship of pair.removedRelationships) {
+            if (!allowDrops) {
+                const actions = relationship.cardinality === "one"
+                    ? [
+                        ...(relationship.optional === true
+                            ? []
+                            : [
+                                `ALTER COLUMN ${quoteIdentifier(relationshipColumn(relationship).name)} DROP NOT NULL`,
+                            ]),
+                        ...(attached
+                            ? [
+                                `DROP CONSTRAINT ${quoteIdentifier(relationshipForeignKey(pair.current.name, relationship).name)}`,
+                            ]
+                            : []),
+                    ]
+                    : [];
+                draft.drops.push(step({
+                    kind: "removeRelationship",
+                    classification: "change",
+                    description: `Remove relationship ${pair.current.name}.${relationship.name}, retaining its links.`,
+                    sql: relationship.cardinality === "one"
+                        ? actions.length === 0
+                            ? []
+                            : [alterTable(table, actions.join(", "))]
+                        : attached
+                            ? detachForeignKeys(joinTable(pair.current.name, relationship))
+                            : [],
+                }));
+                continue;
+            }
+            const statement = relationship.cardinality === "one"
+                ? alterTable(table, `DROP COLUMN ${quoteIdentifier(relationshipColumn(relationship).name)}`)
+                : `DROP TABLE ${quoteIdentifier(joinTable(pair.current.name, relationship).name)}`;
+            draft.drops.push(step({
+                kind: "dropRelationship",
+                classification: "destructive",
+                description: `Drop relationship ${pair.current.name}.${relationship.name} and its links.`,
+                sql: [statement],
+            }));
+        }
+        for (const property of pair.removedProperties) {
+            if (!allowDrops) {
+                const column = propertyColumn(pair.current.name, property);
+                // Kept storage holds no foreign keys, so a kept file revision never blocks maintenance.
+                const actions = [
+                    ...(column.notNull ? [`ALTER COLUMN ${quoteIdentifier(column.name)} DROP NOT NULL`] : []),
+                    ...(column.default === undefined
+                        ? []
+                        : [`ALTER COLUMN ${quoteIdentifier(column.name)} DROP DEFAULT`]),
+                    ...(property.type === "blob" && attached
+                        ? [
+                            `DROP CONSTRAINT ${quoteIdentifier(blobForeignKey(pair.current.name, property).name)}`,
+                        ]
+                        : []),
+                ];
+                draft.drops.push(step({
+                    kind: "removeProperty",
+                    classification: "change",
+                    description: `Remove property ${pair.current.name}.${property.name}, retaining its values.`,
+                    sql: actions.length === 0 ? [] : [alterTable(table, actions.join(", "))],
+                }));
+                continue;
+            }
+            const enumStorage = propertyEnum(pair.current.name, property);
+            draft.drops.push(step({
+                kind: "dropProperty",
+                classification: "destructive",
+                description: `Drop property ${pair.current.name}.${property.name} and its values.`,
+                sql: [
+                    alterTable(table, `DROP COLUMN ${quoteIdentifier(propertyColumn(pair.current.name, property).name)}`),
+                    ...(enumStorage === undefined
+                        ? []
+                        : [`DROP TYPE ${quoteIdentifier(enumStorage.name)}`]),
+                ],
+            }));
+        }
+    }
+    if (!allowDrops) {
+        for (const pair of pairs) {
+            // Dropped columns used to drop these indexes implicitly. Retained columns need explicit
+            // cleanup so removed unique properties and compound indexes cannot constrain active writes.
+            const removedColumns = new Set([
+                ...pair.removedProperties.map((property) => propertyColumn(pair.current.name, property).name),
+                ...pair.removedRelationships
+                    .filter((relationship) => relationship.cardinality === "one")
+                    .map((relationship) => relationshipColumn(relationship).name),
+            ]);
+            for (const index of entityStorage(pair.current).table.indexes) {
+                if (index.columns.some((column) => removedColumns.has(column))) {
+                    draft.drops.push(step({
+                        kind: "dropIndex",
+                        classification: "change",
+                        description: `Drop index ${index.name} (${index.origin}).`,
+                        sql: [`DROP INDEX ${quoteIdentifier(index.name)}`],
+                    }));
+                }
+            }
+        }
+    }
+    if (removedEntities.length === 0) {
+        return;
+    }
+    const names = removedEntities.map(({ entity }) => entity.name);
+    if (!allowDrops) {
+        for (const { entity } of removedEntities) {
+            // A successor under the removed name collides with the kept storage, refused with the
+            // other kept names; one that only claims to be its rename has a new id.
+            const successor = addedEntities.find((candidate) => candidate.renamedFrom === entity.name && candidate.name !== entity.name);
+            if (successor !== undefined) {
+                draft.refusals.push(refusal("name-collision", entity.name, `${entity.name}'s storage is retained. ${successor.name} has the new id ${successor.id}; ` +
+                    `entity ids never change, so restore ${entity.id} to keep ${entity.name}'s records.`));
+            }
+        }
+        draft.drops.push(step({
+            kind: "removeEntities",
+            classification: "change",
+            description: `Remove entities ${names.join(", ")}, retaining their records and history.`,
+            sql: removedEntities.flatMap((removed) => {
+                const storage = physicalStorage(removed);
+                return [storage.table, ...storage.joins].flatMap(detachForeignKeys);
+            }),
+        }));
+        return;
+    }
+    // One statement per object kind: Postgres resolves the references between the dropped tables.
+    // An entity's kept fields go with it: their join tables and enum types are its storage too.
+    const storages = removedEntities.map(physicalStorage);
+    const quotedList = (names) => names.map(quoteIdentifier).join(", ");
+    const joins = storages.flatMap((storage) => storage.joins.map((join) => join.name));
+    const enums = storages.flatMap((storage) => storage.enums.map((storage) => storage.name));
+    const noun = names.length === 1 ? "entity" : "entities";
+    draft.drops.push(step({
+        kind: "dropEntities",
+        classification: "destructive",
+        description: `Drop ${noun} ${names.join(", ")} with their records and history.`,
+        sql: [
+            ...(joins.length === 0 ? [] : [`DROP TABLE ${quotedList(joins)}`]),
+            `DROP TABLE ${quotedList(storages.map((storage) => storage.history.name))}`,
+            `DROP TABLE ${quotedList(storages.map((storage) => storage.table.name))}`,
+            ...(enums.length === 0 ? [] : [`DROP TYPE ${quotedList(enums)}`]),
+        ],
+    }));
+}
+/** Retired tables must neither block active record deletion nor lose retained rows to cascades. */
+function detachForeignKeys(table) {
+    return table.constraints
+        .filter((constraint) => constraint.kind === "foreignKey")
+        .map((constraint) => alterTable(table.name, `DROP CONSTRAINT ${quoteIdentifier(constraint.name)}`));
+}
+// Renames ----------------------------------------------------------------------------------------
+function renameEntity(model, from, to) {
+    // Kept storage follows too: a kept join table's key column is named after its target.
+    return model.map((stored) => ({
+        ...stored,
+        entity: {
+            ...stored.entity,
+            name: stored.entity.name === from ? to : stored.entity.name,
+            relationships: stored.entity.relationships.map((relationship) => relationship.to === from ? { ...relationship, to } : relationship),
+        },
+    }));
+}
+function renameProperty(model, entityId, from, to) {
+    return model.map((stored) => {
+        if (stored.entity.id !== entityId || stored.removed) {
+            return stored;
+        }
+        const { entity } = stored;
+        return {
+            ...stored,
+            entity: {
+                ...entity,
+                properties: entity.properties.map((property) => property.name === from && !stored.kept.properties.has(from)
+                    ? { ...property, name: to }
+                    : property),
+                indexes: entity.indexes.map((index) => ({
+                    ...index,
+                    properties: index.properties.map((field) => (field === from ? to : field)),
+                })),
+            },
+        };
+    });
+}
+function renameStatement(before, after) {
+    const from = quoteIdentifier(before.name);
+    const to = quoteIdentifier(after.name);
+    switch (before.kind) {
+        case "table":
+            return `ALTER TABLE ${from} RENAME TO ${to}`;
+        case "type":
+            return `ALTER TYPE ${from} RENAME TO ${to}`;
+        case "index":
+            // Renaming a primary key's index renames the constraint too.
+            return `ALTER INDEX ${from} RENAME TO ${to}`;
+        case "column":
+            return alterTable(after.table, `RENAME COLUMN ${from} TO ${to}`);
+        case "constraint":
+            return alterTable(after.table, `RENAME CONSTRAINT ${from} TO ${to}`);
+    }
+}
+/**
+ * The statements that take the objects of one model to the objects of the same model renamed. Within a
+ * namespace, a rename waits until its new name is free; a cycle cannot be ordered and is undefined.
+ */
+function renameStatements(before, after) {
+    if (before.length !== after.length) {
+        throw new Error("A rename changed the shape of the storage model.");
+    }
+    const occupied = new Map();
+    for (const object of before) {
+        const scope = scopeOf(object);
+        const names = occupied.get(scope) ?? new Set();
+        names.add(object.name);
+        occupied.set(scope, names);
+    }
+    const renames = before
+        .map((object, position) => ({ before: object, after: after[position] }))
+        .filter((pair) => pair.before.name !== pair.after.name);
+    // Tables first, so that column and constraint renames address tables by their new names.
+    const groups = [
+        renames.filter((pair) => GLOBAL_KINDS.has(pair.before.kind)),
+        renames.filter((pair) => pair.before.kind === "column"),
+        renames.filter((pair) => pair.before.kind === "constraint"),
+    ];
+    const statements = [];
+    for (const group of groups) {
+        const pending = [...group];
+        while (pending.length > 0) {
+            const ready = pending.findIndex((pair) => !occupied.get(scopeOf(pair.before))?.has(pair.after.name));
+            if (ready === -1) {
+                return undefined;
+            }
+            const [pair] = pending.splice(ready, 1);
+            if (pair === undefined) {
+                break;
+            }
+            const names = occupied.get(scopeOf(pair.before));
+            names.delete(pair.before.name);
+            names.add(pair.after.name);
+            statements.push(renameStatement(pair.before, pair.after));
+        }
+    }
+    return statements;
+}
+/** Orders renames so that each new name is free when its rename runs; undefined on a cycle. */
+function orderRenames(renames, names) {
+    const occupied = new Set(names);
+    const pending = [...renames];
+    const ordered = [];
+    while (pending.length > 0) {
+        const ready = pending.findIndex((rename) => !occupied.has(rename.to));
+        if (ready === -1) {
+            return undefined;
+        }
+        const [rename] = pending.splice(ready, 1);
+        occupied.delete(rename.from);
+        occupied.add(rename.to);
+        ordered.push(rename);
+    }
+    return ordered;
+}
+function logicalRenames(pairs, refusals) {
+    const entityRenames = orderRenames(pairs
+        .filter((pair) => pair.current.name !== pair.target.name)
+        .map((pair) => ({ from: pair.current.name, to: pair.target.name })), pairs.map((pair) => pair.current.name));
+    if (entityRenames === undefined) {
+        refusals.push(refusal("rename-conflict", pairs.map((pair) => pair.target.name).join(", "), "entity renames swap names in a cycle; deploy them in separate steps."));
+        return [];
+    }
+    const renames = entityRenames.map(({ from, to }) => ({
+        kind: "renameEntity",
+        path: to,
+        description: `Rename entity ${from} to ${to}, with its history, enum types, indexes and join tables.`,
+        apply: (model) => renameEntity(model, from, to),
+    }));
+    for (const pair of pairs) {
+        const propertyRenames = orderRenames(pair.properties
+            .filter((property) => property.current.name !== property.target.name)
+            .map((property) => ({ from: property.current.name, to: property.target.name })), pair.properties.map((property) => property.current.name));
+        if (propertyRenames === undefined) {
+            refusals.push(refusal("rename-conflict", pair.target.name, "property renames swap names in a cycle; deploy them in separate steps."));
+            continue;
+        }
+        for (const { from, to } of propertyRenames) {
+            renames.push({
+                kind: "renameProperty",
+                path: `${pair.target.name}.properties.${to}`,
+                description: `Rename property ${pair.target.name}.${from} to ${to}.`,
+                apply: (model) => renameProperty(model, pair.target.id, from, to),
+                ...(pair.current.properties.some((property) => property.name === from && property.type === "blob")
+                    ? {
+                        metadataSql: ["_blobs", "_blob_uploads", "_blob_references"].map((table) => `UPDATE ${quoteIdentifier(table)} SET property_id = ${quoteLiteral(to)} ` +
+                            `WHERE entity_id = ${quoteLiteral(pair.target.id)} AND property_id = ${quoteLiteral(from)}`),
+                    }
+                    : {}),
+            });
+        }
+    }
+    return renames;
+}
+/**
+ * Plans the renames over everything the database stores once the drops ran, kept storage included,
+ * and returns that model with every target name in place.
+ */
+function planRenames(input) {
+    const { pairs, draft } = input;
+    let model = [...input.model];
+    for (const rename of logicalRenames(pairs, draft.refusals)) {
+        const next = rename.apply(model);
+        const found = collisions(storageObjects(next));
+        // A name kept storage holds changes which objects exist, so pair them only without collisions.
+        const statements = found.length > 0 ? undefined : renameStatements(storageObjects(model), storageObjects(next));
+        if (found.length > 0 || statements === undefined) {
+            const kept = keptCollisionRefusals(found);
+            draft.refusals.push(...(kept.length > 0
+                ? kept
+                : [
+                    refusal("rename-conflict", rename.path, `${rename.description.replace(/\.$/, "")} cannot run in this deploy: a name it ` +
+                        "takes is still in use. Deploy the renames in separate steps."),
+                ]));
+            return model;
+        }
+        draft.renames.push(step({
+            kind: rename.kind,
+            classification: "rename",
+            description: rename.description,
+            sql: [...statements, ...(rename.metadataSql ?? [])],
+        }));
+        model = next;
+    }
+    return model;
+}
+// Changes to surviving entities ------------------------------------------------------------------
+function isSubsequence(values, of) {
+    let position = 0;
+    for (const value of of) {
+        if (value === values[position]) {
+            position += 1;
+        }
+    }
+    return position === values.length;
+}
+function sameIndex(left, right) {
+    return (left.table === right.table &&
+        left.unique === right.unique &&
+        left.columns.length === right.columns.length &&
+        left.columns.every((column, position) => column === right.columns[position]));
+}
+function optionValues(property) {
+    return (property.options ?? []).map((option) => option.value);
+}
+/** Plans option changes; returns true when the column was rebuilt with the target default. */
+function planSelectChange(input) {
+    const { entity, before, after, draft } = input;
+    const path = `${entity}.properties.${after.name}`;
+    const currentValues = optionValues(before);
+    const targetValues = optionValues(after);
+    if (currentValues.length === targetValues.length &&
+        currentValues.every((value, position) => value === targetValues[position])) {
+        return false;
+    }
+    const removed = currentValues.filter((value) => !targetValues.includes(value));
+    if (removed.length === 0 && isSubsequence(currentValues, targetValues)) {
+        // ALTER TYPE … ADD VALUE commits before the transaction, which may then use the new values.
+        const type = quoteIdentifier(enumTypeName(input.appliedEntity, input.appliedProperty));
+        const added = targetValues.filter((value) => !currentValues.includes(value));
+        const firstKept = targetValues.find((value) => currentValues.includes(value));
+        const statements = targetValues.flatMap((value, position) => {
+            if (currentValues.includes(value)) {
+                return [];
+            }
+            const placement = position === 0
+                ? `BEFORE ${quoteLiteral(firstKept)}`
+                : `AFTER ${quoteLiteral(targetValues[position - 1])}`;
+            return [`ALTER TYPE ${type} ADD VALUE IF NOT EXISTS ${quoteLiteral(value)} ${placement}`];
+        });
+        draft.before.push(step({
+            kind: "addSelectOption",
+            classification: "additive",
+            transactional: false,
+            description: `Add ${added.map((value) => `"${value}"`).join(", ")} to the options of ${entity}.${after.name}.`,
+            sql: statements,
+        }));
+        return false;
+    }
+    // Postgres cannot reorder or drop enum values: build the type again and convert the column.
+    const table = quoteIdentifier(tableName(entity));
+    const column = quoteIdentifier(propertyColumn(entity, after).name);
+    const type = quoteIdentifier(enumTypeName(entity, after.name));
+    const temporary = quoteIdentifier(`_ontology_rebuild_${draft.rebuilds}`);
+    const currentDefault = defaultExpression(before);
+    const targetDefault = defaultExpression(after);
+    const reason = removed.length > 0
+        ? `drops ${removed.map((value) => `"${value}"`).join(", ")}`
+        : "changes their order";
+    draft.rebuilds += 1;
+    draft.changes.push(step({
+        kind: "rebuildSelect",
+        classification: removed.length > 0 && input.allowDrops ? "destructive" : "change",
+        validatesData: removed.length > 0,
+        description: `Rebuild the options of ${entity}.${after.name} (${reason}).`,
+        sql: [
+            `CREATE TYPE ${temporary} AS ENUM (${targetValues.map(quoteLiteral).join(", ")})`,
+            ...(currentDefault === undefined
+                ? []
+                : [`ALTER TABLE ${table} ALTER COLUMN ${column} DROP DEFAULT`]),
+            `ALTER TABLE ${table} ALTER COLUMN ${column} TYPE ${temporary} USING ${column}::text::${temporary}`,
+            `DROP TYPE ${type}`,
+            `ALTER TYPE ${temporary} RENAME TO ${type}`,
+            ...(targetDefault === undefined
+                ? []
+                : [`ALTER TABLE ${table} ALTER COLUMN ${column} SET DEFAULT ${targetDefault}`]),
+        ],
+    }));
+    return true;
+}
+function planPropertyChange(input) {
+    const { entity, before, after, draft } = input;
+    const path = `${entity}.properties.${after.name}`;
+    const table = tableName(entity);
+    const column = quoteIdentifier(propertyColumn(entity, after).name);
+    if (before.type !== after.type) {
+        draft.refusals.push(refusal("type-change", path, input.restored
+            ? `was a ${before.type} when it was removed, and the database keeps its values; they ` +
+                `are not converted to ${after.type}. Declare it as a ${before.type} to restore it, ` +
+                "or choose another name."
+            : `changes type from ${before.type} to ${after.type}. Stored values are not converted; ` +
+                "add a property with the new type and move the values with an action instead."));
+        return;
+    }
+    const rebuilt = after.type === "select" ? planSelectChange(input) : false;
+    if (before.optional !== after.optional) {
+        draft.changes.push(step({
+            kind: "changeOptional",
+            classification: "change",
+            validatesData: !after.optional,
+            description: after.optional
+                ? `Make ${entity}.${after.name} optional.`
+                : `Make ${entity}.${after.name} required; fails while any record has no value.`,
+            sql: [
+                alterTable(table, `ALTER COLUMN ${column} ${after.optional ? "DROP" : "SET"} NOT NULL`),
+            ],
+        }));
+    }
+    const currentDefault = defaultExpression(before);
+    const targetDefault = defaultExpression(after);
+    if (!rebuilt && currentDefault !== targetDefault) {
+        draft.changes.push(step({
+            kind: "changeDefault",
+            classification: "change",
+            description: targetDefault === undefined
+                ? `Remove the default of ${entity}.${after.name}.`
+                : `Change the default of ${entity}.${after.name} to ${targetDefault}.`,
+            sql: [
+                alterTable(table, targetDefault === undefined
+                    ? `ALTER COLUMN ${column} DROP DEFAULT`
+                    : `ALTER COLUMN ${column} SET DEFAULT ${targetDefault}`),
+            ],
+        }));
+    }
+    const currentCheck = propertyCheck(entity, before);
+    const targetCheck = propertyCheck(entity, after);
+    if (currentCheck?.definition !== targetCheck?.definition) {
+        draft.changes.push(step({
+            kind: "changeCheck",
+            classification: "change",
+            validatesData: targetCheck !== undefined,
+            description: targetCheck === undefined
+                ? `Remove the bounds of ${entity}.${after.name}.`
+                : `Check the bounds of ${entity}.${after.name}; fails while any record is out of bounds.`,
+            sql: [
+                ...(currentCheck === undefined
+                    ? []
+                    : [alterTable(table, `DROP CONSTRAINT ${quoteIdentifier(currentCheck.name)}`)]),
+                ...(targetCheck === undefined ? [] : [addConstraintStatement(table, targetCheck)]),
+            ],
+        }));
+    }
+}
+function planRelationshipChange(input) {
+    const { entity, before, after, draft } = input;
+    const table = tableName(entity);
+    if (after.cardinality !== "one") {
+        return;
+    }
+    if ((before.optional === true) !== (after.optional === true)) {
+        const column = quoteIdentifier(relationshipColumn(after).name);
+        draft.changes.push(step({
+            kind: "changeOptional",
+            classification: "change",
+            validatesData: after.optional !== true,
+            description: after.optional === true
+                ? `Make relationship ${entity}.${after.name} optional.`
+                : `Make relationship ${entity}.${after.name} required; fails while any record has none.`,
+            sql: [
+                alterTable(table, `ALTER COLUMN ${column} ${after.optional === true ? "DROP" : "SET"} NOT NULL`),
+            ],
+        }));
+    }
+    const currentKey = relationshipForeignKey(entity, before);
+    const targetKey = relationshipForeignKey(entity, after);
+    if (input.attached && currentKey.definition !== targetKey.definition) {
+        draft.changes.push(step({
+            kind: "changeOnDelete",
+            classification: "change",
+            description: `Change onDelete of ${entity}.${after.name} to ${after.onDelete}.`,
+            sql: [
+                alterTable(table, `DROP CONSTRAINT ${quoteIdentifier(currentKey.name)}`),
+                addConstraintStatement(table, targetKey),
+            ],
+        }));
+    }
+}
+/** Columns that exist before the migration with the same name and meaning: safe to index concurrently. */
+function stableColumns(pair) {
+    if (pair.current.name !== pair.target.name) {
+        return new Set();
+    }
+    return new Set([
+        ...Object.values(SYSTEM_COLUMNS),
+        ...pair.properties
+            .filter((property) => property.current.name === property.target.name)
+            .map((property) => propertyColumn(pair.target.name, property.target).name),
+        ...pair.relationships
+            .filter((relationship) => relationship.target.cardinality === "one")
+            .map((relationship) => relationshipColumn(relationship.target).name),
+    ]);
+}
+function planIndexChanges(input) {
+    const { pair, before, appliedNames, draft } = input;
+    // Kept fields have no indexes: a restored field's are built again.
+    const currentStorage = physicalStorage(before).table;
+    const currentIndexes = currentStorage.indexes;
+    // Indexes over a refused member (a relationship whose target changed) wait for that refusal.
+    const known = new Set([
+        ...currentStorage.columns.map((column) => column.name),
+        ...pair.addedProperties.map((property) => propertyColumn(pair.target.name, property).name),
+        ...pair.addedRelationships
+            .filter((relationship) => relationship.cardinality === "one")
+            .map((relationship) => relationshipColumn(relationship).name),
+    ]);
+    const targetIndexes = entityStorage(pair.target).table.indexes.filter((index) => index.columns.every((column) => known.has(column)));
+    const stable = stableColumns(pair);
+    for (const index of currentIndexes) {
+        const replacement = targetIndexes.find((candidate) => candidate.name === index.name);
+        if (replacement !== undefined && sameIndex(index, replacement)) {
+            continue;
+        }
+        draft.indexDrops.push(step({
+            kind: "dropIndex",
+            classification: "change",
+            description: `Drop index ${index.name} (${index.origin}).`,
+            sql: [`DROP INDEX ${quoteIdentifier(index.name)}`],
+        }));
+    }
+    for (const index of targetIndexes) {
+        const existing = currentIndexes.find((candidate) => candidate.name === index.name);
+        if (existing !== undefined && sameIndex(existing, index)) {
+            continue;
+        }
+        const concurrent = existing === undefined &&
+            !appliedNames.has(index.name) &&
+            index.columns.every((column) => stable.has(column));
+        const description = `Add ${index.unique ? "unique " : ""}index ${index.name} (${index.origin}).`;
+        if (concurrent) {
+            // A failed concurrent build leaves an invalid index behind; dropping it first makes a rerun work.
+            draft.before.push(step({
+                kind: "addIndex",
+                classification: "additive",
+                transactional: false,
+                validatesData: index.unique,
+                description,
+                sql: [
+                    `DROP INDEX CONCURRENTLY IF EXISTS ${quoteIdentifier(index.name)}`,
+                    createIndexStatement(index, { concurrently: true }),
+                ],
+            }));
+            continue;
+        }
+        draft.indexes.push(step({
+            kind: "addIndex",
+            classification: "additive",
+            validatesData: index.unique,
+            description,
+            sql: [createIndexStatement(index)],
+        }));
+    }
+}
+/**
+ * Restores the foreign keys a restored entity or field lost when it was kept, under the target's
+ * names. Each validates the kept rows: they may refer to records deleted meanwhile.
+ */
+function planRestoredForeignKeys(input) {
+    const { pair, before, draft } = input;
+    const declaredStorage = entityStorage({
+        ...pair.target,
+        properties: pair.properties.map(({ target }) => target),
+        relationships: pair.relationships.map(({ target }) => target),
+        indexes: [],
+    });
+    const physical = physicalStorage(before);
+    const present = new Set([physical.table, ...physical.joins].flatMap((table) => table.constraints.map((constraint) => constraint.name)));
+    for (const table of [declaredStorage.table, ...declaredStorage.joins]) {
+        for (const constraint of table.constraints) {
+            if (constraint.kind !== "foreignKey" || present.has(constraint.name)) {
+                continue;
+            }
+            draft.foreignKeys.push(step({
+                kind: "addForeignKey",
+                classification: "additive",
+                validatesData: true,
+                description: `Restore foreign key ${constraint.name} of ${table.name}; fails while a kept row ` +
+                    `refers to a ${constraint.references === USER_TABLE ? "user" : "record"} deleted since.`,
+                sql: [addConstraintStatement(table.name, constraint)],
+            }));
+        }
+    }
+}
+function planEntityChanges(input) {
+    const { pair, renamed, appliedNames, allowDrops, draft } = input;
+    const stored = renamed.find((entity) => entity.entity.id === pair.target.id && !entity.removed);
+    // A refused rename leaves the entity under its applied name; the plan cannot be applied anyway.
+    if (stored === undefined || stored.entity.name !== pair.target.name) {
+        return;
+    }
+    const before = stored.entity;
+    const entity = pair.target.name;
+    const table = tableName(entity);
+    if (pair.restored) {
+        draft.changes.push(step({
+            kind: "restoreEntity",
+            classification: "change",
+            description: `Restore entity ${entity} with the records and history its storage kept.`,
+            sql: [],
+        }));
+    }
+    // Kept fields that stay kept share the model; a refused rename must not meet one of them.
+    const active = (kind, name) => !stored.kept[kind].has(name) || stored.restoring[kind].has(name);
+    for (const property of pair.properties) {
+        const renamedProperty = before.properties.find(({ name }) => name === property.target.name && active("properties", name));
+        if (renamedProperty === undefined) {
+            continue;
+        }
+        const restored = pair.restoredFields.properties.has(property.target.name);
+        if (restored) {
+            draft.changes.push(step({
+                kind: "restoreProperty",
+                classification: "change",
+                description: `Restore property ${entity}.${property.target.name} with the values its column kept.`,
+                sql: [],
+            }));
+        }
+        planPropertyChange({
+            entity,
+            appliedEntity: pair.current.name,
+            appliedProperty: property.current.name,
+            before: renamedProperty,
+            after: property.target,
+            restored,
+            allowDrops,
+            draft,
+        });
+    }
+    for (const relationship of pair.relationships) {
+        const renamedRelationship = before.relationships.find(({ name }) => name === relationship.target.name && active("relationships", name));
+        if (renamedRelationship === undefined) {
+            continue;
+        }
+        const restored = pair.restoredFields.relationships.has(relationship.target.name);
+        if (restored) {
+            draft.changes.push(step({
+                kind: "restoreRelationship",
+                classification: "change",
+                description: `Restore relationship ${entity}.${relationship.target.name} with the links its storage kept.`,
+                sql: [],
+            }));
+        }
+        planRelationshipChange({
+            entity,
+            before: renamedRelationship,
+            after: relationship.target,
+            attached: !pair.restored && !restored,
+            draft,
+        });
+    }
+    for (const property of pair.addedProperties) {
+        if (property.type === "blob") {
+            draft.foreignKeys.push(step({
+                kind: "addProperty",
+                classification: "additive",
+                description: `Reference the file revision for ${entity}.${property.name}.`,
+                sql: [addConstraintStatement(table, blobForeignKey(entity, property))],
+            }));
+        }
+        const enumStorage = propertyEnum(entity, property);
+        const check = propertyCheck(entity, property);
+        const column = propertyColumn(entity, property);
+        const actions = [
+            `ADD COLUMN ${columnDefinition(column)}`,
+            ...(check === undefined ? [] : [`ADD ${constraintDefinition(check)}`]),
+        ];
+        draft.additions.push(step({
+            kind: "addProperty",
+            classification: "additive",
+            validatesData: column.notNull && column.default === undefined,
+            description: `Add property ${entity}.${property.name}.`,
+            sql: [
+                ...(enumStorage === undefined ? [] : [createEnumStatement(enumStorage)]),
+                alterTable(table, actions.join(", ")),
+            ],
+        }));
+    }
+    for (const relationship of pair.addedRelationships) {
+        if (relationship.cardinality !== "one") {
+            continue;
+        }
+        const column = relationshipColumn(relationship);
+        const key = relationshipForeignKey(entity, relationship);
+        draft.additions.push(step({
+            kind: "addRelationship",
+            classification: "additive",
+            validatesData: column.notNull,
+            description: `Add relationship ${entity}.${relationship.name} to ${relationship.to}.`,
+            sql: [
+                alterTable(table, `ADD COLUMN ${columnDefinition(column)}, ADD ${constraintDefinition(key)}`),
+            ],
+        }));
+    }
+    planIndexChanges({ pair, before: stored, appliedNames, draft });
+    if (pair.restored ||
+        pair.restoredFields.properties.size + pair.restoredFields.relationships.size > 0) {
+        planRestoredForeignKeys({ pair, before: stored, draft });
+    }
+}
+// New entities and join tables -------------------------------------------------------------------
+function planNewEntities(input) {
+    const { draft } = input;
+    const available = new Set(input.pairs.map((pair) => tableName(pair.target.name)));
+    const remaining = [...input.addedEntities];
+    while (remaining.length > 0) {
+        // Create an entity once every table it references exists; break a cycle at the first entity.
+        const ready = remaining.findIndex((candidate) => entityStorage(candidate).table.constraints.every((constraint) => constraint.references === undefined ||
+            constraint.references === tableName(candidate.name) ||
+            available.has(constraint.references)));
+        const [entity] = remaining.splice(ready === -1 ? 0 : ready, 1);
+        const storage = entityStorage(entity);
+        const deferred = storage.table.constraints.filter((constraint) => constraint.references !== undefined &&
+            constraint.references !== storage.table.name &&
+            !available.has(constraint.references));
+        const inline = storage.table.constraints.filter((constraint) => !deferred.includes(constraint));
+        draft.creates.push(step({
+            kind: "createEntity",
+            classification: "additive",
+            description: `Create entity ${entity.name}: table ${storage.table.name} and history ${storage.history.name}.`,
+            sql: [
+                ...storage.enums.map(createEnumStatement),
+                createTableStatement(storage.table, inline),
+                createTableStatement(storage.history),
+                ...storage.table.indexes.map((index) => createIndexStatement(index)),
+                ...storage.history.indexes.map((index) => createIndexStatement(index)),
+            ],
+        }));
+        for (const constraint of deferred) {
+            draft.foreignKeys.push(step({
+                kind: "addForeignKey",
+                classification: "additive",
+                description: `Add foreign key ${constraint.name} once ${constraint.references} exists.`,
+                sql: [addConstraintStatement(storage.table.name, constraint)],
+            }));
+        }
+        available.add(storage.table.name);
+    }
+}
+function planJoinTables(input) {
+    const added = [
+        ...input.pairs.map((pair) => ({ entity: pair.target, relationships: pair.addedRelationships })),
+        ...input.addedEntities.map((entity) => ({ entity, relationships: entity.relationships })),
+    ];
+    for (const { entity, relationships } of added) {
+        for (const relationship of relationships) {
+            if (relationship.cardinality !== "many") {
+                continue;
+            }
+            const join = joinTable(entity.name, relationship);
+            const name = `${entity.name}.${relationship.name}`;
+            input.draft.joins.push(step({
+                kind: "addRelationship",
+                classification: "additive",
+                description: `Add relationship ${name} to ${relationship.to}: join table ${join.name}.`,
+                sql: [
+                    createTableStatement(join),
+                    ...join.indexes.map((index) => createIndexStatement(index)),
+                ],
+            }));
+        }
+    }
+}