@beechcms/core 0.8.0 → 0.9.0

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"}

package/dist/engine/ddl/seed-ddl-destructive.js

@@ -0,0 +1,149 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2024–2026 Flavio De Musso
+import { junctionTableName, generateFtsTable, generateFtsTriggers } from './ddl.js';
+const BRANCH_SQL_TYPE = {
+    text: 'TEXT',
+    number: 'REAL',
+    boolean: 'INTEGER',
+    date: 'INTEGER',
+    json: 'TEXT',
+    richtext: 'TEXT',
+    file: 'TEXT',
+    tags: 'TEXT',
+    relation: 'TEXT',
+    repeater: 'TEXT',
+};
+/** Branch types that receive a B-tree index in generateIndexes (used by retype to drop/recreate). */
+const INDEXABLE_TYPES = new Set(['text', 'number', 'date', 'boolean', 'relation']);
+function searchBranches(seed) {
+    return seed.branches.filter(b => (b.type === 'text' || b.type === 'richtext') && b.policies?.search !== false);
+}
+function ftsTriggerDrops(slug) {
+    return [
+        `DROP TRIGGER IF EXISTS fts_${slug}_insert;`,
+        `DROP TRIGGER IF EXISTS fts_${slug}_update;`,
+        `DROP TRIGGER IF EXISTS fts_${slug}_delete;`,
+        `DROP TABLE IF EXISTS fts_${slug};`,
+    ];
+}
+/**
+ * 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 function generateDropTable(seed) {
+    const stmts = [];
+    const { slug } = seed;
+    for (const branch of seed.branches) {
+        if (branch.type !== 'relation' || branch.multiple !== true)
+            continue;
+        const jt = junctionTableName(slug, branch.alias);
+        stmts.push(`DROP TABLE IF EXISTS ${jt}_drafts;`);
+        stmts.push(`DROP TABLE IF EXISTS ${jt};`);
+    }
+    stmts.push(...ftsTriggerDrops(slug));
+    stmts.push(`DROP TABLE IF EXISTS content_${slug}_drafts;`);
+    stmts.push(`DROP TABLE IF EXISTS content_${slug};`);
+    return stmts;
+}
+/**
+ * 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 function generateDropColumn(seed, alias) {
+    const stmts = [];
+    const { slug } = seed;
+    const branch = seed.branches.find(b => b.alias === alias);
+    if (!branch)
+        throw new Error(`Branch '${alias}' not found in seed '${slug}'`);
+    if (branch.type === 'relation' && branch.multiple === true) {
+        const jt = junctionTableName(slug, alias);
+        if (seed.allowDrafts)
+            stmts.push(`DROP TABLE IF EXISTS ${jt}_drafts;`);
+        stmts.push(`DROP TABLE IF EXISTS ${jt};`);
+    }
+    else {
+        stmts.push(`ALTER TABLE content_${slug} DROP COLUMN ${alias};`);
+        if (seed.allowDrafts)
+            stmts.push(`ALTER TABLE content_${slug}_drafts DROP COLUMN ${alias};`);
+    }
+    return stmts;
+}
+/**
+ * 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 function generateRenameColumn(seed, fromAlias, toAlias) {
+    const stmts = [];
+    const { slug } = seed;
+    stmts.push(`ALTER TABLE content_${slug} RENAME COLUMN ${fromAlias} TO ${toAlias};`);
+    if (seed.allowDrafts) {
+        stmts.push(`ALTER TABLE content_${slug}_drafts RENAME COLUMN ${fromAlias} TO ${toAlias};`);
+    }
+    return stmts;
+}
+/**
+ * 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 function planFtsRebuild(seed) {
+    const rtBranches = searchBranches(seed);
+    if (rtBranches.length === 0)
+        return [];
+    const { slug } = seed;
+    const stmts = [...ftsTriggerDrops(slug)];
+    const ftsTable = generateFtsTable(seed);
+    if (ftsTable)
+        stmts.push(ftsTable);
+    stmts.push(...generateFtsTriggers(seed));
+    const cols = rtBranches.map(b => b.alias);
+    stmts.push(`INSERT INTO fts_${slug}(entry_id, ${cols.join(', ')}) SELECT id, ${cols.join(', ')} FROM content_${slug};`);
+    return stmts;
+}
+/**
+ * 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 function planRetypeColumn(seed, alias, newType, updatedSeed) {
+    const branch = seed.branches.find(b => b.alias === alias);
+    if (!branch)
+        throw new Error(`Branch '${alias}' not found in seed '${seed.slug}'`);
+    const { slug } = seed;
+    const newSqlType = BRANCH_SQL_TYPE[newType];
+    const tmpAlias = `${alias}_migrate`;
+    const stmts = [];
+    // Always drop FTS first to avoid "column referenced in trigger" errors on DROP COLUMN.
+    stmts.push(...ftsTriggerDrops(slug));
+    // Drop the branch index if it exists on the old column (required before DROP COLUMN).
+    if (INDEXABLE_TYPES.has(branch.type) && branch.policies?.filter !== false) {
+        stmts.push(`DROP INDEX IF EXISTS idx_${slug}_${alias};`);
+    }
+    // Main table: add migration column, copy data, drop old, rename.
+    stmts.push(`ALTER TABLE content_${slug} ADD COLUMN ${tmpAlias} ${newSqlType};`);
+    stmts.push(`UPDATE content_${slug} SET ${tmpAlias} = CAST(${alias} AS ${newSqlType});`);
+    stmts.push(`ALTER TABLE content_${slug} DROP COLUMN ${alias};`);
+    stmts.push(`ALTER TABLE content_${slug} RENAME COLUMN ${tmpAlias} TO ${alias};`);
+    // Recreate index for the renamed column if the new type warrants it.
+    if (INDEXABLE_TYPES.has(newType) && branch.policies?.filter !== false) {
+        stmts.push(`CREATE INDEX IF NOT EXISTS idx_${slug}_${alias} ON content_${slug}(${alias});`);
+    }
+    // Drafts table (no indexes to worry about).
+    if (seed.allowDrafts) {
+        stmts.push(`ALTER TABLE content_${slug}_drafts ADD COLUMN ${tmpAlias} ${newSqlType};`);
+        stmts.push(`UPDATE content_${slug}_drafts SET ${tmpAlias} = CAST(${alias} AS ${newSqlType});`);
+        stmts.push(`ALTER TABLE content_${slug}_drafts DROP COLUMN ${alias};`);
+        stmts.push(`ALTER TABLE content_${slug}_drafts RENAME COLUMN ${tmpAlias} TO ${alias};`);
+    }
+    // Rebuild FTS if the seed has searchable branches in the updated definition.
+    const rebuild = planFtsRebuild(updatedSeed);
+    stmts.push(...rebuild);
+    return { statements: stmts, ftsRebuildNeeded: rebuild.length > 0 };
+}

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

@@ -0,0 +1,43 @@
+import type { Seed } from '../types.js';
+/**
+ * Full create-from-scratch statement set for a seed. Mirrors the CLI's buildStatements.
+ * Order: parent table → indexes → draft table → FTS table → FTS triggers →
+ * per multi-relation: junction table → junction indexes → junction draft table.
+ * Callers that create several seeds must order seeds with sortSeedsByDependencies
+ * first so relation FK targets exist.
+ */
+export declare function planCreateSeed(seed: Seed): string[];
+export interface ExtendPlan {
+    statements: string[];
+    ftsRebuildNeeded: boolean;
+}
+/**
+ * Additive extension: given the columns that already exist on content_{slug}
+ * (from PRAGMA table_info, passed in by the caller), return ONLY the statements
+ * needed to add new branches — ADD COLUMN + indexes, plus junction tables for
+ * new multi-relation branches. Never drops or renames.
+ *
+ * FTS: SQLite cannot ALTER an fts5 table's columns. If a new text/richtext
+ * searchable branch was added, ftsRebuildNeeded=true signals the caller
+ * (sprint 03) to handle it — no DROP is emitted.
+ *
+ * Draft tables: pass `existingDraftColumns` (PRAGMA table_info on content_{slug}_drafts) to have the
+ * `live_snapshot_at` system column added retroactively; omit it to skip that check entirely.
+ */
+export declare function planExtendSeed(seed: Seed, existingColumns: Set<string>, existingDraftColumns?: Set<string> | null): ExtendPlan;
+/**
+ * Destructive FTS rebuild (sprint 06). SQLite cannot ALTER an fts5 table's
+ * columns, so when a searchable branch is added, renamed, retyped, or dropped
+ * the only correct fix is to drop and recreate the `fts_{slug}` virtual table
+ * (and its insert/update/delete triggers), then backfill from `content_{slug}`.
+ *
+ * Returns an empty array when the seed has no searchable branches — in that
+ * case the caller should instead drop any leftover FTS table via
+ * generateDropTable's FTS statements. The returned statements are destructive
+ * and must run through ISchemaMutator.execDestructive, never execDdl.
+ *
+ * Order: drop triggers → drop fts table → recreate table → recreate triggers →
+ * backfill existing rows.
+ */
+export declare function planFtsRebuild(seed: Seed): string[];
+//# sourceMappingURL=seed-ddl.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"seed-ddl.d.ts","sourceRoot":"","sources":["../../../src/engine/ddl/seed-ddl.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,aAAa,CAAA;AAgBvC;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,IAAI,GAAG,MAAM,EAAE,CAanD;AAED,MAAM,WAAW,UAAU;IACzB,UAAU,EAAE,MAAM,EAAE,CAAA;IACpB,gBAAgB,EAAE,OAAO,CAAA;CAC1B;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,cAAc,CAC5B,IAAI,EAAE,IAAI,EACV,eAAe,EAAE,GAAG,CAAC,MAAM,CAAC,EAC5B,oBAAoB,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,GAAG,IAAI,GACxC,UAAU,CAmCZ;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,IAAI,GAAG,MAAM,EAAE,CA0BnD"}

package/dist/engine/ddl/seed-ddl.js

@@ -0,0 +1,115 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2024–2026 Flavio De Musso
+import { generateCreateTable, generateDraftTable, generateIndexes, generateFtsTable, generateFtsTriggers, generateAddColumn, generateAddDraftSnapshotColumn, generateJunctionTable, generateJunctionIndexes, generateJunctionDraftTable, generateEnableSoftDelete, indexableSearchBranches, } from './ddl.js';
+/**
+ * Full create-from-scratch statement set for a seed. Mirrors the CLI's buildStatements.
+ * Order: parent table → indexes → draft table → FTS table → FTS triggers →
+ * per multi-relation: junction table → junction indexes → junction draft table.
+ * Callers that create several seeds must order seeds with sortSeedsByDependencies
+ * first so relation FK targets exist.
+ */
+export function planCreateSeed(seed) {
+    const stmts = [generateCreateTable(seed), ...generateIndexes(seed)];
+    const draft = generateDraftTable(seed);
+    if (draft)
+        stmts.push(draft);
+    const fts = generateFtsTable(seed);
+    if (fts)
+        stmts.push(fts, ...generateFtsTriggers(seed));
+    for (const branch of seed.branches) {
+        if (branch.type !== 'relation' || branch.multiple !== true)
+            continue;
+        stmts.push(generateJunctionTable(seed, branch), ...generateJunctionIndexes(seed, branch));
+        const dj = generateJunctionDraftTable(seed, branch);
+        if (dj)
+            stmts.push(dj);
+    }
+    return stmts;
+}
+/**
+ * Additive extension: given the columns that already exist on content_{slug}
+ * (from PRAGMA table_info, passed in by the caller), return ONLY the statements
+ * needed to add new branches — ADD COLUMN + indexes, plus junction tables for
+ * new multi-relation branches. Never drops or renames.
+ *
+ * FTS: SQLite cannot ALTER an fts5 table's columns. If a new text/richtext
+ * searchable branch was added, ftsRebuildNeeded=true signals the caller
+ * (sprint 03) to handle it — no DROP is emitted.
+ *
+ * Draft tables: pass `existingDraftColumns` (PRAGMA table_info on content_{slug}_drafts) to have the
+ * `live_snapshot_at` system column added retroactively; omit it to skip that check entirely.
+ */
+export function planExtendSeed(seed, existingColumns, existingDraftColumns) {
+    const statements = [];
+    let ftsRebuildNeeded = false;
+    for (const branch of seed.branches) {
+        if (branch.type === 'relation' && branch.multiple === true) {
+            // junction table is CREATE IF NOT EXISTS — safe to re-emit
+            statements.push(generateJunctionTable(seed, branch), ...generateJunctionIndexes(seed, branch));
+            const dj = generateJunctionDraftTable(seed, branch);
+            if (dj)
+                statements.push(dj);
+            continue;
+        }
+        if (existingColumns.has(branch.alias))
+            continue;
+        statements.push(generateAddColumn(seed, branch));
+        if ((branch.type === 'text' || branch.type === 'richtext') && branch.policies?.search !== false) {
+            ftsRebuildNeeded = true;
+        }
+    }
+    // System column, not a branch: the branch loop above can never emit it.
+    if (seed.softDelete && !existingColumns.has('deleted_at')) {
+        statements.push(...generateEnableSoftDelete(seed));
+    }
+    // Draft-table system column. Emitted only when the caller actually introspected
+    // content_{slug}_drafts: `undefined` means "not introspected" and `null` means "table absent",
+    // and in both cases emitting a non-idempotent ADD COLUMN would abort the caller's whole DDL batch.
+    if (seed.allowDrafts &&
+        existingDraftColumns != null &&
+        !existingDraftColumns.has('live_snapshot_at')) {
+        statements.push(generateAddDraftSnapshotColumn(seed));
+    }
+    // CREATE INDEX IF NOT EXISTS — idempotent, safe to re-run
+    statements.push(...generateIndexes(seed));
+    return { statements, ftsRebuildNeeded };
+}
+/**
+ * Destructive FTS rebuild (sprint 06). SQLite cannot ALTER an fts5 table's
+ * columns, so when a searchable branch is added, renamed, retyped, or dropped
+ * the only correct fix is to drop and recreate the `fts_{slug}` virtual table
+ * (and its insert/update/delete triggers), then backfill from `content_{slug}`.
+ *
+ * Returns an empty array when the seed has no searchable branches — in that
+ * case the caller should instead drop any leftover FTS table via
+ * generateDropTable's FTS statements. The returned statements are destructive
+ * and must run through ISchemaMutator.execDestructive, never execDdl.
+ *
+ * Order: drop triggers → drop fts table → recreate table → recreate triggers →
+ * backfill existing rows.
+ */
+export function planFtsRebuild(seed) {
+    const branches = indexableSearchBranches(seed);
+    if (branches.length === 0)
+        return [];
+    const slug = seed.slug;
+    const ftsTable = `fts_${slug}`;
+    const contentTable = `content_${slug}`;
+    const cols = branches.map(b => b.alias);
+    const ftsTableDdl = generateFtsTable(seed);
+    const triggers = generateFtsTriggers(seed);
+    // generateFtsTable/Triggers return non-null here (branches.length > 0 checked).
+    if (!ftsTableDdl)
+        return [];
+    const ftsColList = ['entry_id', ...cols].join(', ');
+    const selectList = ['id', ...cols].join(', ');
+    return [
+        `DROP TRIGGER IF EXISTS fts_${slug}_insert;`,
+        `DROP TRIGGER IF EXISTS fts_${slug}_update;`,
+        `DROP TRIGGER IF EXISTS fts_${slug}_delete;`,
+        `DROP TABLE IF EXISTS ${ftsTable};`,
+        ftsTableDdl,
+        ...triggers,
+        `INSERT INTO ${ftsTable}(${ftsColList}) SELECT ${selectList} FROM ${contentTable};`,
+    ];
+}

package/dist/engine/ddl/seed-purge-guards.d.ts

@@ -0,0 +1,7 @@
+import type { Seed } from '../types.js';
+/** Blocks writes from requests that loaded a seed immediately before its purge began. */
+export declare function generateSeedPurgeGuards(seed: Seed): {
+    create: string[];
+    drop: string[];
+};
+//# sourceMappingURL=seed-purge-guards.d.ts.map

package/dist/engine/ddl/seed-purge-guards.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"seed-purge-guards.d.ts","sourceRoot":"","sources":["../../../src/engine/ddl/seed-purge-guards.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,aAAa,CAAA;AAEvC,yFAAyF;AACzF,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,IAAI,GAAG;IAAE,MAAM,EAAE,MAAM,EAAE,CAAC;IAAC,IAAI,EAAE,MAAM,EAAE,CAAA;CAAE,CAcxF"}

package/dist/engine/ddl/seed-purge-guards.js

@@ -0,0 +1,19 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2024–2026 Flavio De Musso
+/** Blocks writes from requests that loaded a seed immediately before its purge began. */
+export function generateSeedPurgeGuards(seed) {
+    if (!/^[a-z0-9_]+$/.test(seed.slug))
+        throw new Error(`Unsafe seed slug: ${seed.slug}`);
+    const tables = [`content_${seed.slug}`, ...(seed.allowDrafts ? [`content_${seed.slug}_drafts`] : [])];
+    const operations = ['INSERT', 'UPDATE', 'DELETE'];
+    const create = [];
+    const drop = [];
+    for (const table of tables) {
+        for (const operation of operations) {
+            const name = `purge_guard_${table}_${operation.toLowerCase()}`;
+            create.push(`CREATE TRIGGER ${name} BEFORE ${operation} ON ${table} BEGIN SELECT RAISE(ABORT, 'seed_purge_in_progress'); END;`);
+            drop.push(`DROP TRIGGER IF EXISTS ${name};`);
+        }
+    }
+    return { create, drop };
+}

package/dist/engine/engine.d.ts

@@ -1,4 +1,5 @@
-export * from './ddl.js';
-export * from './query.js';
-export * from './serialize.js';
+export * from './ddl/ddl.js';
+export * from './query/query.js';
+export * from './query/serialize.js';
+export * from './query/active-clause.js';
 //# sourceMappingURL=engine.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../../src/engine/engine.ts"],"names":[],"mappings":"AACA,cAAc,UAAU,CAAA;AACxB,cAAc,YAAY,CAAA;AAC1B,cAAc,gBAAgB,CAAA"}
+{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../../src/engine/engine.ts"],"names":[],"mappings":"AACA,cAAc,cAAc,CAAA;AAC5B,cAAc,kBAAkB,CAAA;AAChC,cAAc,sBAAsB,CAAA;AACpC,cAAc,0BAA0B,CAAA"}

package/dist/engine/engine.js

@@ -1,4 +1,5 @@
 // SPDX-License-Identifier: MIT
-export * from './ddl.js';
-export * from './query.js';
-export * from './serialize.js';
+export * from './ddl/ddl.js';
+export * from './query/query.js';
+export * from './query/serialize.js';
+export * from './query/active-clause.js';

package/dist/engine/introspection/introspection.d.ts

@@ -0,0 +1,101 @@
+/**
+ * @module engine/introspection
+ * Reads live schema state out of D1 through an INJECTED executor.
+ *
+ * Executor-agnostic on purpose: the CLI reaches D1 through a synchronous shell/SQLite path
+ * (`queryD1`) and the Worker through its `D1Database` binding, and neither tier may import the
+ * other (`graphify path "createBeechApp" "queryD1"` must keep returning no path). `@beechcms/core`
+ * owns the STATEMENTS and the SHAPES; the caller owns the connection.
+ *
+ * Read-only by contract: every statement here is a `PRAGMA` or a `SELECT`. Schema mutation stays
+ * the exclusive business of the Botanical Engine's DDL path (`engine/seed-ddl.ts`).
+ */
+import type { Seed } from '../types.js';
+/**
+ * The one capability the introspection primitive needs from a database connection.
+ *
+ * Implementations MUST: execute the statement as-is, return one object per row with column names
+ * as keys, and reject/throw on failure. They MUST NOT cache, batch, rewrite or retry — a stale
+ * answer here becomes a wrong fingerprint, which becomes a false "your types are stale" error in
+ * someone else's production client.
+ */
+export interface SchemaQueryExecutor {
+    all<T extends Record<string, unknown>>(sql: string): Promise<T[]>;
+}
+/** Thrown when live state cannot be read or cannot be trusted. */
+export declare class IntrospectionError extends Error {
+    readonly cause?: unknown | undefined;
+    constructor(message: string, cause?: unknown | undefined);
+}
+/** One physical column, as SQLite reports it. */
+export interface LiveColumn {
+    name: string;
+    /** Declared storage type, upper-cased (`TEXT` | `INTEGER` | `REAL` | …). */
+    sqlType: string;
+    notNull: boolean;
+    isPk: boolean;
+    /** Declared DEFAULT expression verbatim, or null. */
+    defaultValue: string | null;
+}
+/** One foreign-key constraint on a physical table. */
+export interface LiveForeignKey {
+    /** Local column carrying the reference. */
+    column: string;
+    /** Referenced table, e.g. `content_team`. */
+    targetTable: string;
+    /** Referenced column, e.g. `id`. */
+    targetColumn: string;
+    /** Upper-cased, e.g. `SET NULL`. */
+    onDelete: string;
+    /** Upper-cased, e.g. `NO ACTION`. */
+    onUpdate: string;
+}
+/** One index on a physical table. SQLite's implicit `sqlite_autoindex_*` entries are excluded. */
+export interface LiveIndex {
+    name: string;
+    unique: boolean;
+}
+/** The physical state of one table. `exists: false` means SQLite reports no such table. */
+export interface LiveTable {
+    name: string;
+    exists: boolean;
+    /** Physical order, as returned by `PRAGMA table_info` (cid order). */
+    columns: LiveColumn[];
+    /** Sorted by `column`, then `targetTable`, for deterministic output. */
+    foreignKeys: LiveForeignKey[];
+    /** Sorted by `name`. */
+    indexes: LiveIndex[];
+}
+/** The physical state of a set of tables. `tables` is sorted by name. */
+export interface LiveSchema {
+    tables: LiveTable[];
+}
+/** Returns `name` unchanged when it is a safe SQL identifier; throws otherwise. */
+export declare function assertSafeIdentifier(name: string): string;
+/**
+ * Physical state of one table. A table SQLite does not know returns `{ exists: false }` with empty
+ * lists rather than throwing: "missing" is a legitimate diff outcome, not an error.
+ *
+ * `PRAGMA table_info` answers an unknown table with zero rows on the SQLite path and raises on some
+ * wrangler paths, so both outcomes collapse to the same result.
+ */
+export declare function introspectTable(executor: SchemaQueryExecutor, table: string): Promise<LiveTable>;
+/**
+ * Names of the physical tables SQLite holds, optionally restricted to a `LIKE` prefix
+ * (e.g. `content_`). Sorted, `sqlite_*` internals excluded.
+ */
+export declare function listTables(executor: SchemaQueryExecutor, prefix?: string): Promise<string[]>;
+/**
+ * Physical state of several tables at once. With no explicit list, every `content_*` table is
+ * introspected — the set a schema export or a drift check cares about.
+ */
+export declare function introspectSchema(executor: SchemaQueryExecutor, tables?: string[]): Promise<LiveSchema>;
+/**
+ * The DECLARED schema: every active seed definition, read live from D1.
+ *
+ * This — not `beech.schema.ts` — is the source of truth for generated types and for the schema
+ * fingerprint (feature brief, business rule 1). The manifest file is a desired-state artifact and
+ * may legitimately be ahead of, or behind, what is deployed.
+ */
+export declare function introspectSeedDefinitions(executor: SchemaQueryExecutor): Promise<Seed[]>;
+//# sourceMappingURL=introspection.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"introspection.d.ts","sourceRoot":"","sources":["../../../src/engine/introspection/introspection.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,aAAa,CAAA;AAEvC;;;;;;;GAOG;AACH,MAAM,WAAW,mBAAmB;IAClC,GAAG,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,EAAE,CAAC,CAAA;CAClE;AAED,kEAAkE;AAClE,qBAAa,kBAAmB,SAAQ,KAAK;IACd,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO;gBAAzC,OAAO,EAAE,MAAM,EAAW,KAAK,CAAC,EAAE,OAAO,YAAA;CAItD;AAED,iDAAiD;AACjD,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAA;IACZ,4EAA4E;IAC5E,OAAO,EAAE,MAAM,CAAA;IACf,OAAO,EAAE,OAAO,CAAA;IAChB,IAAI,EAAE,OAAO,CAAA;IACb,qDAAqD;IACrD,YAAY,EAAE,MAAM,GAAG,IAAI,CAAA;CAC5B;AAED,sDAAsD;AACtD,MAAM,WAAW,cAAc;IAC7B,2CAA2C;IAC3C,MAAM,EAAE,MAAM,CAAA;IACd,6CAA6C;IAC7C,WAAW,EAAE,MAAM,CAAA;IACnB,oCAAoC;IACpC,YAAY,EAAE,MAAM,CAAA;IACpB,oCAAoC;IACpC,QAAQ,EAAE,MAAM,CAAA;IAChB,qCAAqC;IACrC,QAAQ,EAAE,MAAM,CAAA;CACjB;AAED,kGAAkG;AAClG,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAA;IACZ,MAAM,EAAE,OAAO,CAAA;CAChB;AAED,2FAA2F;AAC3F,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAA;IACZ,MAAM,EAAE,OAAO,CAAA;IACf,sEAAsE;IACtE,OAAO,EAAE,UAAU,EAAE,CAAA;IACrB,wEAAwE;IACxE,WAAW,EAAE,cAAc,EAAE,CAAA;IAC7B,wBAAwB;IACxB,OAAO,EAAE,SAAS,EAAE,CAAA;CACrB;AAED,yEAAyE;AACzE,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,SAAS,EAAE,CAAA;CACpB;AA6CD,mFAAmF;AACnF,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAOzD;AAED;;;;;;GAMG;AACH,wBAAsB,eAAe,CACnC,QAAQ,EAAE,mBAAmB,EAC7B,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,SAAS,CAAC,CAgDpB;AAED;;;GAGG;AACH,wBAAsB,UAAU,CAC9B,QAAQ,EAAE,mBAAmB,EAC7B,MAAM,CAAC,EAAE,MAAM,GACd,OAAO,CAAC,MAAM,EAAE,CAAC,CAOnB;AAED;;;GAGG;AACH,wBAAsB,gBAAgB,CACpC,QAAQ,EAAE,mBAAmB,EAC7B,MAAM,CAAC,EAAE,MAAM,EAAE,GAChB,OAAO,CAAC,UAAU,CAAC,CAUrB;AAED;;;;;;GAMG;AACH,wBAAsB,yBAAyB,CAC7C,QAAQ,EAAE,mBAAmB,GAC5B,OAAO,CAAC,IAAI,EAAE,CAAC,CAoBjB"}

package/dist/engine/introspection/introspection.js

@@ -0,0 +1,127 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2024–2026 Flavio De Musso
+/** Thrown when live state cannot be read or cannot be trusted. */
+export class IntrospectionError extends Error {
+    cause;
+    constructor(message, cause) {
+        super(message);
+        this.cause = cause;
+        this.name = 'IntrospectionError';
+    }
+}
+/**
+ * SQLite identifiers cannot be bound as parameters, so every table name reaching a PRAGMA is
+ * interpolated — and therefore must be proven safe first. Table names in this system are always
+ * `content_{slug}` / `rel_{slug}_{alias}` / a structural table, all of which match this pattern.
+ */
+const SAFE_IDENTIFIER = /^[A-Za-z_][A-Za-z0-9_]*$/;
+/** Returns `name` unchanged when it is a safe SQL identifier; throws otherwise. */
+export function assertSafeIdentifier(name) {
+    if (!SAFE_IDENTIFIER.test(name)) {
+        throw new IntrospectionError(`Refusing to introspect '${name}': not a plain SQL identifier. Table names are never user input in BeechCMS.`);
+    }
+    return name;
+}
+/**
+ * Physical state of one table. A table SQLite does not know returns `{ exists: false }` with empty
+ * lists rather than throwing: "missing" is a legitimate diff outcome, not an error.
+ *
+ * `PRAGMA table_info` answers an unknown table with zero rows on the SQLite path and raises on some
+ * wrangler paths, so both outcomes collapse to the same result.
+ */
+export async function introspectTable(executor, table) {
+    const name = assertSafeIdentifier(table);
+    const empty = { name, exists: false, columns: [], foreignKeys: [], indexes: [] };
+    let info;
+    try {
+        info = await executor.all(`PRAGMA table_info(${name})`);
+    }
+    catch {
+        return empty;
+    }
+    if (info.length === 0)
+        return empty;
+    const columns = info.map(row => ({
+        name: row.name,
+        sqlType: String(row.type ?? '').toUpperCase(),
+        notNull: row.notnull === 1,
+        isPk: row.pk > 0,
+        defaultValue: row.dflt_value ?? null,
+    }));
+    let fkRows = [];
+    let indexRows = [];
+    try {
+        fkRows = await executor.all(`PRAGMA foreign_key_list(${name})`);
+        indexRows = await executor.all(`PRAGMA index_list(${name})`);
+    }
+    catch {
+        // A table with neither FKs nor indexes answers with zero rows on some drivers and raises on
+        // others; an unreadable constraint list must not hide the column list we already have.
+    }
+    const foreignKeys = fkRows
+        .map(row => ({
+        column: row.from,
+        targetTable: row.table,
+        targetColumn: row.to ?? 'id',
+        onDelete: String(row.on_delete ?? '').toUpperCase(),
+        onUpdate: String(row.on_update ?? '').toUpperCase(),
+    }))
+        .sort((a, b) => a.column.localeCompare(b.column) || a.targetTable.localeCompare(b.targetTable));
+    const indexes = indexRows
+        // Implicit indexes SQLite mints for UNIQUE/PK are not schema an author declared, and their
+        // names are not stable across environments.
+        .filter(row => !row.name.startsWith('sqlite_autoindex_'))
+        .map(row => ({ name: row.name, unique: row.unique === 1 }))
+        .sort((a, b) => a.name.localeCompare(b.name));
+    return { name, exists: true, columns, foreignKeys, indexes };
+}
+/**
+ * Names of the physical tables SQLite holds, optionally restricted to a `LIKE` prefix
+ * (e.g. `content_`). Sorted, `sqlite_*` internals excluded.
+ */
+export async function listTables(executor, prefix) {
+    if (prefix !== undefined)
+        assertSafeIdentifier(`${prefix}x`);
+    const filter = prefix ? ` AND name LIKE '${prefix}%'` : '';
+    const rows = await executor.all(`SELECT name FROM sqlite_master WHERE type = 'table' AND name NOT LIKE 'sqlite_%'${filter} ORDER BY name ASC`);
+    return rows.map(row => row.name);
+}
+/**
+ * Physical state of several tables at once. With no explicit list, every `content_*` table is
+ * introspected — the set a schema export or a drift check cares about.
+ */
+export async function introspectSchema(executor, tables) {
+    const names = tables ?? await listTables(executor, 'content_');
+    const sorted = [...names].sort((a, b) => a.localeCompare(b));
+    const result = [];
+    // Sequential on purpose: the CLI executor is a synchronous shell/SQLite call behind a Promise,
+    // and D1 rejects unbounded concurrent statements from one request.
+    for (const name of sorted) {
+        result.push(await introspectTable(executor, name));
+    }
+    return { tables: result };
+}
+/**
+ * The DECLARED schema: every active seed definition, read live from D1.
+ *
+ * This — not `beech.schema.ts` — is the source of truth for generated types and for the schema
+ * fingerprint (feature brief, business rule 1). The manifest file is a desired-state artifact and
+ * may legitimately be ahead of, or behind, what is deployed.
+ */
+export async function introspectSeedDefinitions(executor) {
+    let rows;
+    try {
+        rows = await executor.all(`SELECT slug, definition FROM seeds WHERE status = 'active' ORDER BY slug ASC`);
+    }
+    catch (error) {
+        throw new IntrospectionError('Failed to read the `seeds` table from D1.', error);
+    }
+    return rows.map(row => {
+        try {
+            return JSON.parse(row.definition);
+        }
+        catch (error) {
+            throw new IntrospectionError(`Seed '${row.slug}' holds a definition that is not valid JSON; D1 state is corrupt.`, error);
+        }
+    });
+}