@beechcms/core 0.8.0 → 0.9.0

package/dist/engine/introspection/relation-audit.d.ts

@@ -0,0 +1,46 @@
+/**
+ * @module engine/relation-audit
+ * Finds relation branches whose physical storage no longer matches the deployed definition.
+ *
+ * Releases before the additive relation gate could persist a changed `multiple`, `targetSeed` or
+ * `onDelete` without migrating the FK column, the `rel_<slug>_<alias>` junction table or the FK
+ * policy. The gate prevents new mismatches; this audit identifies databases that already have one.
+ *
+ * Read-only by contract: only `PRAGMA` and `SELECT COUNT(*)` statements are issued, through the
+ * injected executor. Nothing is repaired and no row is ever touched.
+ */
+import type { Seed } from '../types.js';
+import { type SchemaQueryExecutor } from './introspection.js';
+/** What is wrong with the storage of one relation branch. */
+export type RelationStorageIssue = 
+/** Definition says single (or multiple) but the data lives in the other shape. */
+'wrong_storage'
+/** Neither the FK column nor the junction table exists. */
+ | 'missing_storage'
+/** The FK points at a different table than `targetSeed`. */
+ | 'fk_target_mismatch'
+/** The FK `ON DELETE` rule differs from the effective `onDelete`. */
+ | 'fk_on_delete_mismatch';
+export interface RelationStorageFinding {
+    seed: string;
+    alias: string;
+    issue: RelationStorageIssue;
+    /** What the deployed definition requires, e.g. `junction rel_posts_tags`. */
+    expected: string;
+    /** What the database holds. */
+    actual: string;
+    /**
+     * Rows or values sitting in storage the definition no longer points at. Always 0 for
+     * `missing_storage` and the FK findings: those carry no stranded values by themselves.
+     */
+    strandedRows: number;
+}
+/**
+ * Compares every relation branch of the given (active) seeds against the physical tables.
+ *
+ * Seeds whose `content_<slug>` table is missing are skipped: that is plain schema drift and is
+ * reported by the schema diff, not a relation-storage mismatch. Findings are ordered by seed, then
+ * branch order, so the report is deterministic.
+ */
+export declare function auditRelationStorage(executor: SchemaQueryExecutor, seeds: Seed[]): Promise<RelationStorageFinding[]>;
+//# sourceMappingURL=relation-audit.d.ts.map

package/dist/engine/introspection/relation-audit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"relation-audit.d.ts","sourceRoot":"","sources":["../../../src/engine/introspection/relation-audit.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAU,IAAI,EAAE,MAAM,aAAa,CAAA;AAE/C,OAAO,EAIL,KAAK,mBAAmB,EACzB,MAAM,oBAAoB,CAAA;AAE3B,6DAA6D;AAC7D,MAAM,MAAM,oBAAoB;AAC9B,kFAAkF;AAChF,eAAe;AACjB,2DAA2D;GACzD,iBAAiB;AACnB,4DAA4D;GAC1D,oBAAoB;AACtB,qEAAqE;GACnE,uBAAuB,CAAA;AAE3B,MAAM,WAAW,sBAAsB;IACrC,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,EAAE,MAAM,CAAA;IACb,KAAK,EAAE,oBAAoB,CAAA;IAC3B,6EAA6E;IAC7E,QAAQ,EAAE,MAAM,CAAA;IAChB,+BAA+B;IAC/B,MAAM,EAAE,MAAM,CAAA;IACd;;;OAGG;IACH,YAAY,EAAE,MAAM,CAAA;CACrB;AAkGD;;;;;;GAMG;AACH,wBAAsB,oBAAoB,CACxC,QAAQ,EAAE,mBAAmB,EAC7B,KAAK,EAAE,IAAI,EAAE,GACZ,OAAO,CAAC,sBAAsB,EAAE,CAAC,CAiBnC"}

package/dist/engine/introspection/relation-audit.js

@@ -0,0 +1,103 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2024–2026 Flavio De Musso
+import { junctionTableName } from '../ddl/ddl.js';
+import { assertSafeIdentifier, introspectTable, } from './introspection.js';
+/** Default `ON DELETE` rule, per storage shape (mirrors `engine/ddl`). */
+function effectiveOnDelete(branch) {
+    return (branch.onDelete ?? (branch.multiple === true ? 'CASCADE' : 'SET NULL')).toUpperCase();
+}
+async function countRows(executor, sql) {
+    const rows = await executor.all(sql);
+    return Number(rows[0]?.n ?? 0);
+}
+/** Checks the FK that carries the reference: the `alias` column, or the junction's `target_id`. */
+function fkFindings(seed, branch, fk, location) {
+    const expectedTarget = `content_${branch.targetSeed}`;
+    const expectedRule = effectiveOnDelete(branch);
+    const base = { seed: seed.slug, alias: branch.alias, strandedRows: 0 };
+    const expected = `${location} -> ${expectedTarget}(id) ON DELETE ${expectedRule}`;
+    if (!fk) {
+        return [{ ...base, issue: 'fk_target_mismatch', expected, actual: `${location} has no foreign key` }];
+    }
+    const actual = `${location} -> ${fk.targetTable}(${fk.targetColumn}) ON DELETE ${fk.onDelete}`;
+    const findings = [];
+    if (fk.targetTable !== expectedTarget)
+        findings.push({ ...base, issue: 'fk_target_mismatch', expected, actual });
+    if (fk.onDelete !== expectedRule)
+        findings.push({ ...base, issue: 'fk_on_delete_mismatch', expected, actual });
+    return findings;
+}
+async function auditBranch(executor, seed, branch, contentColumns, contentForeignKeys) {
+    const isMultiple = branch.multiple === true;
+    const junction = junctionTableName(seed.slug, branch.alias);
+    const draftJunction = `${junction}_drafts`;
+    const alias = assertSafeIdentifier(branch.alias);
+    const base = { seed: seed.slug, alias: branch.alias };
+    const liveJunction = await introspectTable(executor, junction);
+    const liveDraftJunction = await introspectTable(executor, draftJunction);
+    const hasColumn = contentColumns.has(alias);
+    if (isMultiple) {
+        if (hasColumn) {
+            const strandedRows = await countRows(executor, `SELECT COUNT(*) AS n FROM content_${seed.slug} WHERE "${alias}" IS NOT NULL`);
+            return [{
+                    ...base,
+                    issue: 'wrong_storage',
+                    expected: `junction ${junction}`,
+                    actual: `${liveJunction.exists ? `junction ${junction} and ` : ''}column content_${seed.slug}.${alias}`,
+                    strandedRows,
+                }];
+        }
+        if (!liveJunction.exists) {
+            return [{ ...base, issue: 'missing_storage', expected: `junction ${junction}`, actual: 'no junction table', strandedRows: 0 }];
+        }
+        const findings = fkFindings(seed, branch, liveJunction.foreignKeys.find(fk => fk.column === 'target_id'), `${junction}.target_id`);
+        if (seed.allowDrafts && !liveDraftJunction.exists) {
+            findings.push({ ...base, issue: 'missing_storage', expected: `drafts junction ${draftJunction}`, actual: 'no drafts junction table', strandedRows: 0 });
+        }
+        return findings;
+    }
+    // Single relation: the value lives in a column; any junction left behind holds stranded links.
+    if (liveJunction.exists || liveDraftJunction.exists) {
+        let strandedRows = 0;
+        if (liveJunction.exists)
+            strandedRows += await countRows(executor, `SELECT COUNT(*) AS n FROM ${junction}`);
+        if (liveDraftJunction.exists)
+            strandedRows += await countRows(executor, `SELECT COUNT(*) AS n FROM ${draftJunction}`);
+        return [{
+                ...base,
+                issue: 'wrong_storage',
+                expected: `column content_${seed.slug}.${alias}`,
+                actual: `${hasColumn ? `column content_${seed.slug}.${alias} and ` : ''}junction ${junction}`,
+                strandedRows,
+            }];
+    }
+    if (!hasColumn) {
+        return [{ ...base, issue: 'missing_storage', expected: `column content_${seed.slug}.${alias}`, actual: 'no column', strandedRows: 0 }];
+    }
+    return fkFindings(seed, branch, contentForeignKeys.get(alias), `content_${seed.slug}.${alias}`);
+}
+/**
+ * Compares every relation branch of the given (active) seeds against the physical tables.
+ *
+ * Seeds whose `content_<slug>` table is missing are skipped: that is plain schema drift and is
+ * reported by the schema diff, not a relation-storage mismatch. Findings are ordered by seed, then
+ * branch order, so the report is deterministic.
+ */
+export async function auditRelationStorage(executor, seeds) {
+    const findings = [];
+    const ordered = [...seeds].sort((a, b) => a.slug.localeCompare(b.slug));
+    // Sequential on purpose: see `introspectSchema`.
+    for (const seed of ordered) {
+        const content = await introspectTable(executor, `content_${assertSafeIdentifier(seed.slug)}`);
+        if (!content.exists)
+            continue;
+        const columns = new Set(content.columns.map(column => column.name));
+        const foreignKeys = new Map(content.foreignKeys.map(fk => [fk.column, fk]));
+        for (const branch of seed.branches) {
+            if (branch.type !== 'relation' || !branch.targetSeed)
+                continue;
+            findings.push(...await auditBranch(executor, seed, branch, columns, foreignKeys));
+        }
+    }
+    return findings;
+}

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

@@ -0,0 +1,74 @@
+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 = 2;
+/** The response-shape-bearing subset of a `Branch`. */
+export interface ContractBranch {
+    alias: string;
+    type: Branch['type'];
+    format?: Branch['format'];
+    multiple?: boolean;
+    options?: string[];
+    requiredOnCreate: boolean;
+    requiredOnUpdate: boolean;
+    targetSeed?: string;
+    /** From `resolvePolicies`, so an explicitly-written default hashes like an omitted one. */
+    visibility: 'full' | 'masked' | 'hidden';
+    publicRead: boolean;
+    publicEdit: boolean;
+    minItems?: number;
+    maxItems?: number;
+    /** Present only when true: the dictionary shape is part of the public contract (`?lang=all`, writes). */
+    localized?: boolean;
+    /** Repeater sub-fields, same projection, recursively. */
+    fields?: ContractBranch[];
+}
+/** The response-shape-bearing subset of a `Seed`. */
+export interface ContractSeed {
+    slug: string;
+    displayNameAlias: string;
+    allowDrafts: boolean;
+    allowPublicRead: boolean;
+    allowPublicPost: boolean;
+    allowPublicEdit: boolean;
+    branches: ContractBranch[];
+}
+/** The exact value that gets canonicalized and hashed. */
+export interface SchemaContract {
+    fingerprintVersion: number;
+    seeds: ContractSeed[];
+}
+/**
+ * Reduces seeds to what a response shape depends on.
+ *
+ * Deliberately EXCLUDED, and each for a reason a future reader must not "fix":
+ * - `id` (`br_XX`) — a stable internal handle; it never appears in a payload, and minting order
+ *   differs between an environment built by migration and one grown through the dashboard.
+ * - `label`, `labelPlural`, `hint`, `dashboard`, `layout` — presentation, never response shape.
+ * - `retentionDays`, `onDelete`, `policies.search|filter|sort`, `numberOptions`, `fileOptions`,
+ *   `policies.classification|privacy` — behaviour and storage concerns that leave the response
+ *   shape identical. (`privacy` DOES change a stored value's encoding, but the API type stays
+ *   `string`; drift there is a data concern, not a type concern.)
+ * - option `color` — presentation only; a color edit cannot change a response byte.
+ * - 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/introspection/schema-fingerprint.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema-fingerprint.d.ts","sourceRoot":"","sources":["../../../src/engine/introspection/schema-fingerprint.ts"],"names":[],"mappings":"AAoBA,OAAO,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,aAAa,CAAA;AAG/C;;;;GAIG;AACH,eAAO,MAAM,0BAA0B,IAAI,CAAA;AAE3C,uDAAuD;AACvD,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,MAAM,CAAA;IACb,IAAI,EAAE,MAAM,CAAC,MAAM,CAAC,CAAA;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC,QAAQ,CAAC,CAAA;IACzB,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,OAAO,CAAC,EAAE,MAAM,EAAE,CAAA;IAClB,gBAAgB,EAAE,OAAO,CAAA;IACzB,gBAAgB,EAAE,OAAO,CAAA;IACzB,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,2FAA2F;IAC3F,UAAU,EAAE,MAAM,GAAG,QAAQ,GAAG,QAAQ,CAAA;IACxC,UAAU,EAAE,OAAO,CAAA;IACnB,UAAU,EAAE,OAAO,CAAA;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,yGAAyG;IACzG,SAAS,CAAC,EAAE,OAAO,CAAA;IACnB,yDAAyD;IACzD,MAAM,CAAC,EAAE,cAAc,EAAE,CAAA;CAC1B;AAED,qDAAqD;AACrD,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAA;IACZ,gBAAgB,EAAE,MAAM,CAAA;IACxB,WAAW,EAAE,OAAO,CAAA;IACpB,eAAe,EAAE,OAAO,CAAA;IACxB,eAAe,EAAE,OAAO,CAAA;IACxB,eAAe,EAAE,OAAO,CAAA;IACxB,QAAQ,EAAE,cAAc,EAAE,CAAA;CAC3B;AAED,0DAA0D;AAC1D,MAAM,WAAW,cAAc;IAC7B,kBAAkB,EAAE,MAAM,CAAA;IAC1B,KAAK,EAAE,YAAY,EAAE,CAAA;CACtB;AA4BD;;;;;;;;;;;;;;;;GAgBG;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/introspection/schema-fingerprint.js

@@ -0,0 +1,102 @@
+// 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 '../privacy/policies.js';
+import { isSingleChoiceTags, tagOptionValues } from '../seeds/tag-options.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 = 2;
+function projectBranch(branch) {
+    const policies = resolvePolicies(branch);
+    return {
+        alias: branch.alias,
+        type: branch.type,
+        ...(branch.format !== undefined ? { format: branch.format } : {}),
+        // `tags` always carry the resolved mode, so an omitted `multiple` hashes like `true`.
+        ...(branch.type === 'tags'
+            ? { multiple: !isSingleChoiceTags(branch) }
+            : 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: tagOptionValues(branch) } : {}),
+        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 } : {}),
+        // Spread only when true so every schema without localized branches keeps its fingerprint.
+        ...(branch.localized === true ? { localized: true } : {}),
+        ...(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.)
+ * - option `color` — presentation only; a color edit cannot change a response byte.
+ * - 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/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.d.ts.map

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