@snolla/data 0.0.0-stage → 1.0.7

package/dist/scripts/owners-audit.mjs

@@ -0,0 +1,443 @@
+// The R1 owner-resolution audit: verifier of task:3815, moved into the
+// repository by task:3863 so that its central proof is reproducible.
+//
+//   node packages/data/scripts/owners-audit.mjs
+//   MSSQL_AUDIT_URL=… node packages/data/scripts/owners-audit.mjs --source=mssql
+//
+// `--source=fixture` (the default) runs the checks against the synthetic,
+// deterministic SQLite fixture built from the contract itself — no database, no
+// secrets, same report on every machine — and, unless `--no-compare` is passed,
+// pins that report to the committed production dry-run (`owners/prod-audit-report.json`),
+// so a "green" fixture cannot outlive a contract edit that production never saw.
+// `--source=mssql` runs exactly the same checks, read-only, against a live MSSQL
+// source (the verified local copy of production, or production itself, in check
+// queries only); pass `--compare` to pin it to the committed report too.
+//
+// Any discrepancy outside the quarantine is a non-zero exit: the audit is the
+// oracle, so `--expect-zero` is not a mode, it is the only behaviour.
+import fs from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { createOwnersFixture, loadContract } from './owners-fixture.mjs';
+export const REPO_CONTRACT = loadContract();
+export const PROD_EVIDENCE = fileURLToPath(new URL('./owners/prod-audit-report.json', import.meta.url));
+const lower = (s) => String(s).toLowerCase();
+const num = (v) => Number(v ?? 0);
+// ---------------------------------------------------------------- adapters ---
+/** SQLite adapter over a `node:sqlite` handle (the fixture, or a file copy). */
+export const sqliteAdapter = (db, { source = 'fixture', target = 'in-memory owners fixture' } = {}) => ({
+    source,
+    target,
+    quote: (name) => `"${String(name).replaceAll('"', '""')}"`,
+    query: async (sql) => db.prepare(sql).all(),
+    tableColumns: async (tables) => {
+        const map = new Map();
+        for (const table of tables) {
+            map.set(lower(table), new Set(db.prepare('SELECT name FROM pragma_table_info(?)').all(table).map((r) => lower(r.name))));
+        }
+        return map;
+    },
+    tablesWithColumn: async (column) => {
+        const tables = db.prepare("SELECT name FROM sqlite_master WHERE type = 'table'").all().map((r) => String(r.name));
+        const found = new Set();
+        for (const table of tables) {
+            const has = db.prepare('SELECT name FROM pragma_table_info(?)').all(table).some((r) => lower(r.name) === lower(column));
+            if (has)
+                found.add(lower(table));
+        }
+        return found;
+    },
+    close: async () => { },
+});
+/**
+ * Read-only MSSQL adapter. The URL comes from the environment (`MSSQL_AUDIT_URL`),
+ * never from the repository: credentials are a `secret:`-ref, not a file
+ * (canon/gates Г6). Both the legacy `sqlserver://host:port;key=value;…` form and
+ * the `sqlserver://user:pass@host:port/database?…` form are accepted.
+ */
+export const parseMssqlUrl = (url) => {
+    const stripped = String(url).replace(/^sqlserver:\/\//i, '').replace(/^mssql:\/\//i, '');
+    const queryAt = stripped.indexOf('?');
+    const body = queryAt < 0 ? stripped : stripped.slice(0, queryAt);
+    const queryString = queryAt < 0 ? '' : stripped.slice(queryAt + 1);
+    const [authorityPart, ...tail] = body.split(';');
+    // URI spelling: [user[:password]@]host[:port][/database], and a password may
+    // itself contain `@` (the userinfo ends at the LAST `@`) or `:` (only the
+    // first `:` separates user from password).
+    const slash = authorityPart.indexOf('/');
+    const authority = slash < 0 ? authorityPart : authorityPart.slice(0, slash);
+    const databasePath = slash < 0 ? '' : authorityPart.slice(slash + 1);
+    const at = authority.lastIndexOf('@');
+    const userinfo = at < 0 ? '' : authority.slice(0, at);
+    const hostPort = at < 0 ? authority : authority.slice(at + 1);
+    const [host, port] = hostPort.split(':');
+    const kv = {};
+    for (const chunk of tail) {
+        const i = chunk.indexOf('=');
+        if (i > 0)
+            kv[lower(chunk.slice(0, i)).trim()] = chunk.slice(i + 1).trim();
+    }
+    for (const chunk of queryString.split('&')) {
+        const i = chunk.indexOf('=');
+        if (i > 0)
+            kv[lower(chunk.slice(0, i))] = chunk.slice(i + 1);
+    }
+    const dec = (s) => { try {
+        return decodeURIComponent(s ?? '');
+    }
+    catch {
+        return s ?? '';
+    } };
+    const colon = userinfo.indexOf(':');
+    return {
+        server: host,
+        port: Number(port || 1433),
+        database: dec(kv.database ?? databasePath) || undefined,
+        user: dec(colon < 0 ? userinfo : userinfo.slice(0, colon)) || dec(kv.user),
+        password: dec(colon < 0 ? '' : userinfo.slice(colon + 1)) || dec(kv.password),
+        encrypt: kv.encrypt !== 'false',
+        trustServerCertificate: kv.trustservercertificate === 'true',
+    };
+};
+export const mssqlAdapter = async ({ url, source = 'mssql', target } = {}) => {
+    const { default: tedious } = await import('tedious');
+    const cfg = parseMssqlUrl(url);
+    const connection = new tedious.Connection({
+        server: cfg.server,
+        options: {
+            port: cfg.port,
+            database: cfg.database,
+            encrypt: cfg.encrypt,
+            trustServerCertificate: cfg.trustServerCertificate,
+            rowCollectionOnRequestCompletion: true,
+            requestTimeout: 120000,
+            connectTimeout: 20000,
+            validateBulkLoadParameters: false,
+        },
+        authentication: { type: 'default', options: { userName: cfg.user, password: cfg.password } },
+    });
+    const open = new Promise((resolve, reject) => {
+        connection.on('error', (e) => reject(e));
+        connection.connect((err) => (err ? reject(err) : resolve()));
+    });
+    await open;
+    const query = (sql) => new Promise((resolve, reject) => {
+        const request = new tedious.Request(sql, (err, _count, rows) => (err ? reject(err) : resolve(rows.map((r) => Object.fromEntries(r.map((c) => [c.metadata.colName, c.value]))))));
+        connection.execSqlBatch(request);
+    });
+    return {
+        source,
+        target: target ?? `${cfg.server}/${cfg.database}`,
+        quote: (name) => `[${String(name).replaceAll(']', ']]')}]`,
+        query,
+        tableColumns: async (tables) => {
+            const map = new Map();
+            if (!tables.length)
+                return map;
+            const list = tables.map((t) => `'${t.replaceAll("'", "''")}'`).join(',');
+            for (const r of await query(`SELECT TABLE_NAME AS t, COLUMN_NAME AS c FROM INFORMATION_SCHEMA.COLUMNS WHERE TABLE_NAME IN (${list})`)) {
+                const key = lower(r.t);
+                if (!map.has(key))
+                    map.set(key, new Set());
+                map.get(key).add(lower(r.c));
+            }
+            return map;
+        },
+        // the caller passes literal identifiers here, never input
+        tablesWithColumn: async (column) => new Set((await query(`SELECT TABLE_NAME AS t FROM INFORMATION_SCHEMA.COLUMNS WHERE COLUMN_NAME = '${column.replaceAll("'", "''")}'`))
+            .map((r) => lower(r.t))),
+        close: async () => connection.close(),
+    };
+};
+// ------------------------------------------------------------------ audit ---
+/**
+ * Run every contract check against one adapter. Returns the report (the same
+ * shape the production dry-run produced) and the discrepancy list.
+ */
+export async function runOwnerAudit({ adapter, contract = REPO_CONTRACT, log = () => { } }) {
+    const { spec, observed, ownership } = contract;
+    const T = (name) => adapter.quote(name);
+    const discrepancies = [];
+    const report = { _task: 'task:3815', _source: adapter.source, _target: adapter.target, clusters: {} };
+    // --- declared owner targets: (table, pk) pairs the database really has ---
+    const pairs = Object.values(spec.observedOwners).filter((e) => e.table && e.pk).map((e) => `${e.table}.${e.pk}`);
+    const aliasPairs = Object.values(spec.aliases).filter((a) => a.table && a.pk).map((a) => `${a.table}.${a.pk}`);
+    const allPairs = [...new Set([...pairs, ...aliasPairs])];
+    const declaredTables = [...new Set(allPairs.map((p) => p.slice(0, p.lastIndexOf('.'))))];
+    const columnsOf = await adapter.tableColumns(declaredTables);
+    const live = new Set(allPairs.filter((p) => {
+        const i = p.lastIndexOf('.');
+        return columnsOf.get(lower(p.slice(0, i)))?.has(lower(p.slice(i + 1)));
+    }).map(lower));
+    const liveSite = await adapter.tablesWithColumn('SiteId');
+    const quarantineTables = Object.values(spec.observedOwners)
+        .filter((e) => e.status === 'quarantine-only').map((e) => `${e.table}.${e.pk}`);
+    const missingTargets = allPairs.filter((p) => !live.has(lower(p)));
+    report.ownerTargets = { declared: allPairs.length, live: live.size, missingInDb: missingTargets };
+    log(`[targets] declared=${allPairs.length} live=${live.size} missing=${missingTargets.join(', ') || 'none'}`);
+    for (const p of missingTargets) {
+        if (!quarantineTables.includes(p)) {
+            discrepancies.push(`owner target ${p} is missing from the database but is not declared quarantine-only`);
+        }
+    }
+    // --- static: every resolvable owner either carries SiteId or has a path ---
+    const finalByTable = new Map(ownership.final.map((f) => [f.table, f]));
+    report.paths = [];
+    for (const [name, entry] of Object.entries(spec.observedOwners)) {
+        if (entry.status !== 'resolvable')
+            continue;
+        if (liveSite.has(lower(entry.table))) {
+            report.paths.push({ owner: name, table: entry.table, site: 'direct' });
+            continue;
+        }
+        const path = finalByTable.get(entry.table);
+        report.paths.push({ owner: name, table: entry.table, site: path?.path ? `via ${path.path}` : 'MISSING' });
+        if (!path?.path)
+            discrepancies.push(`owner ${name} (${entry.table}) has no SiteId and no path to Sites in the ownership map`);
+    }
+    // --- Gallery: the driver of every observed OwnerName value ---------------
+    const galleryTargets = Object.entries(spec.observedOwners)
+        .filter(([, e]) => e.status === 'resolvable' && live.has(lower(`${e.table}.${e.pk}`)))
+        .map(([name, e]) => ({ name, table: e.table, pk: e.pk }));
+    // the legacy write path also stores alias targets (ProductVariant, BlogTag, …):
+    // an IdOwner pointing at one of those is resolved, not an orphan
+    const aliasTargets = Object.entries(spec.aliases)
+        .filter(([, a]) => a.table && a.pk && live.has(lower(`${a.table}.${a.pk}`)))
+        .map(([name, a]) => ({ name, table: a.table, pk: a.pk }));
+    const unionTargets = [...new Map([...galleryTargets, ...aliasTargets].map((t) => [`${t.table}.${t.pk}`, t])).values()];
+    const notExists = unionTargets
+        .map((t) => `NOT EXISTS (SELECT 1 FROM ${T(t.table)} o WHERE o.${T(t.pk)} = g.IdOwner)`).join(' AND ');
+    const orphanWhere = `g.IdOwner IS NOT NULL AND ${notExists}`;
+    const gallery = (await adapter.query(`SELECT COUNT(*) AS total, SUM(CASE WHEN IdOwner IS NULL THEN 1 ELSE 0 END) AS noOwner FROM ${T('Gallery')}`))[0];
+    const orphanRows = await adapter.query(`SELECT g.OwnerName AS OwnerName, COUNT(*) AS c FROM ${T('Gallery')} g WHERE ${orphanWhere} GROUP BY g.OwnerName ORDER BY COUNT(*) DESC, g.OwnerName ASC`);
+    const orphans = orphanRows.reduce((sum, r) => sum + num(r.c), 0);
+    report.clusters.gallery = {
+        total: num(gallery.total),
+        idOwnerNull: num(gallery.noOwner),
+        orphans,
+        resolved: num(gallery.total) - orphans,
+        unionTargets: unionTargets.map((t) => `${t.name}:${t.table}.${t.pk}`),
+        orphansByOwnerName: Object.fromEntries(orphanRows.map((r) => [String(r.OwnerName), num(r.c)])),
+    };
+    log(`[gallery] total=${report.clusters.gallery.total} resolved=${report.clusters.gallery.resolved} quarantine=${orphans} idOwnerNull=${num(gallery.noOwner)}`);
+    log('[gallery quarantine by OwnerName] ' + Object.entries(report.clusters.gallery.orphansByOwnerName).map(([k, v]) => `${k}=${v}`).join(' '));
+    if (num(gallery.noOwner) !== spec.observedTotals.idOwnerNull) {
+        discrepancies.push(`Gallery.IdOwner IS NULL = ${num(gallery.noOwner)}, contract says ${spec.observedTotals.idOwnerNull}`);
+    }
+    if (orphans !== spec.observedTotals.orphans) {
+        discrepancies.push(`Gallery quarantine = ${orphans}, contract says ${spec.observedTotals.orphans}`);
+    }
+    for (const [name, expected] of Object.entries(observed.gallery.orphansByOwnerName)) {
+        const got = report.clusters.gallery.orphansByOwnerName[name] ?? 0;
+        if (got !== expected)
+            discrepancies.push(`quarantine by OwnerName: ${name} = ${got}, snapshot says ${expected}`);
+    }
+    // --- cascade of the quarantined galleries (row counts, not galleries) ----
+    const cascade = [
+        ['GalleryImage', `EXISTS (SELECT 1 FROM ${T('Gallery')} g WHERE g.IdGallery = t.IdGallery AND ${orphanWhere})`],
+        ['GalleryImageSize', `EXISTS (SELECT 1 FROM ${T('Gallery')} g WHERE g.IdGallery = t.IdGallery AND ${orphanWhere})`],
+        ['GalleryImageFile', `EXISTS (SELECT 1 FROM ${T('GalleryImage')} i WHERE i.IdImage = t.IdImage AND EXISTS (SELECT 1 FROM ${T('Gallery')} g WHERE g.IdGallery = i.IdGallery AND ${orphanWhere}))`],
+        ['GalleryImageSizeWatermark', `EXISTS (SELECT 1 FROM ${T('GalleryImageSize')} s WHERE s.IdSize = t.GalleryImageSize_IdSize AND EXISTS (SELECT 1 FROM ${T('Gallery')} g WHERE g.IdGallery = s.IdGallery AND ${orphanWhere}))`],
+        ['Watermark', `EXISTS (SELECT 1 FROM ${T('Gallery')} g WHERE g.IdGallery = t.IdGallery AND ${orphanWhere})`],
+    ];
+    report.clusters.quarantineCascade = {};
+    for (const [table, condition] of cascade) {
+        const rows = num((await adapter.query(`SELECT COUNT(*) AS c FROM ${T(table)} t WHERE ${condition}`))[0].c);
+        report.clusters.quarantineCascade[table] = rows;
+        const expected = spec.unresolved.cascadeRows[table];
+        if (expected != null && rows !== expected)
+            discrepancies.push(`quarantine cascade ${table} = ${rows}, contract says ${expected}`);
+    }
+    log('[quarantine cascade] ' + Object.entries(report.clusters.quarantineCascade).map(([k, v]) => `${k}=${v}`).join(' '));
+    // --- rows with no site are orphans only (task:3891, retargeted by task:4092) ---
+    // The migration no longer parks anything: an unplaced row keeps `SiteId` NULL and the cutover
+    // refuses by name. The invariant that catches a wrong plan ORDER is unchanged — a child
+    // backfilled from a parent planted later ends the run with a NULL key whose owner resolves —
+    // and it exists only where the tenant key does: a pre-migration source has nothing to
+    // misattribute, so the section is absent rather than a pile of zeroes nobody measured.
+    //
+    // The predicate is the RESOLVER's, not the orphan-cascade count's: a table whose site can
+    // come from either of two parents (`GalleryImageSizeWatermark` hangs off a gallery image
+    // size AND off the watermark) is misattributed only when a leg that resolves to a LIVE
+    // owner exists. Reusing the inverse of the cascade predicate would both miss rows whose
+    // gallery has no owner and flag the rows a fallback leg legitimately filled.
+    const keylessRows = 't.SiteId IS NULL';
+    const notExistsOwners = (alias) => unionTargets
+        .map((t) => `NOT EXISTS (SELECT 1 FROM ${T(t.table)} o WHERE o.${T(t.pk)} = ${alias}.IdOwner)`).join(' AND ');
+    const liveGallery = (alias) => `${alias}.IdOwner IS NOT NULL AND NOT (${notExistsOwners(alias)})`;
+    const viaGallery = (column, alias) => `EXISTS (SELECT 1 FROM ${T('Gallery')} ${alias} WHERE ${alias}.IdGallery = t.${column} AND ${liveGallery(alias)})`;
+    const liveOwner = [
+        ['Gallery', liveGallery('t')],
+        ['GalleryImage', viaGallery('IdGallery', 'lg1')],
+        ['GalleryImageSize', viaGallery('IdGallery', 'lg2')],
+        ['Watermark', viaGallery('IdGallery', 'lg3')],
+        ['GalleryImageFile', `EXISTS (SELECT 1 FROM ${T('GalleryImage')} i JOIN ${T('Gallery')} lg4 ON lg4.IdGallery = i.IdGallery WHERE i.IdImage = t.IdImage AND ${liveGallery('lg4')})`],
+        ['GalleryImageSizeWatermark', `EXISTS (SELECT 1 FROM ${T('GalleryImageSize')} s JOIN ${T('Gallery')} lg5 ON lg5.IdGallery = s.IdGallery WHERE s.IdSize = t.GalleryImageSize_IdSize AND ${liveGallery('lg5')})
+            OR EXISTS (SELECT 1 FROM ${T('Watermark')} w JOIN ${T('Gallery')} lg6 ON lg6.IdGallery = w.IdGallery WHERE w.IdWatermark = t.Watermark_IdWatermark AND ${liveGallery('lg6')})`],
+    ].filter(([table]) => liveSite.has(lower(table)));
+    if (liveOwner.length) {
+        report.clusters.siteLessLiveOwner = {};
+        for (const [table, condition] of liveOwner) {
+            const rows = num((await adapter.query(`SELECT COUNT(*) AS c FROM ${T(table)} t WHERE ${keylessRows} AND (${condition})`))[0].c);
+            if (rows === 0)
+                continue;
+            report.clusters.siteLessLiveOwner[table] = rows;
+            discrepancies.push(`row without a site holds a live owner: ${table} = ${rows} rows with a NULL SiteId whose owner resolves`);
+        }
+        log('[row without a site holds a live owner] ' + (Object.keys(report.clusters.siteLessLiveOwner).length
+            ? JSON.stringify(report.clusters.siteLessLiveOwner) : 'none'));
+    }
+    // --- GalleryImageFile hangs off GalleryImage (no direct gallery FK) ------
+    const broken = num((await adapter.query(`SELECT COUNT(*) AS c FROM ${T('GalleryImageFile')} f WHERE NOT EXISTS (SELECT 1 FROM ${T('GalleryImage')} i WHERE i.IdImage = f.IdImage)`))[0].c);
+    report.clusters.galleryImageFile = { brokenLinkToImage: broken };
+    if (broken !== 0)
+        discrepancies.push(`GalleryImageFile rows without a GalleryImage parent: ${broken}`);
+    // --- Modules: the host is a real FK, not an OwnerName -------------------
+    const moduleColumns = (await adapter.tableColumns(['Modules'])).get('modules') ?? new Set();
+    const hostColumns = ['PostId', 'PageId'].filter((c) => moduleColumns.has(lower(c)));
+    const modTotal = num((await adapter.query(`SELECT COUNT(*) AS c FROM ${T('Modules')}`))[0].c);
+    const modNoHost = num((await adapter.query(`SELECT COUNT(*) AS c FROM ${T('Modules')} WHERE PostId IS NULL AND PageId IS NULL`))[0].c);
+    const modOrphanPost = num((await adapter.query(`SELECT COUNT(*) AS c FROM ${T('Modules')} m WHERE m.PostId IS NOT NULL AND NOT EXISTS (SELECT 1 FROM ${T('Posts')} p WHERE p.PostId = m.PostId)`))[0].c);
+    const modOrphanPage = num((await adapter.query(`SELECT COUNT(*) AS c FROM ${T('Modules')} m WHERE m.PageId IS NOT NULL AND NOT EXISTS (SELECT 1 FROM ${T('Pages')} p WHERE p.PageId = m.PageId)`))[0].c);
+    report.clusters.modules = {
+        hostColumns,
+        total: modTotal,
+        noHost: modNoHost,
+        orphanPost: modOrphanPost,
+        orphanPage: modOrphanPage,
+        resolved: modTotal - modNoHost - modOrphanPost - modOrphanPage,
+    };
+    log(`[modules] total=${modTotal} resolved=${report.clusters.modules.resolved} noHost=${modNoHost} orphanPost=${modOrphanPost} orphanPage=${modOrphanPage}`);
+    if (modNoHost !== 0)
+        discrepancies.push(`Modules without a host (PostId/PageId both NULL): ${modNoHost}`);
+    if (modOrphanPost !== 0 || modOrphanPage !== 0)
+        discrepancies.push(`Modules with a dangling host FK: post=${modOrphanPost} page=${modOrphanPage}`);
+    // --- Numbering: counters resolve through OwnerId; tasks are the seed ----
+    const nt = num((await adapter.query(`SELECT COUNT(*) AS c FROM ${T('NumberingTasks')}`))[0].c);
+    const ncTotal = num((await adapter.query(`SELECT COUNT(*) AS c FROM ${T('NumberingCounters')}`))[0].c);
+    const ncDistinct = num((await adapter.query(`SELECT COUNT(DISTINCT OwnerId) AS c FROM ${T('NumberingCounters')}`))[0].c);
+    const ncNoOwner = num((await adapter.query(`SELECT COUNT(*) AS c FROM ${T('NumberingCounters')} WHERE OwnerId IS NULL`))[0].c);
+    const ncQuarantine = num((await adapter.query(`SELECT COUNT(*) AS c FROM ${T('NumberingCounters')} c WHERE c.OwnerId IS NOT NULL
+        AND NOT EXISTS (SELECT 1 FROM ${T('Blogs')} b WHERE b.BlogId = c.OwnerId)
+        AND NOT EXISTS (SELECT 1 FROM ${T('Stores')} s WHERE s.StoreId = c.OwnerId)
+        AND NOT EXISTS (SELECT 1 FROM ${T('Catalogs')} k WHERE k.CatalogId = c.OwnerId)
+        AND NOT EXISTS (SELECT 1 FROM ${T('Sites')} s WHERE s.SiteId = c.OwnerId)`))[0].c);
+    report.clusters.numbering = { tasks: nt, counters: ncTotal, distinctOwners: ncDistinct, counterNoOwner: ncNoOwner, counterQuarantine: ncQuarantine };
+    log(`[numbering] tasks=${nt} counters=${ncTotal} distinctOwners=${ncDistinct} quarantine=${ncQuarantine}`);
+    if (nt !== spec.numbering.tasks.seed)
+        discrepancies.push(`NumberingTasks = ${nt}, contract seed says ${spec.numbering.tasks.seed}`);
+    if (ncTotal !== spec.numbering.counters.rows)
+        discrepancies.push(`NumberingCounters = ${ncTotal}, contract says ${spec.numbering.counters.rows}`);
+    if (ncDistinct !== spec.numbering.counters.distinctOwners)
+        discrepancies.push(`distinct NumberingCounters.OwnerId = ${ncDistinct}, contract says ${spec.numbering.counters.distinctOwners}`);
+    if (ncNoOwner !== 0)
+        discrepancies.push(`NumberingCounters without OwnerId: ${ncNoOwner}`);
+    // --- dead-template dictionaries: nothing to resolve ---------------------
+    const git = num((await adapter.query(`SELECT COUNT(*) AS c FROM ${T('GalleryImagesTemplates')}`))[0].c);
+    report.clusters.galleryImagesTemplates = { rows: git };
+    if (git !== observed.emptyMaps.GalleryImagesTemplates) {
+        discrepancies.push(`GalleryImagesTemplates = ${git}, snapshot says ${observed.emptyMaps.GalleryImagesTemplates}`);
+    }
+    report.discrepancies = discrepancies;
+    return { report, discrepancies };
+}
+/** Compare a fresh report with a committed one, ignoring where it ran. */
+export const reportDiff = (fresh, expected) => {
+    const strip = ({ _source, _target, ...rest }) => rest;
+    const diff = [];
+    const walk = (a, b, path) => {
+        const keys = [...new Set([...Object.keys(a ?? {}), ...Object.keys(b ?? {})])];
+        for (const key of keys) {
+            const va = a?.[key];
+            const vb = b?.[key];
+            const at = path ? `${path}.${key}` : key;
+            if (va && vb && typeof va === 'object' && typeof vb === 'object')
+                walk(va, vb, at);
+            else if (JSON.stringify(va) !== JSON.stringify(vb))
+                diff.push(`${at}: fresh=${JSON.stringify(va)} expected=${JSON.stringify(vb)}`);
+        }
+    };
+    walk(strip(fresh), strip(expected), '');
+    return diff;
+};
+// -------------------------------------------------------------------- CLI ---
+const args = process.argv.slice(2);
+const flag = (name, fallback = undefined) => {
+    const hit = args.find((a) => a === `--${name}` || a.startsWith(`--${name}=`));
+    if (!hit)
+        return fallback;
+    return hit.includes('=') ? hit.slice(hit.indexOf('=') + 1) : true;
+};
+const source = flag('source', 'fixture');
+const noCompare = args.includes('--no-compare');
+const reportPath = flag('report');
+const compareFlag = flag('compare');
+// the fixture is pinned to the committed production report by default: a green
+// fixture must mean "the contract still matches what production looked like".
+const comparePath = compareFlag
+    ? (compareFlag === true ? PROD_EVIDENCE : compareFlag)
+    : (source === 'fixture' && !noCompare ? PROD_EVIDENCE : null);
+const main = async () => {
+    let adapter;
+    let fixture;
+    if (source === 'fixture') {
+        fixture = createOwnersFixture();
+        adapter = sqliteAdapter(fixture.db, {
+            source: 'fixture: packages/data/scripts/owners-fixture.mjs (synthetic, derived from the contract)',
+            target: `${fixture.tableCount} generated tables`,
+        });
+    }
+    else if (source === 'mssql') {
+        const url = process.env.MSSQL_AUDIT_URL;
+        if (!url) {
+            console.error('MSSQL_AUDIT_URL is not set — the connection string is a secret-ref (canon/gates Г6), not a repo file.');
+            process.exit(2);
+        }
+        try {
+            adapter = await mssqlAdapter({ url });
+        }
+        catch (e) {
+            console.error(`[connect] ${e.message}`);
+            process.exit(2);
+        }
+    }
+    else {
+        console.error(`unknown --source=${source} (fixture | mssql)`);
+        process.exit(2);
+    }
+    const { report, discrepancies } = await runOwnerAudit({ adapter, log: (m) => console.log(m) });
+    await adapter.close();
+    if (reportPath) {
+        fs.writeFileSync(reportPath === true ? 'owners-audit-report.json' : reportPath, JSON.stringify(report, null, 2) + '\n');
+        console.log(`report: ${reportPath}`);
+    }
+    if (comparePath) {
+        let expected;
+        try {
+            expected = JSON.parse(fs.readFileSync(comparePath, 'utf8'));
+        }
+        catch (e) {
+            console.error(`cannot read the comparison report ${comparePath}: ${e.message}`);
+            process.exit(2);
+        }
+        const diff = reportDiff(report, expected);
+        if (diff.length) {
+            console.error(`\nFAIL report drift against ${comparePath}: ${diff.length} field(s) differ`);
+            for (const line of diff)
+                console.error('  ' + line);
+            process.exit(1);
+        }
+        console.log(`[compare] ${comparePath}: identical (mode/target ignored)`);
+    }
+    if (discrepancies.length) {
+        console.error(`\nFAIL owner audit: ${discrepancies.length} discrepancy(ies) outside the quarantine`);
+        for (const d of discrepancies)
+            console.error('  - ' + d);
+        process.exit(1);
+    }
+    console.log('\nPASS owner audit: 0 discrepancies outside the quarantine');
+    const cascadeRows = Object.values(report.clusters.quarantineCascade).reduce((a, b) => a + b, 0);
+    console.log(`  quarantined (allowed): Gallery ${report.clusters.gallery.orphans} + cascade ${cascadeRows} rows, NumberingCounters ${report.clusters.numbering.counterQuarantine}`);
+};
+if (process.argv[1] && fileURLToPath(import.meta.url) === fs.realpathSync(process.argv[1])) {
+    await main();
+}

package/dist/scripts/owners-fixture.d.mts

@@ -0,0 +1,20 @@
+/**
+ * Build the fixture database. Returns the live `DatabaseSync` handle plus the
+ * resolved contract, so a caller can drive the same audit the CLI does.
+ */
+export function createOwnersFixture(): {
+    db: DatabaseSync;
+    contract: {
+        spec: any;
+        observed: any;
+        ownership: any;
+    };
+    tableCount: number;
+};
+export function readContract(file: any): any;
+export function loadContract(): {
+    spec: any;
+    observed: any;
+    ownership: any;
+};
+import { DatabaseSync } from 'node:sqlite';

package/dist/scripts/owners-fixture.mjs

@@ -0,0 +1,192 @@
+// A synthetic, deterministic fixture for the R1 owner-resolution audit
+// (task:3863, the verifier of task:3815).
+//
+// The audit used to run only against the production MSSQL server, which made
+// its central proof (0 discrepancies outside the quarantine) impossible to
+// reproduce: no scripts, no inputs and no report lived in the repository. The
+// fixture below closes that gap — it builds an in-memory SQLite database whose
+// *shape* is derived from the contract itself (`owner-resolve-spec.json`), the
+// frozen production snapshot (`owners-observed.json`) and the ownership map
+// (`ownership-final.json`), so the checker can be exercised anywhere:
+//
+//   node packages/data/scripts/owners-audit.mjs --source=fixture --expect-zero
+//
+// What the fixture proves: the audit *runs deterministically from the repo* and
+// its checks hold on data that satisfies the contract. What it does NOT prove:
+// anything about production. That evidence is the committed report
+// `owners/prod-audit-report.json` plus a re-run in `--source=mssql` mode against
+// the verified local copy of production (wiki:concepts/db-local-prod-copy).
+//
+// Every number here is derived from the contract files, never hardcoded: if the
+// contract says "638 orphans, cascade 297/1048/295/17/14", the generator creates
+// exactly that, and the audit independently re-measures it.
+import fs from 'node:fs';
+import { DatabaseSync } from 'node:sqlite';
+import { fileURLToPath } from 'node:url';
+const CONTRACT_DIR = new URL('./owners/', import.meta.url);
+export const readContract = (file) => JSON.parse(fs.readFileSync(fileURLToPath(new URL(file, CONTRACT_DIR)), 'utf8'));
+export const loadContract = () => ({
+    spec: readContract('owner-resolve-spec.json'),
+    observed: readContract('owners-observed.json'),
+    ownership: readContract('ownership-final.json'),
+});
+const ident = (name) => `"${String(name).replaceAll('"', '""')}"`;
+/**
+ * Build the fixture database. Returns the live `DatabaseSync` handle plus the
+ * resolved contract, so a caller can drive the same audit the CLI does.
+ */
+export function createOwnersFixture() {
+    const contract = loadContract();
+    const { spec, observed, ownership } = contract;
+    const db = new DatabaseSync(':memory:');
+    const created = new Set();
+    const createTable = (table, columns) => {
+        if (created.has(table))
+            return;
+        created.add(table);
+        db.exec(`CREATE TABLE ${ident(table)} (${columns.map(ident).join(', ')})`);
+    };
+    const insert = (table, columns, rows) => {
+        if (!rows.length)
+            return;
+        const stmt = db.prepare(`INSERT INTO ${ident(table)} (${columns.map(ident).join(', ')}) VALUES (${columns.map(() => '?').join(', ')})`);
+        for (const row of rows)
+            stmt.run(...columns.map((c) => row[c]));
+    };
+    const rowsFor = (table, columns, values, map) => {
+        createTable(table, columns);
+        insert(table, columns, values.map(map));
+    };
+    // ---- owner targets: one table per declared (table, pk), then the rows that
+    // the resolved galleries will point at.
+    const siteColOf = new Map(ownership.final.map((f) => [f.table, f.siteCol]));
+    const declaredPairs = new Map(); // table -> pk
+    for (const entry of Object.values(spec.observedOwners)) {
+        if (entry.table && entry.pk)
+            declaredPairs.set(entry.table, entry.pk);
+    }
+    for (const alias of Object.values(spec.aliases)) {
+        if (alias.table && alias.pk && !declaredPairs.has(alias.table))
+            declaredPairs.set(alias.table, alias.pk);
+    }
+    const polyRoots = spec.polyRoots ?? {};
+    const targets = {}; // owner name -> { table, pk, ids: string[] }
+    const galleries = [];
+    const quarantineGalleries = [];
+    for (const [name, entry] of Object.entries(spec.observedOwners)) {
+        if (!entry.table || !entry.pk)
+            throw new Error(`fixture: ${name} has no (table, pk) target`);
+        const total = observed.gallery.byOwnerName?.[name] ?? 0;
+        const orphans = observed.gallery.orphansByOwnerName?.[name] ?? 0;
+        const resolved = total - orphans;
+        if (resolved < 0)
+            throw new Error(`fixture: ${name} has more orphans (${orphans}) than rows (${total})`);
+        const columns = [entry.pk];
+        if (polyRoots[entry.table]?.hostColumns)
+            columns.push(...polyRoots[entry.table].hostColumns);
+        else if (siteColOf.get(entry.table) === 'SiteId')
+            columns.push('SiteId');
+        createTable(entry.table, columns);
+        // Modules is a poly-root: its host is a real FK to Posts (or Pages), so
+        // every module row must point at a host row the fixture also creates.
+        const hostOf = polyRoots[entry.table]?.hostTables ?? {};
+        const ids = [];
+        for (let i = 1; i <= Math.max(resolved, 0); i += 1)
+            ids.push(`${entry.table}#${i}`);
+        const rowCount = Math.max(resolved, entry.status === 'resolvable' && entry.table === 'Modules'
+            ? (polyRoots.Modules.evidence?.total ?? resolved) : resolved);
+        const rows = [];
+        for (let i = 0; i < rowCount; i += 1) {
+            const row = { [entry.pk]: ids[i] ?? `${entry.table}#${i + 1}` };
+            for (const [column, hostTable] of Object.entries(hostOf)) {
+                row[column] = hostTable === 'Posts' ? 'Posts#1' : null;
+            }
+            if (columns.includes('SiteId'))
+                row.SiteId = 'Sites#1';
+            rows.push(row);
+            if (!ids.includes(row[entry.pk]))
+                ids.push(row[entry.pk]);
+        }
+        insert(entry.table, columns, rows);
+        targets[name] = { table: entry.table, pk: entry.pk, ids };
+        for (let i = 0; i < resolved; i += 1) {
+            galleries.push({ IdGallery: `Gallery#${galleries.length + 1}`, IdOwner: ids[i], OwnerName: name });
+        }
+        for (let i = 0; i < orphans; i += 1) {
+            const g = { IdGallery: `Gallery#${galleries.length + 1}`, IdOwner: `orphan:${name}:${i + 1}`, OwnerName: name };
+            galleries.push(g);
+            quarantineGalleries.push(g);
+        }
+    }
+    // Declared but never observed (aliases with a table, the dropped Parts): the
+    // tables must still exist, empty, or the "declared target is missing" check
+    // fires for a reason the contract did not intend.
+    for (const [table, pk] of declaredPairs)
+        createTable(table, [pk]);
+    // ---- poly-root hosts need a row the modules can point at
+    if (polyRoots.Modules)
+        createTable('Pages', ['PageId', 'SiteId']);
+    // ---- numbering: the seed rows and the counters, all resolvable through
+    // owner rows (the contract says quarantine is measured, not allowed).
+    const numbering = spec.numbering ?? {};
+    const taskSeed = numbering.tasks?.seed ?? 0;
+    createTable('NumberingTasks', ['TaskId', 'Label']);
+    insert('NumberingTasks', ['TaskId', 'Label'], Array.from({ length: taskSeed }, (_, i) => ({ TaskId: `NumberingTasks#${i + 1}`, Label: numbering.tasks?.labels?.[i] ?? `task-${i + 1}` })));
+    const counterRows = numbering.counters?.rows ?? 0;
+    const distinctOwners = numbering.counters?.distinctOwners ?? counterRows;
+    createTable('Sites', ['SiteId']);
+    insert('Sites', ['SiteId'], Array.from({ length: distinctOwners }, (_, i) => ({ SiteId: `Sites#${i + 1}` })));
+    createTable('NumberingCounters', ['CounterId', 'OwnerId']);
+    insert('NumberingCounters', ['CounterId', 'OwnerId'], Array.from({ length: counterRows }, (_, i) => ({
+        CounterId: `NumberingCounters#${i + 1}`,
+        OwnerId: `Sites#${(i % distinctOwners) + 1}`,
+    })));
+    // ---- cascade of the quarantined galleries: the child rows stay, that is
+    // the operator's verdict, so the fixture reproduces them exactly.
+    const cascade = spec.unresolved?.cascadeRows ?? {};
+    const orphanIds = quarantineGalleries.map((g) => g.IdGallery);
+    const pickOrphan = (i) => orphanIds[i % orphanIds.length];
+    for (const table of ['GalleryImage', 'GalleryImageSize', 'GalleryImageFile', 'GalleryImageSizeWatermark', 'Watermark']) {
+        const count = cascade[table] ?? 0;
+        if (!count)
+            continue;
+        if (table === 'GalleryImage') {
+            createTable(table, ['IdImage', 'IdGallery']);
+            insert(table, ['IdImage', 'IdGallery'], Array.from({ length: count }, (_, i) => ({
+                IdImage: `GalleryImage#${i + 1}`, IdGallery: pickOrphan(i),
+            })));
+        }
+        else if (table === 'GalleryImageSize') {
+            createTable(table, ['IdSize', 'IdGallery']);
+            insert(table, ['IdSize', 'IdGallery'], Array.from({ length: count }, (_, i) => ({
+                IdSize: `GalleryImageSize#${i + 1}`, IdGallery: pickOrphan(i),
+            })));
+        }
+        else if (table === 'GalleryImageFile') {
+            createTable(table, ['IdFile', 'IdImage']);
+            insert(table, ['IdFile', 'IdImage'], Array.from({ length: count }, (_, i) => ({
+                IdFile: `GalleryImageFile#${i + 1}`, IdImage: `GalleryImage#${(i % (cascade.GalleryImage ?? 1)) + 1}`,
+            })));
+        }
+        else if (table === 'GalleryImageSizeWatermark') {
+            createTable(table, ['Id', 'GalleryImageSize_IdSize']);
+            insert(table, ['Id', 'GalleryImageSize_IdSize'], Array.from({ length: count }, (_, i) => ({
+                Id: `GalleryImageSizeWatermark#${i + 1}`,
+                GalleryImageSize_IdSize: `GalleryImageSize#${(i % (cascade.GalleryImageSize ?? 1)) + 1}`,
+            })));
+        }
+        else {
+            createTable(table, ['IdWatermark', 'IdGallery']);
+            insert(table, ['IdWatermark', 'IdGallery'], Array.from({ length: count }, (_, i) => ({
+                IdWatermark: `Watermark#${i + 1}`, IdGallery: pickOrphan(i),
+            })));
+        }
+    }
+    // ---- the dead-template dictionary (0 rows on production, and the contract
+    // uses it as a "is the audit looking where it says" control).
+    createTable('GalleryImagesTemplates', ['IdTemplate']);
+    // ---- the poly-root itself
+    createTable('Gallery', ['IdGallery', 'IdOwner', 'OwnerName']);
+    insert('Gallery', ['IdGallery', 'IdOwner', 'OwnerName'], galleries);
+    return { db, contract, tableCount: created.size };
+}