@beechcms/core 0.8.0 → 0.9.0

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"}

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

@@ -0,0 +1,111 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2024–2026 Flavio De Musso
+import { cleanString, isPlainObject } from '../validation/primitives.js';
+import { normalizeTagValue, TAG_MAX_LENGTH, TAG_OPTIONS_MAX_COUNT } from './tag-value.js';
+/** Accepted option color format: 6-digit hex, the value `<input type="color">` emits. */
+export const TAG_OPTION_COLOR_RE = /^#[0-9a-fA-F]{6}$/;
+/** True only for a `tags` branch with `multiple === false`. Omitted `multiple` on `tags` means multiple choice. */
+export function isSingleChoiceTags(branch) {
+    return branch.type === 'tags' && branch.multiple === false;
+}
+/** Option values in declared order; `[]` when the branch has no options. */
+export function tagOptionValues(branch) {
+    return (branch.options ?? []).map(option => option.value);
+}
+/** The option whose `value` equals `value` exactly, or `undefined`. */
+export function findTagOption(branch, value) {
+    return branch.options?.find(option => option.value === value);
+}
+/** Issues for one option entry; `seenValues` accumulates the values already declared on the branch. */
+function optionEntryIssues(prefix, entry, index, seenValues) {
+    if (typeof entry === 'string') {
+        return [`${prefix}option #${index} must be an object { value, color }, not a plain string.`];
+    }
+    if (!isPlainObject(entry)) {
+        return [`${prefix}option #${index} must be an object { value, color }.`];
+    }
+    const issues = [];
+    const { value, color } = entry;
+    const validValue = typeof value === 'string' && value !== '' && value === cleanString(value);
+    if (!validValue) {
+        issues.push(`${prefix}option #${index} value must be a non-empty string without leading or trailing whitespace.`);
+    }
+    else {
+        const normalized = normalizeTagValue(value);
+        if (!normalized.ok) {
+            issues.push(normalized.reason === 'too-long'
+                ? `${prefix}option '${value.slice(0, 40)}' value is too long (max ${TAG_MAX_LENGTH} characters).`
+                : `${prefix}option #${index} value is not valid text (lone surrogate).`);
+        }
+        else if (normalized.value !== value) {
+            issues.push(`${prefix}option #${index} value must already be normalized: no invisible or control characters, `
+                + `single spaces, Unicode NFC (use ${JSON.stringify(normalized.value)}).`);
+        }
+        else if (seenValues.has(value)) {
+            issues.push(`${prefix}duplicate option value '${value}'.`);
+        }
+        else {
+            seenValues.add(value);
+        }
+    }
+    if (typeof color !== 'string' || !TAG_OPTION_COLOR_RE.test(color)) {
+        const optionLabel = validValue ? `'${value}'` : `#${index}`;
+        issues.push(`${prefix}option ${optionLabel} color must be a hex color #RRGGBB (got '${String(color)}').`);
+    }
+    return issues;
+}
+function branchTagOptionsIssues(prefix, branch) {
+    const raw = branch;
+    const issues = [];
+    if (raw.options !== undefined) {
+        if (branch.type === 'text') {
+            return [
+                `${prefix}options are not supported on type 'text'. `
+                    + `Use type 'tags' with options (add multiple: false for a single choice).`,
+            ];
+        }
+        if (branch.type !== 'tags') {
+            return [`${prefix}options are only supported on type 'tags' (got '${String(branch.type)}').`];
+        }
+    }
+    if (branch.type === 'tags') {
+        if (raw.multiple !== undefined && typeof raw.multiple !== 'boolean') {
+            issues.push(`${prefix}multiple must be a boolean.`);
+        }
+        if (raw.options !== undefined) {
+            if (!Array.isArray(raw.options) || raw.options.length === 0) {
+                issues.push(`${prefix}options must be a non-empty array of { value, color } objects.`);
+            }
+            else if (raw.options.length > TAG_OPTIONS_MAX_COUNT) {
+                issues.push(`${prefix}options must contain at most ${TAG_OPTIONS_MAX_COUNT} entries (got ${raw.options.length}).`);
+            }
+            else {
+                const seenValues = new Set();
+                raw.options.forEach((entry, index) => {
+                    issues.push(...optionEntryIssues(prefix, entry, index, seenValues));
+                });
+            }
+        }
+    }
+    return issues;
+}
+/**
+ * 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 function tagOptionsIssues(branch) {
+    const issues = branchTagOptionsIssues(`branch '${branch.alias}': `, branch);
+    const subFields = Array.isArray(branch.fields) ? branch.fields : [];
+    for (const sub of subFields) {
+        issues.push(...subFieldIssues(branch.alias, sub));
+    }
+    return issues;
+}
+function subFieldIssues(parentAlias, sub) {
+    const issues = branchTagOptionsIssues(`branch '${parentAlias}': sub-field '${sub.alias}': `, sub);
+    const nested = Array.isArray(sub.fields) ? sub.fields : [];
+    for (const child of nested) {
+        issues.push(...subFieldIssues(sub.alias, child));
+    }
+    return issues;
+}

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

@@ -0,0 +1,31 @@
+/** Max tags stored in one `tags` field. Tags flag small things; more than this stops being a label set. */
+export declare const TAG_MAX_COUNT = 10;
+/** Max user-perceived characters (grapheme clusters) in one tag, so one emoji or `é` counts as 1. */
+export declare const TAG_MAX_LENGTH = 25;
+/** Hard UTF-8 byte ceiling per tag: bounds stacked combining marks ("zalgo") that fit in 25 graphemes. */
+export declare const TAG_MAX_BYTES = 100;
+/** Max options a closed-vocabulary `tags` branch may declare. */
+export declare const TAG_OPTIONS_MAX_COUNT = 50;
+/** Array size accepted before cleaning, so blanks the cleaner drops do not eat the real budget. */
+export declare const TAG_RAW_MAX_COUNT = 50;
+/** Why a tag value cannot be stored. */
+export type TagValueRejection = 'ill-formed' | 'too-long';
+/** Outcome of {@link normalizeTagValue}: the canonical value (possibly `''`), or why it was rejected. */
+export type TagValueResult = {
+    readonly ok: true;
+    readonly value: string;
+} | {
+    readonly ok: false;
+    readonly reason: TagValueRejection;
+};
+/**
+ * Canonical form of one tag, the single rule shared by payload validation, seed option validation and filters:
+ * invisible and control characters removed (an emoji-gluing joiner survives), every whitespace run (tab, newline,
+ * NBSP, line separator…) collapsed to one space, trimmed, Unicode NFC. Case is preserved (`Foo` ≠ `foo`).
+ *
+ * `ok: true` with `''` means the tag was blank after cleaning: callers decide whether to drop or reject it.
+ * Rejected, never repaired: a lone UTF-16 surrogate (not valid UTF-8) and a value over
+ * {@link TAG_MAX_LENGTH} characters or {@link TAG_MAX_BYTES} bytes. Pure, never throws.
+ */
+export declare function normalizeTagValue(raw: string): TagValueResult;
+//# sourceMappingURL=tag-value.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"tag-value.d.ts","sourceRoot":"","sources":["../../../src/engine/seeds/tag-value.ts"],"names":[],"mappings":"AAKA,2GAA2G;AAC3G,eAAO,MAAM,aAAa,KAAK,CAAA;AAC/B,qGAAqG;AACrG,eAAO,MAAM,cAAc,KAAK,CAAA;AAChC,0GAA0G;AAC1G,eAAO,MAAM,aAAa,MAAM,CAAA;AAChC,iEAAiE;AACjE,eAAO,MAAM,qBAAqB,KAAK,CAAA;AACvC,mGAAmG;AACnG,eAAO,MAAM,iBAAiB,KAAK,CAAA;AAgBnC,wCAAwC;AACxC,MAAM,MAAM,iBAAiB,GAAG,YAAY,GAAG,UAAU,CAAA;AAEzD,yGAAyG;AACzG,MAAM,MAAM,cAAc,GACtB;IAAE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAC7C;IAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,iBAAiB,CAAA;CAAE,CAAA;AAM9D;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,cAAc,CAc7D"}

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

@@ -0,0 +1,51 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2024–2026 Flavio De Musso
+import { byteLength, stripControlChars } from '../validation/primitives.js';
+/** Max tags stored in one `tags` field. Tags flag small things; more than this stops being a label set. */
+export const TAG_MAX_COUNT = 10;
+/** Max user-perceived characters (grapheme clusters) in one tag, so one emoji or `é` counts as 1. */
+export const TAG_MAX_LENGTH = 25;
+/** Hard UTF-8 byte ceiling per tag: bounds stacked combining marks ("zalgo") that fit in 25 graphemes. */
+export const TAG_MAX_BYTES = 100;
+/** Max options a closed-vocabulary `tags` branch may declare. */
+export const TAG_OPTIONS_MAX_COUNT = 50;
+/** Array size accepted before cleaning, so blanks the cleaner drops do not eat the real budget. */
+export const TAG_RAW_MAX_COUNT = 50;
+/**
+ * Invisible or layout-altering code points that render as nothing but make two tags differ:
+ * C1 controls, soft hyphen, Mongolian vowel separator, zero-width space/non-joiner, LRM/RLM,
+ * bidi embeddings and isolates (spoofing), word joiner and invisible operators, BOM, and the
+ * Unicode "tag" block (invisible payloads). The zero-width joiner is handled by {@link STRAY_JOINER_RE}.
+ */
+const INVISIBLE_CHARS_RE = /[\u0080-\u009F\u00AD\u180E\u200B\u200C\u200E\u200F\u202A-\u202E\u2060-\u206F\uFEFF\u{E0000}-\u{E007F}]/gu;
+/** Zero-width joiner not gluing two emoji pictographs; between two (family, profession emoji) it is meaningful and kept. */
+const STRAY_JOINER_RE = /(?<!\p{Extended_Pictographic}\uFE0F?)\u200D|\u200D(?!\p{Extended_Pictographic})/gu;
+const LONE_SURROGATE_RE = /[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/;
+const UNICODE_WHITESPACE_RUN_RE = /\s+/g;
+const graphemeSegmenter = new Intl.Segmenter(undefined, { granularity: 'grapheme' });
+function graphemeCount(input) {
+    return [...graphemeSegmenter.segment(input)].length;
+}
+/**
+ * Canonical form of one tag, the single rule shared by payload validation, seed option validation and filters:
+ * invisible and control characters removed (an emoji-gluing joiner survives), every whitespace run (tab, newline,
+ * NBSP, line separator…) collapsed to one space, trimmed, Unicode NFC. Case is preserved (`Foo` ≠ `foo`).
+ *
+ * `ok: true` with `''` means the tag was blank after cleaning: callers decide whether to drop or reject it.
+ * Rejected, never repaired: a lone UTF-16 surrogate (not valid UTF-8) and a value over
+ * {@link TAG_MAX_LENGTH} characters or {@link TAG_MAX_BYTES} bytes. Pure, never throws.
+ */
+export function normalizeTagValue(raw) {
+    if (LONE_SURROGATE_RE.test(raw))
+        return { ok: false, reason: 'ill-formed' };
+    const value = stripControlChars(raw)
+        .replaceAll(INVISIBLE_CHARS_RE, '')
+        .replaceAll(STRAY_JOINER_RE, '')
+        .replaceAll(UNICODE_WHITESPACE_RUN_RE, ' ')
+        .trim()
+        .normalize('NFC');
+    if (byteLength(value) > TAG_MAX_BYTES || graphemeCount(value) > TAG_MAX_LENGTH) {
+        return { ok: false, reason: 'too-long' };
+    }
+    return { ok: true, value };
+}

package/dist/engine/types.d.ts

@@ -6,6 +6,7 @@
  */
 import type { FileAccept } from '../media/file-types.js';
 import type { DashboardView } from '../dashboard-layout/view-authorization.js';
+import type { LocaleConfig } from './localization/localization.js';
 /** All supported field value types for a Branch. */
 export type BranchType = 'text' | 'number' | 'boolean' | 'json' | 'date' | 'richtext' | 'file' | 'tags' | 'relation' | 'repeater';
 /** Specialized configuration for a branch of type 'number'. */
@@ -57,6 +58,16 @@ export interface ActorContext {
     userId?: string;
     role?: string;
 }
+/** One entry of a `tags` branch's closed vocabulary. Array order is significant (menu, kanban columns, sort). */
+export interface TagOption {
+    /**
+     * Stored value and identity. Unique within the branch; compared exactly (case-sensitive, never trimmed).
+     * Must already be in canonical form (`normalizeTagValue(value).value === value`) and at most `TAG_MAX_LENGTH` characters.
+     */
+    value: string;
+    /** Presentation-only color, `#RRGGBB`. Lives in the seed only — never persisted in entries. */
+    color: string;
+}
 /** Branch: definition of a single field. `alias` is the SQL column name. */
 export interface Branch {
     /**
@@ -83,16 +94,19 @@ export interface Branch {
      */
     format?: 'plain' | 'markdown' | 'html' | 'date' | 'datetime' | 'asset-list';
     /**
-     * Optional cardinality for media fields:
-     * - false/undefined: single asset (string URL)
-     * - true: asset list (string[] URL)
+     * Cardinality:
+     * - `file`: false/undefined → single URL; true → URL list.
+     * - `relation`: false/undefined → FK column; true → junction table.
+     * - `tags`: undefined/true → multiple choice (default); false → at most one value. The value is always an array.
      */
     multiple?: boolean;
     /**
-     * Predefined vocabulary for tag/select/multiselect fields.
-     * Static list defined in the Seed (not persisted to the DB).
+     * Closed vocabulary — valid ONLY on `tags` (any other type is a fatal seed error).
+     * When present: non-empty, at most `TAG_OPTIONS_MAX_COUNT` entries, unique canonical values, `#RRGGBB` colors;
+     * written values must be one of the option values.
+     * Static seed metadata, never persisted in entries.
      */
-    options?: string[];
+    options?: TagOption[];
     /** Required on create — generates NOT NULL in generateCreateTable. */
     requiredOnCreate?: boolean;
     /** Required on update. */
@@ -123,6 +137,15 @@ export interface Branch {
     numberOptions?: NumberFieldOptions;
     /** Advanced options for file fields. Ignored if type !== 'file'. */
     fileOptions?: FileFieldOptions;
+    /**
+     * Field-level localization. When true, the branch's existing column stores a locale dictionary
+     * (`{"it": "Scarpa", "en": "Shoe"}`) instead of a single value. Metadata-only: toggling it never
+     * emits DDL and never rewrites rows — values written before the toggle stay readable as-is.
+     * Valid only on top-level `text | richtext | json` branches with `plain` storage (not
+     * `confidential` / `restricted`); never on repeater sub-fields. Enforced by seed-validation.ts
+     * (Fatal 17). Default: false.
+     */
+    localized?: boolean;
     /**
      * Slug of the referenced Seed (without the `content_` prefix).
      * REQUIRED when `type === 'relation'`. Ignored otherwise.
@@ -213,6 +236,13 @@ export interface Seed {
      * Default: false.
      */
     allowDrafts?: boolean;
+    /**
+     * Enables the Trash for this content type. When true, `content_{slug}` carries a
+     * `deleted_at INTEGER NULL` column, `DELETE` becomes a reversible soft delete, and every
+     * read excludes trashed rows unless the caller opts in via `SelectOptions.trashed`.
+     * Default: false.
+     */
+    softDelete?: boolean;
     /**
      * Alias of the branch used as the entry's human-readable name (e.g. "title", "name", "author").
      * Required — UIs use it for display without heuristics.
@@ -235,7 +265,7 @@ export interface Seed {
 /** Comparison/matching operator applied by a filter condition. */
 export type FilterOperator = 'eq' | 'neq' | 'gt' | 'gte' | 'lt' | 'lte' | 'contains' | 'not_contains' | 'starts_with' | 'ends_with' | 'is_empty' | 'is_not_empty' | 'in' | 'not_in' | 'has_tag' | 'has_any_tag' | 'has_all_tags';
 /** Declared value type of a filtered column, used to normalize/coerce filter values before binding. */
-export type FilterType = 'text' | 'number' | 'date' | 'boolean' | 'tags' | 'select' | 'system' | 'json';
+export type FilterType = 'text' | 'number' | 'date' | 'boolean' | 'tags' | 'select' | 'system' | 'json' | 'repeater';
 /** A single operator + value pair applied to a FilterGroup's column. */
 export interface FilterCondition {
     /** Operator to apply. */
@@ -251,6 +281,20 @@ export interface FilterGroup {
     /** Conditions applied to this column, ANDed together. */
     conditions: FilterCondition[];
 }
+/**
+ * Soft-delete visibility for a read.
+ *  - 'active'  (default) — only rows with `deleted_at IS NULL`
+ *  - 'trashed'           — only rows with `deleted_at IS NOT NULL` (the Trash view)
+ *  - 'any'               — no predicate (restore/purge lookups, reconciliation)
+ * Ignored entirely for seeds without `softDelete: true`.
+ */
+export type TrashedMode = 'active' | 'trashed' | 'any';
+/** The language a read resolves localized branches to (consumed by `buildSelectQuery`). */
+export interface SelectLocale {
+    /** Locale that filters and ORDER BY compare in. Must match `LOCALE_CODE_RE`; the builder throws otherwise. */
+    readonly code: string;
+    readonly config: LocaleConfig;
+}
 export interface SelectOptions {
     /** Filter groups. Joined by `filterLogic` (default AND); conditions within a group are always ANDed. */
     filters?: FilterGroup[];
@@ -268,6 +312,8 @@ export interface SelectOptions {
     };
     /** Filters by status. null = no status filter. */
     status?: string | null;
+    /** Soft-delete visibility. Defaults to 'active': omitting it can never leak a trashed row. */
+    trashed?: TrashedMode;
     /** Full-text search — uses FTS5 if the seed has indexable richtext/text branches. */
     search?: string;
     /** Column projection. Empty = SELECT *. */
@@ -284,6 +330,12 @@ export interface SelectOptions {
      * while keeping the join/where clauses intact for accurate counts.
      */
     isCount?: boolean;
+    /**
+     * When set, filters and ORDER BY on localized branches compare the value resolved to `locale.code`
+     * (requested → default → first stored translation → legacy raw value) instead of the stored JSON.
+     * Absent: every column is compared raw, exactly as before localization existed.
+     */
+    locale?: SelectLocale;
 }
 /** SQL string paired with its ordered parameter bindings, ready for a D1 `.bind(...)` call. */
 export interface ParameterizedQuery {

package/dist/engine/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/engine/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/engine/types.ts"],"names":[],"mappings":"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"}

package/dist/engine/validation/cache.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cache.d.ts","sourceRoot":"","sources":["../../../src/engine/validation/cache.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AACvB,OAAO,KAAK,EAAsB,IAAI,EAAwC,MAAM,aAAa,CAAA;AAEjG,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AAgIjD;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,eAAe,GAAG,CAAC,CAAC,SAAS,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,UAAU,CAAC,CAAC,CAsCjH"}
+{"version":3,"file":"cache.d.ts","sourceRoot":"","sources":["../../../src/engine/validation/cache.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AACvB,OAAO,KAAK,EAAsB,IAAI,EAAwC,MAAM,aAAa,CAAA;AAEjG,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AA2IjD;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,eAAe,GAAG,CAAC,CAAC,SAAS,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,UAAU,CAAC,CAAC,CA+CjH"}

package/dist/engine/validation/cache.js

@@ -1,7 +1,9 @@
 // SPDX-License-Identifier: MIT
 // Copyright (c) 2024–2026 Flavio De Musso
 import { z } from 'zod';
-import { schemaForBranch } from './schema-builders.js';
+import { isSingleChoiceTags, tagOptionValues } from '../seeds/tag-options.js';
+import { isLocalizedBranch } from '../localization/localization.js';
+import { schemaForBranch, localizedSchema } from './schema-builders.js';
 /** Max entries kept per cache map before evicting the least recently used. */
 const SEED_SCHEMA_CACHE_MAX_SIZE = 150;
 /** Cache storing compiled Zod schemas for relation-free seeds. */
@@ -54,7 +56,8 @@ function buildBranchFingerprint(branch) {
         a: branch.alias,
         t: branch.type,
         f: branch.format ?? null,
-        m: branch.multiple === true,
+        m: branch.type === 'tags' ? !isSingleChoiceTags(branch) : branch.multiple === true,
+        o: branch.options ? tagOptionValues(branch) : null,
         rc: branch.requiredOnCreate === true,
         ru: branch.requiredOnUpdate === true,
         n: branch.numberOptions ?? null,
@@ -62,6 +65,7 @@ function buildBranchFingerprint(branch) {
         mi: branch.minItems ?? null,
         ma: branch.maxItems ?? null,
         sub: branch.fields?.map(buildBranchFingerprint) ?? null,
+        lo: branch.localized === true,
     };
 }
 /**
@@ -88,6 +92,9 @@ function buildCacheKey(seed, options) {
         options.allowNull ? '1' : '0',
         options.enforceRequiredFields ? '1' : '0',
         String(options.maxTextLength),
+        options.localeConfig
+            ? `${options.localeConfig.defaultLocale}>${options.localeConfig.locales.join(',')}`
+            : '-',
     ].join('|');
 }
 /**
@@ -125,8 +132,17 @@ export function compileSeedSchema(seed, options) {
     const requiredFlag = options.operation === 'create' ? 'requiredOnCreate' : 'requiredOnUpdate';
     const shape = {};
     for (const branch of seed.branches) {
-        const branchSchema = schemaForBranch(branch, options);
-        const isRequired = branch[requiredFlag] && options.enforceRequiredFields;
+        const branchLocaleConfig = options.localeConfig && isLocalizedBranch(branch) ? options.localeConfig : undefined;
+        const branchSchema = branchLocaleConfig
+            ? localizedSchema(branch, options, branchLocaleConfig)
+            : schemaForBranch(branch, options);
+        // A localized branch uses patch semantics on update (buildLocalizedPatch omits it entirely when no
+        // locale was touched), so the object schema must accept the key being absent even when required —
+        // detectMissingRequired() checks the *value* (default-locale presence/emptiness) with full patch
+        // awareness; a non-optional key here would fail the whole payload's parse and silently drop every
+        // other submitted field with it.
+        const isPatchExempt = branchLocaleConfig != null && options.operation === 'update';
+        const isRequired = branch[requiredFlag] && options.enforceRequiredFields && !isPatchExempt;
         shape[branch.alias] = isRequired ? branchSchema : branchSchema.optional();
     }
     const compiled = z.object(shape).strict();