@impetik/xeer-mcp 0.2.5 → 0.2.7

package/vendor/spec/schema.js

@@ -0,0 +1,409 @@
+import { z } from 'zod';
+import { CAPABILITIES, SOURCE_FORMAT, } from './types.js';
+import { STORAGE_DEFAULT_READ_BYTES, STORAGE_DEFAULT_WRITE_BYTES, STORAGE_MAX_OBJECT_BYTES, STORAGE_MAX_READ_BYTES, STORAGE_MAX_WRITE_BYTES, } from './storage.js';
+import { SQL_EXPRESSION_MAX_LENGTH } from './sql-expression.js';
+import { databaseDdl, indexColumns, referenceCycle, RESERVED_TABLE_PREFIXES, reservedTableName } from './table-ddl.js';
+const identifier = z.string().regex(/^[A-Za-z][A-Za-z0-9_]*$/, 'must be an identifier');
+const sourcePath = z.string().min(1).refine((value) => !value.includes('\\'), 'must use forward slashes');
+const title = z.string().min(1).max(120)
+    .refine((value) => value === value.trim(), 'must not have leading or trailing whitespace')
+    .refine((value) => !/[\u0000-\u001f\u007f]/.test(value), 'must not contain control characters');
+const language = z.string().max(35)
+    .regex(/^[A-Za-z]{2,3}(?:-[A-Za-z0-9]{2,8})*$/, 'must be a constrained BCP 47 language tag');
+const description = z.string().max(300)
+    .refine((value) => value === value.trim(), 'must not have leading or trailing whitespace')
+    .refine((value) => !/[\u0000-\u001f\u007f]/.test(value), 'must not contain control characters');
+const favicon = z.string().min(2).max(256)
+    .regex(/^\/[A-Za-z0-9._~!$&'()*+,;=:@/-]+$/, 'must be a root-relative public asset path')
+    .refine((value) => !value.includes('//'), 'must not contain empty path segments')
+    .refine((value) => value.split('/').slice(1).every((segment) => segment !== '.' && segment !== '..'), 'must not contain dot path segments');
+/**
+ * A SQL expression, bounded but otherwise unexamined here: what may appear inside one is decided by
+ * `sql-expression.ts`, and checking it needs the table's field list, which a field cannot see. The
+ * table and manifest refinements below run the real check by generating the DDL.
+ */
+const expression = z.string().min(1).max(SQL_EXPRESSION_MAX_LENGTH);
+const collation = z.enum(['binary', 'nocase', 'rtrim']);
+const referentialAction = z.enum(['noAction', 'restrict', 'cascade', 'setNull', 'setDefault']);
+const LOWERCASE_HEX = /^(?:[0-9a-f]{2})*$/;
+const ISO_TIMESTAMP = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{1,3})?Z$/;
+/** The types a `default` is written in, one per field type. */
+const DEFAULT_JS_TYPE = Object.freeze({
+    string: 'string', datetime: 'string', json: 'string', bytes: 'string', ref: 'string',
+    number: 'number', boolean: 'boolean',
+});
+/**
+ * A default has to satisfy the column it defaults, and SQLite will not say so. `CREATE TABLE` accepts
+ * a DEFAULT that every CHECK on the column rejects, and only fails once a row actually uses it — so
+ * a schema can be applied cleanly and then refuse the first insert that omits the field.
+ */
+function refineDefault(field, ctx) {
+    const value = field.default;
+    if (value === undefined)
+        return;
+    const issue = (message) => ctx.addIssue({ code: 'custom', path: ['default'], message });
+    if (field.generated)
+        return issue('is not valid on a generated column, which computes its own value');
+    const expected = DEFAULT_JS_TYPE[field.type];
+    if (expected !== undefined && typeof value !== expected) {
+        return issue(`must be a ${expected} for a ${field.type} field`);
+    }
+    if (typeof value !== 'string')
+        return;
+    if (field.type === 'bytes' && !LOWERCASE_HEX.test(value)) {
+        return issue('must be an even number of lowercase hex digits for a bytes field');
+    }
+    if (field.type === 'datetime' && (!ISO_TIMESTAMP.test(value) || Number.isNaN(Date.parse(value)))) {
+        return issue('must be an ISO-8601 UTC timestamp for a datetime field');
+    }
+    if (field.type === 'json') {
+        try {
+            JSON.parse(value);
+        }
+        catch {
+            return issue('must be valid JSON for a json field');
+        }
+    }
+    if (field.enum !== undefined && !field.enum.includes(value)) {
+        return issue('is not one of the declared enum values, so no row could ever hold it');
+    }
+    if (field.maxLength !== undefined && value.length > field.maxLength) {
+        return issue(`is longer than the declared maxLength of ${field.maxLength}`);
+    }
+}
+const fieldSchema = z.strictObject({
+    type: z.enum(['string', 'number', 'boolean', 'datetime', 'bytes', 'json', 'ref']),
+    optional: z.boolean().optional(),
+    maxLength: z.number().int().positive().optional(),
+    unique: z.boolean().optional(),
+    enum: z.array(z.string().max(1_000)).min(1).max(1_000).optional(),
+    default: z.union([z.string().max(1_000), z.number(), z.boolean()]).optional(),
+    collate: collation.optional(),
+    table: identifier.optional(),
+    onDelete: referentialAction.optional(),
+    onUpdate: referentialAction.optional(),
+    generated: z.strictObject({ expression, stored: z.boolean().optional() }).optional(),
+}).superRefine((field, ctx) => {
+    const only = (key, types, message) => {
+        if (field[key] !== undefined && !types.includes(field.type)) {
+            ctx.addIssue({ code: 'custom', path: [key], message });
+        }
+    };
+    only('maxLength', ['string', 'bytes'], 'is only valid for string or bytes fields');
+    only('enum', ['string'], 'is only valid for a string field');
+    only('collate', ['string'], 'is only valid for a string field');
+    only('table', ['ref'], 'is only valid for a ref field');
+    only('onDelete', ['ref'], 'is only valid for a ref field');
+    only('onUpdate', ['ref'], 'is only valid for a ref field');
+    if (field.type === 'ref' && field.table === undefined) {
+        ctx.addIssue({ code: 'custom', path: ['table'], message: 'is required: a ref must name the table it references' });
+    }
+    if (field.enum !== undefined) {
+        for (const [position, value] of field.enum.entries()) {
+            if (field.enum.indexOf(value) !== position) {
+                ctx.addIssue({ code: 'custom', path: ['enum', position], message: `lists ${JSON.stringify(value)} twice` });
+            }
+        }
+    }
+    // Both actions are accepted by CREATE TABLE and then fail every delete or update that fires them.
+    for (const [key, action] of [['onDelete', field.onDelete], ['onUpdate', field.onUpdate]]) {
+        if (action === 'setNull' && field.optional !== true) {
+            ctx.addIssue({ code: 'custom', path: [key], message: 'needs the field to be optional, because it writes NULL' });
+        }
+        if (action === 'setDefault' && field.default === undefined) {
+            ctx.addIssue({ code: 'custom', path: [key], message: 'needs the field to declare a default, because it writes one' });
+        }
+    }
+    refineDefault(field, ctx);
+});
+const indexTermSchema = z.union([
+    identifier,
+    z.strictObject({ column: identifier, collate: collation.optional(), desc: z.boolean().optional() }),
+    z.strictObject({ expression, desc: z.boolean().optional() }),
+]);
+/**
+ * An index is a bare list of columns or the full form. The shorthand covers most indexes and reads
+ * better than the object it means, so it stays rather than being migrated away from.
+ */
+const indexSchema = z.union([
+    z.array(identifier).min(1),
+    z.strictObject({
+        columns: z.array(indexTermSchema).min(1),
+        unique: z.boolean().optional(),
+        where: expression.optional(),
+    }),
+]);
+const tableSchema = z.strictObject({
+    fields: z.record(identifier, fieldSchema),
+    indexes: z.record(identifier, indexSchema).optional(),
+    unique: z.array(z.array(identifier).min(1)).optional(),
+    checks: z.record(identifier, expression).optional(),
+}).superRefine((table, ctx) => {
+    for (const [indexName, definition] of Object.entries(table.indexes ?? {})) {
+        const seen = new Set();
+        for (const [position, field] of indexColumns(definition).entries()) {
+            if (!(field in table.fields)) {
+                ctx.addIssue({
+                    code: 'custom',
+                    path: ['indexes', indexName, position],
+                    message: `references unknown field ${JSON.stringify(field)}`,
+                });
+            }
+            if (seen.has(field)) {
+                ctx.addIssue({
+                    code: 'custom',
+                    path: ['indexes', indexName, position],
+                    message: `duplicates field ${JSON.stringify(field)}`,
+                });
+            }
+            seen.add(field);
+        }
+    }
+    for (const [position, tuple] of (table.unique ?? []).entries()) {
+        const seen = new Set();
+        for (const [member, field] of tuple.entries()) {
+            if (!(field in table.fields)) {
+                ctx.addIssue({ code: 'custom', path: ['unique', position, member],
+                    message: `references unknown field ${JSON.stringify(field)}` });
+            }
+            if (seen.has(field)) {
+                ctx.addIssue({ code: 'custom', path: ['unique', position, member],
+                    message: `duplicates field ${JSON.stringify(field)}` });
+            }
+            seen.add(field);
+        }
+    }
+    for (const reserved of ['id', 'createdAt', 'updatedAt']) {
+        if (reserved in table.fields) {
+            ctx.addIssue({ code: 'custom', path: ['fields', reserved], message: 'is reserved by the runtime' });
+        }
+    }
+});
+/**
+ * The rules a single table cannot check for itself, plus the generator as a backstop.
+ *
+ * A `ref` names another table, which only the whole schema can confirm; and every expression in the
+ * table — a CHECK, a generated column, an index predicate — is only checkable against the field list
+ * the generator already has. Rather than restate those rules, this runs `databaseDdl` and reports
+ * what it refuses. That makes the two impossible to disagree: a manifest passes `xeer check` exactly
+ * when the DDL for it can be generated, which is what `table-ddl.ts` exists to guarantee.
+ */
+function refineDatabaseTables(tables, ctx, base) {
+    for (const tableName of Object.keys(tables)) {
+        // A declared table is created under its own plain name, so `SELECT * FROM posts` is what an
+        // operator types. That is only safe if a declaration cannot claim a name the platform already
+        // uses: an application table called `xeer_logs` would otherwise shadow the runtime's own.
+        if (reservedTableName(tableName)) {
+            ctx.addIssue({
+                code: 'custom',
+                path: [...base, tableName],
+                message: `is a reserved table name; ${RESERVED_TABLE_PREFIXES.join(', ')} are reserved for the platform`,
+            });
+        }
+        const fields = tables[tableName].fields ?? {};
+        for (const [fieldName, field] of Object.entries(fields)) {
+            if (field.type !== 'ref' || field.table === undefined)
+                continue;
+            if (!Object.hasOwn(tables, field.table)) {
+                ctx.addIssue({
+                    code: 'custom',
+                    path: [...base, tableName, 'fields', fieldName, 'table'],
+                    message: `references ${JSON.stringify(field.table)}, which this schema does not declare`,
+                });
+            }
+        }
+    }
+    // A reference cycle has no order that can drop its tables; see `referenceCycle`.
+    const cycle = referenceCycle({ version: 1, tables: tables });
+    if (cycle) {
+        ctx.addIssue({
+            code: 'custom',
+            path: [...base, cycle[0]],
+            message: `takes part in a reference cycle (${cycle.join(' → ')}); the tables in one cannot be created or dropped in any order`,
+        });
+    }
+    for (const tableName of Object.keys(tables)) {
+        try {
+            databaseDdl({ version: 1, tables: { [tableName]: tables[tableName] } });
+        }
+        catch (error) {
+            ctx.addIssue({
+                code: 'custom',
+                path: [...base, tableName],
+                message: error instanceof Error ? error.message : String(error),
+            });
+        }
+    }
+}
+/** The normalized database fragment embedded in artifacts and review metadata. */
+export const normalizedDatabaseSchema = z.strictObject({
+    version: z.number().int().positive(),
+    tables: z.record(identifier, tableSchema),
+}).superRefine((schema, ctx) => refineDatabaseTables(schema.tables, ctx, ['tables']));
+export const applicationManifestSchema = z.strictObject({
+    $schema: z.string().url().optional(),
+    format: z.literal(SOURCE_FORMAT),
+    name: z.string().regex(/^[a-z][a-z0-9-]{1,62}$/, 'must be a lowercase slug between 2 and 63 characters'),
+    entrypoints: z.strictObject({
+        client: sourcePath,
+        server: sourcePath,
+    }),
+    app: z.strictObject({
+        spa: z.boolean().optional(),
+        title: title.optional(),
+        language: language.optional(),
+        description: description.optional(),
+        favicon: favicon.optional(),
+    }).optional(),
+    database: z.strictObject({
+        version: z.number().int().positive().optional(),
+        tables: z.record(identifier, tableSchema),
+    }).optional(),
+    /**
+     * The `storage` capability's declared limits (#29). Every field is capped at the platform ceiling
+     * here rather than clamped silently at call time: a manifest that asks for more than the platform
+     * gives is a repairable diagnostic, and an application whose declared limit is a lie is worse than
+     * one that will not build.
+     */
+    storage: z.strictObject({
+        maxObjectBytes: z.number().int().positive().max(STORAGE_MAX_OBJECT_BYTES).optional(),
+        readBytes: z.number().int().positive().max(STORAGE_MAX_READ_BYTES).optional(),
+        writeBytes: z.number().int().positive().max(STORAGE_MAX_WRITE_BYTES).optional(),
+    }).optional(),
+    capabilities: z.array(z.enum(CAPABILITIES)).optional(),
+    budgets: z.strictObject({
+        queryRows: z.number().int().positive().max(10_000).optional(),
+        mutationWrites: z.number().int().positive().max(1_000).optional(),
+        requestBytes: z.number().int().positive().max(4 * 1024 * 1024).optional(),
+        responseBytes: z.number().int().positive().max(4 * 1024 * 1024).optional(),
+        // Zero is a declaration, not an omission: it says the application wants no server push at all,
+        // and the runtime answers `live_disabled` for it rather than a retryable budget refusal. The
+        // bound is `min(0)` and not `positive()` so the editor schema publishes `minimum: 0`.
+        liveConnections: z.number().int().min(0).max(1_000).optional(),
+    }).optional(),
+}).superRefine((manifest, ctx) => {
+    // Caught here, at `xeer check` time, rather than as a failure when the schema is applied.
+    refineDatabaseTables(manifest.database?.tables ?? {}, ctx, ['database', 'tables']);
+    const capabilities = new Set(manifest.capabilities ?? []);
+    for (const [index, name] of (manifest.capabilities ?? []).entries()) {
+        if ((manifest.capabilities ?? []).indexOf(name) !== index) {
+            ctx.addIssue({ code: 'custom', path: ['capabilities', index], message: `is declared twice: ${JSON.stringify(name)}` });
+        }
+    }
+    if (manifest.database && !capabilities.has('database')) {
+        ctx.addIssue({ code: 'custom', path: ['capabilities'], message: 'must include "database" when a database is declared' });
+    }
+    if (!manifest.database && capabilities.has('database')) {
+        ctx.addIssue({ code: 'custom', path: ['database'], message: 'must be declared when the database capability is enabled' });
+    }
+    // The same two-way rule, for the same reason: a config block nobody granted is dead configuration,
+    // and a granted capability with no block is a limit set nobody declared. Unlike `database`, whose
+    // block carries the whole schema, an empty `"storage": {}` is legitimate — it means "the platform
+    // defaults" — so the block must be *present*, not non-empty.
+    if (manifest.storage && !capabilities.has('storage')) {
+        ctx.addIssue({ code: 'custom', path: ['capabilities'], message: 'must include "storage" when a storage block is declared' });
+    }
+    if (!manifest.storage && capabilities.has('storage')) {
+        ctx.addIssue({ code: 'custom', path: ['storage'],
+            message: 'must be declared when the storage capability is enabled; use {} for the platform defaults' });
+    }
+});
+/** Stable editor-facing schema location emitted into every scaffolded `xeer.app.json`. */
+export const APPLICATION_MANIFEST_SCHEMA_URL = 'https://docs.xeer.run/application-v0.schema.json';
+/**
+ * JSON Schema generated from the same Zod object that validates manifests at runtime. The few
+ * cross-field rules below mirror `superRefine` constraints that JSON Schema can express, while
+ * compiler diagnostics remain authoritative for rules such as index fields referring to a declared
+ * table field.
+ */
+const generatedApplicationManifestJsonSchema = z.toJSONSchema(applicationManifestSchema);
+const generatedManifestProperties = generatedApplicationManifestJsonSchema.properties;
+const describeProperty = (name, description) => ({
+    ...generatedManifestProperties[name],
+    description,
+});
+export const applicationManifestJsonSchema = Object.freeze({
+    ...generatedApplicationManifestJsonSchema,
+    $id: APPLICATION_MANIFEST_SCHEMA_URL,
+    title: 'Xeer application source manifest v0',
+    description: 'The complete declarative application manifest read by the Xeer compiler.',
+    properties: {
+        ...generatedManifestProperties,
+        $schema: describeProperty('$schema', 'Editor schema hint. Xeer does not fetch this URL during validation.'),
+        format: describeProperty('format', 'Manifest protocol discriminator; exactly xeer.application-source.v0.'),
+        name: describeProperty('name', 'Lowercase application slug, between 2 and 63 characters.'),
+        entrypoints: describeProperty('entrypoints', 'Project-relative client and server source entrypoints.'),
+        app: describeProperty('app', 'Browser metadata and SPA behavior.'),
+        database: describeProperty('database', 'Typed application database schema. Requires the database capability.'),
+        storage: describeProperty('storage', 'Private object-storage limits. Requires the storage capability.'),
+        capabilities: {
+            ...describeProperty('capabilities', 'Powers granted to the application. Duplicate names are invalid.'),
+            uniqueItems: true,
+        },
+        budgets: describeProperty('budgets', 'Per-operation resource ceilings, each lowerable from platform defaults.'),
+    },
+    allOf: [
+        {
+            if: { required: ['database'] },
+            then: { required: ['capabilities'], properties: {
+                    capabilities: { type: 'array', contains: { const: 'database' } },
+                } },
+        },
+        {
+            if: { required: ['capabilities'], properties: {
+                    capabilities: { type: 'array', contains: { const: 'database' } },
+                } },
+            then: { required: ['database'] },
+        },
+        {
+            if: { required: ['storage'] },
+            then: { required: ['capabilities'], properties: {
+                    capabilities: { type: 'array', contains: { const: 'storage' } },
+                } },
+        },
+        {
+            if: { required: ['capabilities'], properties: {
+                    capabilities: { type: 'array', contains: { const: 'storage' } },
+                } },
+            then: { required: ['storage'] },
+        },
+    ],
+});
+export function parseApplicationManifest(value) {
+    return applicationManifestSchema.parse(value);
+}
+export function normalizeApplicationManifest(manifest) {
+    return {
+        format: SOURCE_FORMAT,
+        name: manifest.name,
+        entrypoints: { ...manifest.entrypoints },
+        app: {
+            spa: manifest.app?.spa ?? true,
+            title: manifest.app?.title ?? manifest.name,
+            language: manifest.app?.language ?? 'en',
+            description: manifest.app?.description ?? '',
+            favicon: manifest.app?.favicon ?? null,
+        },
+        database: { version: manifest.database?.version ?? 1, tables: manifest.database?.tables ?? {} },
+        // Normalized only when declared. The schema above has already rejected a block without the
+        // capability, so `manifest.storage` being present *is* the capability being granted.
+        storage: manifest.storage
+            ? {
+                maxObjectBytes: manifest.storage.maxObjectBytes ?? STORAGE_MAX_OBJECT_BYTES,
+                readBytes: manifest.storage.readBytes ?? STORAGE_DEFAULT_READ_BYTES,
+                writeBytes: manifest.storage.writeBytes ?? STORAGE_DEFAULT_WRITE_BYTES,
+            }
+            : null,
+        capabilities: [...(manifest.capabilities ?? [])].sort(),
+        budgets: {
+            queryRows: manifest.budgets?.queryRows ?? 1_000,
+            mutationWrites: manifest.budgets?.mutationWrites ?? 100,
+            requestBytes: manifest.budgets?.requestBytes ?? 1_048_576,
+            responseBytes: manifest.budgets?.responseBytes ?? 1_048_576,
+            // Off unless the application asks for it. One browser tab holding a live query pins the
+            // application's Durable Object continuously, so a positive default charged every application
+            // for a feature most never used. Declare a positive value to turn it on.
+            liveConnections: manifest.budgets?.liveConnections ?? 0,
+        },
+    };
+}

package/vendor/spec/sql-expression.d.ts

@@ -0,0 +1,91 @@
+/**
+ * The SQL text primitives every generated statement is built out of, and the one place an
+ * author-written expression is allowed to become SQL.
+ *
+ * A manifest may carry expressions — a table CHECK, a generated column, a partial index's WHERE, an
+ * index over `lower(title)`. There is no way to bind those as parameters: they are DDL, not values,
+ * so they reach SQLite as text. That makes them the only part of the manifest that could smuggle
+ * syntax into a statement, and the reason this module exists is to make "expression" a closed
+ * vocabulary rather than a passthrough.
+ *
+ * The expression is lexed into tokens and re-emitted from them. Nothing survives that the lexer did
+ * not recognize, which buys three things at once:
+ *
+ *   - **Escaping.** A column reference is re-emitted through {@link sqlIdentifier} and a string
+ *     through {@link sqlStringLiteral}, so quoting is structural rather than a rule someone has to
+ *     remember. There is no path by which raw author text reaches the statement.
+ *   - **Scope.** Every bare word is either a keyword, an allowlisted function, or a column of *this*
+ *     table. A statement separator, a comment, a bind parameter, a qualified `other.column`, and the
+ *     word `SELECT` all have no token, so a subquery cannot be written at all.
+ *   - **Determinism.** Whitespace and keyword case are normalized on the way out, so the same
+ *     expression always produces byte-identical DDL.
+ *
+ * The function allowlist holds only *deterministic* functions. That is not caution: SQLite refuses a
+ * non-deterministic function in a CHECK, a generated column, and an index, so `datetime('now')` in
+ * any of those positions is an error at CREATE time. Rejecting it here turns a failure when the
+ * schema is applied into a diagnostic when it is written.
+ */
+/** Every function an expression may call. Deterministic only — see the module comment. */
+export declare const SQL_EXPRESSION_FUNCTIONS: readonly string[];
+/**
+ * How many arguments each allowlisted function takes, as `[minimum, maximum]`.
+ *
+ * SQLite reports a bad count as `wrong number of arguments to function lower()` when the statement
+ * is prepared, which for DDL means when the schema is applied rather than when it is written. The
+ * table is exhaustive over {@link SQL_EXPRESSION_FUNCTIONS} and a test holds it that way, because a
+ * function reachable without an entry would be a function nobody counts.
+ *
+ * `max` and `min` are the reason this is not merely tidiness. Both are scalar with two or more
+ * arguments and *aggregates* with one, and SQLite answers the aggregate form with `misuse of
+ * aggregate function max()` in a CHECK, a generated column and an index alike. Requiring two
+ * arguments keeps `max(position, 0)` and turns `max(position)` into a diagnostic.
+ */
+export declare const SQL_FUNCTION_ARITY: Readonly<Record<string, readonly [number, number]>>;
+/**
+ * The longest expression a manifest may declare. An expression is copied verbatim into the schema
+ * hash, the DDL, and every diagnostic that quotes it, so it is bounded for the same reason a field
+ * name is.
+ */
+export declare const SQL_EXPRESSION_MAX_LENGTH = 1000;
+/**
+ * The most interior nodes an expression may build.
+ *
+ * Cloudflare's SQLite refuses an expression tree deeper than 100. Measured in workerd by bisection:
+ * a chain of 100 bare terms — that is, 99 `AND` operators — parses, and 101 terms (100 operators)
+ * fails with "Expression tree is too large (maximum depth 100)". The limit counts operators rather
+ * than terms. The character cap does not stand in for it: 1000 characters buys well over 100 terms,
+ * so without a node budget a manifest could pass `xeer check` and then fail to apply.
+ *
+ * Every interior node of the tree is built by exactly one operator, function call, or grammar
+ * keyword, and a root-to-leaf path visits each of its nodes once — so depth never exceeds the count
+ * of those tokens. Counting them is therefore a sound upper bound, and one that stays cheap: it
+ * needs no parser, only the tokens the lexer already produced.
+ *
+ * What is deliberately *not* counted is anything that costs no depth. An `IN` list is a single node
+ * however many values it holds — 2000 of them parse, and 1000 of them still reject a non-member —
+ * so a long enum is free.
+ * Parentheses are free too: workerd parsed 200 nested ones without complaint.
+ */
+export declare const SQL_EXPRESSION_MAX_NODES = 90;
+export declare class SqlExpressionError extends Error {
+    constructor(message: string);
+}
+/** `title` → `"title"`. Doubling the quote is the whole of SQLite's identifier escaping. */
+export declare function sqlIdentifier(name: string): string;
+/** `O'Brien` → `'O''Brien'`. Doubling the apostrophe is the whole of SQLite's string escaping. */
+export declare function sqlStringLiteral(value: string): string;
+/** `00ff` → `X'00ff'`. Lowercase hex only, so one byte sequence has exactly one spelling. */
+export declare function sqlBlobLiteral(hex: string): string;
+/** SQL has no spelling for NaN or an infinity, so a number that is not finite has no literal. */
+export declare function sqlNumberLiteral(value: number): string;
+export interface CompiledSqlExpressionV0 {
+    /** The canonical SQL text, safe to embed in a statement. */
+    readonly sql: string;
+    /** Every column the expression reads, sorted and deduplicated. */
+    readonly columns: readonly string[];
+}
+/**
+ * Validate an author-written expression against the columns it is allowed to read, and return the
+ * canonical SQL for it. Throws {@link SqlExpressionError} with a message naming the rule it broke.
+ */
+export declare function compileSqlExpression(source: string, columns: readonly string[]): CompiledSqlExpressionV0;