@beechcms/core 0.7.0 → 0.8.1

package/dist/engine/ddl/ddl.js

@@ -0,0 +1,574 @@
+import { resolvePolicies, resolveClassification } from '../privacy/policies.js';
+/**
+ * Helper function to determine if a branch requires a blind index column.
+ * Returns true if storage classification is 'encrypt' and filtering is not explicitly disabled.
+ */
+export function hasBlindIndex(branch) {
+    const resolved = resolveClassification(branch);
+    return resolved.storage === 'encrypt' && branch.policies?.filter !== false;
+}
+/**
+ * Mapping of core branch types to SQLite column types.
+ */
+const BRANCH_TYPE_SQL = {
+    text: { sqlType: 'TEXT' },
+    number: { sqlType: 'REAL' },
+    boolean: { sqlType: 'INTEGER' },
+    date: { sqlType: 'INTEGER' }, // Unix timestamp (seconds)
+    json: { sqlType: 'TEXT' }, // Serialized JSON string
+    richtext: { sqlType: 'TEXT' },
+    file: { sqlType: 'TEXT' }, // Single URL or serialized JSON array of URLs
+    tags: { sqlType: 'TEXT' }, // Serialized JSON array or object
+    relation: { sqlType: 'TEXT' }, // Foreign Key reference stored as TEXT (id of the target row)
+    repeater: { sqlType: 'TEXT' }, // Serialized JSON array of records
+};
+/**
+ * System-defined columns that exist on all content tables.
+ */
+export const SYSTEM_COLUMNS = new Set(['id', 'slug', 'status', 'created_at', 'updated_at', 'deleted_at']);
+/**
+ * Returns the SQL table name for a given Seed.
+ *
+ * @param seed The seed definition.
+ * @returns The table name.
+ */
+export function tableName(seed) {
+    return `content_${seed.slug}`;
+}
+/**
+ * Returns the draft SQL table name for a given Seed.
+ *
+ * @param seed The seed definition.
+ * @returns The draft table name.
+ */
+function draftTableName(seed) {
+    return `content_${seed.slug}_drafts`;
+}
+/**
+ * Returns the FTS (Full-Text Search) virtual table name for a given Seed.
+ *
+ * @param seed The seed definition.
+ * @returns The FTS table name.
+ */
+export function ftsTableName(seed) {
+    return `fts_${seed.slug}`;
+}
+/**
+ * Returns the vector table name for a given Seed.
+ *
+ * @param seed The seed definition.
+ * @returns The vector table name.
+ */
+export function vectorTableName(seed) {
+    return `vector_${seed.slug}`;
+}
+/**
+ * Determines whether a column is valid for a given Seed (either system column or branch alias).
+ *
+ * @param seed The seed definition.
+ * @param col The column name to check.
+ * @returns True if the column is valid, false otherwise.
+ */
+export function isValidColumn(seed, col) {
+    if (col === 'deleted_at')
+        return seed.softDelete === true;
+    if (SYSTEM_COLUMNS.has(col))
+        return true;
+    return seed.branches.some(b => b.alias === col);
+}
+/**
+ * Filters the branches of a Seed to return only the ones that are indexable for full-text search.
+ *
+ * @param seed The seed definition.
+ * @returns An array of indexable branches.
+ */
+export function indexableSearchBranches(seed) {
+    return seed.branches.filter(b => {
+        if (b.type !== 'text' && b.type !== 'richtext')
+            return false;
+        const { search, public: isPublic } = resolvePolicies(b);
+        return search && isPublic;
+    });
+}
+/**
+ * The default ON DELETE referential integrity rule for single-value relations.
+ */
+const DEFAULT_ON_DELETE_RULE = 'SET NULL';
+/**
+ * Builds the SQL foreign key clause for a single-value relation branch.
+ *
+ * Multi-relation branches (multiple: true) produce NO column on the parent table;
+ * they live in a dedicated junction table. Returns an empty string for them.
+ *
+ * @param branch The branch definition.
+ * @throws {Error} If the relation branch is missing the `targetSeed` parameter.
+ * @returns The foreign key SQL clause, or an empty string.
+ */
+function buildForeignKeyClause(branch) {
+    if (branch.type !== 'relation')
+        return '';
+    if (branch.multiple === true)
+        return '';
+    if (!branch.targetSeed) {
+        throw new Error(`Branch "${branch.alias}" is of type 'relation' but has no targetSeed`);
+    }
+    const onDeleteRule = branch.onDelete ?? DEFAULT_ON_DELETE_RULE;
+    return ` REFERENCES content_${branch.targetSeed}(id) ON DELETE ${onDeleteRule}`;
+}
+/**
+ * Generates the SQL `CREATE TABLE IF NOT EXISTS content_{slug}` statement
+ * with system columns and one column per branch.
+ *
+ * @param seed The seed definition.
+ * @returns The CREATE TABLE SQL statement.
+ */
+export function generateCreateTable(seed) {
+    const table = tableName(seed);
+    const lines = [
+        `CREATE TABLE IF NOT EXISTS ${table} (`,
+        `  id         TEXT    NOT NULL PRIMARY KEY,`,
+        // Soft-delete tables carry uniqueness in a PARTIAL unique index instead, so a trashed
+        // row stops reserving its slug. An inline UNIQUE would become a sqlite_autoindex that
+        // no ALTER TABLE can drop later.
+        seed.softDelete
+            ? `  slug       TEXT    NOT NULL,`
+            : `  slug       TEXT    NOT NULL UNIQUE,`,
+        `  status     TEXT    NOT NULL DEFAULT 'draft' CHECK (status IN ('draft', 'review', 'published', 'archived')),`,
+    ];
+    for (const branch of seed.branches) {
+        if (branch.type === 'relation' && branch.multiple === true)
+            continue;
+        const { sqlType } = BRANCH_TYPE_SQL[branch.type];
+        let col = `  ${branch.alias}  ${sqlType}`;
+        if (branch.requiredOnCreate)
+            col += ' NOT NULL';
+        if (branch.type === 'boolean')
+            col += ` CHECK (${branch.alias} IN (0, 1))`;
+        col += buildForeignKeyClause(branch);
+        lines.push(col + ',');
+        if (hasBlindIndex(branch)) {
+            lines.push(`  ${branch.alias}_bidx  TEXT,`);
+        }
+    }
+    lines.push(`  created_at INTEGER NOT NULL DEFAULT (unixepoch()),`);
+    lines.push(`  updated_at INTEGER NOT NULL DEFAULT (unixepoch())` + (seed.softDelete ? ',' : ''));
+    if (seed.softDelete)
+        lines.push(`  deleted_at INTEGER`);
+    lines.push(`);`);
+    return lines.join('\n');
+}
+/**
+ * Generates the SQL `CREATE TABLE IF NOT EXISTS content_{slug}_drafts` statement
+ * for seeds that allow drafts.
+ *
+ * @param seed The seed definition.
+ * @returns The draft table CREATE TABLE SQL statement, or null if drafts are disabled.
+ */
+export function generateDraftTable(seed) {
+    if (!seed.allowDrafts)
+        return null;
+    const table = `content_${seed.slug}_drafts`;
+    const mainTable = `content_${seed.slug}`;
+    const lines = [
+        `CREATE TABLE IF NOT EXISTS ${table} (`,
+        `  entry_id  TEXT NOT NULL PRIMARY KEY`,
+        `            REFERENCES ${mainTable}(id) ON DELETE CASCADE,`,
+    ];
+    for (const branch of seed.branches) {
+        if (branch.type === 'relation' && branch.multiple === true)
+            continue;
+        const { sqlType } = BRANCH_TYPE_SQL[branch.type];
+        let col = `  ${branch.alias}  ${sqlType}`;
+        if (branch.type === 'boolean')
+            col += ` CHECK (${branch.alias} IN (0, 1))`;
+        lines.push(col + ',');
+        if (hasBlindIndex(branch)) {
+            lines.push(`  ${branch.alias}_bidx  TEXT,`);
+        }
+    }
+    lines.push(`  _touched_fields  TEXT,`);
+    // Live-row `updated_at` as it stood when this draft was created, written once and never re-based.
+    // Nullable on purpose: drafts created before optimistic-concurrency publish existed carry NULL and
+    // publish unchecked, so enabling this feature cannot block an in-flight draft.
+    lines.push(`  live_snapshot_at  INTEGER,`);
+    lines.push(`  updated_at  INTEGER NOT NULL DEFAULT (unixepoch())`);
+    lines.push(`);`);
+    return lines.join('\n');
+}
+/**
+ * Generates the SQL `ALTER TABLE content_{slug} ADD COLUMN {alias} {type}` statement.
+ *
+ * @param seed The seed definition.
+ * @param branch The branch definition for the new column.
+ * @returns The ALTER TABLE SQL statement.
+ */
+export function generateAddColumn(seed, branch) {
+    const { sqlType } = BRANCH_TYPE_SQL[branch.type];
+    return `ALTER TABLE ${tableName(seed)} ADD COLUMN ${branch.alias} ${sqlType}${buildForeignKeyClause(branch)};`;
+}
+/**
+ * Generates the `ALTER TABLE content_{slug}_drafts ADD COLUMN live_snapshot_at INTEGER` statement
+ * for a draft table provisioned before the column existed.
+ *
+ * System column, not a branch — `generateAddColumn` iterates `seed.branches` and can never emit it.
+ * NOT idempotent: `ADD COLUMN` fails when the column is already present and `ISchemaMutator.execDdl`
+ * aborts the whole batch on the first failing statement, so the caller MUST check the physical
+ * columns first (see `planExtendSeed`).
+ *
+ * @param seed The seed definition. Caller must have verified `seed.allowDrafts`.
+ * @returns The ALTER TABLE statement.
+ */
+export function generateAddDraftSnapshotColumn(seed) {
+    return `ALTER TABLE content_${seed.slug}_drafts ADD COLUMN live_snapshot_at INTEGER;`;
+}
+/**
+ * Generates SQL index statements for system fields (status, created_at)
+ * and indexable branch columns.
+ *
+ * @param seed The seed definition.
+ * @returns An array of CREATE INDEX SQL statements.
+ */
+export function generateIndexes(seed) {
+    const table = tableName(seed);
+    const slug = seed.slug;
+    const indexes = [
+        `CREATE INDEX IF NOT EXISTS idx_${slug}_status ON ${table}(status);`,
+        `CREATE INDEX IF NOT EXISTS idx_${slug}_created_at ON ${table}(created_at);`,
+    ];
+    for (const branch of seed.branches) {
+        if (branch.type === 'relation' && branch.multiple === true)
+            continue;
+        const isRelation = branch.type === 'relation';
+        if (!isRelation && !resolvePolicies(branch).filter)
+            continue;
+        if (['text', 'number', 'date', 'boolean', 'relation'].includes(branch.type)) {
+            indexes.push(`CREATE INDEX IF NOT EXISTS idx_${slug}_${branch.alias} ON ${table}(${branch.alias});`);
+        }
+        if (hasBlindIndex(branch)) {
+            indexes.push(`CREATE INDEX IF NOT EXISTS idx_${slug}_${branch.alias}_bidx ON ${table}(${branch.alias}_bidx);`);
+        }
+    }
+    if (seed.softDelete) {
+        indexes.push(`CREATE INDEX IF NOT EXISTS idx_${slug}_deleted_at ON ${table}(deleted_at);`);
+        // Active rows only: a trashed row releases its slug for reuse (feature brief §4).
+        indexes.push(`CREATE UNIQUE INDEX IF NOT EXISTS idx_${slug}_slug_active ON ${table}(slug) WHERE deleted_at IS NULL;`);
+    }
+    return indexes;
+}
+/**
+ * Generates the FTS5 virtual table definition for indexable text/richtext branches.
+ *
+ * @param seed The seed definition.
+ * @returns The CREATE VIRTUAL TABLE SQL statement, or null if no branches are indexable.
+ */
+export function generateFtsTable(seed) {
+    const rtBranches = indexableSearchBranches(seed);
+    if (rtBranches.length === 0)
+        return null;
+    const ftsTable = ftsTableName(seed);
+    const cols = rtBranches.map(b => `  ${b.alias}`).join(',\n');
+    return [
+        `CREATE VIRTUAL TABLE IF NOT EXISTS ${ftsTable} USING fts5(`,
+        `  entry_id UNINDEXED,`,
+        `${cols},`,
+        `  tokenize = 'unicode61'`,
+        `);`,
+    ].join('\n');
+}
+/**
+ * Generates FTS5 triggers (insert, update, delete) to keep the FTS virtual table synchronized.
+ *
+ * @param seed The seed definition.
+ * @returns An array of CREATE TRIGGER SQL statements.
+ */
+export function generateFtsTriggers(seed) {
+    const rtBranches = indexableSearchBranches(seed);
+    if (rtBranches.length === 0)
+        return [];
+    const table = tableName(seed);
+    const ftsTable = ftsTableName(seed);
+    const slug = seed.slug;
+    const cols = rtBranches.map(b => b.alias);
+    const ftsColList = ['entry_id', ...cols].join(', ');
+    const newValList = ['new.id', ...cols.map(c => `new.${c}`)].join(', ');
+    return [
+        [
+            `CREATE TRIGGER IF NOT EXISTS fts_${slug}_insert`,
+            `AFTER INSERT ON ${table} BEGIN`,
+            `  INSERT INTO ${ftsTable}(${ftsColList}) VALUES (${newValList});`,
+            `END;`,
+        ].join('\n'),
+        [
+            `CREATE TRIGGER IF NOT EXISTS fts_${slug}_update`,
+            `AFTER UPDATE OF ${cols.join(', ')} ON ${table} BEGIN`,
+            `  DELETE FROM ${ftsTable} WHERE entry_id = old.id;`,
+            `  INSERT INTO ${ftsTable}(${ftsColList}) VALUES (${newValList});`,
+            `END;`,
+        ].join('\n'),
+        [
+            `CREATE TRIGGER IF NOT EXISTS fts_${slug}_delete`,
+            `AFTER DELETE ON ${table} BEGIN`,
+            `  DELETE FROM ${ftsTable} WHERE entry_id = old.id;`,
+            `END;`,
+        ].join('\n'),
+    ];
+}
+/**
+ * Generates the SQL `CREATE TABLE IF NOT EXISTS vector_{slug}` statement
+ * for indexable text/richtext branches.
+ *
+ * @param seed The seed definition.
+ * @returns The CREATE TABLE SQL statement, or null if no branches are indexable.
+ */
+export function generateVectorTable(seed) {
+    const rtBranches = indexableSearchBranches(seed);
+    if (rtBranches.length === 0)
+        return null;
+    const table = vectorTableName(seed);
+    return [
+        `CREATE TABLE IF NOT EXISTS ${table} (`,
+        `  entry_id TEXT NOT NULL PRIMARY KEY REFERENCES content_${seed.slug}(id) ON DELETE CASCADE,`,
+        `  vector   BLOB NOT NULL`,
+        `);`,
+    ].join('\n');
+}
+/**
+ * Returns the list of expected columns for a Seed's table.
+ * Used to compare current vs expected schema (diffing).
+ *
+ * @param seed The seed definition.
+ * @returns The array of expected schema columns.
+ */
+export function getExpectedColumns(seed) {
+    const branchCols = [];
+    for (const b of seed.branches) {
+        if (b.type === 'relation' && b.multiple === true)
+            continue;
+        branchCols.push({
+            name: b.alias,
+            sqlType: BRANCH_TYPE_SQL[b.type].sqlType,
+            notNull: b.requiredOnCreate ?? false,
+            isPk: false,
+        });
+        if (hasBlindIndex(b)) {
+            branchCols.push({
+                name: `${b.alias}_bidx`,
+                sqlType: 'TEXT',
+                notNull: false,
+                isPk: false,
+            });
+        }
+    }
+    return [
+        { name: 'id', sqlType: 'TEXT', notNull: true, isPk: true },
+        { name: 'slug', sqlType: 'TEXT', notNull: true, isPk: false },
+        { name: 'status', sqlType: 'TEXT', notNull: true, isPk: false },
+        ...branchCols,
+        { name: 'created_at', sqlType: 'INTEGER', notNull: true, isPk: false },
+        { name: 'updated_at', sqlType: 'INTEGER', notNull: true, isPk: false },
+        ...(seed.softDelete
+            ? [{ name: 'deleted_at', sqlType: 'INTEGER', notNull: false, isPk: false }]
+            : []),
+    ];
+}
+/**
+ * Returns the junction table name for a many-to-many relation branch.
+ * Format: `rel_<seedSlug>_<branchAlias>`.
+ *
+ * @param seedSlug The slug of the parent Seed.
+ * @param branchAlias The alias of the relation branch.
+ * @returns The junction table name.
+ */
+export function junctionTableName(seedSlug, branchAlias) {
+    return `rel_${seedSlug}_${branchAlias}`;
+}
+/**
+ * Generates `CREATE TABLE IF NOT EXISTS rel_<seed>_<alias>` statement for a multi-relation branch.
+ *
+ * @param seed The parent seed definition.
+ * @param branch The multi-relation branch definition.
+ * @throws {Error} If called on a non-multi-relation branch or if `targetSeed` is missing.
+ * @returns The CREATE TABLE SQL statement.
+ */
+export function generateJunctionTable(seed, branch) {
+    if (branch.type !== 'relation' || branch.multiple !== true) {
+        throw new Error(`Branch "${branch.alias}" is not a multi-relation`);
+    }
+    if (!branch.targetSeed) {
+        throw new Error(`Branch "${branch.alias}" has no targetSeed`);
+    }
+    const onDeleteRule = branch.onDelete ?? 'CASCADE';
+    const table = junctionTableName(seed.slug, branch.alias);
+    return [
+        `CREATE TABLE IF NOT EXISTS ${table} (`,
+        `  parent_id  TEXT NOT NULL REFERENCES content_${seed.slug}(id)    ON DELETE CASCADE,`,
+        `  target_id  TEXT NOT NULL REFERENCES content_${branch.targetSeed}(id) ON DELETE ${onDeleteRule},`,
+        `  position   INTEGER NOT NULL DEFAULT 0,`,
+        `  created_at INTEGER NOT NULL DEFAULT (unixepoch()),`,
+        `  PRIMARY KEY (parent_id, target_id)`,
+        `);`,
+    ].join('\n');
+}
+/**
+ * Generates the two B-tree indexes for a junction table:
+ * one on `parent_id` (listing entries by parent) and one on `target_id` (handling cascade checks from target side).
+ *
+ * @param seed The parent seed definition.
+ * @param branch The multi-relation branch definition.
+ * @returns An array of CREATE INDEX SQL statements.
+ */
+export function generateJunctionIndexes(seed, branch) {
+    const table = junctionTableName(seed.slug, branch.alias);
+    return [
+        `CREATE INDEX IF NOT EXISTS idx_${table}_parent ON ${table}(parent_id);`,
+        `CREATE INDEX IF NOT EXISTS idx_${table}_target ON ${table}(target_id);`,
+    ];
+}
+/**
+ * Generates the drafts junction table `rel_<seed>_<alias>_drafts` for a many-to-many relation branch.
+ *
+ * @param seed The parent seed definition.
+ * @param branch The multi-relation branch definition.
+ * @returns The CREATE TABLE SQL statement, or null if drafts are disabled.
+ */
+export function generateJunctionDraftTable(seed, branch) {
+    if (!seed.allowDrafts)
+        return null;
+    if (branch.type !== 'relation' || branch.multiple !== true)
+        return null;
+    const table = `${junctionTableName(seed.slug, branch.alias)}_drafts`;
+    const mainDraftTable = `content_${seed.slug}_drafts`;
+    return [
+        `CREATE TABLE IF NOT EXISTS ${table} (`,
+        `  entry_id   TEXT NOT NULL REFERENCES ${mainDraftTable}(entry_id) ON DELETE CASCADE,`,
+        `  target_id  TEXT NOT NULL,`,
+        `  position   INTEGER NOT NULL DEFAULT 0,`,
+        `  PRIMARY KEY (entry_id, target_id)`,
+        `);`,
+    ].join('\n');
+}
+/**
+ * Returns every `DROP TABLE IF EXISTS` needed to fully remove a content type:
+ * the main table, the drafts table (if drafts enabled), full-text search table/triggers, and junction tables.
+ *
+ * @param seed The seed definition.
+ * @returns An array of DROP TABLE / DROP TRIGGER SQL statements.
+ */
+export function generateDropTable(seed) {
+    const stmts = [];
+    for (const branch of seed.branches) {
+        if (branch.type !== 'relation' || branch.multiple !== true)
+            continue;
+        const jt = junctionTableName(seed.slug, branch.alias);
+        stmts.push(`DROP TABLE IF EXISTS ${jt}_drafts;`);
+        stmts.push(`DROP TABLE IF EXISTS ${jt};`);
+    }
+    if (seed.allowDrafts) {
+        stmts.push(`DROP TABLE IF EXISTS ${draftTableName(seed)};`);
+    }
+    if (indexableSearchBranches(seed).length > 0) {
+        const slug = seed.slug;
+        stmts.push(`DROP TRIGGER IF EXISTS fts_${slug}_insert;`);
+        stmts.push(`DROP TRIGGER IF EXISTS fts_${slug}_update;`);
+        stmts.push(`DROP TRIGGER IF EXISTS fts_${slug}_delete;`);
+        stmts.push(`DROP TABLE IF EXISTS ${ftsTableName(seed)};`);
+        stmts.push(`DROP TABLE IF EXISTS ${vectorTableName(seed)};`);
+    }
+    stmts.push(`DROP TABLE IF EXISTS ${tableName(seed)};`);
+    return stmts;
+}
+/**
+ * Returns the `DROP COLUMN` SQL statements for removing a single field.
+ * Drops the junction table for multi-relations, or alters the tables to drop the column.
+ *
+ * @param seed The seed definition.
+ * @param alias The alias of the branch to drop.
+ * @returns An array of SQL statements.
+ */
+export function generateDropColumn(seed, alias) {
+    const branch = seed.branches.find(b => b.alias === alias);
+    if (branch && branch.type === 'relation' && branch.multiple === true) {
+        const jt = junctionTableName(seed.slug, alias);
+        return [
+            `DROP TABLE IF EXISTS ${jt}_drafts;`,
+            `DROP TABLE IF EXISTS ${jt};`,
+        ];
+    }
+    const stmts = [`ALTER TABLE ${tableName(seed)} DROP COLUMN ${alias};`];
+    if (branch && seed.allowDrafts) {
+        stmts.push(`ALTER TABLE ${draftTableName(seed)} DROP COLUMN ${alias};`);
+    }
+    return stmts;
+}
+/**
+ * Returns the `RENAME COLUMN` SQL statements for renaming a field's alias.
+ * For a multi-relation branch, renames the junction table (+ drafts junction table) instead.
+ *
+ * @param seed The seed definition.
+ * @param from The old alias.
+ * @param to The new alias.
+ * @returns An array of SQL statements.
+ */
+export function generateRenameColumn(seed, from, to) {
+    const branch = seed.branches.find(b => b.alias === from);
+    if (branch && branch.type === 'relation' && branch.multiple === true) {
+        const oldJt = junctionTableName(seed.slug, from);
+        const newJt = junctionTableName(seed.slug, to);
+        const stmts = [`ALTER TABLE ${oldJt} RENAME TO ${newJt};`];
+        if (seed.allowDrafts) {
+            stmts.push(`ALTER TABLE ${oldJt}_drafts RENAME TO ${newJt}_drafts;`);
+        }
+        return stmts;
+    }
+    const stmts = [`ALTER TABLE ${tableName(seed)} RENAME COLUMN ${from} TO ${to};`];
+    if (branch && seed.allowDrafts) {
+        stmts.push(`ALTER TABLE ${draftTableName(seed)} RENAME COLUMN ${from} TO ${to};`);
+    }
+    return stmts;
+}
+/**
+ * Returns the statements that change a column's SQL type in place using CAST, bypassing SQLite rebuild limitations.
+ *
+ * @param seed The seed definition.
+ * @param branch The target branch definition (carrying the new type).
+ * @throws {Error} If called on a multi-relation branch.
+ * @returns An array of SQL statements.
+ */
+export function generateRetypeColumn(seed, branch) {
+    if (branch.type === 'relation' && branch.multiple === true) {
+        throw new Error(`Branch "${branch.alias}" is a multi-relation and has no column to retype`);
+    }
+    const { sqlType } = BRANCH_TYPE_SQL[branch.type];
+    const alias = branch.alias;
+    const tmp = `__retype_${alias}`;
+    const rebuild = (table) => [
+        `ALTER TABLE ${table} ADD COLUMN ${tmp} ${sqlType};`,
+        `UPDATE ${table} SET ${tmp} = CAST(${alias} AS ${sqlType});`,
+        `ALTER TABLE ${table} DROP COLUMN ${alias};`,
+        `ALTER TABLE ${table} RENAME COLUMN ${tmp} TO ${alias};`,
+    ];
+    const stmts = rebuild(tableName(seed));
+    if (seed.allowDrafts)
+        stmts.push(...rebuild(draftTableName(seed)));
+    return stmts;
+}
+/**
+ * Additive statements that turn soft delete on for a table that already exists.
+ *
+ * The partial unique index is emitted for correctness on tables that were CREATED with
+ * `softDelete: true`. On a pre-existing table the inline `slug … UNIQUE` survives as a
+ * sqlite_autoindex that SQLite cannot drop via ALTER; there the partial index is redundant
+ * and a trashed slug stays reserved until the table is rebuilt (see ROADMAP deferral).
+ * Returns [] when the seed does not opt in.
+ */
+export function generateEnableSoftDelete(seed) {
+    if (!seed.softDelete)
+        return [];
+    const table = tableName(seed);
+    const slug = seed.slug;
+    return [
+        `ALTER TABLE ${table} ADD COLUMN deleted_at INTEGER;`,
+        `CREATE INDEX IF NOT EXISTS idx_${slug}_deleted_at ON ${table}(deleted_at);`,
+        `CREATE UNIQUE INDEX IF NOT EXISTS idx_${slug}_slug_active ON ${table}(slug) WHERE deleted_at IS NULL;`,
+    ];
+}

package/dist/engine/ddl/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/ddl/schema-mutator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema-mutator.d.ts","sourceRoot":"","sources":["../../../src/engine/ddl/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/ddl/schema-mutator.js

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

package/dist/engine/ddl/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/ddl/seed-ddl-destructive.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"seed-ddl-destructive.d.ts","sourceRoot":"","sources":["../../../src/engine/ddl/seed-ddl-destructive.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,IAAI,EAAU,UAAU,EAAE,MAAM,aAAa,CAAA;AAkC3D;;;;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"}