@impetik/xeer-mcp 0.2.4 → 0.2.6

package/vendor/spec/table-ddl.d.ts

@@ -0,0 +1,162 @@
+/**
+ * Translation from a declared application schema into the SQLite DDL that backs it: one real table
+ * per declared table, one real column per declared field.
+ *
+ * This replaces a generic single-table document store, where every application table's rows shared
+ * one physical `xeer_records` table with their fields packed into a JSON column. That shape made
+ * four things structurally impossible, because a table-level constraint cannot be scoped to a
+ * subset of a shared table's rows:
+ *
+ *   per-field NOT NULL, per-table CHECK (so: no enums), FOREIGN KEY (so: no cascade), real types.
+ *
+ * With one table per declared table those are ordinary DDL, and the runtime stops hand-rolling what
+ * the database already does. The module is dependency-free and lives in `spec` for the reason
+ * `storage.ts` gives: the compiler validates against these rules and the runtime applies them, and
+ * a rule the two disagreed on would mean an application that builds and then fails at call time.
+ *
+ * Everything the manifest can say about a column is said in DDL here, and every identifier and
+ * literal reaches the statement through `sql-expression.ts` rather than by concatenation — which is
+ * also why an author-written expression is lexed and re-emitted instead of interpolated.
+ *
+ * The generator is total: `tableDdl` throws rather than emitting a statement it cannot vouch for, so
+ * a definition that reaches it is either valid DDL or an error, never invalid SQL. The manifest
+ * schema runs it as its final check for exactly that reason.
+ *
+ * That promise once held only for what this module inspected and not for what it merely passed
+ * through. An author-written expression was lexed but never parsed, so `title AND`, `lower()` and
+ * `max(position)` each generated a clean `CREATE TABLE` that SQLite then refused — `near ")": syntax
+ * error`, `wrong number of arguments to function lower()`, `misuse of aggregate function max()` —
+ * turning a diagnostic into a failure when the schema was applied. `sql-expression.ts` now validates
+ * grammar and argument counts, which is what closes the gap; the tests below carry the corpus of
+ * expressions that used to get through.
+ */
+import type { NormalizedDatabaseSchemaV0 } from './schema-plan.js';
+import type { CollationName, TableDefinition, TableIndexDefinition } from './types.js';
+/**
+ * Identifier prefixes an application may not name a table with.
+ *
+ * `xeer_` and `_xeer_` are the runtime's own bookkeeping tables. `sqlite_` and `_cf_` are refused by
+ * SQLite and by workerd respectively, so those two are reservations the platform already enforces.
+ * `__cf_` and `cf_` are *not* — measured in workerd, a table called `__cf_anything` is created
+ * happily — but the platform keeps its key-value data in a hidden `__cf_kv`, so this list reserves
+ * the prefix as policy rather than relying on an enforcement that does not exist.
+ *
+ * A declared table is created under its own plain name — so that `SELECT * FROM posts` is what an
+ * operator actually types — which is only safe if these cannot collide with it.
+ */
+export declare const RESERVED_TABLE_PREFIXES: readonly string[];
+/** SQLite identifiers are case-insensitive, so the reservation has to be too. */
+export declare function reservedTableName(name: string): boolean;
+/**
+ * The physical name of a declared index.
+ *
+ * Length-prefixed because SQLite holds indexes and tables in one namespace and a naive
+ * `${table}_${index}` is ambiguous: table `posts` index `by_slug` and table `posts_by` index `slug`
+ * would both want `posts_by_slug`. Index names are never typed by hand, so legibility is worth less
+ * here than a proof that two declarations can never claim one name.
+ */
+export declare function physicalIndexName(tableName: string, indexName: string): string;
+/**
+ * The index over `(created_at, id)` that every table carries whether or not it declares one.
+ *
+ * Every read the runtime issues ends `ORDER BY created_at, id` — it is the total order rows are
+ * returned in, and the one admin paging seeks into — so without this each read is a full scan and a
+ * sort. The single-table store had exactly this index and it was lost when rows moved into per-table
+ * tables; this puts it back per table.
+ *
+ * A distinct prefix from {@link physicalIndexName}, so it can never collide with a declared index
+ * however that index is named.
+ */
+export declare function rowOrderIndexName(tableName: string): string;
+/** The runtime-owned columns, named here so a declaration can be checked against them. */
+export declare const RUNTIME_COLUMN_NAMES: readonly string[];
+/**
+ * Cloudflare's SQLite caps a table at 100 columns, well below stock SQLite's 2000. Measured in
+ * workerd: the hundredth column is accepted and the hundred-and-first fails with "too many columns".
+ */
+export declare const MAX_TABLE_COLUMNS = 100;
+/**
+ * The most fields a table may declare: the platform's column limit less the runtime's own three.
+ *
+ * Generated columns are charged against it, virtual and stored alike — confirmed in workerd, where
+ * a table of 100 columns including five generated ones is accepted and 101 is not. Refusing this at
+ * check time turns a schema that cannot be applied into a diagnostic while it is being written.
+ */
+export declare const MAX_TABLE_FIELDS: number;
+export declare class TableDdlError extends Error {
+    constructor(message: string);
+}
+/** One index member with every option settled, so nothing downstream re-derives a default. */
+export type NormalizedIndexTermV0 = {
+    readonly column: string;
+    readonly expression: null;
+    readonly collate: CollationName | null;
+    readonly desc: boolean;
+} | {
+    readonly column: null;
+    readonly expression: string;
+    readonly collate: null;
+    readonly desc: boolean;
+};
+export interface NormalizedIndexV0 {
+    readonly columns: readonly NormalizedIndexTermV0[];
+    readonly unique: boolean;
+    readonly where: string | null;
+}
+/**
+ * The full form of an index, which the array shorthand is sugar for. Every consumer — the DDL below,
+ * the schema hash, the change plan — reads the index through here, so the two spellings of one index
+ * are the same index everywhere and not just where someone remembered to handle both.
+ */
+export declare function normalizedIndex(definition: TableIndexDefinition): NormalizedIndexV0;
+/** The declared columns an index reads, for callers that only need to know what it covers. */
+export declare function indexColumns(definition: TableIndexDefinition): string[];
+/** How one index member reads in a diagnostic: `status`, `position DESC`, `(lower("title"))`. */
+export declare function indexTermLabel(term: NormalizedIndexTermV0): string;
+export interface TableDdlV0 {
+    readonly table: string;
+    readonly createTable: string;
+    /**
+     * The `(created_at, id)` index every table carries. Separate from {@link createIndexes}, which
+     * means the indexes the *schema declared* — a caller that reports or diffs declared indexes should
+     * not have to filter a runtime-owned one out of them.
+     */
+    readonly rowOrderIndex: string;
+    readonly createIndexes: readonly string[];
+}
+export declare function tableDdl(name: string, table: TableDefinition): TableDdlV0;
+/**
+ * Declared tables ordered so that a table always follows the tables it references.
+ *
+ * `CREATE TABLE` does not need this — SQLite resolves a forward `REFERENCES` at write time, so any
+ * order creates cleanly. `DROP TABLE` does: with foreign keys on, dropping a table runs an implicit
+ * `DELETE FROM`, which fires the referencing table's constraints. Dropping a parent first therefore
+ * either fails outright or cascades into a child nobody asked to empty, and reversing this order
+ * removes the problem instead of deferring it. That matters because the alternative —
+ * `PRAGMA defer_foreign_keys` — moves the failure to the commit at the request boundary, which in a
+ * Durable Object resets the whole object and discards everything the request did.
+ *
+ * Alphabetical within a tier and alphabetical at the roots, so the result is still a byte-stable
+ * function of the schema. A reference cycle cannot be ordered; the walk breaks it at a deterministic
+ * point and leaves the caller to cope, which for `CREATE` is free and for `DROP` is the one case
+ * ordering cannot solve.
+ */
+/**
+ * A cycle in the reference graph, as the tables that form it, or `null` when there is none.
+ *
+ * A cycle is refused rather than ordered around, because there is no order that satisfies it. Two
+ * tables that reference each other can be *created* in either order — SQLite resolves a forward
+ * reference at write time — but they cannot be *dropped* in any order at all: whichever goes first
+ * fires the other's constraint. The only escape is `PRAGMA defer_foreign_keys`, and a violation
+ * still pending when the request ends resets the whole Durable Object and discards everything the
+ * request did. So the hazard is removed here, at check time, rather than mitigated at apply time.
+ *
+ * A self-reference is not a cycle: a tree's `parentId` orders against nothing and drops fine.
+ */
+export declare function referenceCycle(schema: NormalizedDatabaseSchemaV0): string[] | null;
+export declare function tableCreationOrder(schema: NormalizedDatabaseSchemaV0): string[];
+/**
+ * Every table's DDL, parents first, in a deterministic order so two runs of the same schema are
+ * byte-identical. Reverse this order to drop them; see {@link tableCreationOrder}.
+ */
+export declare function databaseDdl(schema: NormalizedDatabaseSchemaV0): readonly TableDdlV0[];

package/vendor/spec/table-ddl.js

@@ -0,0 +1,508 @@
+/**
+ * Translation from a declared application schema into the SQLite DDL that backs it: one real table
+ * per declared table, one real column per declared field.
+ *
+ * This replaces a generic single-table document store, where every application table's rows shared
+ * one physical `xeer_records` table with their fields packed into a JSON column. That shape made
+ * four things structurally impossible, because a table-level constraint cannot be scoped to a
+ * subset of a shared table's rows:
+ *
+ *   per-field NOT NULL, per-table CHECK (so: no enums), FOREIGN KEY (so: no cascade), real types.
+ *
+ * With one table per declared table those are ordinary DDL, and the runtime stops hand-rolling what
+ * the database already does. The module is dependency-free and lives in `spec` for the reason
+ * `storage.ts` gives: the compiler validates against these rules and the runtime applies them, and
+ * a rule the two disagreed on would mean an application that builds and then fails at call time.
+ *
+ * Everything the manifest can say about a column is said in DDL here, and every identifier and
+ * literal reaches the statement through `sql-expression.ts` rather than by concatenation — which is
+ * also why an author-written expression is lexed and re-emitted instead of interpolated.
+ *
+ * The generator is total: `tableDdl` throws rather than emitting a statement it cannot vouch for, so
+ * a definition that reaches it is either valid DDL or an error, never invalid SQL. The manifest
+ * schema runs it as its final check for exactly that reason.
+ *
+ * That promise once held only for what this module inspected and not for what it merely passed
+ * through. An author-written expression was lexed but never parsed, so `title AND`, `lower()` and
+ * `max(position)` each generated a clean `CREATE TABLE` that SQLite then refused — `near ")": syntax
+ * error`, `wrong number of arguments to function lower()`, `misuse of aggregate function max()` —
+ * turning a diagnostic into a failure when the schema was applied. `sql-expression.ts` now validates
+ * grammar and argument counts, which is what closes the gap; the tests below carry the corpus of
+ * expressions that used to get through.
+ */
+import { compileSqlExpression, sqlBlobLiteral, sqlIdentifier, sqlNumberLiteral, sqlStringLiteral, } from './sql-expression.js';
+/**
+ * Identifier prefixes an application may not name a table with.
+ *
+ * `xeer_` and `_xeer_` are the runtime's own bookkeeping tables. `sqlite_` and `_cf_` are refused by
+ * SQLite and by workerd respectively, so those two are reservations the platform already enforces.
+ * `__cf_` and `cf_` are *not* — measured in workerd, a table called `__cf_anything` is created
+ * happily — but the platform keeps its key-value data in a hidden `__cf_kv`, so this list reserves
+ * the prefix as policy rather than relying on an enforcement that does not exist.
+ *
+ * A declared table is created under its own plain name — so that `SELECT * FROM posts` is what an
+ * operator actually types — which is only safe if these cannot collide with it.
+ */
+export const RESERVED_TABLE_PREFIXES = Object.freeze(['xeer_', '_xeer_', 'sqlite_', '_cf_', '__cf_']);
+/** SQLite identifiers are case-insensitive, so the reservation has to be too. */
+export function reservedTableName(name) {
+    const normalized = name.toLowerCase();
+    return RESERVED_TABLE_PREFIXES.some((prefix) => normalized.startsWith(prefix));
+}
+const quote = sqlIdentifier;
+/**
+ * The physical name of a declared index.
+ *
+ * Length-prefixed because SQLite holds indexes and tables in one namespace and a naive
+ * `${table}_${index}` is ambiguous: table `posts` index `by_slug` and table `posts_by` index `slug`
+ * would both want `posts_by_slug`. Index names are never typed by hand, so legibility is worth less
+ * here than a proof that two declarations can never claim one name.
+ */
+export function physicalIndexName(tableName, indexName) {
+    return `xeer_index_${tableName.length}_${tableName}_${indexName.length}_${indexName}`;
+}
+/**
+ * The index over `(created_at, id)` that every table carries whether or not it declares one.
+ *
+ * Every read the runtime issues ends `ORDER BY created_at, id` — it is the total order rows are
+ * returned in, and the one admin paging seeks into — so without this each read is a full scan and a
+ * sort. The single-table store had exactly this index and it was lost when rows moved into per-table
+ * tables; this puts it back per table.
+ *
+ * A distinct prefix from {@link physicalIndexName}, so it can never collide with a declared index
+ * however that index is named.
+ */
+export function rowOrderIndexName(tableName) {
+    return `xeer_rows_${tableName.length}_${tableName}`;
+}
+/**
+ * The storage class each declared type is held in.
+ *
+ * `number` is NUMERIC rather than REAL so that a whole number is stored — and dumped by a CLI — as
+ * `7` rather than `7.0`, while a fractional one keeps its precision. A JavaScript number is an IEEE
+ * double either way; NUMERIC only decides which of the two SQLite representations it lands in. When
+ * the schema vocabulary grows an explicit integer type — what `z.number().int()` would compile to
+ * if schemas ever move into TypeScript — it maps to INTEGER here and `number` keeps NUMERIC.
+ *
+ * `datetime` is ISO-8601 TEXT so lexical order is chronological order, which is what lets `ORDER BY`
+ * work on a timestamp with no conversion. `bytes` is a real BLOB rather than base64 in a string:
+ * smaller, and one encode/decode hop removed from every read and write. `ref` is TEXT because the
+ * `id` it points at is.
+ */
+const STORAGE_CLASS = Object.freeze({
+    string: 'TEXT',
+    number: 'NUMERIC',
+    boolean: 'INTEGER',
+    datetime: 'TEXT',
+    bytes: 'BLOB',
+    json: 'TEXT',
+    ref: 'TEXT',
+});
+const REFERENTIAL_ACTION_SQL = Object.freeze({
+    noAction: 'NO ACTION',
+    restrict: 'RESTRICT',
+    cascade: 'CASCADE',
+    setNull: 'SET NULL',
+    setDefault: 'SET DEFAULT',
+});
+const COLLATION_SQL = Object.freeze({
+    binary: 'BINARY',
+    nocase: 'NOCASE',
+    rtrim: 'RTRIM',
+});
+/** The runtime-owned columns, named here so a declaration can be checked against them. */
+export const RUNTIME_COLUMN_NAMES = Object.freeze(['id', 'created_at', 'updated_at']);
+/**
+ * Cloudflare's SQLite caps a table at 100 columns, well below stock SQLite's 2000. Measured in
+ * workerd: the hundredth column is accepted and the hundred-and-first fails with "too many columns".
+ */
+export const MAX_TABLE_COLUMNS = 100;
+/**
+ * The most fields a table may declare: the platform's column limit less the runtime's own three.
+ *
+ * Generated columns are charged against it, virtual and stored alike — confirmed in workerd, where
+ * a table of 100 columns including five generated ones is accepted and 101 is not. Refusing this at
+ * check time turns a schema that cannot be applied into a diagnostic while it is being written.
+ */
+export const MAX_TABLE_FIELDS = MAX_TABLE_COLUMNS - RUNTIME_COLUMN_NAMES.length;
+/**
+ * The runtime-owned columns every table carries. They lead the column list so a `SELECT *` — in the
+ * CLI, in a dump, in the admin editor — reads identity first and payload second, and they are
+ * reserved in the manifest schema so a declared field can never collide with one.
+ */
+const RUNTIME_COLUMNS = Object.freeze([
+    '"id" TEXT PRIMARY KEY NOT NULL',
+    '"created_at" TEXT NOT NULL',
+    '"updated_at" TEXT NOT NULL',
+]);
+export class TableDdlError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'TableDdlError';
+    }
+}
+function fail(message) {
+    throw new TableDdlError(message);
+}
+/**
+ * A default is written in the JavaScript type its field is written in, so the field type decides
+ * both which literal syntax to emit and which JavaScript type is even accepted. Getting this wrong
+ * is otherwise invisible until a row is inserted: SQLite does not check a DEFAULT against the
+ * column's own CHECK constraints at CREATE time, only when the default is actually used.
+ */
+function defaultLiteral(name, field) {
+    const value = field.default;
+    const wrong = (expected) => fail(`Field ${JSON.stringify(name)} has a ${typeof value} default but a ${field.type} field needs ${expected}.`);
+    switch (field.type) {
+        case 'number':
+            return typeof value === 'number' ? sqlNumberLiteral(value) : wrong('a number');
+        case 'boolean':
+            return typeof value === 'boolean' ? (value ? '1' : '0') : wrong('a boolean');
+        case 'bytes':
+            return typeof value === 'string' ? sqlBlobLiteral(value) : wrong('a lowercase hex string');
+        default:
+            return typeof value === 'string' ? sqlStringLiteral(value) : wrong('a string');
+    }
+}
+/**
+ * Column-level CHECKs that hold a value to its declared contract.
+ *
+ * Nothing here special-cases an optional field: SQLite evaluates a CHECK against NULL to NULL, and a
+ * CHECK only fails on a definite false, so a nullable column passes without an `OR … IS NULL` arm.
+ */
+function checks(name, field) {
+    const column = quote(name);
+    const constraints = [];
+    if (field.type === 'boolean')
+        constraints.push(`${column} IN (0, 1)`);
+    // Affinity is a preference, not a constraint: a NUMERIC column still accepts 'abc' and stores it
+    // as text. This is what actually makes the column numeric. (A STRICT table looks like it would do
+    // the same job for every type at once, and is twice unusable: STRICT forbids NUMERIC as a column
+    // type, which would force whole numbers back to `7.0`, and it does not even buy the guarantee —
+    // measured in workerd, a STRICT INTEGER column silently coerces the string '42' to 42. So the
+    // guarantee is bought per column instead.)
+    if (field.type === 'number')
+        constraints.push(`typeof(${column}) IN ('integer', 'real')`);
+    if (field.type === 'json')
+        constraints.push(`json_valid(${column})`);
+    // `length()` counts characters on TEXT and bytes on a BLOB, which is exactly what `maxLength`
+    // means for each of the two types the manifest allows it on.
+    if (field.maxLength !== undefined)
+        constraints.push(`length(${column}) <= ${sqlNumberLiteral(field.maxLength)}`);
+    if (field.enum !== undefined) {
+        if (field.type !== 'string')
+            fail(`Field ${JSON.stringify(name)} declares an enum, which only a string field may.`);
+        if (field.enum.length === 0)
+            fail(`Field ${JSON.stringify(name)} declares an empty enum, which no value could satisfy.`);
+        constraints.push(`${column} IN (${field.enum.map(sqlStringLiteral).join(', ')})`);
+    }
+    return constraints.map((constraint) => `CHECK (${constraint})`);
+}
+/**
+ * The FOREIGN KEY clause of a `ref` column.
+ *
+ * `SET NULL` on a NOT NULL column and `SET DEFAULT` on a column with no default are both accepted by
+ * `CREATE TABLE` and then fail every delete that triggers them — a schema that is valid to write and
+ * impossible to use. They are refused here instead.
+ *
+ * There is a third case of that shape which cannot be refused here, because it depends on rows
+ * rather than on the schema: `SET DEFAULT` whose default is not the id of any row in the referenced
+ * table. Measured in workerd, the delete that fires it fails with `FOREIGN KEY constraint failed`,
+ * because the action writes a value the constraint then rejects. Nothing static can see that, so a
+ * default used this way has to name a row the application guarantees exists.
+ *
+ * There is deliberately no way to declare a constraint `DEFERRABLE INITIALLY DEFERRED`, and it must
+ * stay that way. The clause parses, but the violation is then only detected when the transaction
+ * commits — and a Durable Object answers a failed commit by resetting and rolling back the entire
+ * object, not by rejecting the row. Measured in workerd: the orphan insert returns success and the
+ * object is destroyed a moment later. A constraint whose cost is the whole object is worse than one
+ * that fires immediately, so every FK here is immediate.
+ */
+function referenceClause(name, field) {
+    if (field.table === undefined) {
+        fail(`Field ${JSON.stringify(name)} is a ref but names no table to reference.`);
+    }
+    if (reservedTableName(field.table)) {
+        fail(`Field ${JSON.stringify(name)} references ${JSON.stringify(field.table)}, which is a reserved table name.`);
+    }
+    for (const [event, action] of [['DELETE', field.onDelete], ['UPDATE', field.onUpdate]]) {
+        if (action === 'setNull' && field.optional !== true) {
+            fail(`Field ${JSON.stringify(name)} declares ON ${event} SET NULL but is not optional, so every ${event.toLowerCase()} it fires on would fail.`);
+        }
+        if (action === 'setDefault' && field.default === undefined) {
+            fail(`Field ${JSON.stringify(name)} declares ON ${event} SET DEFAULT but has no default, so every ${event.toLowerCase()} it fires on would fail.`);
+        }
+    }
+    return [
+        `REFERENCES ${quote(field.table)} ("id")`,
+        ...(field.onDelete === undefined ? [] : [`ON DELETE ${REFERENTIAL_ACTION_SQL[field.onDelete]}`]),
+        ...(field.onUpdate === undefined ? [] : [`ON UPDATE ${REFERENTIAL_ACTION_SQL[field.onUpdate]}`]),
+    ].join(' ');
+}
+function columnDefinition(name, field, columns) {
+    if (field.generated && field.default !== undefined) {
+        fail(`Field ${JSON.stringify(name)} is generated and also declares a default, which SQLite has no meaning for.`);
+    }
+    // A generated column may read the others but not itself; SQLite would reject the loop, later.
+    const generated = field.generated
+        ? compileSqlExpression(field.generated.expression, columns.filter((column) => column !== name))
+        : null;
+    return [
+        quote(name),
+        STORAGE_CLASS[field.type],
+        ...(generated ? [`GENERATED ALWAYS AS (${generated.sql}) ${field.generated.stored === true ? 'STORED' : 'VIRTUAL'}`] : []),
+        ...(field.optional === true ? [] : ['NOT NULL']),
+        ...(field.default === undefined ? [] : [`DEFAULT ${defaultLiteral(name, field)}`]),
+        // Before UNIQUE, so the implicit index SQLite builds for it compares under this collation.
+        ...(field.collate === undefined ? [] : [`COLLATE ${COLLATION_SQL[field.collate]}`]),
+        ...(field.unique === true ? ['UNIQUE'] : []),
+        ...checks(name, field),
+        ...(field.type === 'ref' ? [referenceClause(name, field)] : []),
+    ].join(' ');
+}
+/**
+ * SQLite rejects a generated column that depends on itself only once the whole CREATE TABLE is
+ * parsed, and reports it as a "generated column loop" naming no column. Finding the cycle here means
+ * the diagnostic can name the columns in it.
+ */
+function refuseGeneratedCycles(table, readable) {
+    const reads = new Map();
+    const names = Object.keys(table.fields).sort();
+    for (const name of names) {
+        const generated = table.fields[name].generated;
+        if (!generated)
+            continue;
+        const { columns } = compileSqlExpression(generated.expression, readable.filter((other) => other !== name));
+        // A runtime column is never generated, so it can never be part of a cycle.
+        reads.set(name, columns.filter((column) => table.fields[column]?.generated !== undefined));
+    }
+    const settled = new Set();
+    const walking = new Set();
+    const walk = (name, path) => {
+        if (settled.has(name))
+            return;
+        if (walking.has(name)) {
+            fail(`Generated columns form a cycle: ${[...path, name].map((entry) => JSON.stringify(entry)).join(' → ')}.`);
+        }
+        walking.add(name);
+        for (const next of reads.get(name) ?? [])
+            walk(next, [...path, name]);
+        walking.delete(name);
+        settled.add(name);
+    };
+    for (const name of reads.keys())
+        walk(name, []);
+}
+function normalizedTerm(term) {
+    if (typeof term === 'string')
+        return { column: term, expression: null, collate: null, desc: false };
+    if ('column' in term) {
+        return { column: term.column, expression: null, collate: term.collate ?? null, desc: term.desc === true };
+    }
+    return { column: null, expression: term.expression, collate: null, desc: term.desc === true };
+}
+/**
+ * The full form of an index, which the array shorthand is sugar for. Every consumer — the DDL below,
+ * the schema hash, the change plan — reads the index through here, so the two spellings of one index
+ * are the same index everywhere and not just where someone remembered to handle both.
+ */
+export function normalizedIndex(definition) {
+    const index = Array.isArray(definition) ? { columns: definition } : definition;
+    return {
+        columns: index.columns.map(normalizedTerm),
+        unique: index.unique === true,
+        where: index.where ?? null,
+    };
+}
+/** The declared columns an index reads, for callers that only need to know what it covers. */
+export function indexColumns(definition) {
+    return normalizedIndex(definition).columns
+        .flatMap((term) => (term.column === null ? [] : [term.column]));
+}
+/** How one index member reads in a diagnostic: `status`, `position DESC`, `(lower("title"))`. */
+export function indexTermLabel(term) {
+    return [
+        term.column ?? `(${term.expression})`,
+        ...(term.collate === null ? [] : [`COLLATE ${COLLATION_SQL[term.collate]}`]),
+        ...(term.desc ? ['DESC'] : []),
+    ].join(' ');
+}
+/**
+ * One index member as SQL.
+ *
+ * A word on the per-term `collate`: prefer a collation on the *column* wherever the choice exists.
+ * An index built `COLLATE NOCASE` over a column whose own collation is BINARY is only used when the
+ * query repeats `COLLATE NOCASE` in the same place — otherwise the planner considers the index
+ * inapplicable and falls back to a full scan, which is measurable in workerd and silent in
+ * production. A column-level collation has no such trap, because every comparison on the column
+ * inherits it. Term-level collation is here for the case a column genuinely needs two orderings.
+ */
+function indexTerm(term, columns) {
+    const parts = [];
+    if (term.column === null) {
+        parts.push(`(${compileSqlExpression(term.expression, columns).sql})`);
+    }
+    else {
+        if (!columns.includes(term.column))
+            fail(`Index term ${JSON.stringify(term.column)} is not a declared field.`);
+        parts.push(quote(term.column));
+        if (term.collate !== null)
+            parts.push(`COLLATE ${COLLATION_SQL[term.collate]}`);
+    }
+    if (term.desc)
+        parts.push('DESC');
+    return parts.join(' ');
+}
+export function tableDdl(name, table) {
+    if (reservedTableName(name)) {
+        throw new Error(`Table name ${JSON.stringify(name)} is reserved: it would shadow a platform table. `
+            + `Reserved prefixes are ${RESERVED_TABLE_PREFIXES.join(', ')}.`);
+    }
+    const fields = Object.keys(table.fields).sort();
+    if (fields.length > MAX_TABLE_FIELDS) {
+        fail(`Table ${JSON.stringify(name)} declares ${fields.length} fields and the limit is ${MAX_TABLE_FIELDS}: `
+            + `the platform caps a table at ${MAX_TABLE_COLUMNS} columns and the runtime owns `
+            + `${RUNTIME_COLUMN_NAMES.join(', ')}. Generated columns count against it too.`);
+    }
+    // The runtime columns are emitted unconditionally, so a field of the same name would be a second
+    // column of that name and SQLite would answer `duplicate column name`. The manifest schema also
+    // reserves the camel-cased spellings an author is more likely to reach for; this catches the
+    // physical names, which are what actually collide.
+    for (const field of fields) {
+        if (RUNTIME_COLUMN_NAMES.includes(field)) {
+            fail(`Field ${JSON.stringify(field)} on ${JSON.stringify(name)} is a reserved runtime column: `
+                + `every table already carries ${RUNTIME_COLUMN_NAMES.join(', ')}. An expression may read them, `
+                + 'but a field may not redeclare one.');
+        }
+    }
+    /**
+     * What an expression or index term of this table may name: the declared fields plus the runtime
+     * columns, which are real columns of the table. `ORDER BY created_at DESC` is the ordinary way to
+     * read a table and it needs an index, which it cannot have if the column cannot be named.
+     */
+    const readable = [...RUNTIME_COLUMN_NAMES, ...fields].sort();
+    refuseGeneratedCycles(table, readable);
+    const uniqueConstraints = (table.unique ?? []).map((tuple) => {
+        if (tuple.length === 0)
+            fail(`Table ${JSON.stringify(name)} declares an empty UNIQUE tuple.`);
+        const seen = new Set();
+        for (const field of tuple) {
+            if (!fields.includes(field))
+                fail(`UNIQUE tuple on ${JSON.stringify(name)} names ${JSON.stringify(field)}, which is not a declared field.`);
+            if (seen.has(field))
+                fail(`UNIQUE tuple on ${JSON.stringify(name)} names ${JSON.stringify(field)} twice.`);
+            seen.add(field);
+        }
+        return `UNIQUE (${tuple.map(quote).join(', ')})`;
+    });
+    // Named, because SQLite quotes the constraint name in the error it raises — which is the whole
+    // difference between "CHECK constraint failed: posts" and one that says which rule was broken.
+    const checkConstraints = Object.keys(table.checks ?? {}).sort().map((checkName) => `CONSTRAINT ${quote(checkName)} CHECK (${compileSqlExpression(table.checks[checkName], readable).sql})`);
+    const columns = [
+        ...RUNTIME_COLUMNS,
+        ...fields.map((field) => columnDefinition(field, table.fields[field], readable)),
+        ...uniqueConstraints,
+        ...checkConstraints,
+    ];
+    const createTable = `CREATE TABLE IF NOT EXISTS ${quote(name)} (\n  ${columns.join(',\n  ')}\n)`;
+    const rowOrderIndex = `CREATE INDEX IF NOT EXISTS ${quote(rowOrderIndexName(name))} `
+        + `ON ${quote(name)} (${quote('created_at')}, ${quote('id')})`;
+    const createIndexes = Object.keys(table.indexes ?? {}).sort().map((indexName) => {
+        const index = normalizedIndex(table.indexes[indexName]);
+        if (index.columns.length === 0)
+            fail(`Index ${JSON.stringify(indexName)} on ${JSON.stringify(name)} has no terms.`);
+        const termList = index.columns.map((term) => indexTerm(term, readable)).join(', ');
+        return `CREATE ${index.unique ? 'UNIQUE ' : ''}INDEX IF NOT EXISTS ${quote(physicalIndexName(name, indexName))} `
+            + `ON ${quote(name)} (${termList})`
+            + (index.where === null ? '' : ` WHERE ${compileSqlExpression(index.where, readable).sql}`);
+    });
+    return { table: name, createTable, rowOrderIndex, createIndexes };
+}
+/**
+ * Declared tables ordered so that a table always follows the tables it references.
+ *
+ * `CREATE TABLE` does not need this — SQLite resolves a forward `REFERENCES` at write time, so any
+ * order creates cleanly. `DROP TABLE` does: with foreign keys on, dropping a table runs an implicit
+ * `DELETE FROM`, which fires the referencing table's constraints. Dropping a parent first therefore
+ * either fails outright or cascades into a child nobody asked to empty, and reversing this order
+ * removes the problem instead of deferring it. That matters because the alternative —
+ * `PRAGMA defer_foreign_keys` — moves the failure to the commit at the request boundary, which in a
+ * Durable Object resets the whole object and discards everything the request did.
+ *
+ * Alphabetical within a tier and alphabetical at the roots, so the result is still a byte-stable
+ * function of the schema. A reference cycle cannot be ordered; the walk breaks it at a deterministic
+ * point and leaves the caller to cope, which for `CREATE` is free and for `DROP` is the one case
+ * ordering cannot solve.
+ */
+/**
+ * A cycle in the reference graph, as the tables that form it, or `null` when there is none.
+ *
+ * A cycle is refused rather than ordered around, because there is no order that satisfies it. Two
+ * tables that reference each other can be *created* in either order — SQLite resolves a forward
+ * reference at write time — but they cannot be *dropped* in any order at all: whichever goes first
+ * fires the other's constraint. The only escape is `PRAGMA defer_foreign_keys`, and a violation
+ * still pending when the request ends resets the whole Durable Object and discards everything the
+ * request did. So the hazard is removed here, at check time, rather than mitigated at apply time.
+ *
+ * A self-reference is not a cycle: a tree's `parentId` orders against nothing and drops fine.
+ */
+export function referenceCycle(schema) {
+    const parentsOf = (name) => [...new Set(Object.values(schema.tables[name].fields)
+            .filter((field) => field.type === 'ref' && field.table !== undefined
+            && field.table !== name && schema.tables[field.table] !== undefined)
+            .map((field) => field.table))].sort();
+    const settled = new Set();
+    const walking = [];
+    const walk = (name) => {
+        const open = walking.indexOf(name);
+        if (open >= 0)
+            return [...walking.slice(open), name];
+        if (settled.has(name))
+            return null;
+        walking.push(name);
+        for (const parent of parentsOf(name)) {
+            const cycle = walk(parent);
+            if (cycle)
+                return cycle;
+        }
+        walking.pop();
+        settled.add(name);
+        return null;
+    };
+    for (const name of Object.keys(schema.tables).sort()) {
+        const cycle = walk(name);
+        if (cycle)
+            return cycle;
+    }
+    return null;
+}
+export function tableCreationOrder(schema) {
+    const names = Object.keys(schema.tables).sort();
+    const referenced = (name) => [...new Set(Object.values(schema.tables[name].fields)
+            .filter((field) => field.type === 'ref' && field.table !== undefined
+            && field.table !== name && schema.tables[field.table] !== undefined)
+            .map((field) => field.table))].sort();
+    const ordered = [];
+    const placed = new Set();
+    const walking = new Set();
+    const visit = (name) => {
+        if (placed.has(name) || walking.has(name))
+            return;
+        walking.add(name);
+        for (const parent of referenced(name))
+            visit(parent);
+        walking.delete(name);
+        placed.add(name);
+        ordered.push(name);
+    };
+    for (const name of names)
+        visit(name);
+    return ordered;
+}
+/**
+ * Every table's DDL, parents first, in a deterministic order so two runs of the same schema are
+ * byte-identical. Reverse this order to drop them; see {@link tableCreationOrder}.
+ */
+export function databaseDdl(schema) {
+    return tableCreationOrder(schema).map((name) => tableDdl(name, schema.tables[name]));
+}