@snolla/data 0.0.0-stage → 1.0.7

package/dist/actor.d.ts

@@ -0,0 +1,28 @@
+import { type Kysely } from 'kysely';
+export declare const UNKNOWN_ACTOR = "\u043D\u0435\u0438\u0437\u0432\u0435\u0441\u0442\u043D\u044B\u0439 \u0430\u043A\u0442\u043E\u0440";
+export declare const UNAVAILABLE_ADMIN = "\u043F\u043E\u043B\u044C\u0437\u043E\u0432\u0430\u0442\u0435\u043B\u044C \u043D\u0435\u0434\u043E\u0441\u0442\u0443\u043F\u0435\u043D";
+/** The administrator columns a name can come from: full name, then username, then email. */
+export interface AdministratorNameRow {
+    AdministratorId?: string | null;
+    FirstName?: string | null;
+    LastName?: string | null;
+    Username?: string | null;
+    Email?: string | null;
+}
+/**
+ * Label for an administrator row, or `пользователь недоступен` when the row is gone.
+ * Takes the row rather than an id so a caller that already joined `Administrators` does
+ * not pay for a second read.
+ */
+export declare const administratorLabel: (row: AdministratorNameRow | null | undefined) => string;
+export interface ResolvedActor {
+    /** The administrator behind the actor id, when the id resolves to one. */
+    administratorId: string | null;
+    label: string;
+}
+/**
+ * Resolve an actor id to the administrator behind it and the label to show.
+ * An id that is neither an administrator nor an API key resolves to nobody — and the
+ * label is the "unknown actor" wording, never the raw GUID.
+ */
+export declare const resolveActor: (db: Kysely<unknown>, actorId: string | null | undefined) => Promise<ResolvedActor>;

package/dist/actor.js

@@ -0,0 +1,63 @@
+// The actor label — one resolver for every surface (requirements:67 R3.5/R3.6, task:3982).
+//
+// A row carries an administrator id (`CreatedById`/`UpdatedById`), and the id is a soft
+// reference: an import into a database without that administrator keeps it, so the row
+// still renders history. Two labels cover the two ways that can end:
+//
+//   * the id resolves to nobody — not an administrator, not an API key:
+//     `неизвестный актор` (there is no person to name);
+//   * the id is an administrator's, but the row is gone from this database:
+//     `пользователь недоступен` (we know who it was, we cannot name them).
+//
+// The chain is the contract's: `Administrators` → `ApiKeys` (a key acts on behalf of its
+// owner) → unknown. Kept here rather than in the admin API so the engine, the cell and a
+// future UI all resolve the same way, and so a surface cannot invent a third wording.
+import { sql } from 'kysely';
+export const UNKNOWN_ACTOR = 'неизвестный актор';
+export const UNAVAILABLE_ADMIN = 'пользователь недоступен';
+/**
+ * Label for an administrator row, or `пользователь недоступен` when the row is gone.
+ * Takes the row rather than an id so a caller that already joined `Administrators` does
+ * not pay for a second read.
+ */
+export const administratorLabel = (row) => {
+    // The row being absent is a different story from the row having no name: an
+    // administrator with no FirstName/Username/Email still exists and can log in, so
+    // calling them "пользователь недоступен" would be a lie about the data.
+    if (!row)
+        return UNAVAILABLE_ADMIN;
+    const full = [row.FirstName, row.LastName].map((part) => part?.trim()).filter(Boolean).join(' ');
+    return full || row.Username?.trim() || row.Email?.trim() || UNKNOWN_ACTOR;
+};
+/** Read an administrator by id, or by the key id that acts on their behalf. */
+const readAdministrator = async (db, actorId) => {
+    const direct = await sql `
+        select ${sql.id('AdministratorId')}, ${sql.id('FirstName')}, ${sql.id('LastName')}, ${sql.id('Username')}, ${sql.id('Email')}
+        from ${sql.table('Administrators')}
+        where ${sql.id('AdministratorId')} = ${actorId}
+    `.execute(db);
+    if (direct.rows[0])
+        return direct.rows[0];
+    const viaKey = await sql `
+        select a.${sql.id('AdministratorId')} as ${sql.id('AdministratorId')}, a.${sql.id('FirstName')} as ${sql.id('FirstName')},
+               a.${sql.id('LastName')} as ${sql.id('LastName')}, a.${sql.id('Username')} as ${sql.id('Username')},
+               a.${sql.id('Email')} as ${sql.id('Email')}
+        from ${sql.table('ApiKeys')} k
+        join ${sql.table('Administrators')} a on a.${sql.id('AdministratorId')} = k.${sql.id('AdministratorId')}
+        where k.${sql.id('ApiKeyId')} = ${actorId}
+    `.execute(db);
+    return viaKey.rows[0] ?? null;
+};
+/**
+ * Resolve an actor id to the administrator behind it and the label to show.
+ * An id that is neither an administrator nor an API key resolves to nobody — and the
+ * label is the "unknown actor" wording, never the raw GUID.
+ */
+export const resolveActor = async (db, actorId) => {
+    if (!actorId)
+        return { administratorId: null, label: UNKNOWN_ACTOR };
+    const administrator = await readAdministrator(db, actorId);
+    if (!administrator)
+        return { administratorId: null, label: UNKNOWN_ACTOR };
+    return { administratorId: administrator.AdministratorId, label: administratorLabel(administrator) };
+};

package/dist/audit.d.ts

@@ -0,0 +1,36 @@
+import { type Kysely } from 'kysely';
+export type AuditCheck = 'missing-table' | 'unexpected-table' | 'missing-tenant-key' | 'unexpected-tenant-key' | 'tenant-key-nullable' | 'divergent-tenant-key' | 'divergent-tenant-key-vs-owner' | 'ambiguous-owner' | 'dangling-owner';
+export interface AuditViolation {
+    check: AuditCheck;
+    table?: string;
+    detail: string;
+    /** how many rows are affected, when the check counts rows. */
+    rows?: number;
+}
+/**
+ * A polymorphic-owner finding. `divergent` and an inexcusable `dangling` are also
+ * violations; `ambiguous` is a report, because picking by declaration order is how the
+ * contract resolves and only the data can say whether the pick was right.
+ */
+export interface OwnerResolveFinding {
+    check: 'divergent-tenant-key-vs-owner' | 'ambiguous-owner' | 'dangling-owner';
+    table: string;
+    detail: string;
+    rows: number;
+    /** `dangling-owner` only: the contract declares this orphan shape legitimate. */
+    allowed?: boolean;
+}
+export interface OwnerResolveReport {
+    divergent: number;
+    ambiguous: number;
+    dangling: number;
+    danglingAllowed: number;
+    findings: OwnerResolveFinding[];
+}
+export interface AuditReport {
+    ok: boolean;
+    checks: number;
+    violations: AuditViolation[];
+    ownerResolve: OwnerResolveReport;
+}
+export declare const auditTenantInvariants: (db: Kysely<unknown>) => Promise<AuditReport>;

package/dist/audit.js

@@ -0,0 +1,198 @@
+// Tenant-invariant audit (task:3814; plan:48 R1-Q2/R1-Q5).
+//
+// A reusable check that a database actually *is* the canon — and stays one after
+// an import. It answers the three questions the acceptance criteria ask:
+//
+//   1. schema: every canon table is present, every site-scoped table carries a
+//      NOT NULL `SiteId`, no table carries one the canon does not declare, and
+//      nothing outside the canon has appeared;
+//   2. data: no row disagrees with its parent about the tenant across a foreign
+//      key chain (`child.SiteId = parent.SiteId`);
+//   3. (removed by task:4052) a quarantine sentinel row used to be required and
+//      checked for its freeze. A single-tenant database has no orphan rows to park,
+//      so the canon carries no such row and there is nothing to verify.
+//
+// Everything is expressed through Kysely, so the same audit runs on Postgres,
+// MariaDB and SQLite — the dialects the product must support (plan:49 Q6).
+//
+// The audit is intentionally independent of the guard: the guard prevents bad
+// writes, the audit proves nothing bad is there. Both read the same canon.
+import { createRequire } from 'node:module';
+import { sql } from 'kysely';
+import { POLY_ROOTS, polyLinks } from './migrations/siteid.mjs';
+import { canonicalSchema, isSiteScoped } from "./schema/index.js";
+const require = createRequire(import.meta.url);
+// The owner-resolution contract, the same one the SiteId migration writes rows through.
+// The audit reads that list rather than a copy of the rules: a check derived from a second
+// copy proves the wrong thing (the defect task:3894 removed from the planner).
+const ownerSpec = require('./scripts/owners/owner-resolve-spec.json');
+const CANON_TABLES = new Map(canonicalSchema.tables.map((t) => [t.name, t]));
+const readRows = (result) => result.rows ?? [];
+const readCount = (result) => {
+    const [first = {}] = readRows(result);
+    const value = first.c ?? Object.values(first)[0];
+    return Number(value ?? 0);
+};
+/** MariaDB and SQLite materialise `bool` as 0/1; Postgres as a real boolean. */
+const isTruthy = (value) => value === true || value === 1 || value === '1';
+export const auditTenantInvariants = async (db) => {
+    const violations = [];
+    // `checks` counts verification steps that actually ran. It is reported so a
+    // caller can tell "nothing was wrong" from "nothing was looked at"; a
+    // formula over the canon would lie exactly when the database drifts.
+    let checks = 0;
+    const liveTables = await db.introspection.getTables();
+    const live = new Map(liveTables.map((t) => [t.name, t]));
+    // 1. schema shape
+    for (const table of canonicalSchema.tables) {
+        checks += 1; // the canon table is present under its own name
+        const liveTable = live.get(table.name);
+        if (!liveTable) {
+            violations.push({ check: 'missing-table', table: table.name, detail: 'canon table is absent from the database' });
+            continue;
+        }
+        checks += 1; // the tenant-key column agrees with the canon (present or not)
+        const expected = table.columns.SiteId !== undefined;
+        const actual = liveTable.columns.find((c) => c.name === 'SiteId');
+        if (expected && !actual) {
+            violations.push({ check: 'missing-tenant-key', table: table.name, detail: 'SiteId column is missing' });
+        }
+        if (!expected && actual) {
+            violations.push({
+                check: 'unexpected-tenant-key',
+                table: table.name,
+                detail: 'SiteId column exists but the canon does not declare it',
+            });
+        }
+        if (expected && actual && table.columns.SiteId.nullable !== true) {
+            checks += 1; // the tenant key is NOT NULL, as the canon says
+            if (actual.isNullable) {
+                violations.push({ check: 'tenant-key-nullable', table: table.name, detail: 'SiteId is nullable, the canon says NOT NULL' });
+            }
+        }
+    }
+    for (const liveTable of liveTables) {
+        checks += 1; // every live table is compared against the canon
+        if (!CANON_TABLES.has(liveTable.name)) {
+            violations.push({ check: 'unexpected-table', table: liveTable.name, detail: 'table outside the canon' });
+        }
+    }
+    // 2. data: the tenant key must agree along every foreign key chain that
+    //    stays inside site-scoped tables
+    for (const child of canonicalSchema.tables.filter(isSiteScoped)) {
+        for (const fk of child.fks ?? []) {
+            const parent = CANON_TABLES.get(fk.ref);
+            if (!parent || !isSiteScoped(parent))
+                continue;
+            if (!live.has(child.name) || !live.has(parent.name))
+                continue;
+            const result = await sql `
+                select count(*) as c
+                from ${sql.table(child.name)} c
+                join ${sql.table(parent.name)} p
+                  on ${sql.join(fk.columns.map((column, i) => sql `${sql.id('c', column)} = ${sql.id('p', fk.refColumns[i])}`), sql ` and `)}
+                where ${sql.id('c', 'SiteId')} <> ${sql.id('p', 'SiteId')}
+            `.execute(db);
+            checks += 1; // one query per FK chain that stays inside the canon
+            const rows = readCount(result);
+            if (rows > 0) {
+                violations.push({
+                    check: 'divergent-tenant-key',
+                    table: child.name,
+                    detail: `${child.name}.${fk.columns.join(', ')} -> ${parent.name}.${fk.refColumns.join(', ')} disagrees with the parent tenant`,
+                    rows,
+                });
+            }
+        }
+    }
+    // 2b. polymorphic owners: these tables take their site from a soft reference
+    //     (`Folders.OwnerId`, `Gallery.IdOwner`, the `PostId`/`PageId` host of `Modules`,
+    //     the counter and watermark legs), so no foreign key can prove the row agrees with
+    //     its owner and no database can refuse the disagreement (task:3977). Content is
+    //     never moved between sites, so the risk is the resolution itself: a divergent row
+    //     would travel to a foreign tenant, a dangling one would travel nowhere (a silent
+    //     loss), and an ambiguous one carries a guess by declaration order forever.
+    const ownerResolve = { divergent: 0, ambiguous: 0, dangling: 0, danglingAllowed: 0, findings: [] };
+    for (const root of [...new Set([...POLY_ROOTS, ...Object.keys(ownerSpec.polyRoots ?? {})])]) {
+        const links = polyLinks(root, ownerSpec).filter((link) => live.has(root) && live.has(link.table));
+        if (!links.length)
+            continue;
+        // A root may resolve through several legs that are NOT candidates for one value:
+        // `GalleryImageSizeWatermark` reads `GalleryImageSize_IdSize` and
+        // `Watermark_IdWatermark`, two different columns. Ambiguity is per column — one value
+        // matching two tables — so only a column with more than one candidate can be ambiguous.
+        const byColumn = new Map();
+        for (const link of links)
+            byColumn.set(link.column, [...(byColumn.get(link.column) ?? []), link]);
+        const contested = [...byColumn.values()].filter((group) => group.length > 1);
+        // "this owner id matches a candidate row" — the probe the shapes below count over.
+        const matched = links.map((link) => sql `case when exists (select 1 from ${sql.table(link.table)} o where ${sql.id('o', link.pk)} = ${sql.id('c', link.column)}) then 1 else 0 end`);
+        const matchedIn = sql `(${sql.join(matched, sql ` + `)})`;
+        const candidates = links.map((link) => `${link.column} -> ${link.table}.${link.pk}`).join(', ');
+        for (const link of links) {
+            checks += 1; // one query per declared resolver
+            const rows = readCount(await sql `
+                    select count(*) as c
+                    from ${sql.table(root)} c
+                    join ${sql.table(link.table)} o on ${sql.id('o', link.pk)} = ${sql.id('c', link.column)}
+                    where ${sql.id('c', 'SiteId')} <> ${sql.id('o', 'SiteId')}
+                `.execute(db));
+            if (rows > 0) {
+                ownerResolve.divergent += rows;
+                const detail = `${root}.${link.column} -> ${link.table}.${link.pk}: ${rows} row(s) disagree with the owner's SiteId`;
+                ownerResolve.findings.push({ check: 'divergent-tenant-key-vs-owner', table: root, detail, rows });
+                violations.push({ check: 'divergent-tenant-key-vs-owner', table: root, detail, rows });
+            }
+        }
+        for (const group of contested) {
+            checks += 1;
+            const probes = group.map((link) => sql `case when exists (select 1 from ${sql.table(link.table)} o where ${sql.id('o', link.pk)} = ${sql.id('c', link.column)}) then 1 else 0 end`);
+            const ambiguous = readCount(await sql `select count(*) as c from ${sql.table(root)} c where (${sql.join(probes, sql ` + `)}) > 1`.execute(db));
+            if (ambiguous > 0) {
+                ownerResolve.ambiguous += ambiguous;
+                ownerResolve.findings.push({
+                    check: 'ambiguous-owner',
+                    table: root,
+                    rows: ambiguous,
+                    detail: `${root}.${group[0].column}: ${ambiguous} row(s) name an owner that exists in more than one candidate (${group.map((l) => `${l.table}.${l.pk}`).join(', ')}) — the resolver took the first declared match`,
+                });
+            }
+        }
+        // An orphan is only a defect when the contract gives it no other way to a site. A
+        // theme folder is the declared exception: no owner, but `*_ThemeId` is a canon FK
+        // and the site comes from the theme (task:3976). Anything else resolved nowhere,
+        // and a site move would leave it behind without a word.
+        const declared = ownerSpec.polyRoots?.[root]?.danglingAllowed;
+        const allowedColumns = (declared?.columns ?? []).filter((column) => (live.get(root)?.columns ?? []).some((c) => c.name === column));
+        const allowed = allowedColumns.length
+            ? sql `(${sql.join(allowedColumns.map((column) => sql `case when ${sql.id('c', column)} is not null then 1 else 0 end`), sql ` + `)}) > 0`
+            : sql `1 = 0`;
+        checks += 1;
+        const [orphans = {}] = readRows(await sql `
+                select
+                    sum(case when ${allowed} then 0 else 1 end) as dangling,
+                    sum(case when ${allowed} then 1 else 0 end) as allowed
+                from ${sql.table(root)} c
+                where ${matchedIn} = 0
+            `.execute(db));
+        const dangling = Number(orphans.dangling ?? 0);
+        if (dangling > 0) {
+            ownerResolve.dangling += dangling;
+            const detail = `${root}: ${dangling} row(s) name no owner at all (${candidates}) and carry no declared alternative — nothing carries them to any site`;
+            ownerResolve.findings.push({ check: 'dangling-owner', table: root, detail, rows: dangling });
+            violations.push({ check: 'dangling-owner', table: root, detail, rows: dangling });
+        }
+        const allowedRows = Number(orphans.allowed ?? 0);
+        if (allowedRows > 0) {
+            ownerResolve.danglingAllowed += allowedRows;
+            ownerResolve.findings.push({
+                check: 'dangling-owner',
+                table: root,
+                rows: allowedRows,
+                allowed: true,
+                detail: `${root}: ${allowedRows} row(s) have no owner but the contract allows it — ${allowedColumns.join(' / ')} carries the site (${declared?.reason ?? 'declared exception'})`,
+            });
+        }
+    }
+    return { ok: violations.length === 0, checks, violations, ownerResolve };
+};

package/dist/dataProvider.d.ts

@@ -0,0 +1,41 @@
+/**
+ * no-DB boot: a registry serving ALL slices from a single JSON fixture root — the engine
+ * comes up and renders with no DB connection and no `config.data.sequelize`.
+ * @param {string} root fixtures root directory
+ * @param {object} [opts] { templatesDir }
+ */
+export function bootFromFixtures(root: string, opts?: object): DataProviderRegistry;
+/**
+ * JSON fixture backend. Reads a directory tree that mirrors the entity/template model:
+ *   <root>/templates/<alias>.template.json   schema-as-file template-defs
+ *   <root>/<slice>/<key>.json                entity rows: { id, …meta, template:"<alias>", content:{…} }
+ * Resolves each row's template-def (schema-as-file), validates the row's content field names
+ * against the template's fields, and returns the DB-loaded entity shape.
+ */
+export class FixtureDataProvider {
+    constructor({ root, templatesDir }?: {});
+    root: string;
+    templatesDir: string;
+    _templateCache: Map<any, any>;
+    _loadTemplate(alias: any): any;
+    _shape(raw: any, slice: any, key: any): any;
+    get(slice: any, key: any): Promise<any>;
+    enumerate(slice: any): Promise<any[]>;
+}
+/**
+ * Per-slice routing over N backends. Different slices can come from different providers
+ * (e.g. pages from fixtures, store-products from the local DB). `routes` maps a slice to a
+ * provider name; `fallback` handles unrouted slices.
+ */
+export class DataProviderRegistry {
+    constructor({ providers, routes, fallback }?: {
+        providers?: {};
+        routes?: {};
+    });
+    providers: {};
+    routes: {};
+    fallback: any;
+    providerFor(slice: any): any;
+    get(slice: any, key: any): any;
+    enumerate(slice: any, opts: any): any;
+}

package/dist/dataProvider.js

@@ -0,0 +1,148 @@
+// Pluggable data-source (snolla-dev-workflow Фаза 0). A provider abstraction over the
+// content store so the engine can render from FIXTURES (no DB) in dev, from the local DB, or
+// from prod — chosen per slice. This unblocks the greenfield dev-loop (no Docker/MSSQL) and
+// serves the vendor-agnostic "move off MSSQL" goal. Design: concepts/snolla-dev-workflow.md
+// §Core primitives → Pluggable data-source; depends on schema-as-file (templateDefs.js).
+//
+// PURE of Sequelize/config — lives at the `@snolla/data` floor and is imported by subpath
+// (`@snolla/data/dataProvider.js`) so it does NOT pull the DB barrel (index.js constructs
+// Sequelize at import). That is precisely what makes **no-DB boot** possible: a fixture
+// provider needs neither a connection nor `config.data.sequelize`.
+//
+// CONTRACT — a DataProvider serves "slices" (content collections: 'pages', 'store-products',
+// 'blog-posts', …):
+//   provider.get(slice, key)        → Promise<row|null>   one entity by key (path/slug/id)
+//   provider.enumerate(slice, opts) → Promise<row[]>      all entities in a slice (listing/sitemap/boot)
+// A returned `row` is **template-shaped = the DB-loaded entity shape** the existing viewModel
+// builders already expect: `{ id, …meta, template: {id,alias,name,content:"<field-defs json>"},
+// content: "<saved-values json>" }`. Producing that shape makes a fixture row a **drop-in** for
+// a Sequelize-loaded row — `getPageViewModel(row, …)` works unchanged, so dev-preview == prod.
+//
+// Фаза-0 scope = the interface + the JSON fixture backend + per-slice routing + no-DB boot.
+// Deferred (documented in concepts/snolla-dev-workflow.md + the task): CSV/SQLite backends,
+// the contentApi prod backend, and rewiring `core/lib/services/*` (the `include:{as:'template'}`
+// path) to source rows from a provider by default. Part/gallery fields still need the file
+// part-template resolver deferred from schema-as-file (fillViewModel:597).
+import { readFileSync, readdirSync, existsSync } from 'fs';
+import { join, resolve, basename } from 'path';
+import { parseTemplateDef } from './templateDefs.js';
+// Normalize authored fixture `content` to the `[{name,value}]` array fillViewModel consumes.
+// Authors may write the ergonomic object form `{ headline: "Hi" }`; the array form
+// `[{name,value}]` (the DB shape) is also accepted verbatim.
+function normalizeContent(content) {
+    if (content == null)
+        return [];
+    if (Array.isArray(content))
+        return content;
+    if (typeof content === 'object') {
+        return Object.keys(content).map((name) => ({ name, value: content[name] }));
+    }
+    throw new Error('data-provider: entity "content" must be an object or an array of {name,value}');
+}
+/**
+ * JSON fixture backend. Reads a directory tree that mirrors the entity/template model:
+ *   <root>/templates/<alias>.template.json   schema-as-file template-defs
+ *   <root>/<slice>/<key>.json                entity rows: { id, …meta, template:"<alias>", content:{…} }
+ * Resolves each row's template-def (schema-as-file), validates the row's content field names
+ * against the template's fields, and returns the DB-loaded entity shape.
+ */
+export class FixtureDataProvider {
+    constructor({ root, templatesDir } = {}) {
+        if (!root)
+            throw new Error('FixtureDataProvider: "root" directory is required');
+        this.root = resolve(root);
+        this.templatesDir = templatesDir ? resolve(templatesDir) : join(this.root, 'templates');
+        this._templateCache = new Map();
+    }
+    _loadTemplate(alias) {
+        if (this._templateCache.has(alias))
+            return this._templateCache.get(alias);
+        const file = join(this.templatesDir, `${alias}.template.json`);
+        if (!existsSync(file)) {
+            throw new Error(`FixtureDataProvider: template-def "${alias}" not found at ${file}`);
+        }
+        const def = parseTemplateDef(JSON.parse(readFileSync(file, 'utf8')));
+        this._templateCache.set(alias, def);
+        return def;
+    }
+    // Map a raw fixture row → the DB-loaded entity shape (template-shape). Validates the row's
+    // content field names against the template-def (schema-as-file). Rows without a `template`
+    // (raw/non-templated data) pass through with content normalized only.
+    _shape(raw, slice, key) {
+        if (raw.template == null) {
+            return { key, ...raw };
+        }
+        const alias = raw.template;
+        const def = this._loadTemplate(alias);
+        const fieldNames = new Set(JSON.parse(def.content).map((f) => f.name));
+        const contentArr = normalizeContent(raw.content);
+        for (const cf of contentArr) {
+            if (!fieldNames.has(cf.name)) {
+                throw new Error(`data-provider (${slice}/${key}): content field "${cf.name}" is not defined in template "${alias}"`);
+            }
+        }
+        return {
+            key,
+            ...raw,
+            // Carry the full DB-loaded template shape, not just id/alias/name/content:
+            // production layout resolution reads `template.customDefaultLayout` (contentPages.js,
+            // resolveStoreLayout) — dropping it renders the wrong layout in dev (dev!=prod drift).
+            template: {
+                id: def.id, alias: def.alias, name: def.name,
+                customDefaultLayout: def.customDefaultLayout, layouts: def.layouts,
+                content: def.content,
+            },
+            content: JSON.stringify(contentArr),
+        };
+    }
+    async get(slice, key) {
+        const file = join(this.root, slice, `${key}.json`);
+        if (!existsSync(file))
+            return null;
+        const raw = JSON.parse(readFileSync(file, 'utf8'));
+        return this._shape(raw, slice, key);
+    }
+    async enumerate(slice) {
+        const dir = join(this.root, slice);
+        if (!existsSync(dir))
+            return [];
+        return readdirSync(dir)
+            .filter((f) => f.endsWith('.json'))
+            .map((f) => {
+            const key = basename(f, '.json');
+            const raw = JSON.parse(readFileSync(join(dir, f), 'utf8'));
+            return this._shape(raw, slice, key);
+        });
+    }
+}
+/**
+ * Per-slice routing over N backends. Different slices can come from different providers
+ * (e.g. pages from fixtures, store-products from the local DB). `routes` maps a slice to a
+ * provider name; `fallback` handles unrouted slices.
+ */
+export class DataProviderRegistry {
+    constructor({ providers = {}, routes = {}, fallback } = {}) {
+        this.providers = providers;
+        this.routes = routes;
+        this.fallback = fallback;
+    }
+    providerFor(slice) {
+        const name = this.routes[slice];
+        const provider = name ? this.providers[name] : this.fallback;
+        if (!provider) {
+            throw new Error(`data-provider: no backend routed for slice "${slice}" and no fallback set`);
+        }
+        return provider;
+    }
+    get(slice, key) { return this.providerFor(slice).get(slice, key); }
+    enumerate(slice, opts) { return this.providerFor(slice).enumerate(slice, opts); }
+}
+/**
+ * no-DB boot: a registry serving ALL slices from a single JSON fixture root — the engine
+ * comes up and renders with no DB connection and no `config.data.sequelize`.
+ * @param {string} root fixtures root directory
+ * @param {object} [opts] { templatesDir }
+ */
+export function bootFromFixtures(root, opts = {}) {
+    return new DataProviderRegistry({ fallback: new FixtureDataProvider({ root, ...opts }) });
+}

package/dist/dataSource.d.ts

@@ -0,0 +1,4 @@
+export function cellConfig(): any;
+export function getSiteProvider(): Promise<any>;
+export function getControlProvider(): Promise<any>;
+export function closeCellProviders(): Promise<void>;

package/dist/dataSource.js

@@ -0,0 +1,65 @@
+// The cell handles a package opens for itself (task:3933).
+//
+// `core/lib/dataSource.js` is the ENGINE's data source: it turns `config.data.provider` into the
+// process-wide provider the render path reads through. The leaf packages that only depend on
+// `@snolla/data` (numbering, mailer, forms-api) need the same cell — but they cannot import core
+// without inventing a dependency edge, so the cell resolution lives here, next to the seam, and
+// core delegates to it. One config read, one provider per channel per process.
+//
+// Two channels, because the data says so:
+//   * `site` — the tenant's own rows (siteId from `config.siteId`, deny-by-default);
+//   * `control` — dictionaries and the site registry, tables that carry no SiteId at all.
+// Only the site channel may be written to (the control channel has nothing site-scoped to write).
+//
+// No `data.provider` key → `null`: the deployment still reads through Sequelize, and every caller
+// keeps its legacy path (the same contract core/lib/dataSource.js documents).
+import config from 'config';
+import { DbDataProvider } from './dbProvider.js';
+/** The configured cell (dialect/dsn + this deployment's siteId), or null for the Sequelize path. */
+export const cellConfig = () => {
+    if (!config.has('data.provider'))
+        return null;
+    return { siteId: config.get('siteId'), ...config.get('data.provider') };
+};
+let siteProvider;
+let controlProvider;
+const build = (cell, channel) => {
+    let pending = DbDataProvider.fromCell({ ...cell, channel }).catch((error) => {
+        // a failed build must not poison the singleton: the next call retries, and the error is
+        // the caller's to see rather than a cached rejected promise
+        if (channel === 'site')
+            siteProvider = undefined;
+        else
+            controlProvider = undefined;
+        throw error;
+    });
+    return pending;
+};
+/** The tenant provider, or null when no cell is configured. */
+export const getSiteProvider = async () => {
+    const cell = cellConfig();
+    if (!cell)
+        return null;
+    if (!siteProvider)
+        siteProvider = build(cell, 'site');
+    return siteProvider;
+};
+/** The control-plane provider (dictionaries, the site registry), or null with no cell. */
+export const getControlProvider = async () => {
+    const cell = cellConfig();
+    if (!cell)
+        return null;
+    if (!controlProvider)
+        controlProvider = build(cell, 'control');
+    return controlProvider;
+};
+/** Close and forget both handles (tests; a future config reload). */
+export const closeCellProviders = async () => {
+    const pending = [siteProvider, controlProvider];
+    siteProvider = undefined;
+    controlProvider = undefined;
+    for (const handle of pending) {
+        if (handle)
+            await (await handle).close();
+    }
+};