@beechcms/core 0.8.1 → 0.9.0

package/dist/engine/seeds/seed-definition-diff.d.ts

@@ -0,0 +1,38 @@
+import type { Branch, Seed } from '../types.js';
+/** A branch as either side of a comparison carries it: stored (`Branch`, with id) or manifest-authored (id optional). */
+export type BranchDefinitionLike = Omit<Branch, 'id' | 'fields'> & {
+    id?: string;
+    fields?: BranchDefinitionLike[];
+};
+/** A seed as either side of a comparison carries it: stored (`Seed`) or manifest-authored (no layout). */
+export type SeedDefinitionLike = Omit<Seed, 'branches' | 'layout'> & {
+    branches: BranchDefinitionLike[];
+    layout?: unknown;
+};
+/** Seed-level flags the engine treats as `false` when omitted. */
+export declare const SEED_DEFINITION_FLAGS: readonly ["allowDrafts", "allowPublicRead", "allowPublicPost", "allowPublicEdit", "softDelete"];
+/** Branch-level flags the engine treats as `false` when omitted. `multiple` is resolved separately (see normalizeBranchDefinition). */
+export declare const BRANCH_DEFINITION_FLAGS: readonly ["requiredOnCreate", "requiredOnUpdate"];
+/**
+ * Comparable form of one branch definition. Two branches are the same definition iff their canonicalStringify bytes match.
+ *
+ * - `id` is dropped, recursively through `fields`.
+ * - `requiredOnCreate` / `requiredOnUpdate` omitted ≡ `false`.
+ * - `multiple` omitted ≡ `true` on `tags` (single source of truth: `isSingleChoiceTags`), ≡ `false` on every other type.
+ * - Every other key, unknown ones included, is copied unchanged: `options` is compared as declared (values, colors, order).
+ */
+export declare function normalizeBranchDefinition(branch: BranchDefinitionLike): Record<string, unknown>;
+/** Comparable form of one seed definition (branches normalized, order kept). `layout` is server-populated and dropped. */
+export declare function normalizeSeedDefinition(seed: SeedDefinitionLike): Record<string, unknown>;
+export interface SeedDefinitionDiff {
+    /** True when the candidate's comparable definition differs from the stored one. Always true when nothing is stored. */
+    changed: boolean;
+    /**
+     * Aliases, in candidate order, of candidate branches that are new (no stored branch with the same id) or whose
+     * comparable definition differs from the stored branch with the same id. `[]` when nothing is stored.
+     */
+    changedBranches: string[];
+}
+/** Compares a stored seed definition with a candidate whose ids were already resolved ({@link resolveCandidateIds}). Pure. */
+export declare function diffSeedDefinition(stored: Seed | null, candidate: Seed): SeedDefinitionDiff;
+//# sourceMappingURL=seed-definition-diff.d.ts.map

package/dist/engine/seeds/seed-definition-diff.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"seed-definition-diff.d.ts","sourceRoot":"","sources":["../../../src/engine/seeds/seed-definition-diff.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,aAAa,CAAA;AAI/C,yHAAyH;AACzH,MAAM,MAAM,oBAAoB,GAAG,IAAI,CAAC,MAAM,EAAE,IAAI,GAAG,QAAQ,CAAC,GAAG;IAAE,EAAE,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,oBAAoB,EAAE,CAAA;CAAE,CAAA;AAEnH,0GAA0G;AAC1G,MAAM,MAAM,kBAAkB,GAAG,IAAI,CAAC,IAAI,EAAE,UAAU,GAAG,QAAQ,CAAC,GAAG;IAAE,QAAQ,EAAE,oBAAoB,EAAE,CAAC;IAAC,MAAM,CAAC,EAAE,OAAO,CAAA;CAAE,CAAA;AAE3H,kEAAkE;AAClE,eAAO,MAAM,qBAAqB,iGAAkG,CAAA;AAEpI,uIAAuI;AACvI,eAAO,MAAM,uBAAuB,mDAAoD,CAAA;AAExF;;;;;;;GAOG;AACH,wBAAgB,yBAAyB,CAAC,MAAM,EAAE,oBAAoB,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAO/F;AAED,0HAA0H;AAC1H,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,kBAAkB,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAMzF;AAED,MAAM,WAAW,kBAAkB;IACjC,uHAAuH;IACvH,OAAO,EAAE,OAAO,CAAA;IAChB;;;OAGG;IACH,eAAe,EAAE,MAAM,EAAE,CAAA;CAC1B;AAED,8HAA8H;AAC9H,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,IAAI,GAAG,IAAI,EAAE,SAAS,EAAE,IAAI,GAAG,kBAAkB,CAe3F"}

package/dist/engine/seeds/seed-definition-diff.js

@@ -0,0 +1,51 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2024–2026 Flavio De Musso
+import { canonicalStringify } from '../../common/canonical-json.js';
+import { isSingleChoiceTags } from './tag-options.js';
+/** Seed-level flags the engine treats as `false` when omitted. */
+export const SEED_DEFINITION_FLAGS = ['allowDrafts', 'allowPublicRead', 'allowPublicPost', 'allowPublicEdit', 'softDelete'];
+/** Branch-level flags the engine treats as `false` when omitted. `multiple` is resolved separately (see normalizeBranchDefinition). */
+export const BRANCH_DEFINITION_FLAGS = ['requiredOnCreate', 'requiredOnUpdate'];
+/**
+ * Comparable form of one branch definition. Two branches are the same definition iff their canonicalStringify bytes match.
+ *
+ * - `id` is dropped, recursively through `fields`.
+ * - `requiredOnCreate` / `requiredOnUpdate` omitted ≡ `false`.
+ * - `multiple` omitted ≡ `true` on `tags` (single source of truth: `isSingleChoiceTags`), ≡ `false` on every other type.
+ * - Every other key, unknown ones included, is copied unchanged: `options` is compared as declared (values, colors, order).
+ */
+export function normalizeBranchDefinition(branch) {
+    const { id: _id, fields, ...rest } = branch;
+    const normalized = { ...rest };
+    for (const flag of BRANCH_DEFINITION_FLAGS)
+        normalized[flag] = branch[flag] === true;
+    normalized.multiple = branch.type === 'tags' ? !isSingleChoiceTags(branch) : branch.multiple === true;
+    if (fields !== undefined)
+        normalized.fields = fields.map(normalizeBranchDefinition);
+    return normalized;
+}
+/** Comparable form of one seed definition (branches normalized, order kept). `layout` is server-populated and dropped. */
+export function normalizeSeedDefinition(seed) {
+    const { layout: _layout, branches, ...rest } = seed;
+    const normalized = { ...rest };
+    for (const flag of SEED_DEFINITION_FLAGS)
+        normalized[flag] = seed[flag] === true;
+    normalized.branches = (branches ?? []).map(normalizeBranchDefinition);
+    return normalized;
+}
+/** Compares a stored seed definition with a candidate whose ids were already resolved ({@link resolveCandidateIds}). Pure. */
+export function diffSeedDefinition(stored, candidate) {
+    if (stored === null)
+        return { changed: true, changedBranches: [] };
+    const storedById = new Map(stored.branches.map(branch => [branch.id, branch]));
+    const changedBranches = candidate.branches
+        .filter(branch => {
+        const previous = storedById.get(branch.id);
+        return previous === undefined
+            || canonicalStringify(normalizeBranchDefinition(branch)) !== canonicalStringify(normalizeBranchDefinition(previous));
+    })
+        .map(branch => branch.alias);
+    const changed = changedBranches.length > 0
+        || canonicalStringify(normalizeSeedDefinition(candidate)) !== canonicalStringify(normalizeSeedDefinition(stored));
+    return { changed, changedBranches };
+}

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

@@ -40,6 +40,23 @@ export declare class SeedRegistry implements ISeedRegistry {
     publicReadable(): Seed[];
     draftEnabled(): Seed[];
 }
+/** A seed the registry refused to serve, with the validation failure that excluded it. */
+export interface QuarantinedSeed {
+    slug: string;
+    reason: string;
+}
+/**
+ * Builds a registry from every seed that validates and sets aside the ones that do not.
+ *
+ * `new SeedRegistry(seeds)` is all-or-nothing: one seed holding a legacy shape (say pre-0.9 tag
+ * options) throws and takes the whole API down. Validation is per seed and independent, so this
+ * validates each seed alone and leaves the failing ones out. Callers log `quarantined`; the rest of
+ * the system keeps serving.
+ */
+export declare function createTolerantSeedRegistry(seeds: ReadonlyArray<Seed>): {
+    registry: SeedRegistry;
+    quarantined: QuarantinedSeed[];
+};
 /**
  * Named subclass of SeedRegistry for use in test suites.
  * Gives tests a semantic name without requiring any dependency on factory.ts.

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

@@ -1 +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"}
+{"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;AAK/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;IAsCzB,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,0FAA0F;AAC1F,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAA;IACZ,MAAM,EAAE,MAAM,CAAA;CACf;AAED;;;;;;;GAOG;AACH,wBAAgB,0BAA0B,CAAC,KAAK,EAAE,aAAa,CAAC,IAAI,CAAC,GAAG;IACtE,QAAQ,EAAE,YAAY,CAAA;IACtB,WAAW,EAAE,eAAe,EAAE,CAAA;CAC/B,CAYA;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

@@ -2,6 +2,7 @@
 // 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';
+import { tagOptionsIssues } from './tag-options.js';
 const BRANCH_ID_RE = /^br_[A-Za-z0-9]+$/;
 export class SeedRegistry {
     seedMap;
@@ -26,6 +27,10 @@ export class SeedRegistry {
                     throw new Error(`Seed "${seed.slug}" has duplicate branch id "${branch.id}".`);
                 }
                 idsInSeed.add(branch.id);
+                const optionIssues = tagOptionsIssues(branch);
+                if (optionIssues.length > 0) {
+                    throw new Error(`Seed "${seed.slug}": ${optionIssues[0]}`);
+                }
             }
         }
         this.orderedSeeds = seeds;
@@ -47,6 +52,28 @@ export class SeedRegistry {
         return this.orderedSeeds.filter(seed => seed.allowDrafts === true);
     }
 }
+/**
+ * Builds a registry from every seed that validates and sets aside the ones that do not.
+ *
+ * `new SeedRegistry(seeds)` is all-or-nothing: one seed holding a legacy shape (say pre-0.9 tag
+ * options) throws and takes the whole API down. Validation is per seed and independent, so this
+ * validates each seed alone and leaves the failing ones out. Callers log `quarantined`; the rest of
+ * the system keeps serving.
+ */
+export function createTolerantSeedRegistry(seeds) {
+    const valid = [];
+    const quarantined = [];
+    for (const seed of seeds) {
+        try {
+            new SeedRegistry([seed]);
+            valid.push(seed);
+        }
+        catch (error) {
+            quarantined.push({ slug: seed.slug, reason: error instanceof Error ? error.message : String(error) });
+        }
+    }
+    return { registry: new SeedRegistry(valid), quarantined };
+}
 /**
  * Named subclass of SeedRegistry for use in test suites.
  * Gives tests a semantic name without requiring any dependency on factory.ts.

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

@@ -1 +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"}
+{"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;AAgB/C,sEAAsE;AACtE,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAMhD;AAMD,mFAAmF;AACnF,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAiCtD;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"}

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

@@ -1,5 +1,6 @@
 // SPDX-License-Identifier: MIT
 // Copyright (c) 2024–2026 Flavio De Musso
+import { tagOptionValues } from './tag-options.js';
 const HEADER = '// Questo file è generato automaticamente da BeechCMS CLI. Non modificarlo direttamente.\n';
 /** System columns emitted by generateCreateTable — always present, never optional. */
 const SYSTEM_FIELDS = `  id: string\n` +
@@ -31,13 +32,11 @@ export function tsTypeForBranch(branch) {
         case 'text':
         case 'richtext':
         case 'file': {
-            const base = branch.type === 'text' && branch.options?.length
-                ? literalUnion(branch.options)
-                : 'string';
-            return branch.type === 'file' && branch.multiple ? `${base}[]` : base;
+            return branch.type === 'file' && branch.multiple ? 'string[]' : 'string';
         }
         case 'tags': {
-            const base = branch.options?.length ? `(${literalUnion(branch.options)})` : 'string';
+            const values = tagOptionValues(branch);
+            const base = values.length > 0 ? `(${literalUnion(values)})` : 'string';
             return `${base}[]`;
         }
         case 'relation':

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

@@ -7,6 +7,11 @@ import type { Seed } from '../types.js';
  * exact same guard — do not inline a divergent copy.
  */
 export declare const BRANCH_ALIAS_RE: RegExp;
+/**
+ * Reason a branch alias is reserved, or `null` when free to use.
+ * Single source for seed validation and the branch rename route.
+ */
+export declare function reservedBranchAliasReason(alias: string): string | null;
 /**
  * Allowed charset for a seed slug identifier.
  * Must consist solely of lowercase ASCII letters, digits, and underscores.

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

@@ -1 +1 @@
-{"version":3,"file":"seed-validation.d.ts","sourceRoot":"","sources":["../../../src/engine/seeds/seed-validation.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,aAAa,CAAA;AAUvC;;;;;;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,CAkW5E;AAED,6CAA6C;AAC7C,wBAAgB,cAAc,CAAC,KAAK,EAAE,IAAI,EAAE,GAAG,OAAO,CAErD"}
+{"version":3,"file":"seed-validation.d.ts","sourceRoot":"","sources":["../../../src/engine/seeds/seed-validation.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,aAAa,CAAA;AAWvC;;;;;;GAMG;AACH,eAAO,MAAM,eAAe,QAAyB,CAAA;AAErD;;;GAGG;AACH,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CActE;AAED;;;;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,CA2V5E;AAED,6CAA6C;AAC7C,wBAAgB,cAAc,CAAC,KAAK,EAAE,IAAI,EAAE,GAAG,OAAO,CAErD"}

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

@@ -5,6 +5,7 @@ import { SYSTEM_COLUMNS } from '../ddl/ddl.js';
 import { LOCALIZABLE_BRANCH_TYPES } from '../localization/localization.js';
 import { resolveClassification } from '../privacy/policies.js';
 import { sortSeedsByDependencies } from './seed-registry.js';
+import { tagOptionsIssues } from './tag-options.js';
 import { SQL_RESERVED_WORDS } from '../sql-reserved-words.js';
 const BRANCH_ID_RE = /^br_[A-Za-z0-9]+$/;
 /**
@@ -15,6 +16,25 @@ 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_]*$/;
+/**
+ * Reason a branch alias is reserved, or `null` when free to use.
+ * Single source for seed validation and the branch rename route.
+ */
+export function reservedBranchAliasReason(alias) {
+    if (SYSTEM_COLUMNS.has(alias)) {
+        return `branch '${alias}' collides with reserved system column. ` +
+            `System columns (id, slug, status, created_at, updated_at) cannot be used as branch aliases.`;
+    }
+    if (AUTOMATION_RESERVED_WORDS.has(alias)) {
+        return `branch '${alias}' uses reserved alias. ` +
+            `This word is used by the automation template grammar.`;
+    }
+    if (SQL_RESERVED_WORDS.has(alias.toLowerCase())) {
+        return `branch '${alias}' uses SQL reserved keyword. ` +
+            `Please pick a different alias to prevent database errors.`;
+    }
+    return null;
+}
 /**
  * Allowed charset for a seed slug identifier.
  * Must consist solely of lowercase ASCII letters, digits, and underscores.
@@ -29,15 +49,18 @@ export const SLUG_RE = SEED_SLUG_RE;
  */
 export function validateSeedDefinitions(seeds) {
     const result = [];
-    // ── Fatal 1: unknown relation targets ────────────────────────────────────
+    // ── Fatal 1: missing or 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 (branch.type !== 'relation')
+                continue;
+            if (!branch.targetSeed) {
+                messages.push(`branch '${branch.alias}' is a relation and requires a targetSeed`);
+            }
+            else if (!slugSet.has(branch.targetSeed)) {
+                messages.push(`branch '${branch.alias}' targets unknown seed '${branch.targetSeed}'`);
             }
         }
         if (messages.length > 0)
@@ -123,18 +146,9 @@ export function validateSeedDefinitions(seeds) {
     for (const seed of seeds) {
         const messages = [];
         for (const branch of seed.branches) {
-            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.`);
-            }
-            else if (SQL_RESERVED_WORDS.has(branch.alias.toLowerCase())) {
-                messages.push(`branch '${branch.alias}' uses SQL reserved keyword. ` +
-                    `Please pick a different alias to prevent database errors.`);
-            }
+            const reason = reservedBranchAliasReason(branch.alias);
+            if (reason)
+                messages.push(reason);
         }
         if (messages.length > 0)
             result.push({ slug: seed.slug, messages, fatal: true });
@@ -203,14 +217,14 @@ export function validateSeedDefinitions(seeds) {
         if (messages.length > 0)
             result.push({ slug: seed.slug, messages, fatal: false });
     }
-    // ── Warning 9: displayNameAlias not in branches ───────────────────────────
+    // ── Fatal 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,
+                fatal: true,
             });
         }
     }
@@ -356,6 +370,12 @@ export function validateSeedDefinitions(seeds) {
         if (messages.length > 0)
             result.push({ slug: seed.slug, messages, fatal: true });
     }
+    // ── Fatal 18: tags options / cardinality ───────────────────────────────────
+    for (const seed of seeds) {
+        const messages = seed.branches.flatMap(branch => tagOptionsIssues(branch));
+        if (messages.length > 0)
+            result.push({ slug: seed.slug, messages, fatal: true });
+    }
     return result;
 }
 /** Convenience: true iff no fatal issues. */

package/dist/engine/seeds/tag-migration.d.ts

@@ -0,0 +1,73 @@
+/**
+ * @module engine/tag-migration
+ * Data migration from the pre-0.9 tag/choice shapes to the closed-vocabulary `tags` contract.
+ *
+ * Before 0.9 a choice field was either `text` + `options` (a single value stored as a plain string)
+ * or `tags` + `options: string[]`. Since 0.9 `options` exists only on `tags` as `{ value, color }[]`,
+ * and every stored value is a JSON array. Databases holding the old shapes were rejected at boot with
+ * no way forward; this module computes the way forward.
+ *
+ * Everything here is pure: it plans from seed definitions and emits SQL text. Nothing is executed,
+ * so the same plan drives the CLI dry run, `--apply`, and the audit.
+ */
+import type { Seed } from '../types.js';
+import type { SchemaQueryExecutor } from '../introspection/introspection.js';
+/**
+ * Colors assigned, in declaration order, to legacy options that never carried one.
+ * Deterministic on purpose: re-running the plan yields the same definition.
+ */
+export declare const TAG_MIGRATION_PALETTE: readonly string[];
+/** What the plan does with one branch. */
+export type TagMigrationAction = 
+/** `text` + `options` becomes single-choice `tags`; stored strings are wrapped into arrays. */
+'text-to-tags'
+/** `tags` whose `options` are plain strings or carry invalid colors; stored values are untouched. */
+ | 'tags-options'
+/** Cannot be converted safely; a human must edit the seed. */
+ | 'manual';
+export interface TagMigrationStep {
+    seed: string;
+    /** Dotted path when the branch is nested in a repeater, otherwise the alias. */
+    alias: string;
+    action: TagMigrationAction;
+    /** One line, operator-facing. */
+    summary: string;
+    /** Non-fatal remarks (e.g. a full-text index that still covers the column). */
+    warnings: string[];
+}
+export interface TagMigrationPlan {
+    steps: TagMigrationStep[];
+    /** Rewritten definitions, only for seeds that changed. Seeds with a `manual` step are not rewritten. */
+    seeds: Seed[];
+}
+/** True when the plan has anything to report or do. */
+export declare function hasTagMigrationWork(plan: TagMigrationPlan): boolean;
+/** Steps a human must resolve. */
+export declare function manualTagSteps(plan: TagMigrationPlan): TagMigrationStep[];
+/**
+ * Computes what moving `seeds` to the 0.9 tags contract takes. Seeds that already comply produce no
+ * step and no rewritten definition, so a clean database yields an empty plan (the operation is idempotent).
+ */
+export declare function planTagMigration(seeds: readonly Seed[]): TagMigrationPlan;
+/**
+ * The statements that carry the plan out, in execution order: stored values first, then the seed
+ * definitions, then the registry-version bump that tells every isolate to rebuild its cached registry.
+ * Value wrapping touches the live table and, when drafts are on, the drafts table.
+ *
+ * `originals` are the definitions the plan was computed from (the physical tables are named after them).
+ */
+export declare function tagMigrationStatements(plan: TagMigrationPlan, originals: readonly Seed[]): string[];
+/** A stored value that is not in the (new) vocabulary of its branch. */
+export interface TagOrphan {
+    seed: string;
+    alias: string;
+    value: string;
+    rows: number;
+}
+/**
+ * Reads, before anything is changed, the stored values the new vocabulary would not contain. They are
+ * reported, never deleted or rewritten: the operator decides whether to add an option or fix the rows.
+ * Read-only (`SELECT` through the injected executor).
+ */
+export declare function findTagOrphans(executor: SchemaQueryExecutor, plan: TagMigrationPlan, originals: readonly Seed[]): Promise<TagOrphan[]>;
+//# sourceMappingURL=tag-migration.d.ts.map

package/dist/engine/seeds/tag-migration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tag-migration.d.ts","sourceRoot":"","sources":["../../../src/engine/seeds/tag-migration.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAU,IAAI,EAAa,MAAM,aAAa,CAAA;AAE1D,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,mCAAmC,CAAA;AAK5E;;;GAGG;AACH,eAAO,MAAM,qBAAqB,EAAE,SAAS,MAAM,EAElD,CAAA;AAED,0CAA0C;AAC1C,MAAM,MAAM,kBAAkB;AAC5B,+FAA+F;AAC7F,cAAc;AAChB,qGAAqG;GACnG,cAAc;AAChB,8DAA8D;GAC5D,QAAQ,CAAA;AAEZ,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAA;IACZ,gFAAgF;IAChF,KAAK,EAAE,MAAM,CAAA;IACb,MAAM,EAAE,kBAAkB,CAAA;IAC1B,iCAAiC;IACjC,OAAO,EAAE,MAAM,CAAA;IACf,+EAA+E;IAC/E,QAAQ,EAAE,MAAM,EAAE,CAAA;CACnB;AAED,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,gBAAgB,EAAE,CAAA;IACzB,wGAAwG;IACxG,KAAK,EAAE,IAAI,EAAE,CAAA;CACd;AAED,uDAAuD;AACvD,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,gBAAgB,GAAG,OAAO,CAEnE;AAED,kCAAkC;AAClC,wBAAgB,cAAc,CAAC,IAAI,EAAE,gBAAgB,GAAG,gBAAgB,EAAE,CAEzE;AA2GD;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,SAAS,IAAI,EAAE,GAAG,gBAAgB,CAuBzE;AAeD;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,gBAAgB,EAAE,SAAS,EAAE,SAAS,IAAI,EAAE,GAAG,MAAM,EAAE,CA2BnG;AAED,wEAAwE;AACxE,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,EAAE,MAAM,CAAA;IACb,KAAK,EAAE,MAAM,CAAA;IACb,IAAI,EAAE,MAAM,CAAA;CACb;AAOD;;;;GAIG;AACH,wBAAsB,cAAc,CAClC,QAAQ,EAAE,mBAAmB,EAC7B,IAAI,EAAE,gBAAgB,EACtB,SAAS,EAAE,SAAS,IAAI,EAAE,GACzB,OAAO,CAAC,SAAS,EAAE,CAAC,CA2BtB"}

package/dist/engine/seeds/tag-migration.js

@@ -0,0 +1,212 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2024–2026 Flavio De Musso
+import { draftTableName, indexableSearchBranches, tableName } from '../ddl/ddl.js';
+import { cleanString, isPlainObject } from '../validation/primitives.js';
+import { TAG_OPTION_COLOR_RE, tagOptionsIssues } from './tag-options.js';
+import { normalizeTagValue, TAG_OPTIONS_MAX_COUNT } from './tag-value.js';
+/**
+ * Colors assigned, in declaration order, to legacy options that never carried one.
+ * Deterministic on purpose: re-running the plan yields the same definition.
+ */
+export const TAG_MIGRATION_PALETTE = [
+    '#3b82f6', '#22c55e', '#f59e0b', '#ef4444', '#8b5cf6', '#14b8a6', '#ec4899', '#64748b',
+];
+/** True when the plan has anything to report or do. */
+export function hasTagMigrationWork(plan) {
+    return plan.steps.length > 0;
+}
+/** Steps a human must resolve. */
+export function manualTagSteps(plan) {
+    return plan.steps.filter(step => step.action === 'manual');
+}
+function paletteColor(index) {
+    return TAG_MIGRATION_PALETTE[index % TAG_MIGRATION_PALETTE.length];
+}
+/**
+ * Converts whatever a legacy `options` array held into the `{ value, color }` contract.
+ * Returns `null` when nothing salvageable remains (the caller then asks for a manual fix).
+ */
+function rewriteOptions(raw) {
+    if (!Array.isArray(raw) || raw.length === 0 || raw.length > TAG_OPTIONS_MAX_COUNT)
+        return null;
+    const seen = new Set();
+    const options = [];
+    raw.forEach((entry, index) => {
+        let candidate;
+        let color;
+        if (typeof entry === 'string') {
+            candidate = entry;
+        }
+        else if (isPlainObject(entry) && typeof entry.value === 'string') {
+            candidate = entry.value;
+            color = typeof entry.color === 'string' && TAG_OPTION_COLOR_RE.test(entry.color) ? entry.color : undefined;
+        }
+        if (candidate === undefined)
+            return;
+        const normalized = normalizeTagValue(cleanString(candidate));
+        if (!normalized.ok || normalized.value === '' || seen.has(normalized.value))
+            return;
+        seen.add(normalized.value);
+        options.push({ value: normalized.value, color: color ?? paletteColor(options.length) });
+    });
+    return options.length > 0 ? options : null;
+}
+function manual(branch, summary) {
+    return { branch, step: { alias: branch.alias, action: 'manual', summary, warnings: [] } };
+}
+function isSafeIdentifier(name) {
+    return /^[A-Za-z_][A-Za-z0-9_]*$/.test(name);
+}
+/** Plans the rewrite of one top-level branch; `null` when it already honours the contract. */
+function planBranch(seed, branch) {
+    const raw = branch;
+    const ownIssues = tagOptionsIssues({ ...branch, fields: [] });
+    const nestedIssues = tagOptionsIssues(branch).length - ownIssues.length;
+    if (ownIssues.length === 0) {
+        return nestedIssues > 0
+            ? manual(branch, `a repeater sub-field of '${branch.alias}' uses the legacy options shape; edit the seed by hand`)
+            : null;
+    }
+    if (!isSafeIdentifier(branch.alias)) {
+        return manual(branch, `alias '${branch.alias}' is not a plain SQL identifier`);
+    }
+    if (branch.type !== 'text' && branch.type !== 'tags') {
+        return manual(branch, `options are not supported on type '${branch.type}'; remove them from the seed`);
+    }
+    if (branch.localized === true) {
+        return manual(branch, `'${branch.alias}' is localized; its stored locale dictionary cannot be wrapped automatically`);
+    }
+    if (nestedIssues > 0) {
+        return manual(branch, `'${branch.alias}' also has legacy options in a repeater sub-field; edit the seed by hand`);
+    }
+    const options = rewriteOptions(raw.options);
+    if (!options) {
+        return manual(branch, `'${branch.alias}' has no usable options (empty, over ${TAG_OPTIONS_MAX_COUNT}, or all invalid)`);
+    }
+    const rewritten = branch.type === 'text'
+        ? { ...branch, type: 'tags', multiple: false, options }
+        : { ...branch, options };
+    if (tagOptionsIssues(rewritten).length > 0) {
+        return manual(branch, `'${branch.alias}' still violates the tags contract after conversion`);
+    }
+    const warnings = [];
+    if (branch.type === 'text' && indexableSearchBranches({ ...seed, branches: [branch] }).length > 0) {
+        warnings.push(`'${branch.alias}' was full-text indexed as text; run \`beech schema diff\` to check the search index`);
+    }
+    return branch.type === 'text'
+        ? {
+            branch: rewritten,
+            step: {
+                alias: branch.alias,
+                action: 'text-to-tags',
+                summary: `'${branch.alias}': text + options → single-choice tags (${options.length} options, values wrapped into arrays)`,
+                warnings,
+            },
+        }
+        : {
+            branch: rewritten,
+            step: {
+                alias: branch.alias,
+                action: 'tags-options',
+                summary: `'${branch.alias}': options rewritten as { value, color } (${options.length} options, values untouched)`,
+                warnings,
+            },
+        };
+}
+/**
+ * Computes what moving `seeds` to the 0.9 tags contract takes. Seeds that already comply produce no
+ * step and no rewritten definition, so a clean database yields an empty plan (the operation is idempotent).
+ */
+export function planTagMigration(seeds) {
+    const steps = [];
+    const rewrittenSeeds = [];
+    for (const seed of seeds) {
+        const seedSteps = [];
+        let changed = false;
+        const branches = seed.branches.map(branch => {
+            const rewrite = planBranch(seed, branch);
+            if (!rewrite)
+                return branch;
+            seedSteps.push({ seed: seed.slug, ...rewrite.step });
+            if (rewrite.step.action !== 'manual')
+                changed = true;
+            return rewrite.branch;
+        });
+        steps.push(...seedSteps);
+        // A seed with an unresolved branch is left exactly as stored: half a migration is worse than none.
+        if (changed && !seedSteps.some(step => step.action === 'manual')) {
+            rewrittenSeeds.push({ ...seed, branches });
+        }
+    }
+    return { steps, seeds: rewrittenSeeds };
+}
+function quote(value) {
+    return `'${value.replace(/'/g, "''")}'`;
+}
+/** `text-to-tags` steps of `seed` that the plan will rewrite. */
+function wrapAliases(plan, seed) {
+    const rewritten = plan.seeds.some(candidate => candidate.slug === seed.slug);
+    if (!rewritten)
+        return [];
+    return plan.steps
+        .filter(step => step.seed === seed.slug && step.action === 'text-to-tags')
+        .map(step => step.alias);
+}
+/**
+ * The statements that carry the plan out, in execution order: stored values first, then the seed
+ * definitions, then the registry-version bump that tells every isolate to rebuild its cached registry.
+ * Value wrapping touches the live table and, when drafts are on, the drafts table.
+ *
+ * `originals` are the definitions the plan was computed from (the physical tables are named after them).
+ */
+export function tagMigrationStatements(plan, originals) {
+    const statements = [];
+    for (const original of originals) {
+        for (const alias of wrapAliases(plan, original)) {
+            const tables = [tableName(original), ...(original.allowDrafts ? [draftTableName(original)] : [])];
+            for (const table of tables) {
+                statements.push(`UPDATE ${table} SET ${alias} = NULL WHERE ${alias} = '';`);
+                statements.push(`UPDATE ${table} SET ${alias} = json_array(${alias}) `
+                    + `WHERE ${alias} IS NOT NULL AND NOT (json_valid(${alias}) AND json_type(${alias}) = 'array');`);
+            }
+        }
+    }
+    for (const seed of plan.seeds) {
+        statements.push(`UPDATE seeds SET definition = ${quote(JSON.stringify(seed))}, updated_at = unixepoch() WHERE slug = ${quote(seed.slug)};`);
+    }
+    if (plan.seeds.length > 0) {
+        statements.push(`UPDATE seed_meta SET value = CAST(CAST(value AS INTEGER) + 1 AS TEXT) WHERE id = 'registry_version';`);
+    }
+    return statements;
+}
+/**
+ * Reads, before anything is changed, the stored values the new vocabulary would not contain. They are
+ * reported, never deleted or rewritten: the operator decides whether to add an option or fix the rows.
+ * Read-only (`SELECT` through the injected executor).
+ */
+export async function findTagOrphans(executor, plan, originals) {
+    const orphans = [];
+    for (const rewritten of plan.seeds) {
+        const original = originals.find(seed => seed.slug === rewritten.slug);
+        if (!original)
+            continue;
+        const table = tableName(original);
+        for (const step of plan.steps.filter(candidate => candidate.seed === rewritten.slug && candidate.action !== 'manual')) {
+            const branch = rewritten.branches.find(candidate => candidate.alias === step.alias);
+            if (!branch?.options)
+                continue;
+            const allowed = branch.options.map(option => quote(option.value)).join(', ');
+            const sql = step.action === 'text-to-tags'
+                ? `SELECT ${step.alias} AS value, COUNT(*) AS n FROM ${table} `
+                    + `WHERE ${step.alias} IS NOT NULL AND ${step.alias} != '' AND ${step.alias} NOT IN (${allowed}) GROUP BY ${step.alias}`
+                : `SELECT j.value AS value, COUNT(*) AS n FROM ${table}, `
+                    + `json_each(CASE WHEN json_valid(${table}.${step.alias}) THEN ${table}.${step.alias} ELSE '[]' END) AS j `
+                    + `WHERE j.value NOT IN (${allowed}) GROUP BY j.value`;
+            const rows = await executor.all(sql);
+            for (const row of rows) {
+                orphans.push({ seed: rewritten.slug, alias: step.alias, value: String(row.value), rows: Number(row.n) });
+            }
+        }
+    }
+    return orphans;
+}

package/dist/engine/seeds/tag-options.d.ts

@@ -0,0 +1,15 @@
+import type { Branch, TagOption } from '../types.js';
+/** Accepted option color format: 6-digit hex, the value `<input type="color">` emits. */
+export declare const TAG_OPTION_COLOR_RE: RegExp;
+/** True only for a `tags` branch with `multiple === false`. Omitted `multiple` on `tags` means multiple choice. */
+export declare function isSingleChoiceTags(branch: Pick<Branch, 'type' | 'multiple'>): boolean;
+/** Option values in declared order; `[]` when the branch has no options. */
+export declare function tagOptionValues(branch: Pick<Branch, 'options'>): string[];
+/** The option whose `value` equals `value` exactly, or `undefined`. */
+export declare function findTagOption(branch: Pick<Branch, 'options'>, value: string): TagOption | undefined;
+/**
+ * Seed-definition issues for `options` / `multiple` on this branch AND, recursively, its repeater sub-fields.
+ * Pure, never throws, works on untyped input (stored JSON may carry any shape). `[]` = valid.
+ */
+export declare function tagOptionsIssues(branch: Branch): string[];
+//# sourceMappingURL=tag-options.d.ts.map

package/dist/engine/seeds/tag-options.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tag-options.d.ts","sourceRoot":"","sources":["../../../src/engine/seeds/tag-options.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,aAAa,CAAA;AAIpD,yFAAyF;AACzF,eAAO,MAAM,mBAAmB,QAAsB,CAAA;AAEtD,mHAAmH;AACnH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,MAAM,GAAG,UAAU,CAAC,GAAG,OAAO,CAErF;AAED,4EAA4E;AAC5E,wBAAgB,eAAe,CAAC,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,SAAS,CAAC,GAAG,MAAM,EAAE,CAEzE;AAED,uEAAuE;AACvE,wBAAgB,aAAa,CAAC,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,SAAS,CAAC,EAAE,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS,CAEnG;AA8ED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAOzD"}