@beechcms/core 0.4.3 → 0.6.0-preview.1

package/dist/seed-layout.js

@@ -0,0 +1,169 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2024–2026 Flavio De Musso
+import { z } from 'zod';
+import { findBranchById } from './seed-registry.js';
+// ---------------------------------------------------------------------------
+// Branch-type rules used by both the default generator and the validator.
+// ---------------------------------------------------------------------------
+/** Branch types that must occupy a section alone, full width. */
+export const FULL_WIDTH_BRANCH_TYPES = new Set(['richtext']);
+/** Returns true when a branch is a gallery (file + multiple/asset-list). */
+export function isGalleryBranch(branch) {
+    return branch.type === 'file'
+        && (branch.multiple === true || branch.format === 'asset-list');
+}
+/** Branch types currently unsupported in the Layout Builder. */
+export const UNSUPPORTED_BRANCH_TYPES = new Set(['json']);
+/** Aliases that are NEVER included in the editor form (handled by other UI). */
+export const SYSTEM_ALIASES = new Set([
+    'id', 'slug', 'status', 'created_at', 'updated_at',
+]);
+/** True when the branch is eligible to appear in the layout at all. */
+export function isLayoutableBranch(branch) {
+    if (SYSTEM_ALIASES.has(branch.alias))
+        return false;
+    if (branch.policies?.visibility === 'hidden')
+        return false;
+    if (UNSUPPORTED_BRANCH_TYPES.has(branch.type))
+        return false;
+    return true;
+}
+/** True when the branch must occupy a dedicated full-width section. */
+export function isFullWidthBranch(branch) {
+    return FULL_WIDTH_BRANCH_TYPES.has(branch.type) || isGalleryBranch(branch);
+}
+/** Branches considered SEO fields. Matches the existing rule in entry-editor.tsx. */
+export function isSeoBranch(branch) {
+    return branch.alias.startsWith('meta');
+}
+// ---------------------------------------------------------------------------
+// Zod schema for shape validation
+// ---------------------------------------------------------------------------
+export const layoutFieldSchema = z.object({ branchId: z.string().regex(/^br_[A-Za-z0-9]+$/) });
+export const layoutColumnSchema = z.object({
+    id: z.string().min(1),
+    fields: z.array(layoutFieldSchema),
+});
+export const layoutSectionSchema = z.object({
+    id: z.string().min(1),
+    label: z.string().optional(),
+    hideLabel: z.boolean().optional(),
+    hideBorder: z.boolean().optional(),
+    collapsible: z.boolean().optional(),
+    columns: z.array(layoutColumnSchema).min(1).max(4),
+});
+export const layoutTabSchema = z.object({
+    id: z.string().min(1),
+    label: z.string().min(1).max(60),
+    sections: z.array(layoutSectionSchema).min(1),
+});
+export const formLayoutSchema = z.object({
+    version: z.literal(1),
+    tabs: z.array(layoutTabSchema).min(1).max(8),
+});
+// ---------------------------------------------------------------------------
+// Default layout generator
+// ---------------------------------------------------------------------------
+const DEFAULT_COLUMNS_PER_SECTION = 3;
+const defaultIdFactory = () => crypto.randomUUID();
+function buildSectionsForBranches(branches, newId) {
+    const sections = [];
+    let currentColumns = [];
+    function flushCompact() {
+        if (currentColumns.length === 0)
+            return;
+        sections.push({ id: newId(), columns: currentColumns });
+        currentColumns = [];
+    }
+    for (const branch of branches) {
+        if (isFullWidthBranch(branch)) {
+            flushCompact();
+            sections.push({
+                id: newId(),
+                label: branch.label,
+                hideLabel: true,
+                columns: [{ id: newId(), fields: [{ branchId: branch.id }] }],
+            });
+        }
+        else {
+            currentColumns.push({ id: newId(), fields: [{ branchId: branch.id }] });
+            if (currentColumns.length >= DEFAULT_COLUMNS_PER_SECTION) {
+                flushCompact();
+            }
+        }
+    }
+    flushCompact();
+    if (sections.length === 0) {
+        sections.push({ id: newId(), columns: [{ id: newId(), fields: [] }] });
+    }
+    return sections;
+}
+export function generateDefaultLayout(seed, opts) {
+    const newId = opts?.newId ?? defaultIdFactory;
+    const layoutable = seed.branches.filter(isLayoutableBranch);
+    const seo = layoutable.filter(isSeoBranch);
+    const main = layoutable.filter((b) => !isSeoBranch(b));
+    const dataTab = {
+        id: newId(),
+        label: 'Data',
+        sections: buildSectionsForBranches(main, newId),
+    };
+    const seoTab = {
+        id: newId(),
+        label: 'SEO',
+        sections: buildSectionsForBranches(seo, newId),
+    };
+    return { version: 1, tabs: [dataTab, seoTab] };
+}
+export function validateLayoutAgainstSeed(layout, seed) {
+    const errors = [];
+    const seenBranchIds = new Set();
+    const cleanedTabs = layout.tabs.map((tab) => ({
+        ...tab,
+        sections: tab.sections.map((section) => ({
+            ...section,
+            columns: section.columns.map((col) => ({
+                ...col,
+                fields: (col.fields ?? []).filter((f) => {
+                    const branch = findBranchById(seed, f.branchId);
+                    if (!branch)
+                        return false;
+                    if (UNSUPPORTED_BRANCH_TYPES.has(branch.type) || SYSTEM_ALIASES.has(branch.alias))
+                        return false;
+                    return true;
+                }),
+            })),
+        })),
+    }));
+    // Duplicate and full-width constraint checks on cleaned layout
+    for (const tab of cleanedTabs) {
+        for (const section of tab.sections) {
+            const fieldsInSection = [];
+            for (const col of section.columns) {
+                for (const f of col.fields) {
+                    const branch = findBranchById(seed, f.branchId);
+                    if (!branch)
+                        continue;
+                    if (seenBranchIds.has(f.branchId)) {
+                        errors.push(`Branch '${branch.alias}' (id=${f.branchId}) appears more than once in the layout.`);
+                    }
+                    else {
+                        seenBranchIds.add(f.branchId);
+                        fieldsInSection.push(branch);
+                    }
+                }
+            }
+            // Full-width branches must occupy a dedicated section
+            const fullWidthInSection = fieldsInSection.filter(isFullWidthBranch);
+            if (fullWidthInSection.length > 0 && fieldsInSection.length > fullWidthInSection.length) {
+                for (const fw of fullWidthInSection) {
+                    errors.push(`Branch '${fw.alias}' (type=${fw.type}) must occupy a dedicated section and cannot share it with other fields.`);
+                }
+            }
+        }
+    }
+    const cleaned = { ...layout, tabs: cleanedTabs };
+    if (errors.length > 0)
+        return { ok: false, errors, cleaned };
+    return { ok: true, cleaned };
+}

package/dist/seed-layout.repository.d.ts

@@ -0,0 +1,18 @@
+import type { FormLayout } from './seed-layout.js';
+export interface SeedLayoutRecord {
+    slug: string;
+    layout: FormLayout;
+    updatedAt: number;
+    updatedBy: string;
+}
+export interface ISeedLayoutRepository {
+    /** Return the stored layout for a seed, or null if none was ever saved. */
+    get(slug: string): Promise<SeedLayoutRecord | null>;
+    /** Return all stored layouts, keyed by slug — used by GET /api/schema to enrich. */
+    getAllAsMap(): Promise<Map<string, FormLayout>>;
+    /** Upsert. `updatedBy` is the writer's user id. */
+    upsert(slug: string, layout: FormLayout, updatedBy: string): Promise<void>;
+    /** Remove the stored row — used by the "Reset" action. */
+    remove(slug: string): Promise<void>;
+}
+//# sourceMappingURL=seed-layout.repository.d.ts.map

package/dist/seed-layout.repository.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"seed-layout.repository.d.ts","sourceRoot":"","sources":["../src/seed-layout.repository.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAA;AAElD,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAA;IACZ,MAAM,EAAE,UAAU,CAAA;IAClB,SAAS,EAAE,MAAM,CAAA;IACjB,SAAS,EAAE,MAAM,CAAA;CAClB;AAED,MAAM,WAAW,qBAAqB;IACpC,2EAA2E;IAC3E,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,GAAG,IAAI,CAAC,CAAA;IACnD,oFAAoF;IACpF,WAAW,IAAI,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC,CAAA;IAC/C,mDAAmD;IACnD,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAC1E,0DAA0D;IAC1D,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;CACpC"}

package/dist/seed-layout.repository.js

@@ -0,0 +1,3 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2024–2026 Flavio De Musso
+export {};

package/dist/seed-registry.d.ts

@@ -1,4 +1,4 @@
-import type { Seed } from './types.js';
+import type { Seed, Branch } from './types.js';
 export interface ISeedRegistry {
     /**
      * Returns all seeds as a flat array, preserving insertion order.
@@ -46,4 +46,26 @@ export declare class SeedRegistry implements ISeedRegistry {
  */
 export declare class InMemorySeedRegistry extends SeedRegistry {
 }
+/** Finds a branch by its stable id within a Seed. Returns null if not found. */
+export declare function findBranchById(seed: Seed, id: string): Branch | null;
+/**
+ * Returns the next free branch id for a seed in the form `br_NN` (zero-padded to 2,
+ * growing as needed). Scans existing ids, never reuses a number already present —
+ * even if a branch was removed, its id is not recycled (ids must be globally stable
+ * for the life of the seed so layouts/automations/FTS triggers never collide).
+ */
+export declare function nextBranchId(seed: Pick<Seed, 'branches'>): string;
+/**
+ * Returns the input seeds reordered so that every seed appears AFTER all the
+ * seeds it depends on (its `relation` branch targets). Pure function — does
+ * not read from any global registry.
+ *
+ * Uses Kahn's algorithm (BFS on in-degree) for cycle detection and topological
+ * ordering. Sprint 3 (CLI / migration runner) consumes this to create tables in
+ * the correct order without disabling SQLite FK constraints.
+ *
+ * @throws {Error} When a relation targets an unknown slug not in `seeds`.
+ * @throws {Error} When a cyclic dependency is detected, listing involved slugs.
+ */
+export declare function sortSeedsByDependencies(seeds: ReadonlyArray<Seed>): Seed[];
 //# sourceMappingURL=seed-registry.d.ts.map

package/dist/seed-registry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"seed-registry.d.ts","sourceRoot":"","sources":["../src/seed-registry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,YAAY,CAAA;AAGtC,MAAM,WAAW,aAAa;IAC5B;;;;OAIG;IACH,GAAG,IAAI,IAAI,EAAE,CAAA;IAEb;;;;OAIG;IACH,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CAAA;IAE9B;;;;;OAKG;IACH,kBAAkB,IAAI,IAAI,EAAE,CAAA;IAE5B;;;OAGG;IACH,cAAc,IAAI,IAAI,EAAE,CAAA;IAExB;;;OAGG;IACH,YAAY,IAAI,IAAI,EAAE,CAAA;CACvB;AAED,qBAAa,YAAa,YAAW,aAAa;IAChD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAmB;IAC3C,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAQ;gBAEzB,KAAK,EAAE,IAAI,EAAE;IAezB,GAAG,IAAI,IAAI,EAAE;IAIb,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI;IAI9B,kBAAkB,IAAI,IAAI,EAAE;IAI5B,cAAc,IAAI,IAAI,EAAE;IAIxB,YAAY,IAAI,IAAI,EAAE;CAGvB;AAED;;;GAGG;AACH,qBAAa,oBAAqB,SAAQ,YAAY;CAAG"}
+{"version":3,"file":"seed-registry.d.ts","sourceRoot":"","sources":["../src/seed-registry.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,YAAY,CAAA;AAG9C,MAAM,WAAW,aAAa;IAC5B;;;;OAIG;IACH,GAAG,IAAI,IAAI,EAAE,CAAA;IAEb;;;;OAIG;IACH,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CAAA;IAE9B;;;;;OAKG;IACH,kBAAkB,IAAI,IAAI,EAAE,CAAA;IAE5B;;;OAGG;IACH,cAAc,IAAI,IAAI,EAAE,CAAA;IAExB;;;OAGG;IACH,YAAY,IAAI,IAAI,EAAE,CAAA;CACvB;AAID,qBAAa,YAAa,YAAW,aAAa;IAChD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAmB;IAC3C,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAQ;gBAEzB,KAAK,EAAE,IAAI,EAAE;IA4BzB,GAAG,IAAI,IAAI,EAAE;IAIb,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI;IAI9B,kBAAkB,IAAI,IAAI,EAAE;IAI5B,cAAc,IAAI,IAAI,EAAE;IAIxB,YAAY,IAAI,IAAI,EAAE;CAGvB;AAED;;;GAGG;AACH,qBAAa,oBAAqB,SAAQ,YAAY;CAAG;AAEzD,gFAAgF;AAChF,wBAAgB,cAAc,CAAC,IAAI,EAAE,IAAI,EAAE,EAAE,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAEpE;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,UAAU,CAAC,GAAG,MAAM,CAQjE;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,aAAa,CAAC,IAAI,CAAC,GAAG,IAAI,EAAE,CAsE1E"}

package/dist/seed-registry.js

@@ -1,14 +1,26 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2024–2026 Flavio De Musso
 import { AUTOMATION_RESERVED_WORDS } from './automations-grammar-words.js';
+const BRANCH_ID_RE = /^br_[A-Za-z0-9]+$/;
 export class SeedRegistry {
     seedMap;
     orderedSeeds;
     constructor(seeds) {
         for (const seed of seeds) {
+            const idsInSeed = new Set();
             for (const branch of seed.branches) {
                 if (AUTOMATION_RESERVED_WORDS.has(branch.alias)) {
                     throw new Error(`Seed "${seed.slug}" uses reserved alias "${branch.alias}". `
                         + `Pick a different alias — this word is used by the automation template grammar.`);
                 }
+                if (!branch.id || !BRANCH_ID_RE.test(branch.id)) {
+                    throw new Error(`Seed "${seed.slug}" branch "${branch.alias}" has invalid id "${branch.id}". `
+                        + `Expected format ^br_[A-Za-z0-9]+$.`);
+                }
+                if (idsInSeed.has(branch.id)) {
+                    throw new Error(`Seed "${seed.slug}" has duplicate branch id "${branch.id}".`);
+                }
+                idsInSeed.add(branch.id);
             }
         }
         this.orderedSeeds = seeds;
@@ -36,3 +48,96 @@ export class SeedRegistry {
  */
 export class InMemorySeedRegistry extends SeedRegistry {
 }
+/** Finds a branch by its stable id within a Seed. Returns null if not found. */
+export function findBranchById(seed, id) {
+    return seed.branches.find(b => b.id === id) ?? null;
+}
+/**
+ * Returns the next free branch id for a seed in the form `br_NN` (zero-padded to 2,
+ * growing as needed). Scans existing ids, never reuses a number already present —
+ * even if a branch was removed, its id is not recycled (ids must be globally stable
+ * for the life of the seed so layouts/automations/FTS triggers never collide).
+ */
+export function nextBranchId(seed) {
+    let max = 0;
+    for (const b of seed.branches) {
+        const m = /^br_0*([0-9]+)$/.exec(b.id);
+        if (m)
+            max = Math.max(max, parseInt(m[1], 10));
+    }
+    const n = max + 1;
+    return `br_${String(n).padStart(2, '0')}`;
+}
+/**
+ * Returns the input seeds reordered so that every seed appears AFTER all the
+ * seeds it depends on (its `relation` branch targets). Pure function — does
+ * not read from any global registry.
+ *
+ * Uses Kahn's algorithm (BFS on in-degree) for cycle detection and topological
+ * ordering. Sprint 3 (CLI / migration runner) consumes this to create tables in
+ * the correct order without disabling SQLite FK constraints.
+ *
+ * @throws {Error} When a relation targets an unknown slug not in `seeds`.
+ * @throws {Error} When a cyclic dependency is detected, listing involved slugs.
+ */
+export function sortSeedsByDependencies(seeds) {
+    const slugSet = new Set(seeds.map(s => s.slug));
+    // Validate all relation targets exist in the input array
+    for (const seed of seeds) {
+        for (const branch of seed.branches) {
+            if (branch.type === 'relation' && branch.targetSeed) {
+                if (!slugSet.has(branch.targetSeed)) {
+                    throw new Error(`Seed '${seed.slug}' relates to unknown target '${branch.targetSeed}'`);
+                }
+            }
+        }
+    }
+    // Build adjacency: inDegree[slug] = number of dependencies
+    //                  dependents[slug] = slugs that depend on slug
+    const inDegree = new Map();
+    const dependents = new Map();
+    for (const seed of seeds) {
+        if (!inDegree.has(seed.slug))
+            inDegree.set(seed.slug, 0);
+        if (!dependents.has(seed.slug))
+            dependents.set(seed.slug, []);
+    }
+    for (const seed of seeds) {
+        // Deduplicate targets to avoid inflating inDegree on multi-branch refs to same seed
+        const targets = new Set(seed.branches
+            .filter(b => b.type === 'relation' && b.targetSeed)
+            .map(b => b.targetSeed));
+        for (const target of targets) {
+            // seed depends on target → increment seed's in-degree
+            inDegree.set(seed.slug, (inDegree.get(seed.slug) ?? 0) + 1);
+            dependents.get(target).push(seed.slug);
+        }
+    }
+    // Kahn's BFS: start with seeds that have no dependencies
+    const seedBySlug = new Map(seeds.map(s => [s.slug, s]));
+    const queue = [];
+    for (const [slug, deg] of inDegree) {
+        if (deg === 0)
+            queue.push(slug);
+    }
+    const result = [];
+    while (queue.length > 0) {
+        const slug = queue.shift();
+        result.push(seedBySlug.get(slug));
+        for (const dependent of dependents.get(slug) ?? []) {
+            const newDeg = (inDegree.get(dependent) ?? 0) - 1;
+            inDegree.set(dependent, newDeg);
+            if (newDeg === 0)
+                queue.push(dependent);
+        }
+    }
+    if (result.length !== seeds.length) {
+        // Cycle exists — collect participating slugs (those with in-degree > 0 after BFS)
+        const cycle = [...inDegree.entries()]
+            .filter(([, deg]) => deg > 0)
+            .map(([slug]) => slug)
+            .sort();
+        throw new Error(`Cyclic dependency detected among seeds: ${cycle.join(', ')}`);
+    }
+    return result;
+}

package/dist/seed-validation.d.ts

@@ -0,0 +1,23 @@
+import type { Seed } from './types.js';
+/**
+ * Allowed charset for a branch alias. An alias becomes a raw SQL column name in
+ * CREATE TABLE / ADD COLUMN / CREATE INDEX and in SELECT/WHERE/ORDER BY clauses
+ * (see engine.ts), so it MUST be restricted to a safe identifier charset to
+ * prevent DDL/query injection. Exported so the seeds API rename route reuses the
+ * exact same guard — do not inline a divergent copy.
+ */
+export declare const BRANCH_ALIAS_RE: RegExp;
+export interface SeedValidationIssue {
+    slug: string;
+    messages: string[];
+    fatal: boolean;
+}
+/**
+ * Pure, console-free, throw-free validation of a seed set.
+ * The single seed being created/edited should be validated in the context of
+ * the full active set: call validateSeedDefinitions([...otherActiveSeeds, edited]).
+ */
+export declare function validateSeedDefinitions(seeds: Seed[]): SeedValidationIssue[];
+/** Convenience: true iff no fatal issues. */
+export declare function isSeedSetValid(seeds: Seed[]): boolean;
+//# sourceMappingURL=seed-validation.d.ts.map

package/dist/seed-validation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"seed-validation.d.ts","sourceRoot":"","sources":["../src/seed-validation.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,YAAY,CAAA;AAMtC;;;;;;GAMG;AACH,eAAO,MAAM,eAAe,QAAsB,CAAA;AAElD,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,MAAM,CAAA;IACZ,QAAQ,EAAE,MAAM,EAAE,CAAA;IAClB,KAAK,EAAE,OAAO,CAAA;CACf;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,IAAI,EAAE,GAAG,mBAAmB,EAAE,CA6I5E;AAED,6CAA6C;AAC7C,wBAAgB,cAAc,CAAC,KAAK,EAAE,IAAI,EAAE,GAAG,OAAO,CAErD"}

package/dist/seed-validation.js

@@ -0,0 +1,156 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2024–2026 Flavio De Musso
+import { AUTOMATION_RESERVED_WORDS } from './automations-grammar-words.js';
+import { sortSeedsByDependencies } from './seed-registry.js';
+const BRANCH_ID_RE = /^br_[A-Za-z0-9]+$/;
+/**
+ * Allowed charset for a branch alias. An alias becomes a raw SQL column name in
+ * CREATE TABLE / ADD COLUMN / CREATE INDEX and in SELECT/WHERE/ORDER BY clauses
+ * (see engine.ts), so it MUST be restricted to a safe identifier charset to
+ * prevent DDL/query injection. Exported so the seeds API rename route reuses the
+ * exact same guard — do not inline a divergent copy.
+ */
+export const BRANCH_ALIAS_RE = /^[a-z][a-z0-9_]*$/;
+/**
+ * Pure, console-free, throw-free validation of a seed set.
+ * The single seed being created/edited should be validated in the context of
+ * the full active set: call validateSeedDefinitions([...otherActiveSeeds, edited]).
+ */
+export function validateSeedDefinitions(seeds) {
+    const result = [];
+    // ── Fatal 1: unknown relation targets ────────────────────────────────────
+    const slugSet = new Set(seeds.map(s => s.slug));
+    for (const seed of seeds) {
+        const messages = [];
+        for (const branch of seed.branches) {
+            if (branch.type === 'relation' && branch.targetSeed) {
+                if (!slugSet.has(branch.targetSeed)) {
+                    messages.push(`branch '${branch.alias}' targets unknown seed '${branch.targetSeed}'`);
+                }
+            }
+        }
+        if (messages.length > 0)
+            result.push({ slug: seed.slug, messages, fatal: true });
+    }
+    // ── Fatal 2: multi-relation with SET NULL ────────────────────────────────
+    for (const seed of seeds) {
+        const messages = [];
+        for (const branch of seed.branches) {
+            if (branch.type === 'relation' && branch.multiple === true && branch.onDelete === 'SET NULL') {
+                messages.push(`Branch '${branch.alias}': multi-relations cannot use ON DELETE SET NULL. ` +
+                    `Use 'CASCADE' or 'RESTRICT'.`);
+            }
+        }
+        if (messages.length > 0)
+            result.push({ slug: seed.slug, messages, fatal: true });
+    }
+    // ── Fatal 3: junction table name collisions / length ─────────────────────
+    {
+        const junctionNames = new Set();
+        for (const seed of seeds) {
+            const messages = [];
+            for (const branch of seed.branches) {
+                if (branch.type !== 'relation' || branch.multiple !== true)
+                    continue;
+                const name = `rel_${seed.slug}_${branch.alias}`;
+                if (name.length > 256) {
+                    messages.push(`Junction table name '${name}' exceeds 256 characters (${name.length})`);
+                }
+                if (junctionNames.has(name)) {
+                    messages.push(`Junction table name collision: '${name}' already used by another seed/branch`);
+                }
+                junctionNames.add(name);
+            }
+            if (messages.length > 0)
+                result.push({ slug: seed.slug, messages, fatal: true });
+        }
+    }
+    // ── Fatal 4: dependency cycles ────────────────────────────────────────────
+    const hasUnknownTargets = result.some(e => e.fatal);
+    if (!hasUnknownTargets) {
+        try {
+            sortSeedsByDependencies(seeds);
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            result.push({ slug: '<graph>', messages: [msg], fatal: true });
+        }
+    }
+    // ── Fatal 5: branch id format / uniqueness ───────────────────────────────
+    for (const seed of seeds) {
+        const messages = [];
+        const idsInSeed = new Set();
+        for (const branch of seed.branches) {
+            if (!branch.id || !BRANCH_ID_RE.test(branch.id)) {
+                messages.push(`branch '${branch.alias}' has invalid id '${branch.id}'. Expected format ^br_[A-Za-z0-9]+$.`);
+            }
+            else if (idsInSeed.has(branch.id)) {
+                messages.push(`duplicate branch id '${branch.id}'`);
+            }
+            if (branch.id)
+                idsInSeed.add(branch.id);
+            // Alias becomes a raw SQL column name — reject anything outside the safe
+            // identifier charset before it can reach DDL/query string interpolation.
+            if (typeof branch.alias !== 'string' || !BRANCH_ALIAS_RE.test(branch.alias)) {
+                messages.push(`branch alias '${branch.alias}' is invalid. Expected format ${BRANCH_ALIAS_RE.source} ` +
+                    `(lowercase letter followed by lowercase letters, digits or underscores).`);
+            }
+        }
+        if (messages.length > 0)
+            result.push({ slug: seed.slug, messages, fatal: true });
+    }
+    // ── Fatal 6: reserved aliases ─────────────────────────────────────────────
+    for (const seed of seeds) {
+        const messages = [];
+        for (const branch of seed.branches) {
+            if (AUTOMATION_RESERVED_WORDS.has(branch.alias)) {
+                messages.push(`branch '${branch.alias}' uses reserved alias. ` +
+                    `This word is used by the automation template grammar.`);
+            }
+        }
+        if (messages.length > 0)
+            result.push({ slug: seed.slug, messages, fatal: true });
+    }
+    // ── Warning 7: duplicate slug ─────────────────────────────────────────────
+    {
+        const slugsSeen = new Set();
+        for (const seed of seeds) {
+            const messages = [];
+            if (slugsSeen.has(seed.slug)) {
+                messages.push(`duplicate slug "${seed.slug}" — each seed must have a unique slug`);
+            }
+            slugsSeen.add(seed.slug);
+            if (messages.length > 0)
+                result.push({ slug: seed.slug, messages, fatal: false });
+        }
+    }
+    // ── Warning 8: duplicate branch alias within a seed ───────────────────────
+    for (const seed of seeds) {
+        const messages = [];
+        const aliasesSeen = new Set();
+        for (const branch of seed.branches) {
+            if (aliasesSeen.has(branch.alias)) {
+                messages.push(`duplicate branch alias "${branch.alias}"`);
+            }
+            aliasesSeen.add(branch.alias);
+        }
+        if (messages.length > 0)
+            result.push({ slug: seed.slug, messages, fatal: false });
+    }
+    // ── Warning 9: displayNameAlias not in branches ───────────────────────────
+    for (const seed of seeds) {
+        const allAliases = new Set(seed.branches.map(b => b.alias));
+        if (!allAliases.has(seed.displayNameAlias)) {
+            result.push({
+                slug: seed.slug,
+                messages: [`displayNameAlias "${seed.displayNameAlias}" not found in branches`],
+                fatal: false,
+            });
+        }
+    }
+    return result;
+}
+/** Convenience: true iff no fatal issues. */
+export function isSeedSetValid(seeds) {
+    return validateSeedDefinitions(seeds).every(i => !i.fatal);
+}

package/dist/seed.repository.d.ts

@@ -0,0 +1,37 @@
+import type { Seed } from './types.js';
+export interface SeedRecord {
+    slug: string;
+    definition: Seed;
+    status: 'active' | 'deleted';
+    source: 'code' | 'runtime';
+    createdAt: number;
+    updatedAt: number;
+}
+/**
+ * Persistence contract for runtime Seed definitions.
+ * Implemented by D1SeedRepository in apps/api/src/shared/seed.repository.d1.ts.
+ *
+ * `listActive()` returns only status='active' rows — this is what the registry is
+ * hydrated from. `getRegistryVersion` / `bumpRegistryVersion` back the multi-isolate
+ * cache token (see docs/Sprints/runtime-seeds/00-overview.md).
+ */
+export interface ISeedRepository {
+    /** All active seed definitions, ordered by created_at ASC. */
+    listActive(): Promise<Seed[]>;
+    /** Every row including soft-deleted ones (for admin/diff use). */
+    listAll(): Promise<SeedRecord[]>;
+    /** Single active-or-deleted record by slug, or null. */
+    get(slug: string): Promise<SeedRecord | null>;
+    /** Insert or replace a definition. Sets source on insert; preserves it on update unless given. */
+    upsert(slug: string, definition: Seed, source?: 'code' | 'runtime'): Promise<void>;
+    /** Soft-delete: set status='deleted'. Table is NOT dropped (additive-only). */
+    softDelete(slug: string): Promise<void>;
+    /** Hard-delete (sprint 06): permanently remove the `seeds` row. The caller is
+     *  responsible for dropping the backing tables first via ISchemaMutator. */
+    hardDelete(slug: string): Promise<void>;
+    /** Current cache token. */
+    getRegistryVersion(): Promise<number>;
+    /** Atomically increment and return the new token. Call after any write. */
+    bumpRegistryVersion(): Promise<number>;
+}
+//# sourceMappingURL=seed.repository.d.ts.map

package/dist/seed.repository.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"seed.repository.d.ts","sourceRoot":"","sources":["../src/seed.repository.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,YAAY,CAAA;AAEtC,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAA;IACZ,UAAU,EAAE,IAAI,CAAA;IAChB,MAAM,EAAE,QAAQ,GAAG,SAAS,CAAA;IAC5B,MAAM,EAAE,MAAM,GAAG,SAAS,CAAA;IAC1B,SAAS,EAAE,MAAM,CAAA;IACjB,SAAS,EAAE,MAAM,CAAA;CAClB;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,eAAe;IAC9B,8DAA8D;IAC9D,UAAU,IAAI,OAAO,CAAC,IAAI,EAAE,CAAC,CAAA;IAC7B,kEAAkE;IAClE,OAAO,IAAI,OAAO,CAAC,UAAU,EAAE,CAAC,CAAA;IAChC,wDAAwD;IACxD,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,CAAA;IAC7C,kGAAkG;IAClG,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAClF,+EAA+E;IAC/E,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IACvC;gFAC4E;IAC5E,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IACvC,2BAA2B;IAC3B,kBAAkB,IAAI,OAAO,CAAC,MAAM,CAAC,CAAA;IACrC,2EAA2E;IAC3E,mBAAmB,IAAI,OAAO,CAAC,MAAM,CAAC,CAAA;CACvC"}

package/dist/seed.repository.js

@@ -0,0 +1,3 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2024–2026 Flavio De Musso
+export {};

package/dist/seeds.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"seeds.d.ts","sourceRoot":"","sources":["../src/seeds.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,YAAY,CAAA;AAEtC;;;GAGG;AACH,eAAO,MAAM,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,IAAI,CAAM,CAAA;AAErD;;GAEG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,IAAI,EAAE,QAI1C;AAED;;GAEG;AACH,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CAEjD"}
+{"version":3,"file":"seeds.d.ts","sourceRoot":"","sources":["../src/seeds.ts"],"names":[],"mappings":"AAGA;;;;GAIG;AACH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,YAAY,CAAA;AAEtC;;;GAGG;AACH,eAAO,MAAM,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,IAAI,CAAM,CAAA;AAErD;;GAEG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,IAAI,EAAE,QAI1C;AAED;;GAEG;AACH,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CAEjD"}

package/dist/seeds.js

@@ -1,3 +1,5 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2024–2026 Flavio De Musso
 /**
  * Registro globale dei Seed.
  * In produzione, questo viene popolato dalle definizioni dell'utente.

package/dist/site-settings.repository.d.ts

@@ -0,0 +1,16 @@
+export interface SiteSettings {
+    siteTitle: string;
+    defaultLanguage: string;
+    timezone: string;
+    currency: string;
+    companyName: string | null;
+    companyWebsite: string | null;
+    companyAbbreviation: string | null;
+}
+export interface ISiteSettingsRepository {
+    /** Returns all stored settings, applying sensible defaults for missing keys. */
+    getAll(): Promise<SiteSettings>;
+    /** Upserts the provided keys. Partial update — unspecified keys are untouched. */
+    setMany(values: Partial<SiteSettings>): Promise<void>;
+}
+//# sourceMappingURL=site-settings.repository.d.ts.map

package/dist/site-settings.repository.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"site-settings.repository.d.ts","sourceRoot":"","sources":["../src/site-settings.repository.ts"],"names":[],"mappings":"AAGA,MAAM,WAAW,YAAY;IAC3B,SAAS,EAAE,MAAM,CAAA;IACjB,eAAe,EAAE,MAAM,CAAA;IACvB,QAAQ,EAAE,MAAM,CAAA;IAChB,QAAQ,EAAE,MAAM,CAAA;IAChB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAA;IAC1B,cAAc,EAAE,MAAM,GAAG,IAAI,CAAA;IAC7B,mBAAmB,EAAE,MAAM,GAAG,IAAI,CAAA;CACnC;AAED,MAAM,WAAW,uBAAuB;IACtC,gFAAgF;IAChF,MAAM,IAAI,OAAO,CAAC,YAAY,CAAC,CAAA;IAC/B,kFAAkF;IAClF,OAAO,CAAC,MAAM,EAAE,OAAO,CAAC,YAAY,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;CACtD"}

package/dist/site-settings.repository.js

@@ -0,0 +1,3 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2024–2026 Flavio De Musso
+export {};

package/dist/slug-utils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"slug-utils.d.ts","sourceRoot":"","sources":["../src/slug-utils.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;GAGG;AACH,wBAAgB,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAU7C;AAGD;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE;IAAE,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,OAAO,CAAC;IAAC,IAAI,CAAC,EAAE,OAAO,CAAA;CAAE,GAAG,MAAM,CASnG"}
+{"version":3,"file":"slug-utils.d.ts","sourceRoot":"","sources":["../src/slug-utils.ts"],"names":[],"mappings":"AAGA;;;GAGG;AAEH;;;GAGG;AACH,wBAAgB,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAU7C;AAGD;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE;IAAE,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,OAAO,CAAC;IAAC,IAAI,CAAC,EAAE,OAAO,CAAA;CAAE,GAAG,MAAM,CASnG"}

package/dist/slug-utils.js

@@ -1,3 +1,5 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2024–2026 Flavio De Musso
 /**
  * Utility per la gestione degli slug.
  * Condivisa tra Dashboard e API pubbliche.