@beechcms/core 0.7.0 → 0.8.1

package/dist/engine/schema-fingerprint.js

@@ -0,0 +1,97 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2024–2026 Flavio De Musso
+/**
+ * @module engine/schema-fingerprint
+ * A deterministic name for "the shape this API answers in".
+ *
+ * Computed from live seed definitions (`introspectSeedDefinitions`), embedded in generated client
+ * types at build time (sprint 3), returned on every public response as `X-Schema-Revision`
+ * (sprint 4), and compared by the client at request time (sprint 5). Both ends MUST compute it
+ * with this function — two implementations would be free to disagree, and a drift detector whose
+ * ends disagree is worse than none.
+ *
+ * What is hashed is a CONTRACT PROJECTION, not the whole seed definition: labels, hints, dashboard
+ * icons and layout cannot change a single response byte, and hashing them would fire a hard
+ * `BeechProblem` in someone else's production client over a typo fix.
+ */
+import { canonicalStringify } from '../common/canonical-json.js';
+import { resolvePolicies } from './policies.js';
+/**
+ * Bumped ONLY when the projection below or the canonical byte format changes — i.e. when
+ * fingerprints computed by two builds are no longer comparable. It is carried in the fingerprint
+ * string itself so a version skew reads as a mismatch instead of as an accidental match.
+ */
+export const SCHEMA_FINGERPRINT_VERSION = 1;
+function projectBranch(branch) {
+    const policies = resolvePolicies(branch);
+    return {
+        alias: branch.alias,
+        type: branch.type,
+        ...(branch.format !== undefined ? { format: branch.format } : {}),
+        ...(branch.multiple !== undefined ? { multiple: branch.multiple } : {}),
+        // Option order is the contract: it is the order a select renders and a union type lists.
+        ...(branch.options !== undefined ? { options: [...branch.options] } : {}),
+        requiredOnCreate: branch.requiredOnCreate ?? false,
+        requiredOnUpdate: branch.requiredOnUpdate ?? false,
+        ...(branch.targetSeed !== undefined ? { targetSeed: branch.targetSeed } : {}),
+        visibility: policies.visibility,
+        publicRead: policies.public,
+        publicEdit: policies.publicEdit,
+        ...(branch.minItems !== undefined ? { minItems: branch.minItems } : {}),
+        ...(branch.maxItems !== undefined ? { maxItems: branch.maxItems } : {}),
+        // Spread only when true so every schema without localized branches keeps its fingerprint.
+        ...(branch.localized === true ? { localized: true } : {}),
+        ...(branch.fields ? { fields: branch.fields.map(projectBranch) } : {}),
+    };
+}
+/**
+ * Reduces seeds to what a response shape depends on.
+ *
+ * Deliberately EXCLUDED, and each for a reason a future reader must not "fix":
+ * - `id` (`br_XX`) — a stable internal handle; it never appears in a payload, and minting order
+ *   differs between an environment built by migration and one grown through the dashboard.
+ * - `label`, `labelPlural`, `hint`, `dashboard`, `layout` — presentation, never response shape.
+ * - `retentionDays`, `onDelete`, `policies.search|filter|sort`, `numberOptions`, `fileOptions`,
+ *   `policies.classification|privacy` — behaviour and storage concerns that leave the response
+ *   shape identical. (`privacy` DOES change a stored value's encoding, but the API type stays
+ *   `string`; drift there is a data concern, not a type concern.)
+ * - anything physical (column order, index names) — see the VETO Audit.
+ *
+ * Seeds are sorted by slug; BRANCH ORDER IS PRESERVED, because it is the declared field order the
+ * generated types and the dashboard form both follow.
+ */
+export function projectSchemaContract(seeds) {
+    return {
+        fingerprintVersion: SCHEMA_FINGERPRINT_VERSION,
+        seeds: [...seeds]
+            .sort((a, b) => a.slug.localeCompare(b.slug))
+            .map(seed => ({
+            slug: seed.slug,
+            displayNameAlias: seed.displayNameAlias,
+            allowDrafts: seed.allowDrafts ?? false,
+            allowPublicRead: seed.allowPublicRead ?? false,
+            allowPublicPost: seed.allowPublicPost ?? false,
+            allowPublicEdit: seed.allowPublicEdit ?? false,
+            branches: seed.branches.map(projectBranch),
+        })),
+    };
+}
+function toHex(buffer) {
+    return Array.from(new Uint8Array(buffer), byte => byte.toString(16).padStart(2, '0')).join('');
+}
+/**
+ * `v{VERSION}:{32 lowercase hex}` — SHA-256 over the canonical JSON of the contract projection,
+ * truncated to 128 bits.
+ *
+ * Truncation is deliberate: this value travels on EVERY public response as `X-Schema-Revision`,
+ * and 128 bits of a SHA-256 digest carries no realistic collision risk for a value space of a few
+ * hundred schema revisions. It is a revision marker, never a security token.
+ *
+ * Web Crypto only — the same API the Worker and Node ≥ 18 both expose, as `webhook-crypto.ts`
+ * already relies on. `@beechcms/core` gains no dependency.
+ */
+export async function computeSchemaFingerprint(seeds) {
+    const bytes = new TextEncoder().encode(canonicalStringify(projectSchemaContract(seeds)));
+    const digest = await crypto.subtle.digest('SHA-256', bytes);
+    return `v${SCHEMA_FINGERPRINT_VERSION}:${toHex(digest).slice(0, 32)}`;
+}

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

@@ -1 +1 @@
-{"version":3,"file":"seed-registry.d.ts","sourceRoot":"","sources":["../../src/engine/seed-registry.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,YAAY,CAAA;AAI9C,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;IAkCzB,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"}
+{"version":3,"file":"seed-registry.d.ts","sourceRoot":"","sources":["../../src/engine/seed-registry.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,YAAY,CAAA;AAI9C,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;IAErC,YAAY,KAAK,EAAE,IAAI,EAAE,EAgCxB;IAED,GAAG,IAAI,IAAI,EAAE,CAEZ;IAED,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CAE7B;IAED,kBAAkB,IAAI,IAAI,EAAE,CAE3B;IAED,cAAc,IAAI,IAAI,EAAE,CAEvB;IAED,YAAY,IAAI,IAAI,EAAE,CAErB;CACF;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,CA0F1E"}

package/dist/engine/seed-registry.js

@@ -113,6 +113,8 @@ export function sortSeedsByDependencies(seeds) {
             .filter(b => b.type === 'relation' && b.targetSeed)
             .map(b => b.targetSeed));
         for (const target of targets) {
+            if (target === seed.slug)
+                continue; // self-reference needs no ordering
             // 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);
@@ -137,11 +139,28 @@ export function sortSeedsByDependencies(seeds) {
         }
     }
     if (result.length !== seeds.length) {
-        // Cycle exists — collect participating slugs (those with in-degree > 0 after BFS)
-        const cycle = [...inDegree.entries()]
+        // Isolate true cycle members
+        const stuck = new Set([...inDegree.entries()]
             .filter(([, deg]) => deg > 0)
-            .map(([slug]) => slug)
-            .sort();
+            .map(([slug]) => slug));
+        const cycleNodes = [...stuck].filter(slug => {
+            const visited = new Set();
+            const queue = [...(dependents.get(slug) ?? [])].filter(s => stuck.has(s));
+            while (queue.length > 0) {
+                const curr = queue.shift();
+                if (curr === slug)
+                    return true;
+                if (!visited.has(curr)) {
+                    visited.add(curr);
+                    for (const next of dependents.get(curr) ?? []) {
+                        if (stuck.has(next))
+                            queue.push(next);
+                    }
+                }
+            }
+            return false;
+        });
+        const cycle = (cycleNodes.length > 0 ? cycleNodes : [...stuck]).sort();
         throw new Error(`Cyclic dependency detected among seeds: ${cycle.join(', ')}`);
     }
     return result;

package/dist/engine/seed-types-generator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"seed-types-generator.d.ts","sourceRoot":"","sources":["../../src/engine/seed-types-generator.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,YAAY,CAAA;AAe9C,sEAAsE;AACtE,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAMhD;AAMD,mFAAmF;AACnF,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAoCtD;AAWD,sDAAsD;AACtD,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,IAAI,GAAG,MAAM,CAYnD;AAED,6EAA6E;AAC7E,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,IAAI,EAAE,GAAG,MAAM,CASvD"}
+{"version":3,"file":"seed-types-generator.d.ts","sourceRoot":"","sources":["../../src/engine/seed-types-generator.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,YAAY,CAAA;AAe9C,sEAAsE;AACtE,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAMhD;AAMD,mFAAmF;AACnF,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAoCtD;AAWD,sDAAsD;AACtD,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,IAAI,GAAG,MAAM,CAYnD;AAED,6EAA6E;AAC7E,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,IAAI,EAAE,GAAG,MAAM,CAcvD"}

package/dist/engine/seed-types-generator.js

@@ -78,9 +78,12 @@ export function interfaceForSeed(seed) {
 export function generateSeedTypes(seeds) {
     const sorted = [...seeds].sort((a, b) => a.slug.localeCompare(b.slug));
     const interfaces = sorted.map(interfaceForSeed).join('\n');
-    const registry = `export interface SeedRegistryTypes {\n` +
-        sorted.map(s => `  ${propName({ alias: s.slug })}: ${pascalCase(s.slug)}`).join('\n') +
-        (sorted.length ? '\n' : '') +
-        `}\n`;
-    return `${HEADER}\n${interfaces}\n${registry}`;
+    const registryProps = sorted
+        .map(s => `  ${propName({ alias: s.slug })}: ${pascalCase(s.slug)}`)
+        .join('\n');
+    const databaseRegistry = `export interface BeechDatabase {\n` +
+        (registryProps ? registryProps + '\n' : '') +
+        `}\n\n` +
+        `export type SeedRegistryTypes = BeechDatabase\n`;
+    return `${HEADER}\n${interfaces}\n${databaseRegistry}`;
 }

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

@@ -7,6 +7,13 @@ import type { Seed } from './types.js';
  * exact same guard — do not inline a divergent copy.
  */
 export declare const BRANCH_ALIAS_RE: RegExp;
+/**
+ * Allowed charset for a seed slug identifier.
+ * Must consist solely of lowercase ASCII letters, digits, and underscores.
+ * Exported so route handlers and validation functions reuse the exact same guard.
+ */
+export declare const SEED_SLUG_RE: RegExp;
+export declare const SLUG_RE: RegExp;
 export interface SeedValidationIssue {
     slug: string;
     messages: string[];

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

@@ -1 +1 @@
-{"version":3,"file":"seed-validation.d.ts","sourceRoot":"","sources":["../../src/engine/seed-validation.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,YAAY,CAAA;AAOtC;;;;;;GAMG;AACH,eAAO,MAAM,eAAe,QAAyB,CAAA;AAErD,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,CA8P5E;AAED,6CAA6C;AAC7C,wBAAgB,cAAc,CAAC,KAAK,EAAE,IAAI,EAAE,GAAG,OAAO,CAErD"}
+{"version":3,"file":"seed-validation.d.ts","sourceRoot":"","sources":["../../src/engine/seed-validation.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,YAAY,CAAA;AAQtC;;;;;;GAMG;AACH,eAAO,MAAM,eAAe,QAAyB,CAAA;AAErD;;;;GAIG;AACH,eAAO,MAAM,YAAY,QAAiB,CAAA;AAC1C,eAAO,MAAM,OAAO,QAAe,CAAA;AAGnC,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,CAkT5E;AAED,6CAA6C;AAC7C,wBAAgB,cAAc,CAAC,KAAK,EAAE,IAAI,EAAE,GAAG,OAAO,CAErD"}

package/dist/engine/seed-validation.js

@@ -1,6 +1,7 @@
 // SPDX-License-Identifier: MIT
 // Copyright (c) 2024–2026 Flavio De Musso
 import { AUTOMATION_RESERVED_WORDS } from '../automations/automations-grammar-words.js';
+import { SYSTEM_COLUMNS } from './ddl.js';
 import { sortSeedsByDependencies } from './seed-registry.js';
 import { SQL_RESERVED_WORDS } from './sql-reserved-words.js';
 const BRANCH_ID_RE = /^br_[A-Za-z0-9]+$/;
@@ -12,6 +13,13 @@ const BRANCH_ID_RE = /^br_[A-Za-z0-9]+$/;
  * exact same guard — do not inline a divergent copy.
  */
 export const BRANCH_ALIAS_RE = /^[a-z][a-zA-Z0-9_]*$/;
+/**
+ * Allowed charset for a seed slug identifier.
+ * Must consist solely of lowercase ASCII letters, digits, and underscores.
+ * Exported so route handlers and validation functions reuse the exact same guard.
+ */
+export const SEED_SLUG_RE = /^[a-z0-9_]+$/;
+export const SLUG_RE = SEED_SLUG_RE;
 /**
  * Pure, console-free, throw-free validation of a seed set.
  * The single seed being created/edited should be validated in the context of
@@ -113,7 +121,11 @@ export function validateSeedDefinitions(seeds) {
     for (const seed of seeds) {
         const messages = [];
         for (const branch of seed.branches) {
-            if (AUTOMATION_RESERVED_WORDS.has(branch.alias)) {
+            if (SYSTEM_COLUMNS.has(branch.alias)) {
+                messages.push(`branch '${branch.alias}' collides with reserved system column. ` +
+                    `System columns (id, slug, status, created_at, updated_at) cannot be used as branch aliases.`);
+            }
+            else if (AUTOMATION_RESERVED_WORDS.has(branch.alias)) {
                 messages.push(`branch '${branch.alias}' uses reserved alias. ` +
                     `This word is used by the automation template grammar.`);
             }
@@ -242,6 +254,16 @@ export function validateSeedDefinitions(seeds) {
                 fatal: true,
             });
         }
+        else if (SYSTEM_COLUMNS.has(seed.displayNameAlias)) {
+            result.push({
+                slug: seed.slug,
+                messages: [
+                    `displayNameAlias '${seed.displayNameAlias}' collides with reserved system column. ` +
+                        `System columns (id, slug, status, created_at, updated_at) cannot be used as displayNameAlias.`,
+                ],
+                fatal: true,
+            });
+        }
         else if (SQL_RESERVED_WORDS.has(seed.displayNameAlias.toLowerCase())) {
             result.push({
                 slug: seed.slug,
@@ -253,6 +275,42 @@ export function validateSeedDefinitions(seeds) {
             });
         }
     }
+    // ── Fatal 13: retentionDays validation ─────────────────────────────────────
+    for (const seed of seeds) {
+        if (seed.retentionDays !== undefined && (!Number.isInteger(seed.retentionDays) || seed.retentionDays <= 0)) {
+            result.push({
+                slug: seed.slug,
+                messages: [
+                    `retentionDays must be a positive integer >= 1 (got ${seed.retentionDays}).`,
+                ],
+                fatal: true,
+            });
+        }
+    }
+    // ── Fatal 14: publicEdit validation ─────────────────────────────────────────
+    for (const seed of seeds) {
+        const messages = [];
+        for (const branch of seed.branches) {
+            if (branch.policies?.publicEdit !== undefined && typeof branch.policies.publicEdit !== 'boolean') {
+                messages.push(`branch '${branch.alias}': policies.publicEdit must be a boolean`);
+            }
+        }
+        if (messages.length > 0)
+            result.push({ slug: seed.slug, messages, fatal: true });
+    }
+    // ── Fatal 15: seed slug format validation ─────────────────────────────────
+    for (const seed of seeds) {
+        if (typeof seed.slug !== 'string' || !SEED_SLUG_RE.test(seed.slug)) {
+            result.push({
+                slug: seed.slug,
+                messages: [
+                    `slug '${seed.slug}' is invalid. Expected format ${SEED_SLUG_RE.source} ` +
+                        `(lowercase letters, numbers, and underscores only).`,
+                ],
+                fatal: true,
+            });
+        }
+    }
     return result;
 }
 /** Convenience: true iff no fatal issues. */

package/dist/engine/seeds/define-seed.d.ts

@@ -0,0 +1,3 @@
+import type { Seed } from '../types.js';
+export declare function defineSeed(seed: Seed): Seed;
+//# sourceMappingURL=define-seed.d.ts.map

package/dist/engine/seeds/define-seed.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"define-seed.d.ts","sourceRoot":"","sources":["../../../src/engine/seeds/define-seed.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,aAAa,CAAA;AAEvC,wBAAgB,UAAU,CAAC,IAAI,EAAE,IAAI,GAAG,IAAI,CAE3C"}

package/dist/engine/seeds/define-seed.js

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

package/dist/engine/seeds/seed-registry.d.ts

@@ -0,0 +1,71 @@
+import type { Seed, Branch } from '../types.js';
+export interface ISeedRegistry {
+    /**
+     * Returns all seeds as a flat array, preserving insertion order.
+     * Decouples callers from the internal storage shape so the registry
+     * implementation can change without touching every route handler.
+     */
+    all(): Seed[];
+    /**
+     * Returns the seed with the given slug, or null if not found.
+     * Provides a single lookup point that can be overridden in tests
+     * without rebuilding the full registry object.
+     */
+    get(slug: string): Seed | null;
+    /**
+     * Returns seeds that are visible in the dashboard sidebar.
+     * A seed is visible when dashboard.hidden is not explicitly true.
+     * Eliminates the seeds.filter(s => !s.dashboard?.hidden) pattern
+     * that would otherwise be duplicated across route handlers.
+     */
+    visibleInDashboard(): Seed[];
+    /**
+     * Returns seeds that have allowPublicRead enabled.
+     * Eliminates the seeds.filter(s => s.allowPublicRead) pattern.
+     */
+    publicReadable(): Seed[];
+    /**
+     * Returns seeds that have the draft workflow enabled.
+     * Eliminates the seeds.filter(s => s.allowDrafts) pattern.
+     */
+    draftEnabled(): Seed[];
+}
+export declare class SeedRegistry implements ISeedRegistry {
+    private readonly seedMap;
+    private readonly orderedSeeds;
+    constructor(seeds: Seed[]);
+    all(): Seed[];
+    get(slug: string): Seed | null;
+    visibleInDashboard(): Seed[];
+    publicReadable(): Seed[];
+    draftEnabled(): Seed[];
+}
+/**
+ * Named subclass of SeedRegistry for use in test suites.
+ * Gives tests a semantic name without requiring any dependency on factory.ts.
+ */
+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/engine/seeds/seed-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"seed-registry.d.ts","sourceRoot":"","sources":["../../../src/engine/seeds/seed-registry.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AAI/C,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;IAkCzB,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,CA0F1E"}

package/dist/engine/seeds/seed-registry.js

@@ -0,0 +1,167 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2024–2026 Flavio De Musso
+import { AUTOMATION_RESERVED_WORDS } from '../../automations/automations-grammar-words.js';
+import { SQL_RESERVED_WORDS } from '../sql-reserved-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 (SQL_RESERVED_WORDS.has(branch.alias.toLowerCase())) {
+                    throw new Error(`Seed "${seed.slug}" uses SQL reserved keyword "${branch.alias}". `
+                        + `Please pick a different alias to prevent database errors.`);
+                }
+                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;
+        this.seedMap = new Map(seeds.map(seed => [seed.slug, seed]));
+    }
+    all() {
+        return this.orderedSeeds;
+    }
+    get(slug) {
+        return this.seedMap.get(slug) ?? null;
+    }
+    visibleInDashboard() {
+        return this.orderedSeeds.filter(seed => seed.dashboard?.hidden !== true);
+    }
+    publicReadable() {
+        return this.orderedSeeds.filter(seed => seed.allowPublicRead === true);
+    }
+    draftEnabled() {
+        return this.orderedSeeds.filter(seed => seed.allowDrafts === true);
+    }
+}
+/**
+ * Named subclass of SeedRegistry for use in test suites.
+ * Gives tests a semantic name without requiring any dependency on factory.ts.
+ */
+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) {
+            if (target === seed.slug)
+                continue; // self-reference needs no ordering
+            // 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) {
+        // Isolate true cycle members
+        const stuck = new Set([...inDegree.entries()]
+            .filter(([, deg]) => deg > 0)
+            .map(([slug]) => slug));
+        const cycleNodes = [...stuck].filter(slug => {
+            const visited = new Set();
+            const queue = [...(dependents.get(slug) ?? [])].filter(s => stuck.has(s));
+            while (queue.length > 0) {
+                const curr = queue.shift();
+                if (curr === slug)
+                    return true;
+                if (!visited.has(curr)) {
+                    visited.add(curr);
+                    for (const next of dependents.get(curr) ?? []) {
+                        if (stuck.has(next))
+                            queue.push(next);
+                    }
+                }
+            }
+            return false;
+        });
+        const cycle = (cycleNodes.length > 0 ? cycleNodes : [...stuck]).sort();
+        throw new Error(`Cyclic dependency detected among seeds: ${cycle.join(', ')}`);
+    }
+    return result;
+}

package/dist/engine/seeds/seed-types-generator.d.ts

@@ -0,0 +1,25 @@
+import type { Seed, Branch } from '../types.js';
+/** slug/alias → PascalCase identifier. 'blog-posts' → 'BlogPosts'. */
+export declare function pascalCase(input: string): string;
+/** Maps a single Branch to its TypeScript type expression (no optional marker). */
+export declare function tsTypeForBranch(branch: Branch): string;
+/** Emits one exported interface for a single Seed. */
+export declare function interfaceForSeed(seed: Seed): string;
+/** Options that affect the emitted module beyond the seed interfaces themselves. */
+export interface SeedTypesOptions {
+    /**
+     * Schema fingerprint to embed as `SCHEMA_FINGERPRINT`, from `computeSchemaFingerprint`.
+     * Omitted ⇒ no constant is emitted and the output is byte-identical to a pre-fingerprint build,
+     * which is what keeps the legacy `beech gen-types` aliases non-breaking.
+     */
+    fingerprint?: string;
+}
+/**
+ * Pure entry point. Deterministic: sorts seeds by slug for stable diffs.
+ *
+ * The embedded fingerprint is the client's half of the drift check: `@beechcms/client` compares it
+ * against the `X-Schema-Revision` header the API returns and raises an actionable error on a
+ * mismatch, instead of trusting a stale response shape.
+ */
+export declare function generateSeedTypes(seeds: Seed[], options?: SeedTypesOptions): string;
+//# sourceMappingURL=seed-types-generator.d.ts.map

package/dist/engine/seeds/seed-types-generator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"seed-types-generator.d.ts","sourceRoot":"","sources":["../../../src/engine/seeds/seed-types-generator.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AAe/C,sEAAsE;AACtE,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAMhD;AAMD,mFAAmF;AACnF,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAoCtD;AAWD,sDAAsD;AACtD,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,IAAI,GAAG,MAAM,CAYnD;AAKD,oFAAoF;AACpF,MAAM,WAAW,gBAAgB;IAC/B;;;;OAIG;IACH,WAAW,CAAC,EAAE,MAAM,CAAA;CACrB;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,IAAI,EAAE,EAAE,OAAO,GAAE,gBAAqB,GAAG,MAAM,CAcvF"}