@snolla/data 0.0.0-stage → 1.0.7

package/dist/migrations/siteid.mjs

@@ -0,0 +1,512 @@
+// SiteId migration planner (task:3872, plan:48 Q5.3, requirements:64 п.1).
+//
+// The production copy is the LEGACY schema: the tables that always carried
+// `SiteId` still do, the other canon site tables do not, `Sites` has no
+// `Kind`/`Writable`. A
+// site cannot be exported from that source — the transfer's guard scopes every
+// read by `SiteId`. This module turns the canon plus a live introspection of the
+// source into a deterministic migration plan, in the order a cutover needs:
+//
+//   1. add the missing `SiteId` columns (nullable);
+//   2. resolve the tenant key in ONE parents-first schedule: each table's parent edges as a CHAIN
+//      ordered by class (canonical hard FK, the source's own FK, the naming convention) where a
+//      link only fills what the previous one left NULL, interleaved with the polymorphic roots
+//      (Gallery / Modules / numbering / watermarks, each root planted once every table its
+//      `resolvers` read carries a site); nothing is parked on a sentinel (task:4092);
+//   3. enforce `NOT NULL` + index on every added column;
+//   4. add `Sites.Writable`, then NOT NULL + index — a table still holding rows with no site is
+//      refused by name, not parked;
+//
+// The plan is pure data — no database — so it is testable and reviewable; the
+// schema is the authority (a table that only exists in the legacy source is never
+// planned), and anything the FK chain cannot reach is reported, not guessed away.
+import { createRequire } from 'node:module';
+import { canonicalSchema, isSiteScoped } from "../schema/index.js";
+const require = createRequire(import.meta.url);
+const ownerSpec = require('../scripts/owners/owner-resolve-spec.json');
+// Polymorphic roots: a site table whose site cannot be read off a single hard FK
+// (a polymorphic owner, a seed, or a union of template tables). The resolver contract lives in
+// `owner-resolve-spec.json`; anything else unresolved is a bug.
+// `Folders` belongs here for the same reason as `Gallery`: its owner is the legacy
+// `IAssetsOwner` (13 implementors, id-probe) — the canon has no FK for it, so the planner used
+// to hand every folder to the sweep (task:3976).
+export const POLY_ROOTS = ['Folders', 'Gallery', 'Modules', '_Modules', 'NumberingCounters', 'GalleryImageSizeWatermark', 'GalleryImagesTemplates'];
+/**
+ * The roots that declare `siteFrom: 'none'`: a dictionary with no owner column that nobody
+ * populates, so it has no site of its own and every row it holds would be the sweep's. The claim
+ * is only true while the table is empty — `declaredNoneWithRows` is where the plan checks it
+ * against the source instead of trusting a snapshot of the spec (task:3998).
+ */
+export const declaredNoneTables = (spec = ownerSpec) => Object.entries(spec.polyRoots ?? {})
+    .filter(([, root]) => root?.siteFrom === 'none')
+    .map(([name]) => name);
+/**
+ * The order oracle (task:3998): every link must read a parent that carries a site EARLIER in the
+ * schedule.
+ *
+ * Readiness inside the planner is a membership question ("is the parent in `resolved`"), and a
+ * set cannot tell earlier from later. The rendered plan is a sequence of UPDATEs, so a link whose
+ * parent is planted after it joins against a still-NULL key and the row is quarantined for no
+ * reason — the defect of task:3891, one level down. Positions, not sets, are what the renderer
+ * obeys; this is the check that says so.
+ */
+export const misorderedLinks = (schedule) => {
+    const position = new Map();
+    schedule.forEach((op, index) => {
+        if (!position.has(op.table))
+            position.set(op.table, index);
+    });
+    const found = [];
+    schedule.forEach((op, index) => {
+        for (const link of op.links ?? []) {
+            const parentAt = position.get(link.parent);
+            // no position: the parent carried SiteId before the schedule started, or it is not a
+            // site table at all — neither is an order this run can get wrong
+            if (parentAt !== undefined && parentAt > index)
+                found.push({ table: op.table, parent: link.parent });
+        }
+    });
+    return found;
+};
+/**
+ * Parents-first order over the hard FKs between the site tables — the mirror of the transfer's
+ * insert order, and the order a purge has to REVERSE: a child dies before its parent, or the
+ * foreign key refuses the delete.
+ */
+const siteFkOrder = (tables) => {
+    const byName = new Map(tables.map((table) => [table.name, table]));
+    const parentsOf = (name) => (byName.get(name)?.fks ?? [])
+        .filter((fk) => !fk.soft && fk.ref !== name && byName.has(fk.ref))
+        .map((fk) => fk.ref);
+    const order = [];
+    const seen = new Set();
+    while (order.length < tables.length) {
+        const ready = tables.filter((table) => !seen.has(table.name) && parentsOf(table.name).every((parent) => seen.has(parent)));
+        // a hard cycle cannot be ordered; take the canon order for what is left rather than spin
+        const batch = ready.length ? ready : tables.filter((table) => !seen.has(table.name));
+        for (const table of batch) {
+            seen.add(table.name);
+            order.push(table);
+        }
+    }
+    return order;
+};
+/** The canon as the production copy looked before the migration. */
+export const legacyFromCanon = (canon = canonicalSchema) => {
+    const tables = {};
+    for (const table of canon.tables) {
+        const columns = Object.keys(table.columns).filter((name) => {
+            if (table.siteIdAdded && name === 'SiteId')
+                return false;
+            if (table.name === 'Sites' && name === 'Writable')
+                return false;
+            return true;
+        });
+        tables[table.name] = {
+            columns,
+            pk: Object.entries(table.columns).find(([, column]) => column.pk === true)?.[0] ?? null,
+            // the legacy schema has no soft references — those are a canon construct
+            fks: (table.fks ?? [])
+                .filter((fk) => !fk.soft)
+                .map((fk) => ({ columns: fk.columns, ref: fk.ref, refColumns: fk.refColumns })),
+        };
+    }
+    return { dialect: 'mssql', tables };
+};
+/** Introspection: `{ dialect, tables: { Name: { columns, pk, fks } } }` — from a live source or the synthetic one. */ export const planSiteIdMigration = ({ canon = canonicalSchema, introspection, spec = ownerSpec } = {}) => {
+    if (!introspection?.tables)
+        throw new Error('plan: a source introspection is required');
+    const source = introspection.tables;
+    const site = canon.tables.filter((t) => isSiteScoped(t) && source[t.name]);
+    const siteNames = new Set(site.map((t) => t.name));
+    const hasSiteId = (name) => (source[name]?.columns ?? []).includes('SiteId');
+    const addColumns = site
+        .filter((t) => !hasSiteId(t.name))
+        .map((t) => ({ op: 'addColumn', table: t.name, column: 'SiteId', columnType: 'uuid' }));
+    // ---- edges: canon hard FKs + live FKs + convention (`XxxId` == a table PK) --
+    // An edge is one way to read a site off a parent, and a table may have several. The CLASS is
+    // the whole point: a canonical hard FK is the declared owner, a live FK is the source's own
+    // constraint, the naming convention is the last resort. The chain is ordered by it
+    // (task:3894 — the planner used to keep the FIRST arc the graph happened to walk and drop the
+    // rest: `ProductTypes` resolved through an empty `CustomCategoryTypes` while its canonical
+    // `Stores` edge was never emitted, and 24/24 rows went to the sentinel with the correct
+    // answer one edge away).
+    const CANON_FK = 0;
+    const LIVE_FK = 1;
+    const CONVENTION = 2;
+    const edgeByKey = new Map();
+    let declaration = 0;
+    const addEdge = (rawRank, parent, table, childKey, parentKey) => {
+        // a half-edge is nothing to join on, and a key that points at ITSELF (`SiteId` -> `Sites.SiteId`)
+        // plants no site — it is already one
+        if (!parent || !table || !childKey || !parentKey)
+            return;
+        // a table's own hierarchy IS a path (task:4092): a `ContentPageParts` row inherits the site
+        // of its parent PART, so the self-edge runs LAST — after the table has been planted from
+        // its real parents — and only fills what is still NULL
+        const rank = parent === table ? CONVENTION + 1 : rawRank;
+        const key = `${parent}|${table}|${childKey}|${parentKey}`;
+        // the same join seen from two classes is one join — the better class wins, or the plan
+        // would render the same UPDATE twice
+        if (edgeByKey.has(key))
+            return;
+        // canonical edges keep the order the canon declares them in — for one child that order is
+        // the ranking within the class (the owner column is declared before the weaker link)
+        edgeByKey.set(key, { rank, order: rank === CANON_FK ? declaration++ : Number.MAX_SAFE_INTEGER, parent, table, childKey, parentKey });
+    };
+    for (const table of canon.tables) {
+        for (const fk of table.fks ?? [])
+            if (!fk.soft)
+                addEdge(CANON_FK, fk.ref, table.name, fk.columns[0], fk.refColumns[0]);
+    }
+    for (const [name, info] of Object.entries(source)) {
+        for (const fk of info.fks ?? [])
+            addEdge(LIVE_FK, fk.ref, name, fk.columns[0], fk.refColumns[0]);
+    }
+    const pkOf = new Map(Object.entries(source).map(([name, info]) => [name, info.pk]));
+    for (const [name, info] of Object.entries(source)) {
+        for (const column of info.columns) {
+            if (column === 'SiteId')
+                continue;
+            const stem = column.replace(/_?Id$/, '');
+            if (!stem || stem === column)
+                continue;
+            // a convention edge is only safe when exactly ONE canon table has that
+            // primary key — `TemplateId` points at half a dozen tables otherwise
+            const candidates = [...pkOf].filter(([candidate, pk]) => pk === column && candidate !== name && siteNames.has(candidate));
+            if (candidates.length === 1)
+                addEdge(CONVENTION, candidates[0][0], name, column, column);
+        }
+    }
+    const compareEdges = (a, b) => a.rank - b.rank
+        || a.order - b.order
+        || a.parent.localeCompare(b.parent)
+        || a.childKey.localeCompare(b.childKey);
+    const linksInto = new Map();
+    for (const edge of [...edgeByKey.values()].sort(compareEdges)) {
+        if (!linksInto.has(edge.table))
+            linksInto.set(edge.table, []);
+        linksInto.get(edge.table).push(edge);
+    }
+    // ---- the schedule: chains parents-first, interleaved with the polymorphic roots -----
+    // `schedule` is the ORDER, and it is the only one: a table may join a parent only after that
+    // parent carries a site. Rendering the joins as one block and the roots as another (the shape
+    // this replaced) backfilled GalleryImage/GalleryImageSize/Watermark/ModuleProperties from a
+    // parent that was still NULL, and the sweep then parked whole families in quarantine
+    // (task:3891). The same discipline now covers a table's SECOND parent: a fallback that runs
+    // before its primary reads a NULL, and the row is quarantined for no reason (task:3894).
+    //
+    // `plantable` OVER-approximates on purpose: it is reachability with the order ignored, so a
+    // pure FK cycle whose members only reach each other is plantable and still unresolvable — it
+    // is reported in `unresolved` (as it must be: nothing in the cycle carries a site) rather
+    // than stepped with an empty chain.
+    // "The column exists" and "the rows carry a site" are two different facts (task:4092):
+    // `FeedPages`, `ContentPageParts` and `_Templates` carry `SiteId` in the legacy source and were
+    // therefore given no step at all — whatever stayed NULL went to the sentinel. A table needs a
+    // step whenever some parent can hand it a site. "No parent" means: no FK to a
+    // site table, no live FK, no convention edge, no poly spec link — the DSL treats `SiteId` as the
+    // tenant key itself, so the Blog/Catalog/Store families declare nothing to inherit from. With the
+    // key already in the source they are self-evident (their rows were scoped before this migration);
+    // without it they are `unresolved` and the run refuses instead of inventing a site (task:4092).
+    const parentsOf = (name) => (linksInto.get(name) ?? []).filter((edge) => edge.parent !== 'Sites' && siteNames.has(edge.parent));
+    const siteOrder = site.map((t) => t.name);
+    const selfEvident = new Set(siteOrder.filter((name) => hasSiteId(name) && !parentsOf(name).length && !POLY_ROOTS.includes(name)));
+    const resolved = new Set(['Sites', ...selfEvident]);
+    const ordered = site.map((t) => t.name);
+    const declaredNone = (name) => spec.polyRoots?.[name]?.siteFrom === 'none';
+    // A root is READY only when every table its resolvers read carries a site:
+    // `GalleryImageSizeWatermark` hangs off `GalleryImageSize`, which is itself a child of the
+    // `Gallery` root. Planting it in the same round as `Gallery` would read a NULL from a parent
+    // planted later — the defect of task:3891, one level deeper (task:3876).
+    const polyReady = (name, carries) => {
+        const links = polyLinks(name, spec);
+        if (!links.length)
+            return declaredNone(name);
+        return links.every((link) => carries.has(link.table));
+    };
+    // Which added tables can EVER carry a site — pure reachability over the edge graph, no order.
+    // An edge from a table that never carries one (`Administrators`) is not a path, and neither is
+    // an arc into a table with no path of its own: `resolved` means "the plan carries a path",
+    // never "the graph found an arc" (task:3894).
+    const plantable = new Set(resolved);
+    for (;;) {
+        let changed = false;
+        for (const name of ordered) {
+            if (plantable.has(name) || selfEvident.has(name))
+                continue;
+            const reachable = POLY_ROOTS.includes(name)
+                ? polyReady(name, plantable)
+                : (linksInto.get(name) ?? []).some((edge) => plantable.has(edge.parent));
+            if (reachable) {
+                plantable.add(name);
+                changed = true;
+            }
+        }
+        if (!changed)
+            break;
+    }
+    const schedule = [];
+    const pending = new Set(ordered.filter((name) => !selfEvident.has(name)));
+    // A chain step links only the parents that ALREADY carry a site: every other parent is either
+    // still to come (then the table waits for it) or has no path at all (then it is no link).
+    const linkKey = (link) => `${link.parent}|${link.childKey}|${link.parentKey}`;
+    const linksOf = (name) => (linksInto.get(name) ?? [])
+        .filter((edge) => edge.parent === name || resolved.has(edge.parent))
+        .map((edge) => ({ parent: edge.parent, childKey: edge.childKey, parentKey: edge.parentKey }));
+    // Which links a table has already been given: a cycle break emits a partial chain, and the
+    // rest is a catch-up step later, never a link emitted twice.
+    const linked = new Map();
+    const step = (name) => {
+        pending.delete(name);
+        resolved.add(name);
+        const links = linksOf(name);
+        const seen = linked.get(name) ?? new Set();
+        linked.set(name, seen);
+        for (const link of links)
+            seen.add(linkKey(link));
+        schedule.push({ op: 'backfillJoin', table: name, links });
+    };
+    for (;;) {
+        let progress = false;
+        // A table waits for EVERY parent its chain will read that can carry a site.
+        for (;;) {
+            const ready = ordered.filter((name) => pending.has(name) && !POLY_ROOTS.includes(name) && plantable.has(name)
+                && (linksInto.get(name) ?? []).filter((edge) => plantable.has(edge.parent) && edge.parent !== name).every((edge) => resolved.has(edge.parent)));
+            if (!ready.length)
+                break;
+            for (const name of ready) {
+                step(name);
+                progress = true;
+            }
+        }
+        for (const name of ordered.filter((n) => pending.has(n) && POLY_ROOTS.includes(n) && polyReady(n, resolved))) {
+            const links = polyLinks(name, spec);
+            // A root may declare that it has no site of its own (`siteFrom: 'none'`) — a
+            // dictionary with no owner column that nobody populates. Then there is nothing to
+            // resolve, and the sweep is the whole answer. A root that is neither linked nor
+            // declared cannot be resolved at all: it is reported so the run refuses (the CLI
+            // exits on a non-empty `unresolved`) instead of quietly handing a whole family to
+            // the quarantine site.
+            pending.delete(name);
+            resolved.add(name);
+            schedule.push({ op: 'backfillPoly', table: name, links, declaredNone: declaredNone(name) });
+            // A root is not ONLY its owner probe: `Folders` also hangs off `*_ThemeId` (canon FK),
+            // and a theme folder carries no owner at all. Leaving the chained half out dropped 768
+            // theme folders — and the 10 827 files beneath them — into the purge (task:3976).
+            const chained = linksOf(name).map((link) => ({ parent: link.parent, childKey: link.childKey, parentKey: link.parentKey }));
+            if (chained.length) {
+                const seen = linked.get(name) ?? new Set();
+                linked.set(name, seen);
+                for (const link of chained)
+                    seen.add(linkKey(link));
+                schedule.push({ op: 'backfillJoin', table: name, links: chained });
+            }
+            progress = true;
+        }
+        if (progress)
+            continue;
+        // Work is left and nothing is ready: the remaining tables wait on each other (a mutual FK
+        // pair — `FeedParams`/`FeedPageParams`). One deterministic step (canon order) breaks the
+        // cycle, so an honest plan always exists and the run terminates. A POLYMORPHIC root is
+        // never a candidate: its site comes from its own contract, and guessing one off a passing
+        // FK is exactly the silent guess task:3891 removed. A pair with no root at all has no
+        // site to inherit (that is not a cycle to break) and lands in `unresolved`.
+        const stuck = ordered.find((name) => pending.has(name) && plantable.has(name) && !POLY_ROOTS.includes(name)
+            && (linksInto.get(name) ?? []).some((edge) => resolved.has(edge.parent)));
+        if (stuck === undefined)
+            break;
+        step(stuck);
+    }
+    // A table stepped by the cycle break linked only what carried a site at that moment, so its
+    // remaining parents — resolved by now, every table that can carry a site is — are emitted as
+    // ONE catch-up step at the end. A fallback link that never runs leaves rows in quarantine the
+    // plan itself could have resolved (task:3894). A table that is never stepped at all has no
+    // resolved parent (or it would be plantable), so nothing is emitted for it here.
+    for (const name of ordered) {
+        // self-evident tables were given no step on purpose: they have no parent to inherit from
+        if (pending.has(name) || selfEvident.has(name) || POLY_ROOTS.includes(name))
+            continue;
+        const seen = linked.get(name) ?? new Set();
+        const missing = linksOf(name).filter((link) => !seen.has(linkKey(link)));
+        if (missing.length)
+            schedule.push({ op: 'backfillJoin', table: name, links: missing });
+    }
+    const unresolved = [...pending].sort();
+    // The plan's two named views of the schedule. They are derived, never accumulated
+    // separately: a second list is a second order, and the second order was wrong.
+    const backfills = schedule.filter((op) => op.op === 'backfillJoin');
+    const poly = schedule.filter((op) => op.op === 'backfillPoly');
+    // There is NO sweep and no sentinel (task:4092). A row that ends the run without a site is a
+    // missing edge in the resolver graph, not data to be filed away: parking it made the loss
+    // invisible (169 175 rows on a green run) and hid the real defect — two tables that already
+    // carried `SiteId` were never backfilled at all. The renderer refuses instead, naming the
+    // table, and `renderPurgeMssql` deletes only what an operator explicitly condemns.
+    const purge = [...siteFkOrder(site)].reverse().map((table) => ({ op: 'purgeNull', table: table.name, pk: pkOf.get(table.name) ?? null }));
+    // NOT NULL and the index are the target shape for EVERY site table, not only the ones this run
+    // gave a column to: a key the catalog still reports nullable is the same defect as a missing one
+    // (task:4092). The canon says NOT NULL everywhere, so the migration owes the database that shape.
+    const siteNamesSorted = [...siteNames].sort();
+    const keyIsNullable = (name) => !hasSiteId(name) || source[name]?.nullable?.SiteId === true;
+    // An index on the key blocks the ALTER (SQL Server 4922), so it comes off first and goes back
+    // afterwards — with the definition the catalog gave, not one the canon guessed: `UK1_Pages` is a
+    // business rule (unique per site and path) and dropping it for good would be silent damage.
+    const indexesOnKey = (name) => (source[name]?.indexes ?? [])
+        .filter((ix) => ix.columns.some((column) => column.name === 'SiteId') || (ix.include ?? []).includes('SiteId'))
+        .map((ix) => ({
+        name: ix.name,
+        unique: Boolean(ix.unique),
+        constraint: Boolean(ix.constraint),
+        columns: ix.columns,
+        include: ix.include ?? [],
+        filter: ix.filter ?? null,
+    }));
+    const notNull = siteNamesSorted
+        .filter(keyIsNullable)
+        .map((table) => ({ op: 'setNotNull', table, column: 'SiteId', rebuild: indexesOnKey(table) }));
+    const indexes = siteNamesSorted.map((table) => ({ op: 'createIndex', table, column: 'SiteId', name: `IX_${table}_SiteId` }));
+    // A declared-none root is a promise that the table is empty. Check it against the source the
+    // plan was built from (the CLI measures those tables with `introspect({ countRows })`), because
+    // the promise was otherwise only compared with a snapshot in `owner-spec-check` — and a row in
+    // a dictionary believed empty goes to the quarantine with nothing in the run to notice
+    // (task:3998). The plan still carries the step; the CLI is where the run is refused.
+    const rowCounts = introspection.rowCounts ?? {};
+    const declaredNoneWithRows = declaredNoneTables(spec)
+        .filter((name) => source[name])
+        .map((name) => ({ table: name, rows: Number(rowCounts[name] ?? 0) }))
+        .filter((entry) => entry.rows > 0);
+    const misordered = misorderedLinks(schedule);
+    return {
+        addColumns,
+        // the order a run must follow: joins and poly roots interleaved parents-first
+        schedule,
+        selfEvident: [...selfEvident].sort(),
+        backfills,
+        poly,
+        purge,
+        notNull,
+        indexes,
+        registry: {
+            addColumns: [
+                { op: 'addColumn', table: 'Sites', column: 'Writable', columnType: 'bool' },
+            ],
+            default: { op: 'backfillRegistry', table: 'Sites', writable: true },
+        },
+        unresolved,
+        declaredNoneWithRows,
+        misordered,
+        summary: {
+            added: addColumns.length,
+            chained: backfills.length,
+            links: backfills.reduce((total, op) => total + op.links.length, 0),
+            polymorphic: poly.length,
+            purge: purge.length,
+            notNull: notNull.length,
+            unresolved: unresolved.length,
+            declaredNoneWithRows: declaredNoneWithRows.length,
+            misordered: misordered.length,
+        },
+    };
+};
+/**
+ * The `(owner column -> table, pk)` links a polymorphic root resolves through.
+ *
+ * The spec is the contract (task:3876): a root declares its `resolvers` explicitly — a parent
+ * chain for watermarks, the soft owner references for counters, the polymorphic owner list for
+ * galleries and modules. There is NO fallback: a root the spec does not describe resolves through
+ * nothing, lands in `unresolved`, and the CLI refuses to run the plan — a spec edit that forgets a
+ * root must fail loudly, not silently probe whatever `observedOwners` happened to list first
+ * (task:3895: `Gallery` and `_Modules` leaned on exactly that implicit order).
+ */
+export const polyLinks = (name, spec) => (spec.polyRoots?.[name]?.resolvers ?? []).filter((link) => link?.column && link?.table && link?.pk);
+/** MSSQL rendering of the plan — the source dialect of a cutover. */
+const dropIndexSql = (table, index) => (index.constraint
+    ? `ALTER TABLE [dbo].[${table}] DROP CONSTRAINT [${index.name}];`
+    : `DROP INDEX [${index.name}] ON [dbo].[${table}];`);
+const createIndexSql = (table, index) => {
+    const columns = index.columns.map((column) => `[${column.name}]${column.descending ? ' DESC' : ''}`).join(', ');
+    const include = index.include?.length ? ` INCLUDE (${index.include.map((name) => `[${name}]`).join(', ')})` : '';
+    const filter = index.filter ? ` WHERE ${index.filter}` : '';
+    return index.constraint
+        ? `ALTER TABLE [dbo].[${table}] ADD CONSTRAINT [${index.name}] UNIQUE (${columns});`
+        : `CREATE ${index.unique ? 'UNIQUE ' : ''}INDEX [${index.name}] ON [dbo].[${table}] (${columns})${include}${filter};`;
+};
+export const renderMssql = (plan) => {
+    const lines = ['-- snolla: SiteId migration (generated from the canon, task:3872). Run on a COPY.', ''];
+    const mssqlType = (type) => ({ uuid: 'UNIQUEIDENTIFIER', string: 'NVARCHAR(20)', bool: 'BIT' })[type] ?? 'NVARCHAR(255)';
+    // the plan states the tenant key's type once; step 1 and step 5 must not be able to disagree
+    // about it (task:3898: step 5 hardcoded UNIQUEIDENTIFIER while step 1 read the spec)
+    const keyTypes = new Map(plan.addColumns.map((op) => [op.table, op.columnType]));
+    const [writableColumn] = plan.registry.addColumns.map((op) => op.column);
+    const literal = (value) => (typeof value === 'boolean' ? (value ? 1 : 0) : `'${value}'`);
+    // every step below is guarded: a rehearsal is re-run after an interruption, and the purge is a
+    // decision taken after the apply — neither may need the whole plan to be a no-op (task:3996)
+    lines.push('-- step 1: add the tenant key (nullable first)');
+    for (const op of plan.addColumns) {
+        lines.push(`IF COL_LENGTH('dbo.${op.table}','SiteId') IS NULL ALTER TABLE [dbo].[${op.table}] ADD [SiteId] ${mssqlType(op.columnType)} NULL;`);
+    }
+    lines.push('', '-- step 2: resolve the tenant key parents-first — a polymorphic root plants its\n-- children, so the root is resolved BEFORE the joins that read it (task:3891)');
+    for (const op of plan.schedule) {
+        if (op.op === 'backfillJoin') {
+            if ((op.links ?? []).length > 1) {
+                lines.push(`-- [dbo].[${op.table}]: ${op.links.length} candidate parents, the declared owner first;\n-- each fallback only fills what the previous link left NULL (task:3894)`);
+            }
+            for (const link of op.links ?? []) {
+                // `SiteId -> Sites.SiteId` is the key reading itself: it carries the table in the
+                // readiness graph, and it writes nothing
+                if (link.childKey === 'SiteId' && link.parentKey === 'SiteId')
+                    continue;
+                lines.push(`UPDATE c SET c.[SiteId] = p.[SiteId] FROM [dbo].[${op.table}] c JOIN [dbo].[${link.parent}] p ON p.[${link.parentKey}] = c.[${link.childKey}] WHERE c.[SiteId] IS NULL;`);
+            }
+            continue;
+        }
+        const links = (op.links ?? []).filter((link) => link.table && link.pk && link.column);
+        if (!links.length) {
+            lines.push(op.declaredNone
+                ? `-- DECLARED NONE: [dbo].[${op.table}] carries no site of its own (owner-resolve-spec siteFrom: none) — any row it holds is the sweep's.`
+                : `-- MANUAL: [dbo].[${op.table}] — no single owner column in the spec; resolve from the legacy link (owner-resolve-spec.json).`);
+        }
+        for (const link of links) {
+            lines.push(`UPDATE c SET c.[SiteId] = o.[SiteId] FROM [dbo].[${op.table}] c JOIN [dbo].[${link.table}] o ON o.[${link.pk}] = c.[${link.column}] WHERE c.[SiteId] IS NULL;`);
+        }
+    }
+    lines.push('', '-- step 3: the registry flag — every real site is writable (nothing is parked, task:4092)');
+    // the registry DDL is rendered from `plan.registry`: the plan states it, the renderer prints it
+    // (task:3898 — the same DDL written in two places drifts apart silently)
+    for (const op of plan.registry.addColumns) {
+        lines.push(`IF COL_LENGTH('dbo.${op.table}','${op.column}') IS NULL ALTER TABLE [dbo].[${op.table}] ADD [${op.column}] ${mssqlType(op.columnType)} NULL;`);
+    }
+    lines.push(`UPDATE [dbo].[${plan.registry.default.table}] SET [${writableColumn}] = ${literal(plan.registry.default.writable)};`);
+    lines.push('', '-- step 4: enforce NOT NULL + index — a table still holding rows with no site THROWS and', '-- names itself. A dangling row is a missing edge in the resolver graph (task:4092); parking', '-- it on a sentinel site is what made the loss invisible while the run reported green.');
+    for (const op of plan.notNull) {
+        lines.push(`IF EXISTS (SELECT 1 FROM [dbo].[${op.table}] WHERE [SiteId] IS NULL) THROW 50000, '${op.table}: rows with no site — fix the edge (owner-resolve-spec / canon FK), do not park them', 1;`);
+        // an index that sits on the key blocks the ALTER (4922): off, tighten, back on — the definition
+        // is the catalog's, so a legacy unique constraint survives the trip
+        for (const index of op.rebuild ?? [])
+            lines.push(dropIndexSql(op.table, index));
+        lines.push(`ALTER TABLE [dbo].[${op.table}] ALTER COLUMN [SiteId] ${mssqlType(keyTypes.get(op.table) ?? 'uuid')} NOT NULL;`);
+        for (const index of op.rebuild ?? [])
+            lines.push(createIndexSql(op.table, index));
+    }
+    for (const op of plan.indexes) {
+        lines.push(`IF NOT EXISTS (SELECT 1 FROM sys.indexes WHERE [name] = '${op.name}' AND [object_id] = OBJECT_ID('dbo.${op.table}')) CREATE INDEX [${op.name}] ON [dbo].[${op.table}] ([SiteId]);`);
+    }
+    return lines.join('\n') + '\n';
+};
+/**
+ * The explicit deletion pass (task:3976, reshaped by task:4092) — the destructive half, rendered
+ * separately on purpose.
+ *
+ * It deletes exactly the rows the plan could not place, and nothing else: no sentinel site, no
+ * invented tenant. Children first — the order is the reverse of the parents-first one, because a
+ * hard FK refuses the other order. An operator runs this only after reading the refusal the
+ * cutover SQL raised: every run of it is a decision that these rows are dead, not misplaced.
+ */
+export const renderPurgeMssql = (plan) => {
+    const lines = ['-- snolla: delete the rows with no site (task:4092). Children first — a hard FK refuses the other order.', ''];
+    for (const op of plan.purge ?? []) {
+        if (!op.pk)
+            continue;
+        lines.push(`DELETE FROM [dbo].[${op.table}] WHERE [SiteId] IS NULL;`);
+    }
+    return lines.join('\n') + '\n';
+};

package/dist/publish.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/publish.js

@@ -0,0 +1 @@
+export {};

package/dist/schema/dsl.d.ts

@@ -0,0 +1,64 @@
+export declare const CANON_TYPES: readonly ["uuid", "string", "text", "int", "bigint", "bool", "decimal", "datetime", "date", "binary", "json", "enum"];
+export type CanonType = (typeof CANON_TYPES)[number];
+/**
+ * How a row gets into a database during a move (task:3936, design wiki:3874 §2).
+ *
+ * One schema serves every mode — a row is not in "another database" because of its
+ * scope. The labels say how a transfer brings it along:
+ *   * `site` — carried by the row's own `SiteId`, with the tenant's ordinary tables;
+ *   * `control` / `registry` / `dictionary` — carries no `SiteId`; provisioned by the
+ *     rows that reference it (or by the cutover), so a bundle does not carry it whole.
+ */
+export type TableScope = 'site' | 'control' | 'registry' | 'dictionary';
+export interface ColumnSpec {
+    type: CanonType;
+    /** for `string`: max characters (dialect-neutral, characters not bytes). */
+    length?: number;
+    /** for `decimal`: total digits. */
+    precision?: number;
+    /** for `decimal`: digits after the point. */
+    scale?: number;
+    /** default false — NOT NULL unless stated otherwise. */
+    nullable?: boolean;
+    pk?: boolean;
+    /** canonical default expression in canon form (dialect-neutral), if any. */
+    default?: string;
+}
+export interface IndexSpec {
+    columns: string[];
+    unique?: boolean;
+}
+export interface FkSpec {
+    columns: string[];
+    ref: string;
+    refColumns: string[];
+    /**
+     * Soft reference (plan:48 R1-Q3): the column keeps pointing at a
+     * control-plane row but the FK is not enforced in the site database —
+     * audit links to `Administrators` and the like.
+     */
+    soft?: boolean;
+}
+export interface TableSpec {
+    name: string;
+    scope: TableScope;
+    /** true for the 81 tables that gain `SiteId` during the migration. */
+    siteIdAdded?: boolean;
+    columns: Record<string, ColumnSpec>;
+    indexes?: IndexSpec[];
+    fks?: FkSpec[];
+}
+export interface SiteSeed {
+    SiteId: string;
+    Alias: string;
+    Title: string;
+    Writable: boolean;
+    Live: boolean;
+    Production: boolean;
+}
+export interface CanonSchema {
+    /** revision of the canon; a bump is a migration (plan:49 Q5). */
+    version: number;
+    tables: TableSpec[];
+}
+export declare const isSiteScoped: (t: TableSpec) => boolean;

package/dist/schema/dsl.js

@@ -0,0 +1,28 @@
+// Canonical schema DSL (task:3812, R2 decisions — plan:49 Q2/Q3/Q4).
+//
+// THE canon is a typed, dialect-neutral description of the product schema.
+// Generators derive from it (task:3820): Kysely `Database` types, per-dialect
+// DDL, the temporary Prisma bridge. Nothing else may describe the schema —
+// hand-written duplicates are what this file exists to remove.
+//
+// Conventions:
+//   * identifiers are PascalCase, exactly as in the legacy DB (plan:49 Q3) —
+//     no renaming tax in ETL or in diffing against the live database;
+//   * column types come from the 12-type vocabulary below (plan:49 Q4); a type
+//     outside it is a canon bug, not a convenience;
+//   * `nullable: false` is the default: a nullable column says so explicitly.
+export const CANON_TYPES = [
+    'uuid',
+    'string',
+    'text',
+    'int',
+    'bigint',
+    'bool',
+    'decimal',
+    'datetime',
+    'date',
+    'binary',
+    'json',
+    'enum',
+];
+export const isSiteScoped = (t) => t.scope === 'site';

package/dist/schema/generate.d.mts

@@ -0,0 +1,14 @@
+export const DIALECTS: string[];
+export function mapType(column: any, dialect: any): any;
+/** Postgres refuses identifiers longer than 63 characters; it is the strictest dialect. */
+export const MAX_IDENTIFIER_LENGTH: 63;
+export function indexName(base: any, index?: number): any;
+export function constraintName(table: any, fk: any, index: any): any;
+export function renderDdlSql(dialect: any): string;
+export function renderDdlModule(): string;
+export function renderKyselyTypes(): string;
+export const ARTIFACTS: {
+    'ddl.ts': () => string;
+    'kysely-types.ts': () => string;
+};
+export function writeAll(): Promise<void>;