@snolla/data 0.0.0-stage → 1.0.7

package/dist/scripts/schema-lengths-audit.d.mts

@@ -0,0 +1,22 @@
+export function canonStringColumns(canon?: import("../schema/dsl.ts").CanonSchema): {
+    table: string;
+    column: string;
+    canon: number;
+}[];
+export function liveCharacterColumns(db: any): Promise<{
+    table: any;
+    column: any;
+    length: number;
+}[]>;
+export function isUnbounded(length: any): boolean;
+export function auditStringLengths(live: Array<{
+    table: string;
+    column: string;
+    length: number;
+}>, canon?: object): {
+    ok: boolean;
+    checked: number;
+    canonColumns: number;
+    canonOnly: object[];
+    violations: object[];
+};

package/dist/scripts/schema-lengths-audit.mjs

@@ -0,0 +1,146 @@
+// The live-width audit: verifier of task:3889 (the rehearsal incident where
+// `snolla site import` died on `value too long for type character varying(128)`).
+//
+//   MSSQL_DSN='Server=…;Database=MoreThenCms;User Id=sa;Password=…;' \
+//     node packages/data/scripts/schema-lengths-audit.mjs
+//
+// Why this exists
+// ---------------
+// The canon (`packages/data/schema/tables.ts`) was bootstrapped from the legacy
+// EF6 models, and its `string(n)` widths were taken from the *model*, not from
+// the physical database. On the live schema 402 character columns are declared
+// wider than the canon (usually exactly twice: 50→100, 64→128, 127→255), so a
+// bundle exported from the live data overflows the canon DDL on import. The live
+// schema is the source of truth for widths (plan:49 Q1), which makes the canon
+// the thing that must be widened — the rehearsal `widen.sql` was a workaround,
+// not a fix.
+//
+// This audit compares every `string(n)` column of the canon against the live
+// column of the same name. It is the oracle the widening is verified against:
+// exit 0 = the canon names exactly the live width.
+//
+// A canon `string(n)` column that does not exist in the live schema is NEW canon
+// data (`Sites.Writable`): reported as `canonOnly`, not a
+// violation — there is no live row to copy.
+//
+// Width rules:
+//   * `canon < live` — the incident: a bundle from the live data does not fit
+//     the canon DDL (task:3889);
+//   * `canon > live` — drift in the other direction; the source of truth says the
+//     wider canon is not what the data does, so it is a failure too (not silently
+//     "safe", because the next reader would trust it);
+//   * live unbounded (`nvarchar(max)` / `text`) against a bounded canon column —
+//     the canon declares a limit the data never had, so it is `canon < live`.
+//
+// Exit code 1 and a named list on any mismatch; exit 2 when `MSSQL_DSN` is not
+// set — an explicit refusal, never a silent green (plan:49 Q6).
+import { fileURLToPath } from 'node:url';
+import fs from 'node:fs';
+import path from 'node:path';
+import { sql } from 'kysely';
+import { canonicalSchema } from "../schema/index.js";
+/** Every `string(n)` column the canon declares, in canon order. */
+export const canonStringColumns = (canon = canonicalSchema) => {
+    const columns = [];
+    for (const table of canon.tables) {
+        for (const [column, spec] of Object.entries(table.columns)) {
+            if (spec.type === 'string' && spec.length !== undefined) {
+                columns.push({ table: table.name, column, canon: spec.length });
+            }
+        }
+    }
+    return columns;
+};
+/**
+ * The live schema's character columns, one object per column. Reading
+ * INFORMATION_SCHEMA keeps the audit independent of the ORM and of a physical
+ * connection shape: the column width is the fact under audit.
+ */
+export const liveCharacterColumns = async (db) => {
+    const result = await sql `
+        select TABLE_NAME as "table", COLUMN_NAME as "column", CHARACTER_MAXIMUM_LENGTH as "length"
+        from INFORMATION_SCHEMA.COLUMNS
+        where CHARACTER_MAXIMUM_LENGTH is not null
+    `.execute(db);
+    return result.rows.map((row) => ({
+        table: row.table,
+        column: row.column,
+        length: Number(row.length),
+    }));
+};
+/** A live width that cannot bound anything: `nvarchar(max)` (-1), `text` (2^31-1). */
+export const isUnbounded = (length) => length <= 0 || length >= 2 ** 31 - 1;
+/**
+ * Compare every canon `string(n)` against the live column of the same name.
+ *
+ * @param {Array<{table: string, column: string, length: number}>} live
+ * @param {object} [canon] schema to audit (default: the canon)
+ * @returns {{ok: boolean, checked: number, canonColumns: number, canonOnly: object[], violations: object[]}}
+ */
+export const auditStringLengths = (live, canon = canonicalSchema) => {
+    const byKey = new Map(live.map((entry) => [`${entry.table}.${entry.column}`, entry]));
+    const declared = canonStringColumns(canon);
+    const canonOnly = [];
+    const violations = [];
+    let checked = 0;
+    for (const { table, column, canon: expected } of declared) {
+        const actual = byKey.get(`${table}.${column}`);
+        if (!actual) {
+            canonOnly.push({ table, column, canon: expected });
+            continue;
+        }
+        checked += 1;
+        if (isUnbounded(actual.length)) {
+            violations.push({ check: 'canon-narrower-than-live', table, column, canon: expected, live: 'max' });
+        }
+        else if (actual.length > expected) {
+            violations.push({ check: 'canon-narrower-than-live', table, column, canon: expected, live: actual.length });
+        }
+        else if (actual.length < expected) {
+            violations.push({ check: 'canon-wider-than-live', table, column, canon: expected, live: actual.length });
+        }
+    }
+    return { ok: violations.length === 0, checked, canonColumns: declared.length, canonOnly, violations };
+};
+// ------------------------------------------------------------------ CLI ---
+const report = async () => {
+    const { openDb } = await import('../dbProvider.js');
+    const db = await openDb({ dialect: 'mssql', dsn: process.env.MSSQL_DSN });
+    try {
+        const result = auditStringLengths(await liveCharacterColumns(db));
+        console.log(`[lengths] canon string(n)=${result.canonColumns} checked=${result.checked} canon-only=${result.canonOnly.length}`);
+        if (result.ok) {
+            console.log('PASS schema-lengths audit: every string(n) names the live width');
+            return true;
+        }
+        console.error(`FAIL schema-lengths audit: ${result.violations.length} discrepancy(ies)`);
+        for (const v of result.violations.slice(0, 40)) {
+            console.error(`  - ${v.check} ${v.table}.${v.column}: canon ${v.canon}, live ${v.live}`);
+        }
+        if (result.violations.length > 40)
+            console.error(`  … and ${result.violations.length - 40} more`);
+        return false;
+    }
+    finally {
+        await db.destroy();
+    }
+};
+if (process.argv[1]) {
+    const self = fileURLToPath(import.meta.url);
+    let direct = false;
+    try {
+        // resolve symlinks when the entry path exists; fall back to a plain resolve
+        // when it does not, so a missing path never crashes the oracle.
+        direct = self === fs.realpathSync(process.argv[1]);
+    }
+    catch {
+        direct = self === path.resolve(process.argv[1]);
+    }
+    if (direct) {
+        if (!process.env.MSSQL_DSN) {
+            console.error('MSSQL_DSN is not set (connection string of the live MSSQL schema to audit)');
+            process.exit(2);
+        }
+        process.exit((await report()) ? 0 : 1);
+    }
+}

package/dist/scripts/siteid-migrate.d.mts

@@ -0,0 +1,7 @@
+export function introspect(db: any, { countRows }?: {
+    countRows?: any[];
+}): Promise<{
+    dialect: string;
+    tables: {};
+    rowCounts: {};
+}>;

package/dist/scripts/siteid-migrate.mjs

@@ -0,0 +1,260 @@
+// `snolla-data siteid-migrate` — the SiteId migration for a legacy source
+// (task:3872, plan:48 Q5.3). Read-only until `--apply`.
+//
+//   node packages/data/scripts/siteid-migrate.mjs --dsn "<mssql dsn>" [--out plan.sql] [--apply] //        [--purge --manifest <dir>]
+//
+// The plan comes from the canon (schema/index.ts) plus a live introspection of the
+// source; the source dialect is MSSQL (a cutover source is never a target). Dry-run
+// is the default: printing the plan is how a cutover is reviewed before a copy is
+// mutated. `--apply` runs the statements in order, on the connection given.
+//
+// `--purge` deletes the rows no resolution could place (task:3976, reshaped by task:4092): the
+// sentinel site is gone, so the leftovers are named by the cutover SQL and condemned by an explicit
+// flag. `--manifest <dir>` writes their primary keys to one CSV per table BEFORE anything is
+// removed — a purge nobody can audit is not a purge.
+import fs from 'node:fs';
+import { sql } from 'kysely';
+import { openDb } from '../dbProvider.js';
+import { canonicalSchema } from "../schema/index.js";
+import { planSiteIdMigration, declaredNoneTables, renderMssql, renderPurgeMssql } from '../migrations/siteid.mjs';
+const arg = (name, fallback = null) => {
+    const index = process.argv.indexOf(`--${name}`);
+    return index >= 0 ? (process.argv[index + 1] ?? true) : fallback;
+};
+/** The source as the planner needs it: tables, columns, PK, foreign keys — plus the row counts of
+ * the tables the spec believes empty, because "believes" is not a measurement (task:3998). */
+export const introspect = async (db, { countRows = [] } = {}) => {
+    const columns = await db
+        .selectFrom('information_schema.columns')
+        .select(['table_name', 'column_name', 'is_nullable'])
+        .where('table_schema', '=', 'dbo')
+        .execute();
+    const primary = await db
+        .selectFrom('information_schema.key_column_usage as k')
+        .innerJoin('information_schema.table_constraints as c', 'c.constraint_name', 'k.constraint_name')
+        .select(['k.table_name', 'k.column_name'])
+        .where('c.constraint_type', '=', 'PRIMARY KEY')
+        .where('k.ordinal_position', '=', 1)
+        .execute();
+    const foreign = await db
+        .selectFrom('sys.foreign_keys as fk')
+        .innerJoin('sys.foreign_key_columns as fkc', 'fkc.constraint_object_id', 'fk.object_id')
+        .innerJoin('sys.tables as pt', 'pt.object_id', 'fkc.parent_object_id')
+        .innerJoin('sys.columns as pc', (join) => join.onRef('pc.object_id', '=', 'fkc.parent_object_id').onRef('pc.column_id', '=', 'fkc.parent_column_id'))
+        .innerJoin('sys.tables as rt', 'rt.object_id', 'fkc.referenced_object_id')
+        .innerJoin('sys.columns as rc', (join) => join.onRef('rc.object_id', '=', 'fkc.referenced_object_id').onRef('rc.column_id', '=', 'fkc.referenced_column_id'))
+        .select(['pt.name as table_name', 'pc.name as column_name', 'rt.name as ref_table', 'rc.name as ref_column'])
+        .execute();
+    const tables = {};
+    const table = (name) => (tables[name] ??= { columns: [], nullable: {}, pk: null, fks: [], indexes: [] });
+    for (const row of columns) {
+        table(row.table_name).columns.push(row.column_name);
+        table(row.table_name).nullable[row.column_name] = row.is_nullable === 'YES';
+    }
+    for (const row of primary)
+        table(row.table_name).pk = row.column_name;
+    for (const row of foreign)
+        table(row.table_name).fks.push({ columns: [row.column_name], ref: row.ref_table, refColumns: [row.ref_column] });
+    // Indexes that sit ON the tenant key (task:4092): SQL Server refuses to tighten a column an
+    // index depends on (4922), so the plan has to take them off, tighten, and put them back. The
+    // definition comes from the catalog, never from the canon: a legacy unique index
+    // (`UK1_Pages`) is a business rule we must restore, not what the canon happens to declare.
+    const indexColumns = await db
+        .selectFrom('sys.indexes as i')
+        .innerJoin('sys.tables as t', 't.object_id', 'i.object_id')
+        .innerJoin('sys.index_columns as ic', (join) => join.onRef('ic.object_id', '=', 'i.object_id').onRef('ic.index_id', '=', 'i.index_id'))
+        .innerJoin('sys.columns as c', (join) => join.onRef('c.object_id', '=', 'ic.object_id').onRef('c.column_id', '=', 'ic.column_id'))
+        .select(['t.name as table_name', 'i.name as index_name', 'i.is_unique', 'i.is_unique_constraint', 'i.has_filter', 'i.filter_definition', 'c.name as column_name', 'ic.key_ordinal', 'ic.is_descending_key', 'ic.is_included_column'])
+        .where('i.is_primary_key', '=', false)
+        .where('i.is_hypothetical', '=', false)
+        .where('t.schema_id', '=', sql `schema_id('dbo')`)
+        .orderBy('i.name')
+        .orderBy('ic.key_ordinal')
+        .execute();
+    const indexByName = new Map();
+    for (const row of indexColumns) {
+        const key = `${row.table_name}|${row.index_name}`;
+        const ix = indexByName.get(key) ?? {
+            name: row.index_name,
+            unique: Boolean(row.is_unique),
+            constraint: Boolean(row.is_unique_constraint),
+            filter: row.has_filter ? row.filter_definition : null,
+            columns: [],
+            include: [],
+        };
+        indexByName.set(key, ix);
+        if (row.is_included_column)
+            ix.include.push(row.column_name);
+        else
+            ix.columns.push({ name: row.column_name, descending: Boolean(row.is_descending_key) });
+        const owner = table(row.table_name);
+        if (!owner.indexes.some((entry) => entry.name === ix.name))
+            owner.indexes.push(ix);
+    }
+    const rowCounts = {};
+    for (const name of countRows) {
+        // a table the source does not have is not counted: the plan never resolves one either
+        if (!tables[name])
+            continue;
+        const result = await sql `select count(*) as total from ${sql.id('dbo')}.${sql.id(name)}`.execute(db);
+        rowCounts[name] = Number(result.rows?.[0]?.total ?? 0);
+    }
+    return { dialect: 'mssql', tables, rowCounts };
+};
+/** Statement splitter: one statement at a time, comments dropped. */
+const statementsOf = (planSql) => planSql
+    .split(/\r?\n/)
+    .filter((line) => !line.trim().startsWith('--') && line.trim())
+    .join('\n')
+    .split(/;\s*\r?\n/)
+    .map((s) => s.trim())
+    .filter(Boolean);
+/**
+ * Writes the primary keys of everything the purge will remove, one CSV per table, and returns the
+ * row counts — the audit trail of an irreversible step (task:3976, reshaped by task:4092).
+ */
+const writeManifest = async (db, plan, dir) => {
+    if (!dir)
+        return {};
+    fs.mkdirSync(dir, { recursive: true });
+    const counts = {};
+    for (const op of plan.purge) {
+        if (!op.pk)
+            continue;
+        const rows = await db.selectFrom(op.table).select(op.pk).where('SiteId', 'is', null).execute();
+        if (!rows.length)
+            continue;
+        counts[op.table] = rows.length;
+        fs.writeFileSync(`${dir}/${op.table}.csv`, [op.pk, ...rows.map((row) => row[op.pk])].join('\n') + '\n');
+    }
+    return counts;
+};
+/** One statement at a time: a cutover rehearsal must stop at the first refusal, not leave a
+ * half-applied schema behind a single batched driver error. */
+const applyStatements = async (db, statements) => {
+    for (let index = 0; index < statements.length; index++) {
+        try {
+            await sql `${sql.raw(statements[index])}`.execute(db);
+        }
+        catch (error) {
+            console.error(`  statement ${index + 1}/${statements.length} failed: ${statements[index].replace(/\s+/g, ' ').slice(0, 240)}`);
+            throw error;
+        }
+    }
+};
+/** Rows still without a site, per table — what the cutover refused to place. */
+const countUnresolved = async (db, plan) => {
+    const counts = {};
+    for (const op of plan.purge) {
+        if (!op.pk)
+            continue;
+        try {
+            const rows = await db.selectFrom(op.table).select(op.pk).where('SiteId', 'is', null).execute();
+            if (rows.length)
+                counts[op.table] = rows.length;
+        }
+        catch {
+            /* a table the source does not have: the plan never resolves one either */
+        }
+    }
+    return counts;
+};
+const main = async () => {
+    const dsn = arg('dsn');
+    if (!dsn) {
+        console.error('siteid-migrate: --dsn is required (the legacy source; a MSSQL connection string)');
+        process.exit(2);
+    }
+    const db = await openDb({ dialect: 'mssql', dsn });
+    try {
+        const introspection = await introspect(db, { countRows: declaredNoneTables() });
+        const plan = planSiteIdMigration({ canon: canonicalSchema, introspection });
+        const { summary } = plan;
+        console.log(`siteid-migrate (dry-run${arg('apply') ? ' → APPLY' : ''})`);
+        console.log(`  add SiteId: ${summary.added} · chained backfills: ${summary.chained} (${summary.links} parent links) · polymorphic roots: ${summary.polymorphic}`);
+        console.log(`  NOT NULL+index: ${summary.notNull} · unresolved: ${summary.unresolved}`);
+        console.log(`  declared-none tables with rows: ${summary.declaredNoneWithRows} · order inversions: ${summary.misordered}`);
+        // Two checks the plan cannot make for itself: a root the spec declares empty while the
+        // source holds rows (task:3998, the spec was only ever compared with a snapshot), and a link
+        // whose parent is planted later in the schedule (a JOIN against a still-NULL key is the
+        // task:3891 defect one level down). Both mean "fix the plan, do not run".
+        if (summary.declaredNoneWithRows) {
+            const named = plan.declaredNoneWithRows.map((entry) => `${entry.table} (${entry.rows} rows)`).join(', ');
+            console.error(`  DECLARED NONE BUT NOT EMPTY (fix the spec or the data, do not run): ${named}`);
+            process.exit(1);
+        }
+        if (summary.misordered) {
+            const named = plan.misordered.map((entry) => `${entry.table}←${entry.parent}`).join(', ');
+            console.error(`  OUT OF ORDER (a link reads a parent planted later, do not run): ${named}`);
+            process.exit(1);
+        }
+        // refuse BEFORE rendering: the sweep parks whatever has no site on the sentinel, so a
+        // rendered plan of an unresolved one is a plan that quietly quarantines a whole family.
+        // The plan is data; the CLI is where an operator is told not to run it (task:3894).
+        if (plan.unresolved.length) {
+            console.error(`  UNRESOLVED (fix the plan, do not run): ${plan.unresolved.join(', ')}`);
+            process.exit(1);
+        }
+        const planSql = renderMssql(plan);
+        const out = arg('out');
+        if (out) {
+            fs.writeFileSync(out, planSql);
+            console.log(`  plan written to ${out}`);
+        }
+        if (arg('apply')) {
+            // apply is destructive: the caller is expected to point it at a COPY (plan:48 Q5.3)
+            const statements = statementsOf(planSql);
+            try {
+                await applyStatements(db, statements);
+                console.log(`  applied ${statements.length} statements`);
+            }
+            catch (error) {
+                // the guard in the cutover SQL stopped on a table that still holds rows with no site.
+                // Report the whole set, not the one table the statement order happened to reach.
+                const left = await countUnresolved(db, plan);
+                const stuck = Object.values(left).reduce((total, count) => total + count, 0);
+                console.error(`  APPLY STOPPED — ${stuck} rows across ${Object.keys(left).length} tables have no site: ${Object.entries(left).map(([table, n]) => `${table} (${n})`).join(', ')}`);
+                console.error('  fix the edge in owner-resolve-spec / the canon FK — or pass --purge --manifest <dir> to delete them');
+                process.exitCode = 1;
+                return;
+            }
+        }
+        else if (!arg('purge')) {
+            console.log('  read-only: pass --apply to run the statements on the source');
+            return;
+        }
+        // ── what the plan could not place (task:4092) ──────────────────────────
+        // Nothing is parked: a row that ends the run without a site is an edge missing from the
+        // resolver graph, and the cutover SQL has already refused by naming the table. `--purge`
+        // is the operator saying "these rows are dead, delete them" — with a manifest of their keys.
+        const unresolved = await countUnresolved(db, plan);
+        const rows = Object.values(unresolved).reduce((total, count) => total + count, 0);
+        if (!arg('purge')) {
+            if (rows) {
+                console.error(`  UNRESOLVED ROWS (${rows} across ${Object.keys(unresolved).length} tables): ${Object.entries(unresolved).map(([table, n]) => `${table} (${n})`).join(', ')}`);
+                console.error('  fix the edge in owner-resolve-spec / the canon FK — or pass --purge --manifest <dir> to delete them');
+                process.exitCode = 1;
+            }
+            else {
+                console.log('  no rows without a site: nothing is parked, nothing to purge');
+            }
+            return;
+        }
+        const manifest = arg('manifest');
+        const counts = await writeManifest(db, plan, manifest);
+        const doomed = Object.values(counts).reduce((total, count) => total + count, 0);
+        console.log(`  purge: ${doomed} rows across ${Object.keys(counts).length} tables${manifest ? ` · manifest in ${manifest}` : ' · NO manifest (pass --manifest <dir> to keep the audit trail)'}`);
+        const purgeStatements = statementsOf(renderPurgeMssql(plan));
+        await applyStatements(db, purgeStatements);
+        const left = await countUnresolved(db, plan);
+        const remaining = Object.values(left).reduce((total, count) => total + count, 0);
+        console.log(`  purge: applied ${purgeStatements.length} deletes · rows still without a site: ${remaining}`);
+        if (remaining)
+            process.exitCode = 1;
+    }
+    finally {
+        await db.destroy();
+    }
+};
+if (process.argv[1] && process.argv[1].replace(/\\/g, '/').endsWith('siteid-migrate.mjs'))
+    await main();

package/dist/scripts/tenant-invariant-audit.d.mts

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

package/dist/scripts/tenant-invariant-audit.mjs

@@ -0,0 +1,34 @@
+// CLI wrapper over the tenant-invariant audit (task:3814): run it against any
+// canon database — a materialised canon, an imported site, a staging copy.
+//
+//   AUDIT_URL=postgres://... node packages/data/scripts/tenant-invariant-audit.mjs
+//   AUDIT_DIALECT=mssql AUDIT_URL='sqlserver://sa:pw@host:1433/MoreThenCms_p1?encrypt=false' \
+//     node packages/data/scripts/tenant-invariant-audit.mjs
+//
+// Every dialect `openDb` serves (task:3913): postgres, mariadb, mssql. MSSQL is the
+// migration source, and it is where the polymorphic-owner block matters most: the legacy
+// copy is exactly the database whose `Folders`/`Gallery` sites were resolved by a probe
+// (task:3977).
+//
+// Exit code 1 with a JSON report when violations are found — suitable for a
+// cutover checklist step (plan:50 Q6).
+import { auditTenantInvariants } from "../audit.js";
+import { openDb } from '../dbProvider.js';
+const url = process.env.AUDIT_URL;
+if (!url) {
+    console.error('AUDIT_URL is not set (connection string of the database to audit)');
+    process.exit(2);
+}
+const dialectName = process.env.AUDIT_DIALECT ?? 'postgres';
+// The tooling seam already speaks every dialect with the same DSN syntax the cell does;
+// re-wiring them here was a second copy that drifted (MariaDB was refused while the audit
+// itself had always been dialect-neutral).
+const db = await openDb({ dialect: dialectName, dsn: url });
+try {
+    const report = await auditTenantInvariants(db);
+    console.log(JSON.stringify(report, null, 2));
+    process.exit(report.ok ? 0 : 1);
+}
+finally {
+    await db.destroy();
+}

package/dist/singleMode.d.ts

@@ -0,0 +1,5 @@
+import type { Kysely } from 'kysely';
+export interface SingleModeReport {
+    siteId: string;
+}
+export declare const assertSingleMode: (db: Kysely<any>) => Promise<SingleModeReport>;

package/dist/singleMode.js

@@ -0,0 +1,23 @@
+export const assertSingleMode = async (db) => {
+    // No exceptions: a cell has one site, and the quarantine bucket it used to carry is gone
+    // (task:4052 — on a single-tenant database there are no orphan rows to park).
+    const sites = await db.selectFrom('Sites').select('SiteId').execute();
+    const stores = await db.selectFrom('Stores').select('StoreId').execute();
+    const links = await db.selectFrom('AdministratorSites').select('Site_Id').distinct().execute();
+    const siteId = sites.length === 1 ? sites[0].SiteId : null;
+    const problems = [];
+    if (sites.length !== 1)
+        problems.push(`${sites.length} sites (single mode expects exactly 1)`);
+    if (stores.length > 1)
+        problems.push(`${stores.length} stores (single mode expects at most 1)`);
+    const foreign = siteId ? [...new Set(links.map((link) => link.Site_Id).filter((id) => id !== siteId))] : [];
+    if (foreign.length)
+        problems.push(`administrator links to a foreign site: ${foreign.join(', ')}`);
+    if (problems.length) {
+        // The site ids are the one thing the operator needs to fix the data, and they
+        // are not secret — a refusal that hides them costs a debugging session.
+        throw new Error(`single mode: this database is not a single-site cell — ${problems.join('; ')}. ` +
+            `Clean the rows or serve the database in shared mode.`);
+    }
+    return { siteId: siteId };
+};

package/dist/sqliteDialect.d.ts

@@ -0,0 +1,6 @@
+export function openSqlite(location?: string): DatabaseSync;
+export function nodeSqliteDialect(database: any): SqliteDialect;
+export function sqliteKysely(location?: string, plugins?: any[]): Kysely<any>;
+import { DatabaseSync } from 'node:sqlite';
+import { SqliteDialect } from 'kysely';
+import { Kysely } from 'kysely';

package/dist/sqliteDialect.js

@@ -0,0 +1,92 @@
+// node:sqlite as a Kysely dialect (task:3821).
+//
+// SQLite is the third target dialect (plan:49 Q4) and the one that needs no
+// third-party driver: Node ships one. Two gaps between better-sqlite3 (what
+// Kysely's SqliteDialect expects) and node:sqlite are bridged here:
+//
+//   * better-sqlite3 marks a statement readable with `reader`; node:sqlite only
+//     answers through `columns()`, which throws for anything that returns no rows;
+//   * SQLite has no boolean type and node:sqlite refuses to bind a boolean, so a
+//     boolean parameter becomes 0/1 at the driver boundary.
+import { DatabaseSync } from 'node:sqlite';
+import { Kysely, SqliteDialect } from 'kysely';
+const bindable = (parameters) => (parameters ?? []).map((value) => typeof value === 'boolean' ? (value ? 1 : 0)
+    // node:sqlite binds neither booleans nor Date objects, and the API layer writes
+    // both: a `Date` is a perfectly ordinary value for a `datetime` column (MSSQL
+    // took it for years). Stored as the canon's datetime text, in UTC — the Date is
+    // an instant, and the reader gets a string back, as it does from every other
+    // string column.
+    : value instanceof Date ? value.toISOString().replace('T', ' ').replace('Z', '')
+        : value);
+class NodeSqliteStatement {
+    constructor(statement) {
+        this.statement = statement;
+    }
+    get reader() {
+        try {
+            this.statement.columns();
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    all(parameters) {
+        return this.statement.all(...bindable(parameters));
+    }
+    run(parameters) {
+        const result = this.statement.run(...bindable(parameters));
+        return { changes: result.changes, lastInsertRowid: result.lastInsertRowid };
+    }
+    iterate(parameters) {
+        return this.statement.iterate(...bindable(parameters));
+    }
+}
+class NodeSqliteDatabase {
+    #open = true;
+    constructor(database) {
+        this.database = database;
+    }
+    prepare(sql) {
+        return new NodeSqliteStatement(this.database.prepare(sql));
+    }
+    /** Idempotent: `destroy()` and the driver's own teardown may both land here. */
+    close() {
+        if (!this.#open)
+            return;
+        this.#open = false;
+        this.database.close();
+    }
+}
+/** Open a node:sqlite database (`:memory:` or a file path). */
+export const openSqlite = (location = ':memory:') => new DatabaseSync(location);
+/** Kysely dialect over an open node:sqlite database. */
+export const nodeSqliteDialect = (database) => new SqliteDialect({ database: new NodeSqliteDatabase(database) });
+/**
+ * Kysely over a node:sqlite database whose `destroy()` releases the file even if
+ * no query ever ran.
+ *
+ * Kysely connects lazily and skips the driver's teardown when it never started,
+ * while `openSqlite` opens (and Windows locks) the file eagerly. A caller that
+ * opens a database and bails before the first query — a cutover tool hitting a
+ * broken bundle, a bad flag — would otherwise leave the file locked. So this
+ * helper owns the handle and closes it on destroy, once, whoever got there first.
+ *
+ * `plugins` rides into the Kysely constructor instead of a later `withPlugin`: that call
+ * returns a *different* instance, and the wrapper it hands back is not the one whose
+ * `destroy()` closes the handle — the file then stays locked on Windows (task:4140).
+ */
+export const sqliteKysely = (location = ':memory:', plugins = []) => {
+    const database = new NodeSqliteDatabase(openSqlite(location));
+    const db = new Kysely({ dialect: new SqliteDialect({ database }), plugins });
+    const destroy = db.destroy.bind(db);
+    db.destroy = async () => {
+        try {
+            await destroy();
+        }
+        finally {
+            database.close();
+        }
+    };
+    return db;
+};

package/dist/templateDefs.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Validate + normalize a schema-as-file template-def object into the DB-loaded shape.
+ * Pure. Throws on structural / vocabulary errors (the load-time lint seam).
+ *
+ * @param {object} def parsed file object (see FILE SHAPE above)
+ * @returns {{id, kind, alias, name, description, customDefaultLayout, layouts, content}}
+ *   `content` is `JSON.stringify(def.fields)` — a drop-in for a Sequelize template row.
+ */
+export function parseTemplateDef(def: object): {
+    id: any;
+    kind: any;
+    alias: any;
+    name: any;
+    description: any;
+    customDefaultLayout: any;
+    layouts: any;
+    content: any;
+};
+/**
+ * Read + parse a template-def JSON file from disk into the normalized DB-loaded shape.
+ * The thin IO wrapper over `parseTemplateDef` (the file-loader the engine plugs in alongside
+ * its DB loader).
+ *
+ * @param {string} filePath absolute or cwd-relative path to a template-def `.json` file
+ * @returns {{id, kind, alias, name, description, customDefaultLayout, layouts, content}}
+ */
+export function loadTemplateDefFile(filePath: string): {
+    id: any;
+    kind: any;
+    alias: any;
+    name: any;
+    description: any;
+    customDefaultLayout: any;
+    layouts: any;
+    content: any;
+};
+export const TEMPLATE_KINDS: Set<string>;
+export const FIELD_TEMPLATE_TYPES: Set<string>;