@snolla/data 0.0.0-stage → 1.0.7

package/dist/scripts/canon-audit.d.mts

@@ -0,0 +1,25 @@
+export namespace LEGACY_SLICE {
+    let total: number;
+    let site: number;
+}
+export namespace CANON_EXPECTED {
+    let total_1: number;
+    export { total_1 as total };
+    let site_1: number;
+    export { site_1 as site };
+    export let nonSite: number;
+    export let control: number;
+    export let registry: number;
+    export let dictionary: number;
+    export let siteIdAdded: number;
+    export let siteExisting: number;
+}
+export const LEGACY_REMOVED_TABLES: string[];
+export function auditCanon({ tables }?: {
+    tables?: object[];
+}): {
+    ok: boolean;
+    problems: string[];
+    counts: object;
+    legacy: object;
+};

package/dist/scripts/canon-audit.mjs

@@ -0,0 +1,213 @@
+// The canon audit: verifier of task:3864 (finding of the umbrella review,
+// task:3831), and the machine-readable form of the numbers reconciliation.
+//
+//   node packages/data/scripts/canon-audit.mjs
+//
+// Why this exists
+// ---------------
+// The decisions (plan:48 Q1, plan:49, plan:50 Q4, requirements:64) took their
+// numbers from the legacy-derived ownership map (wiki:3821 v12), which was
+// built from the 168 EF6 models of the live schema:
+//
+//     121 legacy tables = 112 site-scoped + 9 non-site
+//
+// That is the LEGACY slice. The target canon carries one table FEWER (task:3936,
+// one-schema design wiki:3874 §2):
+//
+//     120 tables = 111 site-scoped + 9 non-site
+//
+// Two tables left the canon after the map was taken:
+//   * `AdministratorReplicas` — one schema for every mode means there is nothing to
+//     replicate: the administrator row lives in the same database in both modes;
+//   * `LogEvents` — dead, nobody writes it.
+// The canon is the authority; the map's 121/112 is a legacy slice, annotated as such
+// in the decisions.
+//
+// Correction (task:3876, operator verdict): the map counted `NumberingTasks` as
+// site-scoped because the EF6 model carried a SiteId that the live table never
+// had — the engine addresses a numbering task by GUID and `NumberingCounters.TaskId`
+// is a hard FK to it, so the table is global config. It moved to the dictionary
+// scope: one table left the site count, so 114/81 became 113/80 while the totals
+// stayed put.
+//
+// This script re-derives every number from the canon and compares it to that
+// annotated expectation, so the reconciliation is reproducible instead of a
+// paragraph that drifts. It also cross-checks the map's composition verdicts
+// (the 47 dropped tables, the control/registry/dictionary split, PK coverage,
+// the tenant key) table by table — not just the totals.
+//
+// Exit code 1 and a named discrepancy list on any mismatch: the audit is the
+// oracle.
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { canonicalSchema, CANON_TYPES, isSiteScoped } from "../schema/index.js";
+// ------------------------------------------------------- declared expectations ---
+// Numbers as annotated in the decisions after task:3864. Keep the legacy pair in
+// sync with plan:48/49/50 and requirements:64; the canon pair is asserted below.
+export const LEGACY_SLICE = { total: 121, site: 112 };
+export const CANON_EXPECTED = {
+    total: 120,
+    site: 111,
+    nonSite: 9,
+    control: 6,
+    registry: 1,
+    dictionary: 2,
+    siteIdAdded: 80,
+    siteExisting: 31,
+};
+// Tables the legacy map counted and the canon no longer carries (task:3936) — the
+// reconciliation subtracts them, so a silent re-add fails here by name. The map never
+// had `AdministratorReplicas` (it was the one-table delta over the map), so it is not
+// subtracted: the delta is simply zero now, and a re-add fails this list too.
+export const LEGACY_REMOVED_TABLES = ['LogEvents'];
+// The 47 tables dropped by the operator verdicts (wiki:3821 v12) — frozen here
+// so a resurrection is a named failure rather than a quietly larger schema.
+const DROPPED = [
+    'Applications', 'AspNetRoles', 'AspNetUserClaims', 'AspNetUserLogins', 'AspNetUserRoles',
+    'AspNetUsers', 'BlogMetaFields', 'BlogMetaTags', 'ContentCacheItems', 'ContentPageMetaTags',
+    'ContentPagePartMetaFields', 'Customers', 'ImageCacheItems', 'Memberships', 'MetaFields',
+    'MetaTags', 'PageMetaFields', 'PageMetaTags', 'Parts', 'PortfolioCategories',
+    'PortfolioCategoryProjects', 'PortfolioMetaFields', 'PortfolioMetaTags', 'PortfolioTagProjects',
+    'PortfolioTags', 'Portfolios', 'PostMetaFields', 'PostMetaTags', 'ProductMetaFields',
+    'ProductMetaTags', 'ProductVariantMetaFields', 'Profiles', 'ProjectComments', 'ProjectLikes',
+    'ProjectMetaFields', 'ProjectMetaTags', 'Projects', 'Roles', 'SearchIndexTasks',
+    'SiteMetaFields', 'SiteMetaTags', 'StoreCategoryMetaFields', 'StoreCategoryMetaTags',
+    'StoreMetaFields', 'StoreMetaTags', 'Users', 'UsersInRoles',
+];
+const CONTROL = ['Accounts', 'Administrators', 'AdministratorAccounts', 'AdministratorSites', 'AdministratorStores', 'ApiKeys'];
+const REGISTRY = ['Sites'];
+const DICTIONARY = ['InventoryPolicies', 'NumberingTasks'];
+const sorted = (a) => [...a].sort();
+/**
+ * Re-derive the canon numbers and compare them to the annotated expectation.
+ *
+ * @param {object} [override]
+ * @param {object[]} [override.tables] table specs to audit (default: the canon)
+ * @returns {{ok: boolean, problems: string[], counts: object, legacy: object}}
+ */
+export const auditCanon = ({ tables = canonicalSchema.tables } = {}) => {
+    const problems = [];
+    const names = tables.map((t) => t.name);
+    const site = tables.filter(isSiteScoped);
+    const nonSite = tables.filter((t) => !isSiteScoped(t));
+    const byScope = (scope) => tables.filter((t) => t.scope === scope);
+    const siteIdAdded = site.filter((t) => t.siteIdAdded);
+    const counts = {
+        total: tables.length,
+        site: site.length,
+        nonSite: nonSite.length,
+        control: byScope('control').length,
+        registry: byScope('registry').length,
+        dictionary: byScope('dictionary').length,
+        siteIdAdded: siteIdAdded.length,
+        siteExisting: site.length - siteIdAdded.length,
+    };
+    // ---- totals and composition (the map's verdicts, in machine form) --------
+    if (counts.total !== CANON_EXPECTED.total) {
+        problems.push(`table count: expected ${CANON_EXPECTED.total}, found ${counts.total}`);
+    }
+    if (counts.site !== CANON_EXPECTED.site) {
+        problems.push(`site-scoped count: expected ${CANON_EXPECTED.site}, found ${counts.site}`);
+    }
+    if (counts.nonSite !== CANON_EXPECTED.nonSite) {
+        problems.push(`non-site count: expected ${CANON_EXPECTED.nonSite}, found ${counts.nonSite}`);
+    }
+    if (counts.control !== CANON_EXPECTED.control) {
+        problems.push(`control count: expected ${CANON_EXPECTED.control}, found ${counts.control}`);
+    }
+    if (counts.registry !== CANON_EXPECTED.registry) {
+        problems.push(`registry count: expected ${CANON_EXPECTED.registry}, found ${counts.registry}`);
+    }
+    if (counts.dictionary !== CANON_EXPECTED.dictionary) {
+        problems.push(`dictionary count: expected ${CANON_EXPECTED.dictionary}, found ${counts.dictionary}`);
+    }
+    const expectedNonSite = sorted([...CONTROL, ...REGISTRY, ...DICTIONARY]);
+    if (JSON.stringify(sorted(nonSite.map((t) => t.name))) !== JSON.stringify(expectedNonSite)) {
+        problems.push(`non-site composition: expected ${expectedNonSite.join(',')}, found ${sorted(nonSite.map((t) => t.name)).join(',')}`);
+    }
+    if (new Set(names).size !== names.length) {
+        const dupes = names.filter((n, i) => names.indexOf(n) !== i);
+        problems.push(`duplicate table names: ${[...new Set(dupes)].join(',')}`);
+    }
+    // ---- the annotated legacy reconciliation ---------------------------------
+    if (counts.total !== LEGACY_SLICE.total - LEGACY_REMOVED_TABLES.length) {
+        problems.push(`legacy total: ${LEGACY_SLICE.total} (legacy slice) - ${LEGACY_REMOVED_TABLES.length} (removed) != ${counts.total}`);
+    }
+    if (counts.site !== LEGACY_SLICE.site - LEGACY_REMOVED_TABLES.length) {
+        problems.push(`legacy site: ${LEGACY_SLICE.site} (legacy slice) - ${LEGACY_REMOVED_TABLES.length} (removed) != ${counts.site}`);
+    }
+    for (const name of LEGACY_REMOVED_TABLES) {
+        if (names.includes(name))
+            problems.push(`removed table is back in the canon: ${name}`);
+    }
+    // ---- the 47 dropped stay dropped ----------------------------------------
+    for (const name of DROPPED) {
+        if (names.includes(name))
+            problems.push(`dropped table present: ${name}`);
+    }
+    // ---- per-table invariants ------------------------------------------------
+    if (counts.siteIdAdded !== CANON_EXPECTED.siteIdAdded) {
+        problems.push(`siteIdAdded count: expected ${CANON_EXPECTED.siteIdAdded}, found ${counts.siteIdAdded}`);
+    }
+    if (counts.siteExisting !== CANON_EXPECTED.siteExisting) {
+        problems.push(`siteIdExisting count: expected ${CANON_EXPECTED.siteExisting}, found ${counts.siteExisting}`);
+    }
+    const vocab = new Set(CANON_TYPES);
+    for (const t of tables) {
+        const hasPk = Object.values(t.columns).some((c) => c.pk === true);
+        if (!hasPk)
+            problems.push(`primary key missing: ${t.name}`);
+        for (const [column, spec] of Object.entries(t.columns)) {
+            if (!vocab.has(spec.type))
+                problems.push(`column vocabulary ${t.name}.${column}: ${spec.type}`);
+        }
+        if (!isSiteScoped(t))
+            continue;
+        const col = t.columns.SiteId;
+        if (!col) {
+            problems.push(`SiteId missing: ${t.name}`);
+            continue;
+        }
+        if (col.nullable === true)
+            problems.push(`SiteId nullable: ${t.name}`);
+        if (col.type !== 'uuid')
+            problems.push(`SiteId type is ${col.type}, expected uuid: ${t.name}`);
+        const indexed = (t.indexes ?? []).some((ix) => ix.columns?.[0] === 'SiteId');
+        if (!indexed)
+            problems.push(`SiteId index missing: ${t.name}`);
+    }
+    return { ok: problems.length === 0, problems, counts, legacy: { ...LEGACY_SLICE, removedTables: LEGACY_REMOVED_TABLES } };
+};
+// ------------------------------------------------------------------ CLI ---
+const report = () => {
+    const result = auditCanon();
+    const { counts } = result;
+    console.log(`[canon] tables=${counts.total} site=${counts.site} non-site=${counts.nonSite}`);
+    console.log(`[canon] control=${counts.control} registry=${counts.registry} dictionary=${counts.dictionary}`);
+    console.log(`[canon] siteIdAdded=${counts.siteIdAdded} siteIdExisting=${counts.siteExisting}`);
+    console.log(`[reconcile] legacy ${LEGACY_SLICE.total}/${LEGACY_SLICE.site} - [${LEGACY_REMOVED_TABLES.join(',')}] = ${counts.total}/${counts.site}`);
+    if (result.ok) {
+        console.log('PASS canon audit: numbers match the annotated decisions');
+    }
+    else {
+        console.error(`FAIL canon audit: ${result.problems.length} discrepancy(ies)`);
+        for (const p of result.problems)
+            console.error(`  - ${p}`);
+    }
+    return result.ok;
+};
+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)
+        process.exit(report() ? 0 : 1);
+}

package/dist/scripts/canon-smoke.d.mts

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

package/dist/scripts/canon-smoke.mjs

@@ -0,0 +1,44 @@
+// Smoke check for the canon generators (task:3820): materialise the generated
+// Postgres DDL in a live database and report the counts. No quarantine row is
+// seeded: the canon carries none (task:4052) and nothing is parked (task:4092).
+//
+// Needs: ADMIN_PG_URL (to create the throwaway database), TEST_PG_URL (host).
+// Run:   ADMIN_PG_URL=... TEST_PG_URL=... node packages/data/scripts/canon-smoke.mjs
+// Smoke check: canon -> generated DDL -> live Postgres.
+import { Client } from 'pg';
+import { renderDdlSql } from './schema/generate.mjs';
+import { canonicalSchema } from "./schema/index.js";
+const admin = new Client({ connectionString: process.env.ADMIN_PG_URL });
+await admin.connect();
+await admin.query('drop database if exists canon');
+await admin.query('create database canon');
+await admin.end();
+const db = new Client({ connectionString: process.env.TEST_PG_URL.replace(/\/spike$/, '/canon') });
+await db.connect();
+await db.query(renderDdlSql('postgres'));
+const quote = (s) => `"${s}"`;
+// fill NOT NULL columns that carry no default with a placeholder of the right type
+const fill = (table, values) => {
+    const spec = canonicalSchema.tables.find((t) => t.name === table);
+    const cols = { ...values };
+    for (const [name, c] of Object.entries(spec.columns)) {
+        if (c.nullable === true || c.default !== undefined || name in cols)
+            continue;
+        cols[name] = c.type === 'bool' ? false
+            : ['int', 'bigint', 'decimal'].includes(c.type) ? 0
+                : c.type === 'uuid' ? '33333333-3333-3333-3333-333333333333'
+                    : c.type === 'datetime' ? new Date().toISOString()
+                        : 'x';
+    }
+    const names = Object.keys(cols);
+    return { text: `insert into ${quote(table)} (${names.map(quote).join(', ')}) values (${names.map((_, i) => `$${i + 1}`).join(', ')})`, values: names.map((n) => cols[n]) };
+};
+const account = fill('Accounts', { AccountId: '11111111-1111-1111-1111-111111111111' });
+const administrator = fill('Administrators', { AdministratorId: '22222222-2222-2222-2222-222222222222' });
+await db.query(account.text, account.values);
+await db.query(administrator.text, administrator.values).catch((e) => console.log('administrators skipped:', e.message));
+const one = async (sql) => (await db.query(sql)).rows[0].c;
+console.log('tables:', await one(`select count(*)::int as c from information_schema.tables where table_schema='public' and table_type='BASE TABLE'`));
+console.log('SiteId indexes:', await one(`select count(*)::int as c from pg_indexes where schemaname='public' and indexname like '%SiteId_idx'`));
+console.log('FK constraints:', await one(`select count(*)::int as c from information_schema.table_constraints where constraint_type='FOREIGN KEY'`));
+await db.end();

package/dist/scripts/dialect-ddl-stand.d.mts

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

package/dist/scripts/dialect-ddl-stand.mjs

@@ -0,0 +1,136 @@
+// Full-canon DDL acceptance on the stand (task:3822, plan:49 Q6).
+//
+// Executes the *whole* generated DDL (122 tables) on every dialect it can
+// reach: SQLite in memory always; Postgres by TEST_PG_URL; MariaDB by
+// TEST_MARIA_URL. It is deliberately not a test file — on MariaDB the ~390
+// statements take minutes on a Windows Docker volume, which is a stand-check
+// cost, not a unit-test one. The fast scenario smoke (same dialects, two tables)
+// is packages/data/test/dialect-smoke.test.js.
+//
+//   TEST_PG_URL=... TEST_MARIA_URL=... TEST_MSSQL_URL=... node packages/data/scripts/dialect-ddl-stand.mjs
+//
+// SQL Server is a TARGET since task:3994, so it executes the same canon DDL — the ADO form
+// of the DSN (`Server=…;Database=…;User Id=…;Password=…`) is what `openDb` expects.
+//
+// One line per dialect with the table count and elapsed ms; exits 1 on the
+// first dialect that cannot take the canon DDL — that failure *is* the finding.
+import { DatabaseSync } from 'node:sqlite';
+import { renderDdlSql } from '../schema/generate.mjs';
+const PG_SCHEMA = 'canon_ddl_stand';
+const MARIA_DATABASE = 'canon_ddl_stand';
+const postgres = async () => {
+    const url = process.env.TEST_PG_URL;
+    if (!url)
+        return null;
+    const { Client } = await import('pg');
+    const client = new Client({ connectionString: url });
+    await client.connect();
+    try {
+        await client.query(`drop schema if exists ${PG_SCHEMA} cascade`);
+        await client.query(`create schema ${PG_SCHEMA}`);
+        await client.query(`set search_path to ${PG_SCHEMA}`);
+        await client.query(renderDdlSql('postgres'));
+        const { rows } = await client.query(`select count(*)::int as c from information_schema.tables where table_schema = $1`, [PG_SCHEMA]);
+        return rows[0].c;
+    }
+    finally {
+        await client.end();
+    }
+};
+const mariadb = async () => {
+    const url = process.env.TEST_MARIA_URL;
+    if (!url)
+        return null;
+    const parsed = new URL(url);
+    const promise = (await import('mysql2/promise')).default;
+    const connection = await promise.createConnection({
+        host: parsed.hostname,
+        port: Number(parsed.port || 3306),
+        user: decodeURIComponent(parsed.username),
+        password: decodeURIComponent(parsed.password),
+        multipleStatements: true,
+    });
+    try {
+        await connection.query(`drop database if exists ${MARIA_DATABASE}`);
+        await connection.query(`create database ${MARIA_DATABASE} character set utf8mb4 collate utf8mb4_unicode_ci`);
+        await connection.query(`use ${MARIA_DATABASE}`);
+        await connection.query(renderDdlSql('mariadb'));
+        const [rows] = await connection.query(`select count(*) as c from information_schema.tables where table_schema = ?`, [MARIA_DATABASE]);
+        return Number(rows[0].c);
+    }
+    finally {
+        await connection.end();
+    }
+};
+const sqlite = async () => {
+    const database = new DatabaseSync(':memory:');
+    try {
+        database.exec(renderDdlSql('sqlite'));
+        return database.prepare(`select count(*) as c from sqlite_master where type = 'table'`).get().c;
+    }
+    finally {
+        database.close();
+    }
+};
+/**
+ * SQL Server as a *target* (task:3994 — the operator made it one). It joins the stand
+ * through the same `openDb`, so the DDL is executed by the same dialect the product
+ * serves: the ADO DSN splits on `;`, hence the manual field read.
+ */
+const mssql = async () => {
+    const dsn = process.env.TEST_MSSQL_URL;
+    if (!dsn)
+        return null;
+    const { openDb } = await import('../dbProvider.js');
+    const { sql } = await import('kysely');
+    const database = process.env.TEST_MSSQL_DATABASE ?? 'canon_ddl_stand';
+    const onDatabase = (name) => dsn.replace(/(database|initial catalog)=[^;]*/i, `Database=${name}`);
+    const master = await openDb({ dialect: 'mssql', dsn: onDatabase('master') });
+    try {
+        await sql.raw(`if db_id('${database}') is not null begin alter database [${database}] set single_user with rollback immediate; drop database [${database}]; end`).execute(master);
+        await sql.raw(`create database [${database}]`).execute(master);
+    }
+    finally {
+        await master.destroy();
+    }
+    const db = await openDb({ dialect: 'mssql', dsn: onDatabase(database) });
+    try {
+        // the DDL header comments are not statements; the driver takes one at a time
+        const sqlText = renderDdlSql('mssql')
+            .split('\n')
+            .filter((line) => !line.trim().startsWith('--'))
+            .join('\n');
+        for (const statement of sqlText.split(/;\s*\n/).map((part) => part.trim()).filter(Boolean)) {
+            await sql.raw(statement).execute(db);
+        }
+        const count = await sql `select count(*) as c from sys.tables`.execute(db);
+        return Number(count.rows[0].c);
+    }
+    finally {
+        await db.destroy();
+    }
+};
+const dialects = [
+    ['sqlite', sqlite],
+    ['postgres', postgres],
+    ['mariadb', mariadb],
+    ['mssql', mssql],
+];
+let failed = false;
+for (const [name, run] of dialects) {
+    const started = Date.now();
+    try {
+        const tables = await run();
+        if (tables === null) {
+            console.log(`${name.padEnd(9)} SKIP (no URL in the environment)`);
+        }
+        else {
+            console.log(`${name.padEnd(9)} ok — ${tables} tables in ${Date.now() - started} ms`);
+        }
+    }
+    catch (error) {
+        failed = true;
+        console.log(`${name.padEnd(9)} FAIL — ${error.message}`);
+    }
+}
+process.exit(failed ? 1 : 0);

package/dist/scripts/owner-spec-check.d.mts

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

package/dist/scripts/owner-spec-check.mjs

@@ -0,0 +1,166 @@
+// Verifier for task:3818 — the owner-name resolution spec, moved into the
+// repository by task:3863 (it used to live in a scratch folder outside version
+// control, next to a hardcoded absolute path).
+//
+// Checks the contract `OwnerName -> (table, pk)` against two independent facts:
+// (1) the frozen live snapshot `owners/owners-observed.json` (a read-only probe
+// of production, 2026-10-13) and (2) the canonical schema in this repository, so
+// a spec entry pointing at a dropped / misspelled table cannot pass.
+//
+// Deterministic: no DB access, no network, no absolute paths.
+//   node packages/data/scripts/owner-spec-check.mjs
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import { canonicalSchema } from "../schema/index.js";
+import { loadContract } from './owners-fixture.mjs';
+const { spec, observed } = loadContract();
+const canonTables = new Map(canonicalSchema.tables.map((t) => [t.name, new Set(Object.keys(t.columns))]));
+const hasColumn = (table, column) => canonTables.get(table)?.has(column) === true;
+/** The declared primary key of a canon table — the column a resolver must join on. */
+const pkOf = (table) => {
+    const spec = canonicalSchema.tables.find((t) => t.name === table);
+    return spec && Object.keys(spec.columns).find((c) => spec.columns[c].pk);
+};
+const failures = [];
+const check = (fn, label) => { try {
+    fn();
+}
+catch (e) {
+    failures.push(`${label}: ${e.message}`);
+} };
+// --- 1. observed set is covered 100% and exactly (no invented, no missing) --
+const observedNames = Object.keys(observed.gallery.byOwnerName).sort();
+const specNames = Object.keys(spec.observedOwners).sort();
+check(() => {
+    const missing = observedNames.filter((n) => !specNames.includes(n));
+    assert.equal(missing.length, 0, `not covered by the spec: ${missing.join(', ')}`);
+}, 'coverage');
+check(() => {
+    const extra = specNames.filter((n) => !observedNames.includes(n));
+    assert.equal(extra.length, 0, `spec has values that never occur in production: ${extra.join(', ')}`);
+}, 'exactness');
+check(() => {
+    assert.equal(specNames.length, 12, `expected 12 observed OwnerName values, spec has ${specNames.length}`);
+}, 'observed count');
+// --- 2. per-value target exists in the canon + row/orphan numbers match ----
+for (const name of specNames.filter((n) => observedNames.includes(n))) {
+    const entry = spec.observedOwners[name];
+    const o = observed.gallery.byOwnerName[name];
+    check(() => {
+        assert.equal(entry.rows, o, `${name}: spec rows=${entry.rows} != snapshot ${o}`);
+    }, `rows:${name}`);
+    check(() => {
+        const orph = observed.gallery.orphansByOwnerName[name] ?? 0;
+        assert.equal(entry.orphans, orph, `${name}: spec orphans=${entry.orphans} != snapshot ${orph}`);
+    }, `orphans:${name}`);
+    check(() => {
+        if (entry.status === 'resolvable') {
+            assert.ok(entry.table && entry.pk, `${name}: resolvable entry needs table+pk`);
+            assert.ok(hasColumn(entry.table, entry.pk), `${name}: canon has no ${entry.table}.${entry.pk}`);
+        }
+        else {
+            assert.equal(entry.status, 'quarantine-only', `${name}: unknown status ${entry.status}`);
+            assert.ok(entry.reason, `${name}: quarantine-only needs a reason`);
+            // a quarantined value either has no target at all or has one that is
+            // already dropped from the canon — say which, explicitly
+            if (entry.table) {
+                assert.equal(canonTables.has(entry.table), false, `${name}: quarantined but ${entry.table} still lives in the canon`);
+            }
+            assert.equal(entry.orphans, entry.rows, `${name}: quarantine-only must be orphan in full`);
+        }
+    }, `target:${name}`);
+}
+// --- 3. totals: the distribution adds up to the live total ------------------
+check(() => {
+    const sum = Object.values(observed.gallery.byOwnerName).reduce((a, b) => a + b, 0);
+    assert.equal(sum, observed.gallery.total, `distribution ${sum} != gallery total ${observed.gallery.total}`);
+    assert.equal(spec.observedTotals.Gallery, observed.gallery.total, 'spec total != snapshot total');
+    assert.equal(spec.observedTotals.orphans, observed.gallery.orphansTotal, 'spec orphans != snapshot orphans');
+    assert.equal(spec.observedTotals.idOwnerNull, observed.gallery.idOwnerNull, 'spec idOwnerNull != snapshot');
+}, 'totals');
+// --- 4. poly-roots have explicit, complete resolution rules -----------------
+// Three declared forms (task:3895): an owner column, host columns, or an explicit `resolvers`
+// list. A root declared `siteFrom: 'none'` carries no site of its own and declares none of them.
+for (const [root, rule] of Object.entries(spec.polyRoots)) {
+    check(() => {
+        assert.ok(canonTables.has(root), `${root}: not a canon table`);
+        if (rule.siteFrom === 'none') {
+            assert.ok(!rule.resolvers && !rule.hostColumns && !rule.ownerColumn, `${root}: declares no site, so it resolves through nothing`);
+        }
+        else if (rule.resolvers) {
+            assert.ok(Array.isArray(rule.resolvers) && rule.resolvers.length, `${root}: resolvers must be a non-empty list`);
+            for (const link of rule.resolvers) {
+                assert.ok(hasColumn(root, link.column), `${root}: canon has no ${link.column}`);
+                assert.ok(canonTables.has(link.table), `${root}: resolver table ${link.table} is not in the canon`);
+                assert.equal(pkOf(link.table), link.pk, `${root}: ${link.table} has no primary key ${link.pk}`);
+            }
+        }
+        else if (rule.hostColumns) {
+            for (const c of rule.hostColumns)
+                assert.ok(hasColumn(root, c), `${root}: canon has no ${c}`);
+            for (const [col, table] of Object.entries(rule.hostTables)) {
+                assert.ok(rule.hostColumns.includes(col), `${root}: hostTables.${col} not in hostColumns`);
+                assert.ok(canonTables.has(table), `${root}: host table ${table} is not in the canon`);
+            }
+        }
+        else {
+            assert.ok(rule.ownerColumn, `${root}: needs ownerColumn, hostColumns or resolvers`);
+            assert.ok(hasColumn(root, rule.ownerColumn), `${root}: canon has no ${rule.ownerColumn}`);
+        }
+        if (rule.siteFrom === 'none') {
+            assert.equal(rule.unresolved, undefined, `${root}: nothing resolves, so nothing is quarantined by it`);
+            return;
+        }
+        // the site comes from the resolved parent row — a polymorphic owner (`owner-row`) or a
+        // declared parent chain (`parent-chain`); the global policy answers for `unresolved`
+        assert.ok(['owner-row', 'parent-chain'].includes(rule.siteFrom), `${root}: site must come from the resolved owner/host row (got ${JSON.stringify(rule.siteFrom)})`);
+        assert.equal(rule.unresolved ?? spec.unresolved?.policy, 'refuse', `${root}: unresolved rows must refuse the run, not be parked`);
+    }, `polyRoot:${root}`);
+}
+check(() => {
+    for (const needed of ['Gallery', 'Modules', '_Modules'])
+        assert.ok(spec.polyRoots[needed], `poly-roots must cover ${needed}`);
+}, 'polyRoots present');
+// --- 5. orphans policy: refuse, never park (task:4092) ---------------------
+// A row that ends the run without a site is a missing edge, so the contract cannot offer a place
+// to put it: the cutover refuses by name and `--purge` (with a manifest) is the only exit.
+check(() => {
+    assert.equal(spec.unresolved.policy, 'refuse', 'there is no parking policy: an unplaced row must stop the run');
+    assert.ok(String(spec.unresolved.exit).includes('--purge'), 'the only exit is an explicit, auditable delete');
+    assert.equal(spec.unresolved.neverDelete, undefined, 'the never-delete verdict is gone with the sentinel');
+    assert.equal(spec.unresolved.sentinelSiteId, undefined, 'no sentinel site: the migration invents no tenant');
+    assert.equal(spec.unresolved.sentinelMarker, undefined, 'and marks no row');
+}, 'unresolved policy');
+// --- 6. numbering rules exist and match the live seed ----------------------
+check(() => {
+    assert.equal(spec.numbering.tasks.seed, observed.numbering.tasks, 'numbering task seed != live 4 defaults');
+    assert.equal(spec.numbering.counters.rows, observed.numbering.counters, 'numbering counters != live 86');
+    assert.equal(spec.numbering.counters.distinctOwners, observed.numbering.counterOwners, 'distinct numbering owners != live 85');
+    assert.ok(spec.numbering.counters.siteFrom, 'numbering counters need a site rule');
+}, 'numbering');
+// --- 7. aliases never dangle ------------------------------------------------
+check(() => {
+    const targets = new Set([...specNames, ...Object.keys(spec.aliases)]);
+    for (const [alias, rule] of Object.entries(spec.aliases)) {
+        if (rule.aliasOf)
+            assert.ok(targets.has(rule.aliasOf), `alias ${alias} -> unknown ${rule.aliasOf}`);
+        else {
+            assert.ok(rule.table && rule.pk, `alias ${alias}: needs table+pk or aliasOf`);
+            assert.ok(hasColumn(rule.table, rule.pk), `alias ${alias}: canon has no ${rule.table}.${rule.pk}`);
+        }
+    }
+    assert.ok(Object.keys(spec.aliases).length > 0, 'aliases must cover the legacy write-path variants');
+}, 'aliases');
+// --- verdict ---------------------------------------------------------------
+const covered = specNames.length;
+const resolvable = specNames.filter((n) => spec.observedOwners[n].status === 'resolvable').length;
+if (failures.length) {
+    console.error(`FAIL owner-resolution spec: ${failures.length} problem(s)`);
+    for (const f of failures)
+        console.error('  - ' + f);
+    process.exit(1);
+}
+console.log('PASS owner-resolution spec');
+console.log(`  observed OwnerName values: ${covered}/${observedNames.length} covered (${resolvable} resolvable, ${covered - resolvable} quarantine-only)`);
+console.log(`  Gallery rows: ${observed.gallery.total}, orphan: ${observed.gallery.orphansTotal}, IdOwner NULL: ${observed.gallery.idOwnerNull}`);
+console.log(`  poly-roots: ${Object.keys(spec.polyRoots).join(', ')} | aliases: ${Object.keys(spec.aliases).length} | unresolved: ${spec.unresolved.policy}`);