@beechcms/core 0.9.4 → 0.9.6

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

@@ -1 +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"}
+{"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,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,MAAM,CAAA;IACV,WAAW,EAAE,MAAM,GAAG,IAAI,CAAA;IAC1B,MAAM,EAAE,MAAM,CAAA;IACd,UAAU,EAAE,MAAM,GAAG,IAAI,CAAA;CAC1B;AAED,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,WAAW,EAAE,CAAA;IACpB,KAAK,EAAE,MAAM,CAAA;CACd;AAED,6EAA6E;AAC7E,MAAM,WAAW,kBAAkB;IACjC,WAAW,CAAC,UAAU,EAAE,IAAI,GAAG,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;IACpE,UAAU,CACR,MAAM,EAAE,aAAa,EACrB,UAAU,EAAE,IAAI,EAChB,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,gBAAgB,CAAC,CAAA;CAC7B;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.d.ts

@@ -0,0 +1,23 @@
+import type { Seed, SelectOptions, ParameterizedQuery } from './types.js';
+/**
+ * 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 declare function buildSelectQuery(seed: Seed, options?: SelectOptions): ParameterizedQuery;
+//# sourceMappingURL=query.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"query.d.ts","sourceRoot":"","sources":["../../src/engine/query.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,IAAI,EAMJ,aAAa,EACb,kBAAkB,EACnB,MAAM,YAAY,CAAC;AAKpB;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,IAAI,EAAE,OAAO,GAAE,aAAkB,GAAG,kBAAkB,CAgH5F"}

package/dist/engine/query.js

@@ -0,0 +1,248 @@
+import { tableName, ftsTableName, isValidColumn, indexableSearchBranches, SYSTEM_COLUMNS } from './ddl.js';
+import { resolveClassification } from './policies.js';
+/**
+ * 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 = SYSTEM_COLUMNS.has(group.column)
+            ? `${table}.${group.column}`
+            : group.column;
+        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 = SYSTEM_COLUMNS.has(orderBy.column)
+                ? `${table}.${orderBy.column}`
+                : orderBy.column;
+            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/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/relations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"relations.d.ts","sourceRoot":"","sources":["../../src/engine/relations.ts"],"names":[],"mappings":"AAGA;;;;;;GAMG;AACH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,YAAY,CAAA;AAEtC,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/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/schema-fingerprint.d.ts

@@ -0,0 +1,71 @@
+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;
+    /** 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,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;AAuBD;;;;;;;;;;;;;;;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"}

package/dist/engine/schema-fingerprint.js

@@ -0,0 +1,95 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2024–2026 Flavio De Musso
+/**
+ * @module engine/schema-fingerprint
+ * A deterministic name for "the shape this API answers in".
+ *
+ * Computed from live seed definitions (`introspectSeedDefinitions`), embedded in generated client
+ * types at build time (sprint 3), returned on every public response as `X-Schema-Revision`
+ * (sprint 4), and compared by the client at request time (sprint 5). Both ends MUST compute it
+ * with this function — two implementations would be free to disagree, and a drift detector whose
+ * ends disagree is worse than none.
+ *
+ * What is hashed is a CONTRACT PROJECTION, not the whole seed definition: labels, hints, dashboard
+ * icons and layout cannot change a single response byte, and hashing them would fire a hard
+ * `BeechProblem` in someone else's production client over a typo fix.
+ */
+import { canonicalStringify } from '../common/canonical-json.js';
+import { resolvePolicies } from './policies.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 const SCHEMA_FINGERPRINT_VERSION = 1;
+function projectBranch(branch) {
+    const policies = resolvePolicies(branch);
+    return {
+        alias: branch.alias,
+        type: branch.type,
+        ...(branch.format !== undefined ? { format: branch.format } : {}),
+        ...(branch.multiple !== undefined ? { multiple: branch.multiple } : {}),
+        // Option order is the contract: it is the order a select renders and a union type lists.
+        ...(branch.options !== undefined ? { options: [...branch.options] } : {}),
+        requiredOnCreate: branch.requiredOnCreate ?? false,
+        requiredOnUpdate: branch.requiredOnUpdate ?? false,
+        ...(branch.targetSeed !== undefined ? { targetSeed: branch.targetSeed } : {}),
+        visibility: policies.visibility,
+        publicRead: policies.public,
+        publicEdit: policies.publicEdit,
+        ...(branch.minItems !== undefined ? { minItems: branch.minItems } : {}),
+        ...(branch.maxItems !== undefined ? { maxItems: branch.maxItems } : {}),
+        ...(branch.fields ? { fields: branch.fields.map(projectBranch) } : {}),
+    };
+}
+/**
+ * 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 function projectSchemaContract(seeds) {
+    return {
+        fingerprintVersion: SCHEMA_FINGERPRINT_VERSION,
+        seeds: [...seeds]
+            .sort((a, b) => a.slug.localeCompare(b.slug))
+            .map(seed => ({
+            slug: seed.slug,
+            displayNameAlias: seed.displayNameAlias,
+            allowDrafts: seed.allowDrafts ?? false,
+            allowPublicRead: seed.allowPublicRead ?? false,
+            allowPublicPost: seed.allowPublicPost ?? false,
+            allowPublicEdit: seed.allowPublicEdit ?? false,
+            branches: seed.branches.map(projectBranch),
+        })),
+    };
+}
+function toHex(buffer) {
+    return Array.from(new Uint8Array(buffer), byte => byte.toString(16).padStart(2, '0')).join('');
+}
+/**
+ * `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 async function computeSchemaFingerprint(seeds) {
+    const bytes = new TextEncoder().encode(canonicalStringify(projectSchemaContract(seeds)));
+    const digest = await crypto.subtle.digest('SHA-256', bytes);
+    return `v${SCHEMA_FINGERPRINT_VERSION}:${toHex(digest).slice(0, 32)}`;
+}

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

@@ -0,0 +1,26 @@
+/** Executes additive schema DDL against the live database and introspects columns.
+ *  Implemented by D1SchemaMutator in apps/api/src/shared/schema-mutator.d1.ts.
+ *  This is the ONLY sanctioned channel for runtime DDL — handlers never touch env.DB. */
+export interface ISchemaMutator {
+    /** Column names currently on a table, or null if the table does not exist. */
+    getColumns(table: string): Promise<Set<string> | null>;
+    /** Runs the given DDL statements in order as a single D1 batch.
+     *  All statements must be additive (CREATE … IF NOT EXISTS / ALTER … ADD COLUMN /
+     *  CREATE INDEX IF NOT EXISTS). Throws on the first failing statement. */
+    execDdl(statements: string[]): Promise<void>;
+    /** `DROP TABLE IF EXISTS {table}`. */
+    dropTable(table: string): Promise<void>;
+    /** `ALTER TABLE {table} DROP COLUMN {column}`. */
+    dropColumn(table: string, column: string): Promise<void>;
+    /** `ALTER TABLE {table} RENAME COLUMN {from} TO {to}`. */
+    renameColumn(table: string, from: string, to: string): Promise<void>;
+    /** Runs a multi-statement destructive batch atomically (FTS rebuild,
+     *  type-change column rebuild, full type drop). The caller assembles the
+     *  statements; the impl validates identifiers and runs them as one D1 batch. */
+    execDestructive(statements: string[]): Promise<void>;
+    /** Reads all rows from a table for the specified columns only.
+     *  Used before DROP TABLE to collect R2 keys for media cleanup.
+     *  All identifiers are validated against `^[A-Za-z0-9_]+$`. */
+    fetchRows(table: string, columns: string[]): Promise<Record<string, unknown>[]>;
+}
+//# sourceMappingURL=schema-mutator.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"schema-mutator.d.ts","sourceRoot":"","sources":["../../src/engine/schema-mutator.ts"],"names":[],"mappings":"AAGA;;yFAEyF;AACzF,MAAM,WAAW,cAAc;IAC7B,8EAA8E;IAC9E,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,GAAG,IAAI,CAAC,CAAA;IACtD;;8EAE0E;IAC1E,OAAO,CAAC,UAAU,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAS5C,sCAAsC;IACtC,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IACvC,kDAAkD;IAClD,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IACxD,0DAA0D;IAC1D,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IACpE;;oFAEgF;IAChF,eAAe,CAAC,UAAU,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAEpD;;mEAE+D;IAC/D,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC,CAAA;CAChF"}

package/dist/engine/schema-mutator.js

@@ -0,0 +1,3 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2024–2026 Flavio De Musso
+export {};

package/dist/engine/seed-ddl-destructive.d.ts

@@ -0,0 +1,40 @@
+import type { Seed, BranchType } from './types.js';
+/**
+ * Ordered DROP TABLE statements for a full hard-delete of a seed's tables.
+ * Order: junction drafts → junctions → FTS triggers → FTS table → drafts → main table.
+ * All statements use IF EXISTS (idempotent).
+ */
+export declare function generateDropTable(seed: Seed): string[];
+/**
+ * DROP COLUMN statements for a single branch (by alias).
+ * For multi-relation branches: drops the junction tables (no column on parent).
+ * For regular branches: drops from main table + drafts table (if allowDrafts).
+ * Does NOT include FTS handling — callers must prepend ftsTriggerDrops() and
+ * append planFtsRebuild() when the branch is searchable.
+ */
+export declare function generateDropColumn(seed: Seed, alias: string): string[];
+/**
+ * RENAME COLUMN statements for a branch alias change.
+ * Updates main table + drafts (if allowDrafts).
+ * Does NOT handle FTS — callers must rebuild FTS separately (SQLite auto-updates
+ * trigger bodies on RENAME but the FTS virtual-table columns keep the old name).
+ */
+export declare function generateRenameColumn(seed: Seed, fromAlias: string, toAlias: string): string[];
+/**
+ * Full FTS rebuild: drop triggers + FTS table, then recreate them, then backfill.
+ * Returns an empty array if the seed has no searchable branches.
+ * The drop steps use IF EXISTS so this is safe to call even if FTS was already dropped.
+ */
+export declare function planFtsRebuild(seed: Seed): string[];
+export interface RetypeColumnPlan {
+    statements: string[];
+    ftsRebuildNeeded: boolean;
+}
+/**
+ * Generates statements to change a branch's SQL storage type using the
+ * add-new-column / copy / drop-old / rename approach.
+ * Includes FTS rebuild statements when the branch is (or becomes) searchable.
+ * `updatedSeed` must already reflect the new type on the renamed branch.
+ */
+export declare function planRetypeColumn(seed: Seed, alias: string, newType: BranchType, updatedSeed: Seed): RetypeColumnPlan;
+//# sourceMappingURL=seed-ddl-destructive.d.ts.map

package/dist/engine/seed-ddl-destructive.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"seed-ddl-destructive.d.ts","sourceRoot":"","sources":["../../src/engine/seed-ddl-destructive.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,IAAI,EAAU,UAAU,EAAE,MAAM,YAAY,CAAA;AAkC1D;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,IAAI,GAAG,MAAM,EAAE,CAgBtD;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,CAgBtE;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,CAQ7F;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,IAAI,GAAG,MAAM,EAAE,CAiBnD;AAED,MAAM,WAAW,gBAAgB;IAC/B,UAAU,EAAE,MAAM,EAAE,CAAA;IACpB,gBAAgB,EAAE,OAAO,CAAA;CAC1B;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,IAAI,EACV,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,UAAU,EACnB,WAAW,EAAE,IAAI,GAChB,gBAAgB,CAyClB"}