@beechcms/core 0.7.0 → 0.8.1

package/dist/engine/query/query.js

@@ -0,0 +1,301 @@
+import { tableName, ftsTableName, isValidColumn, indexableSearchBranches, SYSTEM_COLUMNS } from '../ddl/ddl.js';
+import { resolveClassification } from '../privacy/policies.js';
+import { isLocaleCode, isLocalizedBranch } from '../localization/localization.js';
+/** SQLite GLOB twins of `LOCALE_CODE_RE` (`it`, `ast`, `pt-BR`, `es-419`, …). Keep both in sync. */
+const LOCALE_KEY_GLOBS = [
+    '[a-z][a-z]',
+    '[a-z][a-z][a-z]',
+    '[a-z][a-z]-[A-Z][A-Z]',
+    '[a-z][a-z][a-z]-[A-Z][A-Z]',
+    '[a-z][a-z]-[0-9][0-9][0-9]',
+    '[a-z][a-z][a-z]-[0-9][0-9][0-9]',
+];
+/** A locale code checked for inlining into SQL. The grammar check IS the injection guard — never skip it. */
+function inlineLocale(code) {
+    if (!isLocaleCode(code))
+        throw new TypeError(`Invalid locale code '${code}'`);
+    return code;
+}
+/**
+ * SQL twin of `resolveLocalizedValue`: the value of a localized column in `locale.code`. Self-contained
+ * (no bindings), because `buildFilterCondition` may interpolate a column more than once per clause.
+ * The nested CASE is deliberate: SQLite does not guarantee AND short-circuits, and `json_type` /
+ * `json_each` raise on malformed JSON (a legacy plain-text value).
+ * Dictionary detection mirrors `isStoredLocaleDictionary`: a non-empty object whose keys all match the
+ * locale grammar, and — for `json` only — at least one registered locale key.
+ */
+function localizedColumnSql(column, branch, locale) {
+    const keyIsLocale = LOCALE_KEY_GLOBS.map((glob) => `key GLOB '${glob}'`).join(' OR ');
+    const conditions = [
+        `json_type(${column}) = 'object'`,
+        `EXISTS (SELECT 1 FROM json_each(${column}))`,
+        `NOT EXISTS (SELECT 1 FROM json_each(${column}) WHERE NOT (${keyIsLocale}))`,
+    ];
+    if (branch.type === 'json') {
+        const registered = locale.config.locales.map((code) => `'${inlineLocale(code)}'`).join(', ');
+        conditions.push(`EXISTS (SELECT 1 FROM json_each(${column}) WHERE key IN (${registered}))`);
+    }
+    const path = (code) => `'$."${inlineLocale(code)}"'`;
+    const resolved = `COALESCE(` +
+        `NULLIF(json_extract(${column}, ${path(locale.code)}), ''), ` +
+        `NULLIF(json_extract(${column}, ${path(locale.config.defaultLocale)}), ''), ` +
+        `(SELECT value FROM json_each(${column}) WHERE value IS NOT NULL AND value != '' LIMIT 1))`;
+    return `(CASE WHEN json_valid(${column}) THEN ` +
+        `(CASE WHEN ${conditions.join(' AND ')} THEN ${resolved} ELSE ${column} END) ` +
+        `ELSE ${column} END)`;
+}
+/**
+ * The SQL reference for `alias` in WHERE / ORDER BY: table-qualified system column, localized expression
+ * when `locale` is set, bare alias otherwise (unchanged pre-localization behaviour).
+ */
+function columnSql(seed, table, alias, locale) {
+    if (SYSTEM_COLUMNS.has(alias))
+        return `${table}.${alias}`;
+    const branch = seed.branches.find((b) => b.alias === alias);
+    if (locale && branch && isLocalizedBranch(branch)) {
+        return localizedColumnSql(`${table}.${alias}`, branch, locale);
+    }
+    return alias;
+}
+/**
+ * Builds a parameterized SQL SELECT query and bindings for a given Seed based on search, filtering, status, and ordering options.
+ *
+ * If `options.isCount` is set to `true`, it generates a counting query (`COUNT(*) as total`) rather than returning database rows.
+ * In count mode, column projections (`fields`), ordering (`orderBy` / `kanbanOrder`), and pagination (`LIMIT` / `OFFSET`) clauses and
+ * bindings are omitted, while join and filtering clauses are preserved.
+ *
+ * @param seed The seed definition.
+ * @param options Query configuration options.
+ * @returns The SQL query string and bindings.
+ * @example
+ * ```ts
+ * const { sql, bindings } = buildSelectQuery(postSeed, {
+ *   status: 'published',
+ *   filters: [{ column: 'title', type: 'text', conditions: [{ op: 'contains', value: 'cms' }] }],
+ *   orderBy: { column: 'created_at', dir: 'DESC' },
+ *   pagination: { limit: 20, offset: 0 },
+ * })
+ * ```
+ */
+export function buildSelectQuery(seed, options = {}) {
+    const table = tableName(seed);
+    const { filters = [], orderBy, pagination, status, search, fields } = options;
+    const bindings = [];
+    const whereClauses = [];
+    let joinClause = '';
+    let kanbanOrderClause = '';
+    if (options.kanbanOrder) {
+        joinClause = `LEFT JOIN kanban_positions kp` +
+            ` ON kp.seed_slug = ? AND kp.entry_id = ${table}.id AND kp.axis_branch_id = ?`;
+        bindings.push(options.kanbanOrder.seedSlug, options.kanbanOrder.axisBranchId);
+        kanbanOrderClause = ` ORDER BY (kp.position IS NULL) ASC, kp.position ASC`;
+    }
+    const rtBranches = indexableSearchBranches(seed);
+    if (search && rtBranches.length > 0) {
+        const ftsTable = ftsTableName(seed);
+        joinClause += (joinClause ? ' ' : '') + `INNER JOIN ${ftsTable} ON ${ftsTable}.entry_id = ${table}.id`;
+        whereClauses.push(`${ftsTable} MATCH ?`);
+        bindings.push(`"${search.replace(/"/g, '""')}"*`);
+    }
+    if (status !== undefined && status !== null) {
+        whereClauses.push(`${table}.status = ?`);
+        bindings.push(status);
+    }
+    // Soft delete: 'active' is the default, so a caller that forgets the option can never
+    // observe a trashed row — including the Public API, relation expansion and subqueries,
+    // which all reach SQL only through repository.findMany.
+    if (seed.softDelete) {
+        const trashed = options.trashed ?? 'active';
+        if (trashed === 'active') {
+            whereClauses.push(`${table}.deleted_at IS NULL`);
+        }
+        else if (trashed === 'trashed') {
+            whereClauses.push(`${table}.deleted_at IS NOT NULL`);
+        }
+    }
+    const groupClauses = [];
+    for (const group of filters) {
+        if (!isValidColumn(seed, group.column))
+            continue;
+        const branch = seed.branches.find(b => b.alias === group.column);
+        const isEncrypted = branch ? resolveClassification(branch).storage === 'encrypt' : false;
+        const col = columnSql(seed, table, group.column, options.locale);
+        const condClauses = [];
+        for (const cond of group.conditions) {
+            if (isEncrypted) {
+                const { op } = cond;
+                if (op === 'eq' || op === 'neq' || op === 'in' || op === 'not_in') {
+                    const targetCol = `${table}.${group.column}_bidx`;
+                    const clause = buildFilterCondition(targetCol, group.type, cond, bindings);
+                    if (clause)
+                        condClauses.push(clause);
+                }
+                else if (op === 'is_empty' || op === 'is_not_empty') {
+                    const clause = buildFilterCondition(col, group.type, cond, bindings);
+                    if (clause)
+                        condClauses.push(clause);
+                }
+            }
+            else {
+                const clause = buildFilterCondition(col, group.type, cond, bindings);
+                if (clause)
+                    condClauses.push(clause);
+            }
+        }
+        if (condClauses.length > 0) {
+            groupClauses.push(condClauses.length > 1 ? `(${condClauses.join(' AND ')})` : condClauses[0]);
+        }
+    }
+    if (groupClauses.length > 0) {
+        const joiner = options.filterLogic === 'OR' ? ' OR ' : ' AND ';
+        whereClauses.push(groupClauses.length > 1 ? `(${groupClauses.join(joiner)})` : groupClauses[0]);
+    }
+    let selectCols = options.isCount ? 'COUNT(*) as total' : `${table}.*`;
+    if (!options.isCount && fields && fields.length > 0) {
+        const valid = fields.filter(f => isValidColumn(seed, f));
+        if (valid.length > 0) {
+            selectCols = valid
+                .map(f => (SYSTEM_COLUMNS.has(f) ? `${table}.${f}` : f))
+                .join(', ');
+        }
+    }
+    if (!options.isCount && options.kanbanOrder)
+        selectCols += ', kp.position';
+    let sql = `SELECT ${selectCols} FROM ${table}`;
+    if (joinClause)
+        sql += ` ${joinClause}`;
+    if (whereClauses.length > 0)
+        sql += ` WHERE ${whereClauses.join(' AND ')}`;
+    if (!options.isCount) {
+        if (kanbanOrderClause) {
+            sql += kanbanOrderClause;
+        }
+        else if (orderBy && isValidColumn(seed, orderBy.column)) {
+            const dir = orderBy.dir === 'DESC' ? 'DESC' : 'ASC';
+            const col = columnSql(seed, table, orderBy.column, options.locale);
+            sql += ` ORDER BY ${col} ${dir}`;
+        }
+        else {
+            sql += ` ORDER BY ${table}.created_at DESC`;
+        }
+        if (pagination) {
+            sql += ` LIMIT ? OFFSET ?`;
+            bindings.push(pagination.limit, pagination.offset);
+        }
+    }
+    return { sql, bindings };
+}
+/**
+ * Normalizes user-provided filter values to a format appropriate for SQL execution.
+ *
+ * @param type The type of the filter.
+ * @param value The value to normalize.
+ * @returns The normalized value, or null.
+ */
+function normalizeFilterValue(type, value) {
+    if (value === null || value === undefined)
+        return null;
+    if (type === 'date') {
+        if (typeof value === 'number')
+            return value;
+        if (typeof value === 'string' && value.trim() !== '') {
+            const d = new Date(value);
+            return Number.isNaN(d.getTime()) ? null : Math.floor(d.getTime() / 1000);
+        }
+        return null;
+    }
+    if (type === 'boolean') {
+        return value ? 1 : 0;
+    }
+    if (type === 'number') {
+        if (typeof value === 'number')
+            return value;
+        if (typeof value === 'string' && value.trim() !== '') {
+            const n = Number(value);
+            return Number.isNaN(n) ? null : n;
+        }
+        return null;
+    }
+    return value;
+}
+/**
+ * Translates a filter condition into its SQL clause and adds parameters to the bindings list.
+ *
+ * @param col The column name in the table.
+ * @param type The type of the filter.
+ * @param cond The condition containing the operator and value.
+ * @param bindings The array of bindings where parameterized values are appended.
+ * @returns The SQL condition fragment, or null if invalid.
+ */
+function buildFilterCondition(col, type, cond, bindings) {
+    const { op, value } = cond;
+    if (op === 'is_empty' || op === 'is_not_empty') {
+        const isEmpty = op === 'is_empty';
+        if (type === 'text') {
+            return isEmpty ? `(${col} IS NULL OR ${col} = '')` : `(${col} IS NOT NULL AND ${col} != '')`;
+        }
+        if (type === 'tags' || type === 'json') {
+            return isEmpty
+                ? `(${col} IS NULL OR ${col} = '[]' OR ${col} = '{}')`
+                : `(${col} IS NOT NULL AND ${col} != '[]' AND ${col} != '{}')`;
+        }
+        return isEmpty ? `${col} IS NULL` : `${col} IS NOT NULL`;
+    }
+    if (op === 'in' || op === 'not_in') {
+        if (!Array.isArray(value) || value.length === 0)
+            return null;
+        const normalizedValues = value
+            .map((v) => normalizeFilterValue(type, v))
+            .filter((v) => v !== null);
+        if (normalizedValues.length === 0)
+            return null;
+        const placeholders = normalizedValues.map(() => '?').join(', ');
+        bindings.push(...normalizedValues);
+        return `${col} ${op === 'in' ? 'IN' : 'NOT IN'} (${placeholders})`;
+    }
+    if (op === 'has_tag' || op === 'has_any_tag' || op === 'has_all_tags') {
+        if (type !== 'tags' && type !== 'json')
+            return null;
+        const tags = (op === 'has_tag' ? [value] : Array.isArray(value) ? value : [value])
+            .map(t => String(t));
+        if (tags.length === 0)
+            return null;
+        // json_each on array → value is the element; on object → key is the property name.
+        // Tags stored as ["photo"] (array) or {"photo":"#3b82f6"} (object) must both match.
+        const tagRef = `CASE json_type(${col}) WHEN 'array' THEN value ELSE key END`;
+        if (op === 'has_tag' || op === 'has_any_tag') {
+            const placeholders = tags.map(() => '?').join(', ');
+            bindings.push(...tags);
+            return `EXISTS (SELECT 1 FROM json_each(${col}) WHERE ${tagRef} IN (${placeholders}))`;
+        }
+        const clauses = tags.map(() => `EXISTS (SELECT 1 FROM json_each(${col}) WHERE ${tagRef} = ?)`);
+        bindings.push(...tags);
+        return `(${clauses.join(' AND ')})`;
+    }
+    const normalized = normalizeFilterValue(type, value);
+    if (normalized === null)
+        return null;
+    if (op === 'eq' || op === 'neq') {
+        const sqlOp = op === 'eq' ? '=' : '!=';
+        bindings.push(normalized);
+        return `${col} ${sqlOp} ?`;
+    }
+    if (op === 'contains' || op === 'not_contains' || op === 'starts_with' || op === 'ends_with') {
+        const sqlOp = op === 'not_contains' ? 'NOT LIKE' : 'LIKE';
+        let pattern = String(value);
+        if (op === 'contains' || op === 'not_contains')
+            pattern = `%${pattern}%`;
+        else if (op === 'starts_with')
+            pattern = `${pattern}%`;
+        else if (op === 'ends_with')
+            pattern = `%${pattern}`;
+        bindings.push(pattern);
+        return `${col} ${sqlOp} ?`;
+    }
+    const mathOps = { gt: '>', gte: '>=', lt: '<', lte: '<=' };
+    if (mathOps[op]) {
+        bindings.push(normalized);
+        return `${col} ${mathOps[op]} ?`;
+    }
+    return null;
+}

package/dist/engine/query/relations.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Back-reference helpers for the Beech CMS relation system.
+ *
+ * `buildBackrefMap` is a pure function that iterates the seed registry once
+ * and builds a lookup map: targetSlug → sources that point to it.
+ * Build this once at app factory time and cache it for the process lifetime.
+ */
+import type { Seed } from '../types.js';
+export interface BackrefSource {
+    /** Slug of the seed that owns the relation branch */
+    sourceSlug: string;
+    /** `branch.alias` — the FK column name (single) or join-table name suffix (multi) */
+    branchAlias: string;
+    /** `branch.label` — human label for UI grouping */
+    branchLabel: string;
+    /** 'single' for direct FK, 'multi' for many-to-many join table */
+    relationship: 'single' | 'multi';
+    /** True when branch.onDelete === 'RESTRICT' — used to disable Delete button */
+    restricts: boolean;
+}
+/** Map: targetSlug → every source that points to it */
+export type BackrefMap = Map<string, BackrefSource[]>;
+/**
+ * Builds the back-reference map from an array of seeds.
+ * Pure function — no side-effects, safe to call at startup and cache forever.
+ */
+export declare function buildBackrefMap(seeds: Seed[]): BackrefMap;
+//# sourceMappingURL=relations.d.ts.map

package/dist/engine/query/relations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"relations.d.ts","sourceRoot":"","sources":["../../../src/engine/query/relations.ts"],"names":[],"mappings":"AAGA;;;;;;GAMG;AACH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,aAAa,CAAA;AAEvC,MAAM,WAAW,aAAa;IAC5B,qDAAqD;IACrD,UAAU,EAAE,MAAM,CAAA;IAClB,qFAAqF;IACrF,WAAW,EAAE,MAAM,CAAA;IACnB,mDAAmD;IACnD,WAAW,EAAE,MAAM,CAAA;IACnB,kEAAkE;IAClE,YAAY,EAAE,QAAQ,GAAG,OAAO,CAAA;IAChC,+EAA+E;IAC/E,SAAS,EAAE,OAAO,CAAA;CACnB;AAED,uDAAuD;AACvD,MAAM,MAAM,UAAU,GAAG,GAAG,CAAC,MAAM,EAAE,aAAa,EAAE,CAAC,CAAA;AAErD;;;GAGG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,IAAI,EAAE,GAAG,UAAU,CAoBzD"}

package/dist/engine/query/relations.js

@@ -0,0 +1,25 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2024–2026 Flavio De Musso
+/**
+ * Builds the back-reference map from an array of seeds.
+ * Pure function — no side-effects, safe to call at startup and cache forever.
+ */
+export function buildBackrefMap(seeds) {
+    const map = new Map();
+    for (const seed of seeds) {
+        for (const branch of seed.branches) {
+            if (branch.type !== 'relation' || !branch.targetSeed)
+                continue;
+            const existing = map.get(branch.targetSeed) ?? [];
+            existing.push({
+                sourceSlug: seed.slug,
+                branchAlias: branch.alias,
+                branchLabel: branch.label,
+                relationship: branch.multiple === true ? 'multi' : 'single',
+                restricts: branch.onDelete === 'RESTRICT',
+            });
+            map.set(branch.targetSeed, existing);
+        }
+    }
+    return map;
+}

package/dist/engine/query/serialize.d.ts

@@ -0,0 +1,22 @@
+import type { Branch } from '../types.js';
+/**
+ * Serializes a value for writing to the DB.
+ * boolean → 0/1 | date → Unix timestamp | json/tags/richtext/repeater → JSON string
+ * Localized branches: locale dictionary ↔ compact JSON.
+ *
+ * @param branch The branch definition.
+ * @param value The value to serialize.
+ * @returns The serialized DB value (string, number, or null).
+ */
+export declare function serializeForDb(branch: Branch, value: unknown): string | number | null;
+/**
+ * Deserializes a value read from the DB to its API/JS representation.
+ * 0/1 → boolean | Unix timestamp → ISO 8601 | JSON string → object/array
+ * Localized branches: locale dictionary ↔ compact JSON.
+ *
+ * @param branch The branch definition.
+ * @param value The raw database value.
+ * @returns The deserialized value.
+ */
+export declare function deserializeFromDb(branch: Branch, value: unknown): unknown;
+//# sourceMappingURL=serialize.d.ts.map

package/dist/engine/query/serialize.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"serialize.d.ts","sourceRoot":"","sources":["../../../src/engine/query/serialize.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAEV,MAAM,EAOP,MAAM,aAAa,CAAC;AAoErB;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,IAAI,CA6CrF;AAGD;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,OAAO,CA0CzE"}

package/dist/engine/query/serialize.js

@@ -0,0 +1,175 @@
+import { compactLocalizedDictionary, isLocaleDictionary, isLocalizedBranch } from '../localization/localization.js';
+/**
+ * Checks if a branch represents a multiple asset list field.
+ *
+ * @param branch The branch definition.
+ * @returns True if it's an asset list, false otherwise.
+ */
+function isAssetListBranch(branch) {
+    return branch.type === 'file' && (branch.multiple === true || branch.format === 'asset-list');
+}
+/**
+ * Normalizes an unknown value to a valid HTTP URL string, or null.
+ *
+ * @param value The value to normalize.
+ * @returns The normalized URL string, or null if invalid.
+ */
+function normalizeHttpUrl(value) {
+    if (typeof value !== 'string')
+        return null;
+    const cleaned = value.trim();
+    if (!cleaned)
+        return null;
+    try {
+        const parsed = new URL(cleaned);
+        return parsed.protocol.startsWith('http') ? cleaned : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Safely parses a JSON string, falling back to the raw string on error.
+ *
+ * @param value The string to parse.
+ * @returns The parsed object, or the original string.
+ */
+function parseJsonSafe(value) {
+    try {
+        return JSON.parse(value);
+    }
+    catch {
+        return value;
+    }
+}
+/**
+ * Normalizes raw asset list values to a flat list of valid URL strings.
+ *
+ * @param rawValue The raw value (string, array, or object) to normalize.
+ * @returns An array of unique normalized URL strings.
+ */
+function normalizeAssetListValue(rawValue) {
+    const input = typeof rawValue === 'string' ? parseJsonSafe(rawValue) : rawValue;
+    const values = Array.isArray(input) ? input : [input];
+    const normalized = [];
+    for (const item of values) {
+        if (item == null)
+            continue;
+        const direct = normalizeHttpUrl(item);
+        if (direct) {
+            normalized.push(direct);
+            continue;
+        }
+        if (typeof item === 'object' && !Array.isArray(item)) {
+            const fromObj = normalizeHttpUrl(item.url);
+            if (fromObj)
+                normalized.push(fromObj);
+        }
+    }
+    return [...new Set(normalized)];
+}
+/**
+ * Serializes a value for writing to the DB.
+ * boolean → 0/1 | date → Unix timestamp | json/tags/richtext/repeater → JSON string
+ * Localized branches: locale dictionary ↔ compact JSON.
+ *
+ * @param branch The branch definition.
+ * @param value The value to serialize.
+ * @returns The serialized DB value (string, number, or null).
+ */
+export function serializeForDb(branch, value) {
+    if (value === null || value === undefined)
+        return null;
+    // Must precede the type switch: its `text` case returns null for any object, which would silently
+    // erase a dictionary on a localized text branch.
+    if (isLocalizedBranch(branch) && isLocaleDictionary(value)) {
+        const compact = compactLocalizedDictionary(value);
+        return compact === null ? null : JSON.stringify(compact);
+    }
+    switch (branch.type) {
+        case 'boolean':
+            return value ? 1 : 0;
+        case 'json':
+        case 'tags':
+        case 'richtext':
+            return typeof value === 'string' ? value : JSON.stringify(value);
+        case 'date': {
+            if (typeof value === 'number')
+                return value;
+            if (typeof value === 'string') {
+                const d = new Date(value);
+                if (Number.isNaN(d.getTime()))
+                    return null;
+                if (branch.format === 'date') {
+                    const midnight = Date.UTC(d.getUTCFullYear(), d.getUTCMonth(), d.getUTCDate());
+                    return Math.floor(midnight / 1000);
+                }
+                return Math.floor(d.getTime() / 1000);
+            }
+            return null;
+        }
+        case 'file':
+            if (isAssetListBranch(branch)) {
+                return Array.isArray(value) ? JSON.stringify(value) : typeof value === 'string' ? value : null;
+            }
+            return typeof value === 'string' ? value : null;
+        case 'repeater':
+            return JSON.stringify(Array.isArray(value) ? value : []);
+        default:
+            return typeof value === 'string' ? value : typeof value === 'number' ? value : null;
+    }
+}
+/**
+ * Deserializes a value read from the DB to its API/JS representation.
+ * 0/1 → boolean | Unix timestamp → ISO 8601 | JSON string → object/array
+ * Localized branches: locale dictionary ↔ compact JSON.
+ *
+ * @param branch The branch definition.
+ * @param value The raw database value.
+ * @returns The deserialized value.
+ */
+export function deserializeFromDb(branch, value) {
+    if (branch.type === 'repeater') {
+        if (typeof value !== 'string' || value.length === 0)
+            return [];
+        const parsed = parseJsonSafe(value);
+        return Array.isArray(parsed) ? parsed : [];
+    }
+    if (value === null || value === undefined)
+        return null;
+    // richtext/json already JSON.parse below; text must opt in. A legacy plain string written before the
+    // branch became localized is returned unchanged — the read-side fallback chain handles it.
+    if (branch.type === 'text' && isLocalizedBranch(branch) && typeof value === 'string' && value.startsWith('{')) {
+        const parsed = parseJsonSafe(value);
+        return isLocaleDictionary(parsed) ? parsed : value;
+    }
+    switch (branch.type) {
+        case 'boolean':
+            return value === 1 || value === true;
+        case 'json':
+        case 'tags':
+        case 'richtext': {
+            if (typeof value === 'string') {
+                try {
+                    return JSON.parse(value);
+                }
+                catch {
+                    return value;
+                }
+            }
+            return value;
+        }
+        case 'date': {
+            if (typeof value !== 'number')
+                return null;
+            const d = new Date(value * 1000);
+            return branch.format === 'date' ? d.toISOString().slice(0, 10) : d.toISOString();
+        }
+        case 'file':
+            if (isAssetListBranch(branch))
+                return normalizeAssetListValue(value);
+            return typeof value === 'string' ? value : null;
+        default:
+            return value;
+    }
+}

package/dist/engine/schema-fingerprint.d.ts

@@ -0,0 +1,73 @@
+import type { Branch, Seed } from './types.js';
+/**
+ * Bumped ONLY when the projection below or the canonical byte format changes — i.e. when
+ * fingerprints computed by two builds are no longer comparable. It is carried in the fingerprint
+ * string itself so a version skew reads as a mismatch instead of as an accidental match.
+ */
+export declare const SCHEMA_FINGERPRINT_VERSION = 1;
+/** The response-shape-bearing subset of a `Branch`. */
+export interface ContractBranch {
+    alias: string;
+    type: Branch['type'];
+    format?: Branch['format'];
+    multiple?: boolean;
+    options?: string[];
+    requiredOnCreate: boolean;
+    requiredOnUpdate: boolean;
+    targetSeed?: string;
+    /** From `resolvePolicies`, so an explicitly-written default hashes like an omitted one. */
+    visibility: 'full' | 'masked' | 'hidden';
+    publicRead: boolean;
+    publicEdit: boolean;
+    minItems?: number;
+    maxItems?: number;
+    /** Present only when true: the dictionary shape is part of the public contract (`?lang=all`, writes). */
+    localized?: boolean;
+    /** Repeater sub-fields, same projection, recursively. */
+    fields?: ContractBranch[];
+}
+/** The response-shape-bearing subset of a `Seed`. */
+export interface ContractSeed {
+    slug: string;
+    displayNameAlias: string;
+    allowDrafts: boolean;
+    allowPublicRead: boolean;
+    allowPublicPost: boolean;
+    allowPublicEdit: boolean;
+    branches: ContractBranch[];
+}
+/** The exact value that gets canonicalized and hashed. */
+export interface SchemaContract {
+    fingerprintVersion: number;
+    seeds: ContractSeed[];
+}
+/**
+ * Reduces seeds to what a response shape depends on.
+ *
+ * Deliberately EXCLUDED, and each for a reason a future reader must not "fix":
+ * - `id` (`br_XX`) — a stable internal handle; it never appears in a payload, and minting order
+ *   differs between an environment built by migration and one grown through the dashboard.
+ * - `label`, `labelPlural`, `hint`, `dashboard`, `layout` — presentation, never response shape.
+ * - `retentionDays`, `onDelete`, `policies.search|filter|sort`, `numberOptions`, `fileOptions`,
+ *   `policies.classification|privacy` — behaviour and storage concerns that leave the response
+ *   shape identical. (`privacy` DOES change a stored value's encoding, but the API type stays
+ *   `string`; drift there is a data concern, not a type concern.)
+ * - anything physical (column order, index names) — see the VETO Audit.
+ *
+ * Seeds are sorted by slug; BRANCH ORDER IS PRESERVED, because it is the declared field order the
+ * generated types and the dashboard form both follow.
+ */
+export declare function projectSchemaContract(seeds: Seed[]): SchemaContract;
+/**
+ * `v{VERSION}:{32 lowercase hex}` — SHA-256 over the canonical JSON of the contract projection,
+ * truncated to 128 bits.
+ *
+ * Truncation is deliberate: this value travels on EVERY public response as `X-Schema-Revision`,
+ * and 128 bits of a SHA-256 digest carries no realistic collision risk for a value space of a few
+ * hundred schema revisions. It is a revision marker, never a security token.
+ *
+ * Web Crypto only — the same API the Worker and Node ≥ 18 both expose, as `webhook-crypto.ts`
+ * already relies on. `@beechcms/core` gains no dependency.
+ */
+export declare function computeSchemaFingerprint(seeds: Seed[]): Promise<string>;
+//# sourceMappingURL=schema-fingerprint.d.ts.map

package/dist/engine/schema-fingerprint.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema-fingerprint.d.ts","sourceRoot":"","sources":["../../src/engine/schema-fingerprint.ts"],"names":[],"mappings":"AAoBA,OAAO,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,YAAY,CAAA;AAE9C;;;;GAIG;AACH,eAAO,MAAM,0BAA0B,IAAI,CAAA;AAE3C,uDAAuD;AACvD,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,MAAM,CAAA;IACb,IAAI,EAAE,MAAM,CAAC,MAAM,CAAC,CAAA;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC,QAAQ,CAAC,CAAA;IACzB,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,OAAO,CAAC,EAAE,MAAM,EAAE,CAAA;IAClB,gBAAgB,EAAE,OAAO,CAAA;IACzB,gBAAgB,EAAE,OAAO,CAAA;IACzB,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,2FAA2F;IAC3F,UAAU,EAAE,MAAM,GAAG,QAAQ,GAAG,QAAQ,CAAA;IACxC,UAAU,EAAE,OAAO,CAAA;IACnB,UAAU,EAAE,OAAO,CAAA;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,yGAAyG;IACzG,SAAS,CAAC,EAAE,OAAO,CAAA;IACnB,yDAAyD;IACzD,MAAM,CAAC,EAAE,cAAc,EAAE,CAAA;CAC1B;AAED,qDAAqD;AACrD,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAA;IACZ,gBAAgB,EAAE,MAAM,CAAA;IACxB,WAAW,EAAE,OAAO,CAAA;IACpB,eAAe,EAAE,OAAO,CAAA;IACxB,eAAe,EAAE,OAAO,CAAA;IACxB,eAAe,EAAE,OAAO,CAAA;IACxB,QAAQ,EAAE,cAAc,EAAE,CAAA;CAC3B;AAED,0DAA0D;AAC1D,MAAM,WAAW,cAAc;IAC7B,kBAAkB,EAAE,MAAM,CAAA;IAC1B,KAAK,EAAE,YAAY,EAAE,CAAA;CACtB;AAyBD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,IAAI,EAAE,GAAG,cAAc,CAenE;AAMD;;;;;;;;;;GAUG;AACH,wBAAsB,wBAAwB,CAAC,KAAK,EAAE,IAAI,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAI7E"}