@beechcms/core 0.6.0-preview.4 → 0.6.1

package/dist/engine/validation/richtext-sanitizer.js

@@ -0,0 +1,203 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2024–2026 Flavio De Musso
+import { RICHTEXT_SCHEMA_VERSION, isRichtextEnvelopeV1 } from '../../content/richtext/richtext.js';
+import { stripControlChars, cleanString, isPlainObject, byteLength } from './primitives.js';
+/** Allowlisted TipTap node `type` values. Keep in sync with
+ *  richtext-render.ts::createRichTextHtmlExtensions. */
+const ALLOWED_RICHTEXT_NODE_TYPES = new Set([
+    'doc', 'paragraph', 'text', 'heading', 'blockquote', 'bulletList', 'orderedList',
+    'listItem', 'codeBlock', 'horizontalRule', 'hardBreak', 'image',
+    'table', 'tableRow', 'tableHeader', 'tableCell',
+    'inlineMath', 'blockMath', // Mathematics extension
+]);
+/** Allowlisted TipTap mark `type` values. */
+const ALLOWED_RICHTEXT_MARK_TYPES = new Set([
+    'bold', 'italic', 'strike', 'code', 'link', 'highlight',
+    'superscript', 'subscript', 'textStyle',
+]);
+/** Keys that may carry URLs inside a node/mark attrs. */
+const URL_LIKE_RICHTEXT_KEYS = new Set(['href', 'src']);
+/** Link protocols accepted AFTER normalization. Allowlist, not blocklist. */
+const ALLOWED_URL_PROTOCOLS = new Set(['http', 'https', 'mailto', 'tel']);
+/** DoS guards, evaluated before the sanitizing walk. */
+const RICHTEXT_MAX_DEPTH = 50;
+/** RichText string input is no longer accepted (JSON-only). Reject as invalid. */
+function sanitizeRichtextString(raw) {
+    return { value: raw, dangerous: false, valid: false, size: byteLength(raw) };
+}
+/** Normalizes a URL value and confirms its protocol is allowlisted.
+ *  Strips ALL whitespace + control chars first, defeating java\tscript: obfuscation. */
+function isProtocolAllowed(raw) {
+    const normalized = stripControlChars(raw).replace(/\s+/g, '').toLowerCase();
+    const schemeMatch = /^([a-z][a-z0-9+.-]*):/.exec(normalized);
+    if (!schemeMatch)
+        return true; // relative URL / anchor / fragment — no protocol
+    return ALLOWED_URL_PROTOCOLS.has(schemeMatch[1]);
+}
+/**
+ * Recursively walks a rich text node structure, removing (not just flagging) XSS threats
+ * and control characters. Returns `undefined` for nodes/attrs that must be dropped entirely.
+ *
+ * @param node - The node to walk.
+ * @param state - The shared sanitization state tracking danger flags.
+ * @returns The cleaned rich text node, or `undefined` if it must be removed.
+ */
+function walkRichtextNode(node, state) {
+    if (state.depth > RICHTEXT_MAX_DEPTH) {
+        state.dangerous = true;
+        return undefined;
+    }
+    if (typeof node === 'string')
+        return stripControlChars(node);
+    if (Array.isArray(node)) {
+        state.depth++;
+        const mapped = [];
+        for (const child of node) {
+            const walked = walkRichtextNode(child, state);
+            if (walked !== undefined)
+                mapped.push(walked);
+        }
+        state.depth--;
+        return mapped;
+    }
+    if (!isPlainObject(node))
+        return node;
+    // Node/mark type allowlist: any present `type` that isn't an allowlisted string is dropped.
+    // Objects with no `type` key (e.g. attrs bags) are not nodes and skip this check.
+    if ('type' in node) {
+        const rawType = node.type;
+        const isAllowed = typeof rawType === 'string' &&
+            (ALLOWED_RICHTEXT_NODE_TYPES.has(rawType) || ALLOWED_RICHTEXT_MARK_TYPES.has(rawType));
+        if (!isAllowed) {
+            state.dangerous = true;
+            return undefined;
+        }
+    }
+    const result = Object.create(null);
+    state.depth++;
+    for (const [key, entry] of Object.entries(node)) {
+        if (key === '__proto__' || key === 'constructor' || key === 'prototype') {
+            continue;
+        }
+        const lower = key.toLowerCase();
+        if (lower.startsWith('on')) {
+            state.dangerous = true;
+            continue; // drop event-handler attr
+        }
+        if (URL_LIKE_RICHTEXT_KEYS.has(lower) &&
+            typeof entry === 'string' &&
+            !isProtocolAllowed(entry)) {
+            state.dangerous = true;
+            continue; // drop disallowed URL
+        }
+        const walked = walkRichtextNode(entry, state);
+        if (walked !== undefined)
+            result[key] = walked;
+    }
+    state.depth--;
+    return result;
+}
+/**
+ * Sanitizes a rich text JSON document.
+ *
+ * @param raw - The raw rich text JSON object.
+ * @returns The sanitization result.
+ */
+function sanitizeRichtextJson(raw) {
+    const state = { dangerous: false, depth: 0 };
+    const cleaned = walkRichtextNode(raw, state);
+    const asObject = isPlainObject(cleaned) ? cleaned : {};
+    const valid = asObject.type === 'doc';
+    let serialized;
+    try {
+        serialized = JSON.stringify(asObject);
+    }
+    catch {
+        return { value: asObject, dangerous: state.dangerous, valid: false, size: 0 };
+    }
+    return { value: asObject, dangerous: state.dangerous, valid, size: byteLength(serialized) };
+}
+/**
+ * Main entrance helper to sanitize rich text, handling both v1 envelope formats and raw JSON payloads.
+ * String-form input is rejected (JSON-only). Byte size is fail-fast checked before the sanitizing walk.
+ *
+ * @param raw - The raw rich text input.
+ * @param maxBytes - Maximum allowed serialized size, checked before the walk.
+ * @returns The sanitization result.
+ */
+export function sanitizeRichtext(raw, maxBytes) {
+    const envelopeMode = isRichtextEnvelopeV1(raw);
+    const payload = envelopeMode ? raw.doc : raw;
+    if (typeof payload === 'string') {
+        return sanitizeRichtextString(payload);
+    }
+    if (!isPlainObject(payload)) {
+        return { value: raw, dangerous: false, valid: false, size: 0 };
+    }
+    // Fail-fast DoS pre-check: size BEFORE the sanitizing walk.
+    const rawSize = byteLength(JSON.stringify(payload));
+    if (rawSize > maxBytes) {
+        return { value: raw, dangerous: false, valid: false, size: rawSize, oversize: true };
+    }
+    const jsonResult = sanitizeRichtextJson(payload);
+    if (!jsonResult.valid) {
+        return { value: raw, dangerous: jsonResult.dangerous, valid: false, size: jsonResult.size };
+    }
+    const finalValue = envelopeMode
+        ? { schemaVersion: RICHTEXT_SCHEMA_VERSION, doc: jsonResult.value }
+        : jsonResult.value;
+    // Envelope wrapping changes the serialized bytes; reuse jsonResult.size otherwise.
+    const finalSize = envelopeMode ? byteLength(JSON.stringify(finalValue)) : jsonResult.size;
+    return {
+        value: finalValue,
+        dangerous: jsonResult.dangerous,
+        valid: true,
+        size: finalSize,
+    };
+}
+/**
+ * Gathers all text and latex strings from a rich text structure to compute if it contains content.
+ *
+ * @param node - The rich text node to inspect.
+ * @param sink - Accumulated text chunks.
+ * @param depth - Current recursion depth (guard against pathological structures).
+ */
+function gatherRichtextText(node, sink, depth = 0) {
+    if (depth > RICHTEXT_MAX_DEPTH)
+        return;
+    if (Array.isArray(node)) {
+        for (const child of node)
+            gatherRichtextText(child, sink, depth + 1);
+        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, depth + 1);
+    }
+}
+/**
+ * Checks if a rich text document is effectively empty (contains no text or LaTeX blocks).
+ *
+ * @param value - The rich text document structure.
+ * @returns True if empty, false otherwise.
+ */
+export 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;
+}

package/dist/engine/validation/schema-builders.d.ts

@@ -0,0 +1,12 @@
+import { z } from 'zod';
+import type { Branch } from '../types.js';
+import type { ResolvedOptions } from './index.js';
+/**
+ * Returns the appropriate Zod schema builder for a given branch based on its type.
+ *
+ * @param branch - The branch definition.
+ * @param options - The resolved validation options.
+ * @returns The compiled schema.
+ */
+export declare function schemaForBranch(branch: Branch, options: ResolvedOptions): z.ZodTypeAny;
+//# sourceMappingURL=schema-builders.d.ts.map

package/dist/engine/validation/schema-builders.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema-builders.d.ts","sourceRoot":"","sources":["../../../src/engine/validation/schema-builders.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AACvB,OAAO,KAAK,EAAE,MAAM,EAAc,MAAM,aAAa,CAAA;AAErD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AAmajD;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,eAAe,GAAG,CAAC,CAAC,UAAU,CAMtF"}

package/dist/engine/validation/schema-builders.js

@@ -0,0 +1,413 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2024–2026 Flavio De Musso
+import { z } from 'zod';
+import { extensionFromUrl, isExtensionAccepted } from '../../media/file-types.js';
+import { cleanString, stripControlChars, byteLength, isPlainObject } from './primitives.js';
+import { sanitizeRichtext } from './richtext-sanitizer.js';
+import { resolveFileOptions, isAssetListBranch, collectAssetListItems, extractFileCandidate } from './file-branch.js';
+/**
+ * Validates if a string is a valid ISO 8601 date.
+ *
+ * @param value - The date string to validate.
+ * @returns True if the string is a valid ISO date, false otherwise.
+ */
+function isValidIsoDate(value) {
+    if (!/^\d{4}-\d{2}-\d{2}(?:T\d{2}:\d{2}(?::\d{2}(?:\.\d+)?)?(?:Z|[+-]\d{2}(?::?\d{2})?)?)?$/.test(value)) {
+        return false;
+    }
+    const ts = Date.parse(value);
+    if (Number.isNaN(ts))
+        return false;
+    const y = parseInt(value.slice(0, 4), 10);
+    const m = parseInt(value.slice(5, 7), 10);
+    const d = parseInt(value.slice(8, 10), 10);
+    const date = new Date(Date.UTC(y, m - 1, d));
+    return (date.getUTCFullYear() === y &&
+        date.getUTCMonth() === m - 1 &&
+        date.getUTCDate() === d);
+}
+/**
+ * Wraps a Zod schema to allow null values if `allowNull` is enabled.
+ *
+ * @param schema - The base schema to wrap.
+ * @param allowNull - Whether to allow null values.
+ * @returns The wrapped union schema or the base schema.
+ */
+function withNullable(schema, allowNull) {
+    return allowNull ? z.union([schema, z.null()]) : schema;
+}
+/**
+ * Preprocesses input to convert empty strings or nulls to appropriate fallbacks.
+ *
+ * @param schema - The Zod schema to apply post-preprocessing.
+ * @param allowNull - Whether null/empty should fall back to null (true) or undefined (false).
+ * @returns The preprocessed Zod schema.
+ */
+function withEmptyPreprocessing(schema, allowNull) {
+    const fallback = allowNull ? null : undefined;
+    const wrapped = allowNull ? schema.optional().nullable() : schema.optional();
+    return z.preprocess((val) => {
+        if (val === '')
+            return fallback;
+        if (val === null)
+            return allowNull ? null : val;
+        return val;
+    }, wrapped);
+}
+/**
+ * Compiles a Zod validation schema for a text branch.
+ *
+ * @param options - The resolved validation options.
+ * @param allowNull - Whether null values are allowed.
+ * @returns The compiled text schema.
+ */
+function textSchema(options, allowNull) {
+    const inner = z
+        .string()
+        .transform((value) => cleanString(value))
+        .refine((value) => byteLength(value) <= options.maxTextLength, {
+        message: `Expected string(max:${options.maxTextLength})`,
+    });
+    return withNullable(inner, allowNull);
+}
+/**
+ * Compiles a Zod validation schema for a rich text branch, including sanitization.
+ *
+ * @param options - The resolved validation options.
+ * @param allowNull - Whether null values are allowed.
+ * @returns The compiled rich text schema.
+ */
+function richtextSchema(options, allowNull) {
+    const inner = z.any().transform((value, ctx) => {
+        const sanitized = sanitizeRichtext(value, options.maxTextLength);
+        if (!sanitized.valid) {
+            ctx.addIssue({
+                code: 'custom',
+                message: 'Expected richtext-json|string',
+                params: { expected: 'richtext-json|string' },
+            });
+        }
+        if (sanitized.oversize || sanitized.size > options.maxTextLength) {
+            ctx.addIssue({
+                code: 'custom',
+                message: `Expected richtext(max:${options.maxTextLength})`,
+                params: { expected: `richtext(max:${options.maxTextLength})` },
+            });
+        }
+        if (sanitized.dangerous) {
+            ctx.addIssue({
+                code: 'custom',
+                message: 'Dangerous richtext content',
+                params: { dangerous: true },
+            });
+        }
+        return sanitized.value;
+    });
+    return withNullable(inner, allowNull);
+}
+/** Decimal places of a number, correct for scientific notation (1e-7 → 7). */
+function decimalPlaces(n) {
+    if (!Number.isFinite(n))
+        return 0;
+    const s = n.toString();
+    if (s.includes('e') || s.includes('E')) {
+        const [mantissa, expPart] = s.toLowerCase().split('e');
+        const exp = parseInt(expPart, 10);
+        const mantDecimals = (mantissa.split('.')[1] ?? '').length;
+        return Math.max(0, mantDecimals - exp); // exp is negative for small numbers
+    }
+    return (s.split('.')[1] ?? '').length;
+}
+/**
+ * Compiles a Zod validation schema for a number branch with min/max/step checks.
+ *
+ * @param branch - The number branch definition.
+ * @param allowNull - Whether null values are allowed.
+ * @returns The compiled number schema.
+ */
+function numberSchema(branch, allowNull) {
+    const opts = branch.numberOptions;
+    const base = z.number().superRefine((val, ctx) => {
+        if (!Number.isFinite(val)) {
+            ctx.addIssue({ code: 'custom', message: 'Expected finite number' });
+            return;
+        }
+        if (opts?.min !== undefined && val < opts.min) {
+            ctx.addIssue({ code: 'custom', message: `Expected number(min:${opts.min})` });
+            return;
+        }
+        if (opts?.max !== undefined && val > opts.max) {
+            ctx.addIssue({ code: 'custom', message: `Expected number(max:${opts.max})` });
+            return;
+        }
+        if (opts?.step !== undefined) {
+            const step = opts.step;
+            const origin = opts.min ?? 0;
+            const valDecimals = decimalPlaces(val);
+            const stepDecimals = decimalPlaces(step);
+            const originDecimals = decimalPlaces(origin);
+            const scale = 10 ** Math.max(valDecimals, stepDecimals, originDecimals);
+            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})` });
+            }
+        }
+    });
+    return withEmptyPreprocessing(base, allowNull);
+}
+/**
+ * Compiles a Zod validation schema for a boolean branch.
+ *
+ * @param allowNull - Whether null values are allowed.
+ * @returns The compiled boolean schema.
+ */
+function booleanSchema(allowNull) {
+    return withEmptyPreprocessing(z.boolean(), allowNull);
+}
+/**
+ * Compiles a Zod validation schema for a date branch checking for valid ISO date format.
+ *
+ * @param allowNull - Whether null values are allowed.
+ * @returns The compiled date schema.
+ */
+function dateSchema(allowNull) {
+    const base = z
+        .string()
+        .transform((value) => cleanString(value))
+        .refine((value) => isValidIsoDate(value), { message: 'Expected date(ISO)' });
+    return withEmptyPreprocessing(base, allowNull);
+}
+/** Max nesting depth accepted when walking a `json` branch value. */
+const JSON_MAX_DEPTH = 50;
+/** Max number of items accepted in a `tags` branch array. */
+const MAX_TAGS_COUNT = 100;
+/**
+ * Recursively strips control characters from string leaves while enforcing a
+ * depth cap, mirroring the richtext sanitizer's DoS guards for arbitrary JSON.
+ *
+ * @param value - The value (or sub-value) being walked.
+ * @param depth - Current recursion depth.
+ * @returns The sanitized value, or `undefined` with `tooDeep: true` if the cap was exceeded.
+ */
+function sanitizeJsonValue(value, depth) {
+    if (depth > JSON_MAX_DEPTH)
+        return { value: undefined, tooDeep: true };
+    if (typeof value === 'string')
+        return { value: stripControlChars(value), tooDeep: false };
+    if (Array.isArray(value)) {
+        const out = [];
+        for (const item of value) {
+            const res = sanitizeJsonValue(item, depth + 1);
+            if (res.tooDeep)
+                return res;
+            out.push(res.value);
+        }
+        return { value: out, tooDeep: false };
+    }
+    if (isPlainObject(value)) {
+        const out = {};
+        for (const [k, v] of Object.entries(value)) {
+            const res = sanitizeJsonValue(v, depth + 1);
+            if (res.tooDeep)
+                return res;
+            out[k] = res.value;
+        }
+        return { value: out, tooDeep: false };
+    }
+    return { value, tooDeep: false };
+}
+/**
+ * Compiles a Zod validation schema for a `json` branch, bounding size and nesting
+ * depth like richtext, and stripping control characters from string leaves.
+ *
+ * @param options - The resolved validation options.
+ * @param allowNull - Whether null values are allowed.
+ * @returns The compiled JSON schema.
+ */
+function jsonSchema(options, allowNull) {
+    const base = z
+        .union([z.record(z.string(), z.unknown()), z.array(z.unknown())])
+        .transform((val, ctx) => {
+        // Fail-fast size check before the sanitizing walk, same order as richtext.
+        const rawSize = byteLength(JSON.stringify(val));
+        if (rawSize > options.maxTextLength) {
+            ctx.addIssue({ code: 'custom', message: `Expected json(max:${options.maxTextLength})` });
+            return z.NEVER;
+        }
+        const { value, tooDeep } = sanitizeJsonValue(val, 0);
+        if (tooDeep) {
+            ctx.addIssue({ code: 'custom', message: `Expected json(maxDepth:${JSON_MAX_DEPTH})` });
+            return z.NEVER;
+        }
+        return value;
+    });
+    return withEmptyPreprocessing(base, allowNull);
+}
+/**
+ * Compiles a Zod validation schema for a `tags` branch, constraining it to a
+ * bounded array of cleaned strings (fixes #183: previously any array/object
+ * shape passed, breaking callers like the kanban swap that cast to `string[]`).
+ *
+ * @param options - The resolved validation options.
+ * @param allowNull - Whether null values are allowed.
+ * @returns The compiled tags schema.
+ */
+function tagsSchema(options, allowNull) {
+    const tagSchema = z
+        .string()
+        .transform((value) => cleanString(value))
+        .refine((value) => byteLength(value) <= options.maxTextLength, {
+        message: `Expected string(max:${options.maxTextLength})`,
+    });
+    const base = z.array(tagSchema).max(MAX_TAGS_COUNT, {
+        message: `Expected tags(max:${MAX_TAGS_COUNT})`,
+    });
+    return withEmptyPreprocessing(base, allowNull);
+}
+/**
+ * Compiles a Zod validation schema for a relation branch, validating ID formats using an ID generator.
+ *
+ * @param branch - The relation branch definition.
+ * @param options - The resolved validation options.
+ * @returns The compiled relation schema.
+ */
+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);
+}
+/**
+ * Compiles a Zod validation schema for file or asset list branches.
+ *
+ * @param branch - The file branch definition.
+ * @param allowNull - Whether null values are allowed.
+ * @returns The compiled file schema.
+ */
+function fileSchema(branch, allowNull) {
+    const { accept, maxSize } = 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 valid-${accept}-url-with-extension` });
+        return false;
+    };
+    const verifySize = (size, ctx) => {
+        if (size === null || size <= maxSize)
+            return true;
+        ctx.addIssue({ code: 'custom', message: `Expected file(maxSize:${maxSize})` });
+        return false;
+    };
+    if (isAssetListBranch(branch)) {
+        const inner = z
+            .any()
+            .transform((raw, ctx) => {
+            const items = collectAssetListItems(raw);
+            if (items === null) {
+                ctx.addIssue({ code: 'custom', message: 'Expected valid-url-string[]' });
+                return z.NEVER;
+            }
+            for (const item of items) {
+                if (!verifyExtension(item.url, ctx))
+                    return z.NEVER;
+                if (!verifySize(item.size, ctx))
+                    return z.NEVER;
+            }
+            return items.map((item) => item.url);
+        })
+            .pipe(z.array(z.string().url()));
+        return withEmptyPreprocessing(inner, allowNull);
+    }
+    const inner = z
+        .any()
+        .transform((raw, ctx) => {
+        const candidate = extractFileCandidate(raw);
+        if (!candidate) {
+            ctx.addIssue({ code: 'custom', message: 'Expected valid-url-string' });
+            return z.NEVER;
+        }
+        if (!verifyExtension(candidate.url, ctx))
+            return z.NEVER;
+        if (!verifySize(candidate.size, ctx))
+            return z.NEVER;
+        return candidate.url;
+    })
+        .pipe(z.string().url());
+    return withEmptyPreprocessing(inner, allowNull);
+}
+/**
+ * Sub-branches of a `repeater` are restricted to leaf/scalar types — no nested
+ * `repeater`, `relation`, or `file` (v1 restriction, see types.ts Branch.fields).
+ */
+const REPEATER_DISALLOWED_SUBTYPES = new Set(['repeater', 'relation', 'file']);
+/**
+ * Compiles a Zod validation schema for repeater branches, validating arrays of items matching sub-fields.
+ *
+ * @param branch - The repeater branch definition.
+ * @param options - The resolved validation options.
+ * @returns The compiled repeater schema.
+ */
+function repeaterSchema(branch, options) {
+    const requiredFlag = options.operation === 'create' ? 'requiredOnCreate' : 'requiredOnUpdate';
+    const subBranches = (branch.fields ?? []).filter((sub) => !REPEATER_DISALLOWED_SUBTYPES.has(sub.type));
+    const shape = {};
+    for (const sub of subBranches) {
+        const subSchema = schemaForBranch(sub, options);
+        const isRequired = options.enforceRequiredFields && sub[requiredFlag];
+        shape[sub.alias] = isRequired ? subSchema : subSchema.optional();
+    }
+    // z.object() strips unknown keys by default — old item shapes from a renamed/
+    // removed sub-field are dropped rather than rejected (sprint 10 §5.1).
+    const itemSchema = z.object(shape);
+    let arraySchema = z.array(itemSchema);
+    if (Number.isInteger(branch.minItems) && branch.minItems >= 0) {
+        arraySchema = arraySchema.min(branch.minItems, {
+            message: `Expected array(min:${branch.minItems})`,
+        });
+    }
+    if (Number.isInteger(branch.maxItems) && branch.maxItems >= 0) {
+        arraySchema = arraySchema.max(branch.maxItems, {
+            message: `Expected array(max:${branch.maxItems})`,
+        });
+    }
+    return withEmptyPreprocessing(arraySchema, options.allowNull);
+}
+/** Mapping of branch types to their respective schema compilation functions. */
+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) => jsonSchema(options, options.allowNull),
+    tags: (_branch, options) => tagsSchema(options, options.allowNull),
+    file: (branch, options) => fileSchema(branch, options.allowNull),
+    relation: (branch, options) => relationSchema(branch, options),
+    repeater: (branch, options) => repeaterSchema(branch, options),
+};
+/**
+ * Returns the appropriate Zod schema builder for a given branch based on its type.
+ *
+ * @param branch - The branch definition.
+ * @param options - The resolved validation options.
+ * @returns The compiled schema.
+ */
+export 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);
+}