@beechcms/core 0.5.0 → 0.6.0-preview.1

package/dist/validation.js

@@ -1,243 +1,225 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2024–2026 Flavio De Musso
 import { z } from 'zod';
 import { RICHTEXT_SCHEMA_VERSION, isRichtextEnvelopeV1 } from './richtext.js';
-const DEFAULT_MAX_TEXT_LENGTH = 50000;
+import { extensionFromUrl, isExtensionAccepted } from './file-types.js';
+const DEFAULT_MAX_TEXT_LENGTH = 50_000;
+const DEFAULT_FILE_MAX_SIZE = 5 * 1024 * 1024;
 const CONTROL_CHARS_REGEX = /[\u0000-\u0008\u000B\u000C\u000E-\u001F\u007F]/g;
 const DANGEROUS_TAG_REGEX = /<(script|iframe|object|embed)\b/i;
+const DANGEROUS_TAG_STRIP_REGEX = /<\/?(script|iframe|object|embed)[^>]*>/gi;
 const DANGEROUS_ATTR_REGEX = /\son[a-z]+\s*=/i;
+const DANGEROUS_HANDLER_STRIP_REGEX = /\son[a-z]+\s*=\s*(['"]).*?\1/gi;
 const DANGEROUS_PROTOCOL_REGEX = /^\s*javascript:/i;
-const DANGEROUS_RICHTEXT_NODE_TYPES = new Set(['script', 'iframe', 'object', 'embed']);
-const LINK_LIKE_RICHTEXT_ATTRS = new Set(['href', 'src']);
-const statusSchema = z.enum(['draft', 'review', 'published']);
-const finiteNumberSchema = z.number().refine(Number.isFinite, 'Expected finite number');
-const stringSchema = z.string();
-const booleanSchema = z.boolean();
-const jsonObjectOrArraySchema = z.union([z.record(z.string(), z.unknown()), z.array(z.unknown())]);
-function isAssetListBranch(branch) {
-    return branch.type === 'file' && (branch.multiple === true || branch.format === 'asset-list');
+const FORBIDDEN_RICHTEXT_NODE_TYPES = new Set(['script', 'iframe', 'object', 'embed']);
+const URL_LIKE_RICHTEXT_KEYS = new Set(['href', 'src']);
+const STATUS_VALUES = ['draft', 'review', 'published'];
+const statusSchema = z.enum(STATUS_VALUES);
+// ──────────────────────────────────────────────────────────────────────────────
+// Primitive helpers
+// ──────────────────────────────────────────────────────────────────────────────
+function stripControlChars(input) {
+    return input.replaceAll(CONTROL_CHARS_REGEX, '');
 }
-function normalizeHttpUrl(value) {
-    if (!stringSchema.safeParse(value).success) {
-        return null;
-    }
-    const cleaned = sanitizePlainString(value);
-    if (!cleaned) {
-        return null;
-    }
+function cleanString(input) {
+    return stripControlChars(input).trim();
+}
+function isPlainObject(input) {
+    return typeof input === 'object' && input !== null && !Array.isArray(input);
+}
+function tryParseJson(raw) {
     try {
-        const parsed = new URL(cleaned);
-        if (!parsed.protocol.startsWith('http')) {
-            return null;
-        }
+        return JSON.parse(raw);
     }
     catch {
-        return null;
+        return raw;
     }
-    return cleaned;
 }
-function parseJsonString(value) {
+function parseHttpUrl(input) {
+    if (typeof input !== 'string')
+        return null;
+    const cleaned = cleanString(input);
+    if (cleaned.length === 0)
+        return null;
+    let parsed;
     try {
-        return JSON.parse(value);
+        parsed = new URL(cleaned);
     }
     catch {
-        return value;
-    }
-}
-function isPlainObject(value) {
-    return typeof value === 'object' && value !== null && !Array.isArray(value);
-}
-function normalizeAssetListValue(rawValue) {
-    const input = typeof rawValue === 'string' ? parseJsonString(rawValue) : rawValue;
-    const values = Array.isArray(input) ? input : [input];
-    const normalized = [];
-    for (const item of values) {
-        if (item == null)
-            continue;
-        const directUrl = normalizeHttpUrl(item);
-        if (directUrl) {
-            normalized.push(directUrl);
-            continue;
-        }
-        if (typeof item === 'object' && !Array.isArray(item)) {
-            const nestedUrl = normalizeHttpUrl(item.url);
-            if (nestedUrl) {
-                normalized.push(nestedUrl);
-                continue;
-            }
-        }
         return null;
     }
-    return [...new Set(normalized)];
+    return parsed.protocol.startsWith('http') ? cleaned : null;
+}
+function isValidIsoDate(value) {
+    if (!/^\d{4}-\d{2}-\d{2}/.test(value))
+        return false;
+    const ts = Date.parse(value);
+    if (Number.isNaN(ts))
+        return false;
+    return new Date(ts).toISOString().startsWith(value.slice(0, 10));
 }
-function sanitizePlainString(value) {
-    return value.replaceAll(CONTROL_CHARS_REGEX, '').trim();
+// ──────────────────────────────────────────────────────────────────────────────
+// File branch helpers
+// ──────────────────────────────────────────────────────────────────────────────
+export function resolveFileOptions(branch) {
+    const opts = branch.fileOptions;
+    return {
+        accept: opts?.accept ?? 'any',
+        maxSize: opts?.maxSize ?? DEFAULT_FILE_MAX_SIZE,
+    };
 }
-function collectRichtextVisibleText(value, chunks) {
-    if (Array.isArray(value)) {
-        for (const item of value)
-            collectRichtextVisibleText(item, chunks);
-        return;
-    }
-    if (!isPlainObject(value))
-        return;
-    if (typeof value.text === 'string') {
-        chunks.push(sanitizePlainString(value.text));
-    }
-    const attrs = typeof value.attrs === 'object' && value.attrs !== null ? value.attrs : null;
-    if (attrs && typeof attrs.latex === 'string') {
-        chunks.push(sanitizePlainString(attrs.latex));
-    }
-    if (Array.isArray(value.content)) {
-        for (const nested of value.content)
-            collectRichtextVisibleText(nested, chunks);
-    }
+function isAssetListBranch(branch) {
+    return branch.type === 'file' && (branch.multiple === true || branch.format === 'asset-list');
 }
-function isRichtextDocEmpty(value) {
-    if (!isPlainObject(value))
-        return false;
-    if (isRichtextEnvelopeV1(value)) {
-        return isRichtextDocEmpty(value.doc);
+function extractUrlFromCandidate(candidate) {
+    const direct = parseHttpUrl(candidate);
+    if (direct)
+        return direct;
+    if (isPlainObject(candidate)) {
+        return parseHttpUrl(candidate.url);
     }
-    if (value.type !== 'doc')
-        return false;
-    const chunks = [];
-    collectRichtextVisibleText(value, chunks);
-    return chunks.join('').trim().length === 0;
+    return null;
 }
-function isMissingRequiredValue(value) {
-    if (value == null)
-        return true;
-    if (typeof value === 'string')
-        return sanitizePlainString(value).length === 0;
-    if (Array.isArray(value))
-        return value.length === 0;
-    if (isPlainObject(value)) {
-        if (isRichtextEnvelopeV1(value)) {
-            return isRichtextDocEmpty(value.doc);
+function collectAssetListUrls(raw) {
+    const source = typeof raw === 'string' ? tryParseJson(raw) : raw;
+    const items = Array.isArray(source) ? source : [source];
+    const seen = new Set();
+    const out = [];
+    for (const item of items) {
+        if (item === null || item === undefined)
+            continue;
+        const url = extractUrlFromCandidate(item);
+        if (!url)
+            return null;
+        if (!seen.has(url)) {
+            seen.add(url);
+            out.push(url);
         }
-        if (isRichtextDocEmpty(value))
-            return true;
-        return Object.keys(value).length === 0;
     }
-    return false;
+    return out;
 }
-function sanitizeRichtextString(value) {
-    const noControl = value.replaceAll(CONTROL_CHARS_REGEX, '');
-    const dangerous = DANGEROUS_TAG_REGEX.test(noControl) || DANGEROUS_ATTR_REGEX.test(noControl);
-    // Best-effort sanitization for Sprint 02; complete policy tracked in TODOs below.
-    const strippedTags = noControl.replaceAll(/<\/?(script|iframe|object|embed)[^>]*>/gi, '');
-    const strippedHandlers = strippedTags.replaceAll(/\son[a-z]+\s*=\s*(['"]).*?\1/gi, '');
-    const nextValue = strippedHandlers.trim();
-    return { value: nextValue, dangerous, size: nextValue.length };
-}
-function sanitizeRichtextJsonNode(value, state) {
-    if (typeof value === 'string') {
-        const cleaned = value.replaceAll(CONTROL_CHARS_REGEX, '');
+function sanitizeRichtextString(raw) {
+    const noControls = stripControlChars(raw);
+    const dangerous = DANGEROUS_TAG_REGEX.test(noControls) || DANGEROUS_ATTR_REGEX.test(noControls);
+    const noTags = noControls.replaceAll(DANGEROUS_TAG_STRIP_REGEX, '');
+    const noHandlers = noTags.replaceAll(DANGEROUS_HANDLER_STRIP_REGEX, '');
+    const finalValue = noHandlers.trim();
+    return { value: finalValue, dangerous, valid: true, size: finalValue.length };
+}
+function walkRichtextNode(node, state) {
+    if (typeof node === 'string') {
+        const cleaned = stripControlChars(node);
         if (DANGEROUS_TAG_REGEX.test(cleaned) || DANGEROUS_ATTR_REGEX.test(cleaned)) {
             state.dangerous = true;
         }
         return cleaned;
     }
-    if (Array.isArray(value)) {
-        return value.map((item) => sanitizeRichtextJsonNode(item, state));
-    }
-    if (!isPlainObject(value)) {
-        return value;
+    if (Array.isArray(node)) {
+        return node.map((child) => walkRichtextNode(child, state));
     }
-    const next = {};
-    for (const [key, rawEntry] of Object.entries(value)) {
-        const loweredKey = key.toLowerCase();
-        if (loweredKey.startsWith('on')) {
+    if (!isPlainObject(node))
+        return node;
+    const result = {};
+    for (const [key, entry] of Object.entries(node)) {
+        const lower = key.toLowerCase();
+        if (lower.startsWith('on')) {
             state.dangerous = true;
         }
-        if (loweredKey === 'type' &&
-            typeof rawEntry === 'string' &&
-            DANGEROUS_RICHTEXT_NODE_TYPES.has(rawEntry.toLowerCase())) {
-            state.dangerous = true;
+        if (lower === 'type' && typeof entry === 'string') {
+            if (FORBIDDEN_RICHTEXT_NODE_TYPES.has(entry.toLowerCase())) {
+                state.dangerous = true;
+            }
         }
-        if (LINK_LIKE_RICHTEXT_ATTRS.has(loweredKey) &&
-            typeof rawEntry === 'string' &&
-            DANGEROUS_PROTOCOL_REGEX.test(rawEntry)) {
+        if (URL_LIKE_RICHTEXT_KEYS.has(lower) && typeof entry === 'string' && DANGEROUS_PROTOCOL_REGEX.test(entry)) {
             state.dangerous = true;
         }
-        next[key] = sanitizeRichtextJsonNode(rawEntry, state);
+        result[key] = walkRichtextNode(entry, state);
     }
-    return next;
+    return result;
 }
-function sanitizeRichtextJson(value) {
+function sanitizeRichtextJson(raw) {
     const state = { dangerous: false };
-    const sanitized = sanitizeRichtextJsonNode(value, state);
-    const asObject = isPlainObject(sanitized) ? sanitized : {};
+    const cleaned = walkRichtextNode(raw, state);
+    const asObject = isPlainObject(cleaned) ? cleaned : {};
     const valid = asObject.type === 'doc';
     const serialized = JSON.stringify(asObject);
-    return {
-        value: asObject,
-        dangerous: state.dangerous,
-        valid,
-        size: serialized.length,
-    };
+    return { value: asObject, dangerous: state.dangerous, valid, size: serialized.length };
 }
-function unwrapRichtextPayload(value) {
-    if (isRichtextEnvelopeV1(value)) {
-        return { inner: value.doc, wrapAsEnvelope: true };
+function sanitizeRichtext(raw) {
+    const envelopeMode = isRichtextEnvelopeV1(raw);
+    const payload = envelopeMode ? raw.doc : raw;
+    if (typeof payload === 'string') {
+        return sanitizeRichtextString(payload);
     }
-    return { inner: value, wrapAsEnvelope: false };
-}
-function sanitizeRichtext(value) {
-    const { inner, wrapAsEnvelope } = unwrapRichtextPayload(value);
-    if (typeof inner === 'string') {
-        const sanitized = sanitizeRichtextString(inner);
-        return {
-            value: sanitized.value,
-            dangerous: sanitized.dangerous,
-            valid: true,
-            size: sanitized.size,
-        };
-    }
-    if (isPlainObject(inner)) {
-        const jsonResult = sanitizeRichtextJson(inner);
+    if (isPlainObject(payload)) {
+        const jsonResult = sanitizeRichtextJson(payload);
         if (!jsonResult.valid) {
-            return {
-                value,
-                dangerous: jsonResult.dangerous,
-                valid: false,
-                size: jsonResult.size,
-            };
+            return { value: raw, dangerous: jsonResult.dangerous, valid: false, size: jsonResult.size };
         }
-        const outValue = wrapAsEnvelope
+        const finalValue = envelopeMode
             ? { schemaVersion: RICHTEXT_SCHEMA_VERSION, doc: jsonResult.value }
             : jsonResult.value;
         return {
-            value: outValue,
+            value: finalValue,
             dangerous: jsonResult.dangerous,
             valid: true,
-            size: JSON.stringify(outValue).length,
+            size: JSON.stringify(finalValue).length,
         };
     }
-    return {
-        value,
-        dangerous: false,
-        valid: false,
-        size: 0,
-    };
+    return { value: raw, dangerous: false, valid: false, size: 0 };
 }
-function requiredAliases(seed, operation) {
-    return seed.branches
-        .filter((branch) => (operation === 'create' ? branch.requiredOnCreate : branch.requiredOnUpdate))
-        .map((branch) => branch.alias);
+function gatherRichtextText(node, sink) {
+    if (Array.isArray(node)) {
+        for (const child of node)
+            gatherRichtextText(child, sink);
+        return;
+    }
+    if (!isPlainObject(node))
+        return;
+    if (typeof node.text === 'string') {
+        sink.push(cleanString(node.text));
+    }
+    if (isPlainObject(node.attrs) && typeof node.attrs.latex === 'string') {
+        sink.push(cleanString(node.attrs.latex));
+    }
+    if (Array.isArray(node.content)) {
+        for (const child of node.content)
+            gatherRichtextText(child, sink);
+    }
 }
-function getPreprocessEmpty(allowNull) {
-    return (schema) => z.preprocess((val) => (val === '' || val === null ? (allowNull ? null : undefined) : val), schema.optional());
+function isRichtextDocEmpty(value) {
+    if (!isPlainObject(value))
+        return false;
+    if (isRichtextEnvelopeV1(value)) {
+        return isRichtextDocEmpty(value.doc);
+    }
+    if (value.type !== 'doc')
+        return false;
+    const sink = [];
+    gatherRichtextText(value, sink);
+    return sink.join('').trim().length === 0;
+}
+// ──────────────────────────────────────────────────────────────────────────────
+// Schema builders per branch type
+// ──────────────────────────────────────────────────────────────────────────────
+function withNullable(schema, allowNull) {
+    return allowNull ? z.union([schema, z.null()]) : schema;
+}
+function withEmptyPreprocessing(schema, allowNull) {
+    const fallback = allowNull ? null : undefined;
+    return z.preprocess((val) => (val === '' || val === null ? fallback : val), schema.optional());
 }
-function buildTextSchema(options, nullable) {
-    const schema = stringSchema
-        .transform((value) => sanitizePlainString(value))
+function textSchema(options, allowNull) {
+    const inner = z
+        .string()
+        .transform((value) => cleanString(value))
         .refine((value) => value.length <= options.maxTextLength, {
         message: `Expected string(max:${options.maxTextLength})`,
     });
-    return nullable ? z.union([schema, nullable]) : schema;
+    return withNullable(inner, allowNull);
 }
-function buildRichtextSchema(options, nullable) {
-    const schema = z.any().transform((value, ctx) => {
+function richtextSchema(options, allowNull) {
+    const inner = z.any().transform((value, ctx) => {
         const sanitized = sanitizeRichtext(value);
         if (!sanitized.valid) {
             ctx.addIssue({
@@ -262,182 +244,270 @@ function buildRichtextSchema(options, nullable) {
         }
         return sanitized.value;
     });
-    return nullable ? z.union([schema, nullable]) : schema;
+    return withNullable(inner, allowNull);
 }
-function buildNumberSchema(branch, allowNull, nullable) {
+function numberSchema(branch, allowNull) {
     const opts = branch.numberOptions;
-    const numSchema = z.number();
-    const refinedSchema = numSchema.superRefine((val, ctx) => {
+    const base = z.number().superRefine((val, ctx) => {
         if (!Number.isFinite(val)) {
             ctx.addIssue({ code: 'custom', message: 'Expected finite number' });
-            return z.NEVER;
+            return;
         }
         if (opts?.min !== undefined && val < opts.min) {
             ctx.addIssue({ code: 'custom', message: `Expected number(min:${opts.min})` });
-            return z.NEVER;
+            return;
         }
         if (opts?.max !== undefined && val > opts.max) {
             ctx.addIssue({ code: 'custom', message: `Expected number(max:${opts.max})` });
-            return z.NEVER;
+            return;
         }
         if (opts?.step !== undefined) {
             const step = opts.step;
-            const min = opts.min ?? 0;
-            const valDecimals = (val.toString().split('.')[1] || '').length;
-            const stepDecimals = (step.toString().split('.')[1] || '').length;
-            const decimals = Math.max(valDecimals, stepDecimals);
-            const multiplier = Math.pow(10, decimals);
-            if ((Math.round((val - min) * multiplier) % Math.round(step * multiplier)) !== 0) {
+            const origin = opts.min ?? 0;
+            const valDecimals = (val.toString().split('.')[1] ?? '').length;
+            const stepDecimals = (step.toString().split('.')[1] ?? '').length;
+            const scale = 10 ** Math.max(valDecimals, stepDecimals);
+            const offset = Math.round((val - origin) * scale);
+            const stepScaled = Math.round(step * scale);
+            if (stepScaled !== 0 && offset % stepScaled !== 0) {
                 ctx.addIssue({ code: 'custom', message: `Expected number(step:${step})` });
             }
         }
     });
-    const schema = getPreprocessEmpty(allowNull)(refinedSchema);
-    return nullable ? z.union([schema, nullable]) : schema;
+    return withNullable(withEmptyPreprocessing(base, allowNull), allowNull);
+}
+function booleanSchema(allowNull) {
+    return withNullable(withEmptyPreprocessing(z.boolean(), allowNull), allowNull);
+}
+function dateSchema(allowNull) {
+    const base = z
+        .string()
+        .transform((value) => cleanString(value))
+        .refine((value) => isValidIsoDate(value), { message: 'Expected date(ISO)' });
+    return withNullable(withEmptyPreprocessing(base, allowNull), allowNull);
 }
-function buildDateSchema(allowNull, nullable) {
-    const schema = getPreprocessEmpty(allowNull)(stringSchema
-        .transform((value) => sanitizePlainString(value))
-        .refine((value) => isIsoDateString(value), { message: 'Expected date(ISO)' }));
-    return nullable ? z.union([schema, nullable]) : schema;
+function jsonOrTagsSchema(allowNull) {
+    const base = z.union([z.record(z.string(), z.unknown()), z.array(z.unknown())]);
+    return withNullable(withEmptyPreprocessing(base, allowNull), allowNull);
+}
+function relationSchema(branch, options) {
+    const gen = options.idGenerator;
+    if (!gen) {
+        throw new Error('IIdGenerator must be provided in ValidateSeedPayloadOptions when validating seeds with relation branches. ' +
+            'Pass `idGenerator` (e.g. SystemIdGenerator) in the options object.');
+    }
+    const idSchema = z.string().refine((value) => gen.isValid(value), { message: 'Invalid relation id format' });
+    // Many-to-many: expect string[] with no duplicates
+    if (branch.multiple === true) {
+        const arraySchema = z.array(idSchema).refine((arr) => new Set(arr).size === arr.length, { message: 'Duplicate ids in multi-relation array' });
+        return options.allowNull ? z.union([arraySchema, z.null()]) : arraySchema;
+    }
+    return withNullable(idSchema, options.allowNull);
 }
-function buildFileSchema(branch, allowNull, nullable) {
+function fileSchema(branch, allowNull) {
+    const { accept } = resolveFileOptions(branch);
+    const verifyExtension = (url, ctx) => {
+        if (accept === 'any')
+            return true;
+        const ext = extensionFromUrl(url);
+        if (isExtensionAccepted(ext, accept))
+            return true;
+        ctx.addIssue({ code: 'custom', message: `Expected file(accept:${accept})` });
+        return false;
+    };
     if (isAssetListBranch(branch)) {
-        const schema = getPreprocessEmpty(allowNull)(z.any()
-            .transform((rawValue, ctx) => {
-            const normalized = normalizeAssetListValue(rawValue);
-            if (!normalized) {
+        const inner = z
+            .any()
+            .transform((raw, ctx) => {
+            const urls = collectAssetListUrls(raw);
+            if (urls === null) {
                 ctx.addIssue({ code: 'custom', message: 'Expected url-string[]' });
                 return z.NEVER;
             }
-            return normalized;
+            for (const url of urls) {
+                if (!verifyExtension(url, ctx))
+                    return z.NEVER;
+            }
+            return urls;
         })
-            .pipe(z.array(z.string().url())));
-        return nullable ? z.union([schema, nullable]) : schema;
+            .pipe(z.array(z.string().url()));
+        return withNullable(withEmptyPreprocessing(inner, allowNull), allowNull);
     }
-    const schema = getPreprocessEmpty(allowNull)(z.any()
-        .transform((rawValue, ctx) => {
-        const normalized = normalizeHttpUrl(rawValue);
-        if (!normalized) {
+    const inner = z
+        .any()
+        .transform((raw, ctx) => {
+        const url = parseHttpUrl(raw);
+        if (!url) {
             ctx.addIssue({ code: 'custom', message: 'Expected url-string' });
             return z.NEVER;
         }
-        return normalized;
+        if (!verifyExtension(url, ctx))
+            return z.NEVER;
+        return url;
     })
-        .pipe(z.string().url()));
-    return nullable ? z.union([schema, nullable]) : schema;
-}
-function buildBranchSchema(branch, options) {
-    const nullable = options.allowNull ? z.null() : null;
-    switch (branch.type) {
-        case 'text':
-            return buildTextSchema(options, nullable);
-        case 'richtext':
-            return buildRichtextSchema(options, nullable);
-        case 'number':
-            return buildNumberSchema(branch, options.allowNull, nullable);
-        case 'boolean': {
-            const schema = getPreprocessEmpty(options.allowNull)(booleanSchema);
-            return nullable ? z.union([schema, nullable]) : schema;
-        }
-        case 'date':
-            return buildDateSchema(options.allowNull, nullable);
-        case 'json':
-        case 'tags': {
-            const schema = getPreprocessEmpty(options.allowNull)(jsonObjectOrArraySchema);
-            return nullable ? z.union([schema, nullable]) : schema;
-        }
-        case 'file':
-            return buildFileSchema(branch, options.allowNull, nullable);
-        default:
-            throw new Error(`Unhandled branch type: ${branch.type}`);
+        .pipe(z.string().url());
+    return withNullable(withEmptyPreprocessing(inner, allowNull), allowNull);
+}
+const BRANCH_SCHEMA_BUILDERS = {
+    text: (_branch, options) => textSchema(options, options.allowNull),
+    richtext: (_branch, options) => richtextSchema(options, options.allowNull),
+    number: (branch, options) => numberSchema(branch, options.allowNull),
+    boolean: (_branch, options) => booleanSchema(options.allowNull),
+    date: (_branch, options) => dateSchema(options.allowNull),
+    json: (_branch, options) => jsonOrTagsSchema(options.allowNull),
+    tags: (_branch, options) => jsonOrTagsSchema(options.allowNull),
+    file: (branch, options) => fileSchema(branch, options.allowNull),
+    relation: (branch, options) => relationSchema(branch, options),
+};
+function schemaForBranch(branch, options) {
+    const builder = BRANCH_SCHEMA_BUILDERS[branch.type];
+    if (!builder) {
+        throw new Error(`Unhandled branch type: ${branch.type}`);
     }
+    return builder(branch, options);
 }
-const compiledSchemaCache = new Map();
-function seedFingerprint(seed) {
-    return JSON.stringify({
-        slug: seed.slug,
-        branches: seed.branches.map((branch) => ({
-            alias: branch.alias,
-            type: branch.type,
-            format: branch.format ?? null,
-            multiple: branch.multiple ?? false,
-            requiredOnCreate: branch.requiredOnCreate ?? false,
-            requiredOnUpdate: branch.requiredOnUpdate ?? false,
-            numberOptions: branch.numberOptions ?? null,
-        })),
-    });
+// ──────────────────────────────────────────────────────────────────────────────
+// Seed schema compilation with cache
+// ──────────────────────────────────────────────────────────────────────────────
+const seedSchemaCache = new Map();
+function buildSeedFingerprint(seed) {
+    const parts = seed.branches.map((branch) => ({
+        a: branch.alias,
+        t: branch.type,
+        f: branch.format ?? null,
+        m: branch.multiple === true,
+        rc: branch.requiredOnCreate === true,
+        ru: branch.requiredOnUpdate === true,
+        n: branch.numberOptions ?? null,
+        fi: branch.fileOptions ?? null,
+    }));
+    return JSON.stringify({ s: seed.slug, b: parts });
+}
+function buildCacheKey(seed, options) {
+    return [
+        buildSeedFingerprint(seed),
+        options.operation,
+        options.allowNull ? '1' : '0',
+        String(options.maxTextLength),
+    ].join('|');
 }
 function compileSeedSchema(seed, options) {
-    const key = JSON.stringify({
-        fingerprint: seedFingerprint(seed),
-        operation: options.operation,
-        allowNull: options.allowNull,
-        maxTextLength: options.maxTextLength,
-    });
-    const cached = compiledSchemaCache.get(key);
-    if (cached)
-        return cached;
-    const required = new Set(requiredAliases(seed, options.operation));
+    // Seeds with relation branches cannot be safely cached because the schema
+    // captures the idGenerator by closure, and different generators (e.g.
+    // SystemIdGenerator vs SequentialIdGenerator) have different isValid() semantics.
+    const hasRelation = seed.branches.some((b) => b.type === 'relation');
+    if (!hasRelation) {
+        const key = buildCacheKey(seed, options);
+        const cached = seedSchemaCache.get(key);
+        if (cached)
+            return cached;
+    }
+    const requiredFlag = options.operation === 'create' ? 'requiredOnCreate' : 'requiredOnUpdate';
     const shape = {};
     for (const branch of seed.branches) {
-        const baseSchema = buildBranchSchema(branch, options);
-        shape[branch.alias] = required.has(branch.alias) ? baseSchema : baseSchema.optional();
+        const branchSchema = schemaForBranch(branch, options);
+        shape[branch.alias] = branch[requiredFlag] ? branchSchema : branchSchema.optional();
     }
     const compiled = z.object(shape).strict();
-    compiledSchemaCache.set(key, compiled);
+    if (!hasRelation) {
+        const key = buildCacheKey(seed, options);
+        seedSchemaCache.set(key, compiled);
+    }
     return compiled;
 }
-function makeDetail(field, expected, received) {
-    let receivedType = typeof received;
-    if (received === null)
-        receivedType = 'null';
-    else if (Array.isArray(received))
-        receivedType = 'array';
-    return {
-        field,
-        expected,
-        received: receivedType,
-        message: `Field '${field}' expects type '${expected}' but received '${receivedType}'`,
-    };
-}
-function isIsoDateString(value) {
-    if (!/^\d{4}-\d{2}-\d{2}/.test(value))
-        return false;
-    const parsed = Date.parse(value);
-    if (Number.isNaN(parsed))
-        return false;
-    const d = new Date(parsed);
-    return d.toISOString().startsWith(value.substring(0, 10));
+// ──────────────────────────────────────────────────────────────────────────────
+// Required-field enforcement
+// ──────────────────────────────────────────────────────────────────────────────
+function isEffectivelyEmpty(value) {
+    if (value === null || value === undefined)
+        return true;
+    if (typeof value === 'string')
+        return cleanString(value).length === 0;
+    if (Array.isArray(value))
+        return value.length === 0;
+    if (isPlainObject(value)) {
+        if (isRichtextEnvelopeV1(value))
+            return isRichtextDocEmpty(value.doc);
+        if (isRichtextDocEmpty(value))
+            return true;
+        return Object.keys(value).length === 0;
+    }
+    return false;
 }
-function filterPayloadAliases(seed, payload) {
-    const unknownAliases = [];
+function detectMissingRequired(seed, rawPayload, filtered, parsedData, parseSucceeded, options) {
+    const missing = [];
     const details = [];
-    const allowedAliases = new Set(seed.branches.map((branch) => branch.alias));
-    const filteredPayload = {};
-    for (const [alias, rawValue] of Object.entries(payload)) {
-        if (!allowedAliases.has(alias)) {
-            unknownAliases.push(alias);
+    const op = options.operation;
+    for (const branch of seed.branches) {
+        const isRequired = op === 'create' ? branch.requiredOnCreate : branch.requiredOnUpdate;
+        if (!isRequired)
+            continue;
+        if (!Object.hasOwn(rawPayload, branch.alias)) {
+            missing.push(branch.alias);
             details.push({
-                field: alias,
-                expected: 'known-seed-alias',
-                received: 'unknown-alias',
-                message: `Field '${alias}' is not defined in seed '${seed.slug}'`,
+                field: branch.alias,
+                expected: 'required-field',
+                received: 'missing',
+                message: `Field '${branch.alias}' is required for ${op}`,
             });
             continue;
         }
-        filteredPayload[alias] = rawValue;
+        const candidate = parseSucceeded ? parsedData[branch.alias] : filtered[branch.alias];
+        if (isEffectivelyEmpty(candidate)) {
+            missing.push(branch.alias);
+            details.push({
+                field: branch.alias,
+                expected: 'required-field',
+                received: 'empty',
+                message: `Field '${branch.alias}' cannot be empty for ${op}`,
+            });
+        }
+    }
+    return { missing, details };
+}
+// ──────────────────────────────────────────────────────────────────────────────
+// Issue mapping
+// ──────────────────────────────────────────────────────────────────────────────
+function describeReceivedType(value) {
+    if (value === null)
+        return 'null';
+    if (Array.isArray(value))
+        return 'array';
+    return typeof value;
+}
+function expectedFromMessage(message) {
+    if (typeof message !== 'string')
+        return 'valid-field-value';
+    return message.startsWith('Expected ') ? message.slice('Expected '.length) : 'valid-field-value';
+}
+function splitUnknownAliases(seed, payload) {
+    const knownAliases = new Set(seed.branches.map((branch) => branch.alias));
+    const filtered = {};
+    const unknown = [];
+    const details = [];
+    for (const alias of Object.keys(payload)) {
+        if (knownAliases.has(alias)) {
+            filtered[alias] = payload[alias];
+            continue;
+        }
+        unknown.push(alias);
+        details.push({
+            field: alias,
+            expected: 'known-seed-alias',
+            received: 'unknown-alias',
+            message: `Field '${alias}' is not defined in seed '${seed.slug}'`,
+        });
     }
-    return { filteredPayload, unknownAliases, unknownDetails: details };
+    return { filtered, unknown, details };
 }
-function collectZodIssueDetails(seed, issues, filteredPayload, normalizedOptions) {
-    const unknownAliases = [];
+function processZodIssues(seed, issues, filtered, options) {
     const details = [];
-    const dangerousFields = [];
+    const unknown = [];
+    const dangerous = [];
     for (const issue of issues) {
         if (issue.code === 'unrecognized_keys') {
             for (const alias of issue.keys) {
-                unknownAliases.push(alias);
+                unknown.push(alias);
                 details.push({
                     field: alias,
                     expected: 'known-seed-alias',
@@ -447,83 +517,68 @@ function collectZodIssueDetails(seed, issues, filteredPayload, normalizedOptions
             }
             continue;
         }
-        if (issue.message === 'Required' && normalizedOptions.enforceRequiredFields) {
-            continue; // Let enforceRequiredFields logic handle it properly
-        }
-        const field = String(issue.path[0] ?? 'payload');
-        const receivedValue = filteredPayload[field];
-        const expected = typeof issue.message === 'string' && issue.message.startsWith('Expected ')
-            ? issue.message.replace('Expected ', '')
-            : 'valid-field-value';
-        if (issue.params?.dangerous === true) {
-            dangerousFields.push(field);
-        }
-        details.push(makeDetail(field, expected, receivedValue));
-    }
-    return { unknownAliases, zodDetails: details, dangerousFields };
-}
-function enforceRequiredFields(seed, payload, filteredPayload, data, isSuccess, normalizedOptions) {
-    const requiredFieldsMissing = [];
-    const details = [];
-    for (const branch of seed.branches) {
-        const isRequired = normalizedOptions.operation === 'create' ? branch.requiredOnCreate : branch.requiredOnUpdate;
-        if (!isRequired)
-            continue;
-        const hasProvidedAlias = Object.hasOwn(payload, branch.alias);
-        if (!hasProvidedAlias) {
-            requiredFieldsMissing.push(branch.alias);
-            details.push({
-                field: branch.alias,
-                expected: 'required-field',
-                received: 'missing',
-                message: `Field '${branch.alias}' is required for ${normalizedOptions.operation}`,
-            });
+        if (issue.message === 'Required' && options.enforceRequiredFields) {
             continue;
         }
-        const valueToCheck = isSuccess ? data[branch.alias] : filteredPayload[branch.alias];
-        if (isMissingRequiredValue(valueToCheck)) {
-            requiredFieldsMissing.push(branch.alias);
-            details.push({
-                field: branch.alias,
-                expected: 'required-field',
-                received: 'empty',
-                message: `Field '${branch.alias}' cannot be empty for ${normalizedOptions.operation}`,
-            });
+        const field = String(issue.path[0] ?? 'payload');
+        const params = issue.params;
+        if (params?.dangerous === true) {
+            dangerous.push(field);
         }
+        details.push({
+            field,
+            expected: expectedFromMessage(issue.message),
+            received: describeReceivedType(filtered[field]),
+            message: `Field '${field}' expects type '${expectedFromMessage(issue.message)}' but received '${describeReceivedType(filtered[field])}'`,
+        });
     }
-    return { requiredFieldsMissing, requiredDetails: details };
+    return { details, unknown, dangerous };
 }
+// ──────────────────────────────────────────────────────────────────────────────
+// Public entry points
+// ──────────────────────────────────────────────────────────────────────────────
 /**
- * Common foundation for schema-driven validation and sanitization of payloads.
- * Used by the Public API and reusable in the Botanical Engine.
- *
- * Mandatory execution order at the time of writing:
- *   validate raw → hash (privacy policy) → store
- * Hashing occurs AFTER validation, not before.
- * This ensures that the validated value is the original raw value,
- * not the digest — avoiding false failures on fields with formats (e.g., email).
+ * Schema-driven validation and sanitization of a seed payload.
+ * - Drops unknown aliases (reports them as details).
+ * - Runs branch-specific schemas to coerce / sanitize known values.
+ * - Optionally enforces required-on-create / required-on-update branches.
+ * - Never throws on malformed input — returns a structured result.
  */
 export function validateAndSanitizeSeedPayload(seed, payload, options = {}) {
-    const normalizedOptions = {
+    const resolved = {
         allowNull: options.allowNull ?? false,
         operation: options.operation ?? 'create',
         requireAtLeastOneValidField: options.requireAtLeastOneValidField ?? true,
         enforceRequiredFields: options.enforceRequiredFields ?? true,
         maxTextLength: options.maxTextLength ?? DEFAULT_MAX_TEXT_LENGTH,
+        idGenerator: options.idGenerator,
     };
-    const { filteredPayload, unknownAliases: initialUnknown, unknownDetails } = filterPayloadAliases(seed, payload);
-    const schema = compileSeedSchema(seed, normalizedOptions);
-    const parsed = schema.safeParse(filteredPayload);
-    const data = parsed.success ? { ...parsed.data } : {};
-    const { unknownAliases: zodUnknown, zodDetails, dangerousFields } = parsed.success
-        ? { unknownAliases: [], zodDetails: [], dangerousFields: [] }
-        : collectZodIssueDetails(seed, parsed.error.issues, filteredPayload, normalizedOptions);
-    const { requiredFieldsMissing, requiredDetails } = normalizedOptions.enforceRequiredFields
-        ? enforceRequiredFields(seed, payload, filteredPayload, data, parsed.success, normalizedOptions)
-        : { requiredFieldsMissing: [], requiredDetails: [] };
-    const details = [...unknownDetails, ...zodDetails, ...requiredDetails];
-    if (normalizedOptions.requireAtLeastOneValidField && Object.keys(data).length === 0) {
-        details.push({
+    const { filtered, unknown: preUnknown, details: preDetails } = splitUnknownAliases(seed, payload);
+    const schema = compileSeedSchema(seed, resolved);
+    const parsed = schema.safeParse(filtered);
+    const accumulatedDetails = [...preDetails];
+    const unknownAliases = new Set(preUnknown);
+    const dangerousFields = new Set();
+    let data = {};
+    if (parsed.success) {
+        data = { ...parsed.data };
+    }
+    else {
+        const zodOutcome = processZodIssues(seed, parsed.error.issues, filtered, resolved);
+        accumulatedDetails.push(...zodOutcome.details);
+        for (const alias of zodOutcome.unknown)
+            unknownAliases.add(alias);
+        for (const field of zodOutcome.dangerous)
+            dangerousFields.add(field);
+    }
+    let requiredFieldsMissing = [];
+    if (resolved.enforceRequiredFields) {
+        const requiredOutcome = detectMissingRequired(seed, payload, filtered, data, parsed.success, resolved);
+        requiredFieldsMissing = requiredOutcome.missing;
+        accumulatedDetails.push(...requiredOutcome.details);
+    }
+    if (resolved.requireAtLeastOneValidField && Object.keys(data).length === 0) {
+        accumulatedDetails.push({
             field: 'data',
             expected: 'at-least-one-valid-field',
             received: 'empty',
@@ -532,22 +587,16 @@ export function validateAndSanitizeSeedPayload(seed, payload, options = {}) {
     }
     return {
         data,
-        details,
-        unknownAliases: [...new Set([...initialUnknown, ...zodUnknown])],
-        dangerousFields: [...new Set(dangerousFields)],
+        details: accumulatedDetails,
+        unknownAliases: [...unknownAliases],
+        dangerousFields: [...dangerousFields],
         requiredFieldsMissing,
         hasAnyValidField: Object.keys(data).length > 0,
     };
 }
 /**
- * Validates content status supported by the CMS.
+ * Type-guard for the content status enum.
  */
 export function isValidContentStatus(value) {
     return statusSchema.safeParse(value).success;
 }
-/**
- * Full Zod runtime compiler:
- * - compile per-seed/per-operation with cache
- * - strict unknown aliases
- * - required fields by operation
- */