@workerstack/testing 0.0.0-stage → 0.31.0

package/dist/api/reference/stores/postgres.js

@@ -0,0 +1,188 @@
+/**
+ * Postgres-backed storage for the reference backend.
+ *
+ * Present because Postgres disagrees with SQLite in exactly the places API contracts are
+ * ambiguous, which makes the pair a differential oracle rather than a redundant one:
+ *
+ *   - Types are enforced, so a value is stored as its declared type, not by affinity.
+ *   - Collation is locale-aware, so ordering of unicode and mixed case is a real decision.
+ *   - `LIKE` and `ILIKE` are genuinely different operators rather than one with a pragma.
+ *
+ * Each server instance gets its own scratch database, dropped on close, so runs never collide.
+ */
+import postgres from "postgres";
+import { ENTITIES } from "../model/entities.js";
+import { compileOrder, compileWhere, likeText } from "./sql-compile.js";
+/** The real driver: postgres.js against the server the environment names, its notices silenced. */
+export function connectPostgres(database, max) {
+    return postgres({ database, max, onnotice: () => { } });
+}
+const PG_TYPE = {
+    boolean: "boolean",
+    integer: "bigint",
+    number: "double precision",
+    array: "text",
+    object: "text",
+    string: "text",
+};
+function ident(name) {
+    return `"${name.replace(/"/g, '""')}"`;
+}
+/* How Postgres spells what the shared compiler leaves to the engine. */
+function pgFlavor() {
+    return {
+        binary: (expr) => `${expr} COLLATE "C"`,
+        bind: (args, value) => {
+            args.push(value);
+            return `$${args.length}`;
+        },
+        bool: (value) => value,
+        /* Reads name the declared column. Under COLUMN_NAME_MISMATCH DDL named it otherwise,
+         * and Postgres refuses the read outright where SQLite might silently answer. */
+        column: (_entity, field) => ident(field),
+        hasElement: (expr, element, args) => {
+            args.push(element);
+            return `jsonb_exists(${expr}::jsonb, $${args.length})`;
+        },
+        like: (expr, { insensitive, segments }, args) => {
+            args.push(likeText(segments));
+            return `${expr} ${insensitive ? "ILIKE" : "LIKE"} $${args.length} ESCAPE '\\'`;
+        },
+        position: (expr, { caseSensitive, text }, args) => {
+            args.push(text);
+            return caseSensitive
+                ? `strpos(${expr}, $${args.length}::text)`
+                : `strpos(lower(${expr}), lower($${args.length}::text))`;
+        },
+        random: "random()",
+        toText: (expr) => `${expr}::text`,
+    };
+}
+export class PgStore {
+    flavor = pgFlavor();
+    sql;
+    admin;
+    dbName;
+    defects;
+    entities;
+    constructor(parts) {
+        this.sql = parts.sql;
+        this.admin = parts.admin;
+        this.dbName = parts.dbName;
+        this.defects = parts.defects;
+        this.entities = parts.entities;
+    }
+    static async create(defects, entities = ENTITIES, connect = connectPostgres) {
+        const dbName = `testing_ref_${process.pid}_${Date.now().toString(36)}${Math.floor(Math.random() * 1e6).toString(36)}`;
+        const admin = connect("postgres", 1);
+        await admin.unsafe(`CREATE DATABASE ${ident(dbName)}`);
+        const sql = connect(dbName, 4);
+        const store = new PgStore({ admin, dbName, defects, entities, sql });
+        await store.migrate();
+        return store;
+    }
+    async close() {
+        await this.sql.end({ timeout: 5 });
+        /* Drop with FORCE: a lingering session would otherwise leave scratch databases behind on
+         * every run, which is the same litter problem the API tester reports in the systems it tests. */
+        try {
+            await this.admin.unsafe(`DROP DATABASE IF EXISTS ${ident(this.dbName)} WITH (FORCE)`);
+        }
+        finally {
+            await this.admin.end({ timeout: 5 });
+        }
+    }
+    async migrate() {
+        for (const entity of this.entities) {
+            const columns = entity.fields.map((field) => {
+                const notNull = field.required === true ? " NOT NULL" : "";
+                return `${ident(this.physical(field.name))} ${PG_TYPE[field.type]}${notNull}`;
+            });
+            await this.sql.unsafe(`CREATE TABLE ${ident(entity.plural)} (${columns.join(", ")}, PRIMARY KEY (${ident(this.physical(entity.identity))}))`);
+        }
+    }
+    /** The stored column for a field — diverges from the declared name only under the defect. */
+    physical(name) {
+        return this.defects.has("COLUMN_NAME_MISMATCH") && name === "name" ? "mislabeled_name" : name;
+    }
+    /**
+     * Explicit projection, aliased back to declared names.
+     *
+     * Under COLUMN_NAME_MISMATCH the read asks for a column that does not exist. Postgres errors
+     * outright where SQLite's double-quoted-string fallback silently yields the identifier as a
+     * literal — the same defect, two failure modes, which is the point of running both.
+     */
+    selectList(entity) {
+        return entity.fields
+            .map((f) => {
+            if (!this.defects.has("COLUMN_NAME_MISMATCH") || f.name !== "name") {
+                return `${ident(f.name)} AS ${ident(f.name)}`;
+            }
+            return `'${f.name}'::text AS ${ident(f.name)}`;
+        })
+            .join(", ");
+    }
+    async insert(entity, record) {
+        const names = entity.fields.map((f) => f.name).filter((n) => record[n] !== undefined);
+        const columns = names.map((n) => ident(this.physical(n))).join(", ");
+        const holes = names.map((_, i) => `$${i + 1}`).join(", ");
+        await this.sql.unsafe(`INSERT INTO ${ident(entity.plural)} (${columns}) VALUES (${holes})`, names.map((n) => toPg(record[n])));
+        return (await this.byId(entity, record[entity.identity])) ?? record;
+    }
+    async byId(entity, id) {
+        const rows = await this.sql.unsafe(`SELECT ${this.selectList(entity)} FROM ${ident(entity.plural)} WHERE ${ident(this.physical(entity.identity))} = $1`, [id]);
+        const row = rows[0];
+        return row === undefined ? null : this.decode(entity, row);
+    }
+    async update(entity, id, patch) {
+        const names = Object.keys(patch).filter((n) => entity.fields.some((f) => f.name === n));
+        if (names.length > 0) {
+            const assignments = names.map((n, i) => `${ident(this.physical(n))} = $${i + 1}`).join(", ");
+            await this.sql.unsafe(`UPDATE ${ident(entity.plural)} SET ${assignments} WHERE ${ident(this.physical(entity.identity))} = $${names.length + 1}`, [...names.map((n) => toPg(patch[n])), id]);
+        }
+        return this.byId(entity, id);
+    }
+    async remove(entity, id) {
+        await this.sql.unsafe(`DELETE FROM ${ident(entity.plural)} WHERE ${ident(this.physical(entity.identity))} = $1`, [
+            id,
+        ]);
+    }
+    async select(entity, plan) {
+        const args = [];
+        const where = compileWhere(plan.where, { args, entity, flavor: this.flavor });
+        const order = compileOrder(plan, entity, this.flavor);
+        const rows = await this.sql.unsafe(`SELECT ${this.selectList(entity)} FROM ${ident(entity.plural)} WHERE ${where}${order}`, args);
+        return rows.map((row) => this.decode(entity, row));
+    }
+    /**
+     * Restores declared shapes. `bigint` arrives as a string from the wire protocol and would
+     * fail its own response schema, and a NULL column must read back as null rather than absent.
+     */
+    decode(entity, row) {
+        const out = {};
+        for (const field of entity.fields) {
+            const raw = row[field.name];
+            if (raw === undefined || raw === null) {
+                out[field.name] = null;
+                continue;
+            }
+            out[field.name] =
+                field.type === "integer" || field.type === "number"
+                    ? Number(raw)
+                    : field.type === "boolean"
+                        ? raw === true
+                        : (field.type === "object" || field.type === "array") && typeof raw === "string"
+                            ? JSON.parse(raw)
+                            : raw;
+        }
+        return out;
+    }
+}
+function toPg(value) {
+    if (value === undefined)
+        return null;
+    if (value !== null && typeof value === "object")
+        return JSON.stringify(value);
+    return value;
+}
+//# sourceMappingURL=postgres.js.map

package/dist/api/reference/stores/sql-compile.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Compiles the query AST to SQL for both SQL stores.
+ *
+ * One compiler, so SQLite and Postgres receive the same predicate. What differs is spelled by an
+ * `SqlFlavor`: placeholders, how a value is cast to text, how a case-sensitive pattern match is
+ * written, and which collation means "binary". Those are real engine differences; the meaning of
+ * the predicate is not.
+ */
+import type { EntityDef } from "../model/types.ts";
+import type { FilterNode, LikeSegment, SelectPlan } from "../query-types.ts";
+export type SqlParam = string | number | boolean | null;
+/** A pattern to match: its segments, and whether case is ignored. */
+export interface LikePattern {
+    segments: LikeSegment[];
+    insensitive: boolean;
+}
+/** Text to look for, and whether case must match. */
+export interface Needle {
+    text: string;
+    caseSensitive: boolean;
+}
+export interface SqlFlavor {
+    /** The expression reading a field — a quoted column, or a deliberately wrong one under a defect. */
+    column(entity: EntityDef, field: string): string;
+    /** Appends a bound argument and returns its placeholder. */
+    bind(args: SqlParam[], value: SqlParam): string;
+    /** A boolean as the engine stores it. */
+    bool(value: boolean): SqlParam;
+    toText(expr: string): string;
+    /** Text ordering under a binary collation. */
+    binary(expr: string): string;
+    /** A case-sensitive or case-insensitive match of `expr` against the pattern. */
+    like(expr: string, pattern: LikePattern, args: SqlParam[]): string;
+    /** Where the needle first occurs in `expr`, 1-based, or 0 — with the engine's own case folding. */
+    position(expr: string, needle: Needle, args: SqlParam[]): string;
+    /** Whether a JSON array column holds `element` as one of its elements. */
+    hasElement(expr: string, element: string, args: SqlParam[]): string;
+    random: string;
+}
+/** What every clause of one compilation shares: the entity read, the engine's spelling, the bound arguments. */
+export interface Compilation {
+    entity: EntityDef;
+    flavor: SqlFlavor;
+    args: SqlParam[];
+}
+export declare function compileWhere(node: FilterNode, compilation: Compilation): string;
+/** The ORDER BY clause for a plan's order, or "" when it has none. */
+export declare function compileOrder(plan: Pick<SelectPlan, "collation" | "order" | "shuffleTies">, entity: EntityDef, flavor: SqlFlavor): string;
+/** A LIKE pattern with `\` escaping, for engines whose LIKE honors ESCAPE. */
+export declare function likeText(segments: LikeSegment[]): string;
+/** A GLOB pattern — SQLite's case-sensitive matcher, which needs no pragma. */
+export declare function globText(segments: LikeSegment[]): string;
+//# sourceMappingURL=sql-compile.d.ts.map

package/dist/api/reference/stores/sql-compile.js

@@ -0,0 +1,105 @@
+/**
+ * Compiles the query AST to SQL for both SQL stores.
+ *
+ * One compiler, so SQLite and Postgres receive the same predicate. What differs is spelled by an
+ * `SqlFlavor`: placeholders, how a value is cast to text, how a case-sensitive pattern match is
+ * written, and which collation means "binary". Those are real engine differences; the meaning of
+ * the predicate is not.
+ */
+function isText(entity, field) {
+    return entity.fields.find((f) => f.name === field)?.type === "string";
+}
+function value(flavor, scalar, asText) {
+    if (asText)
+        return String(scalar);
+    if (typeof scalar === "boolean")
+        return flavor.bool(scalar);
+    return scalar;
+}
+export function compileWhere(node, compilation) {
+    const { args, entity, flavor } = compilation;
+    switch (node.kind) {
+        case "const":
+            return node.value ? "1 = 1" : "1 = 0";
+        case "and":
+        case "or":
+            return `(${node.children.map((child) => compileWhere(child, compilation)).join(node.kind === "and" ? " AND " : " OR ")})`;
+        case "isnull":
+            return `${flavor.column(entity, node.field)} IS ${node.negate ? "NOT " : ""}NULL`;
+        case "cmp":
+            return compileCmp(node, compilation);
+        case "in":
+            return compileIn(node, compilation);
+        case "like":
+            return flavor.like(flavor.column(entity, node.field), { insensitive: node.insensitive, segments: node.pattern }, args);
+        case "contains":
+            return compileContains(node, compilation);
+        case "search":
+            return `(${node.fields
+                .map((field) => searchClause(flavor.toText(flavor.column(entity, field)), node, compilation))
+                .join(" OR ")})`;
+    }
+}
+function compileCmp(node, { args, entity, flavor }) {
+    const column = flavor.column(entity, node.field);
+    /* Text compares binary, whatever the database default collation is. */
+    const ref = node.asText ? flavor.toText(column) : isText(entity, node.field) ? flavor.binary(column) : column;
+    const op = { eq: "=", gt: ">", gte: ">=", lt: "<", lte: "<=", neq: "<>" }[node.op];
+    const sql = `${ref} ${op} ${flavor.bind(args, value(flavor, node.value, node.asText))}`;
+    return node.nullsMatch ? `(${sql} OR ${column} IS NULL)` : sql;
+}
+function compileIn(node, { args, entity, flavor }) {
+    const column = flavor.column(entity, node.field);
+    if (node.values.length === 0)
+        return node.negate ? "1 = 1" : "1 = 0";
+    const ref = node.asText ? flavor.toText(column) : column;
+    const holes = node.values.map((member) => flavor.bind(args, value(flavor, member, node.asText))).join(", ");
+    return node.negate ? `(${ref} NOT IN (${holes}) OR ${column} IS NULL)` : `${ref} IN (${holes})`;
+}
+function compileContains(node, { args, entity, flavor }) {
+    const column = flavor.column(entity, node.field);
+    /* The defect matches the serialized array as text, so "red" also matches "redwood". */
+    return node.substring
+        ? `${flavor.position(column, { caseSensitive: true, text: node.value }, args)} > 0`
+        : flavor.hasElement(column, node.value, args);
+}
+function searchClause(expr, node, { args, flavor }) {
+    const at = flavor.position(expr, { caseSensitive: node.caseSensitive, text: node.token }, args);
+    return node.mode === "prefix" ? `${at} = 1` : `${at} > 0`;
+}
+/** The ORDER BY clause for a plan's order, or "" when it has none. */
+export function compileOrder(plan, entity, flavor) {
+    const terms = [];
+    const ordering = { collation: plan.collation, entity, flavor };
+    for (const term of plan.order) {
+        const column = flavor.column(entity, term.field);
+        /* Null placement is written out rather than left to the engine, because the engines
+         * disagree: SQLite sorts nulls first ascending, Postgres last. */
+        terms.push(`${column} IS NULL ${term.nullsFirst ? "DESC" : "ASC"}`);
+        terms.push(`${orderRef(term, column, ordering)} ${term.descending ? "DESC" : "ASC"}`);
+    }
+    if (plan.shuffleTies)
+        terms.push(flavor.random);
+    return terms.length === 0 ? "" : ` ORDER BY ${terms.join(", ")}`;
+}
+/* What one order term sorts by: its text form, its text under the collation, or the bare column. */
+function orderRef(term, column, { collation, entity, flavor }) {
+    if (term.asText)
+        return flavor.toText(column);
+    if (!isText(entity, term.field))
+        return column;
+    return collation === "insensitive" ? `LOWER(${column})` : flavor.binary(column);
+}
+/** A LIKE pattern with `\` escaping, for engines whose LIKE honors ESCAPE. */
+export function likeText(segments) {
+    return segments
+        .map((segment) => segment.kind === "any" ? "%" : segment.kind === "one" ? "_" : segment.text.replace(/[\\%_]/g, (ch) => `\\${ch}`))
+        .join("");
+}
+/** A GLOB pattern — SQLite's case-sensitive matcher, which needs no pragma. */
+export function globText(segments) {
+    return segments
+        .map((segment) => segment.kind === "any" ? "*" : segment.kind === "one" ? "?" : segment.text.replace(/[*?[]/g, (ch) => `[${ch}]`))
+        .join("");
+}
+//# sourceMappingURL=sql-compile.js.map

package/dist/api/reference/stores/sqlite-driver.d.ts

@@ -0,0 +1,54 @@
+/**
+ * How the SQLite-dialect store reaches an engine.
+ *
+ * The store builds SQL; the driver runs it. Splitting them buys the thing an in-process database
+ * cannot give: a *networked* SQLite, where every statement is a round trip, results arrive as
+ * decoded JSON rather than native values, and the engine is a different build with different
+ * compile-time flags. Cloudflare D1 leaves double-quoted-string fallback ON, which `node:sqlite`
+ * compiles off — so a DDL/read naming mismatch is an error on one and silent wrong data on the
+ * other. Only a real D1 can demonstrate which of those a given check survives.
+ *
+ * `node:sqlite` is imported dynamically and only by its own driver. Importing it at module scope
+ * aborts any process on a Node that lacks it (one built without SQLite, or older than 22.13, when it
+ * still needed `--experimental-sqlite`), which has taken down the CLI and the Postgres path once each.
+ */
+export type SqlValue = string | number | null | Uint8Array;
+export type SqlRow = Record<string, unknown>;
+export interface SqliteDriver {
+    /** Human-readable engine name, used in reports so a finding names where it was observed. */
+    readonly engine: string;
+    /**
+     * Whether the engine resolves an unknown double-quoted identifier to a string literal
+     * instead of erroring — SQLite's double-quoted-string misfeature.
+     *
+     * `node:sqlite` compiles it off, D1 leaves it on. That difference decides whether a
+     * DDL/read naming mismatch is a loud error or silent wrong data, so the fixture has to know
+     * which it is: on a DQS engine it can express the bug in its natural form and let the engine
+     * produce the damage, and elsewhere it must emit the resulting literal directly.
+     */
+    readonly dqs: boolean;
+    /** Statement with no bound parameters and no results — DDL. */
+    exec(sql: string): Promise<void>;
+    /** Statement with no results. */
+    run(sql: string, args: SqlValue[]): Promise<void>;
+    /** Statement returning rows. */
+    all(sql: string, args: SqlValue[]): Promise<SqlRow[]>;
+    close(): Promise<void>;
+}
+/** In-process SQLite via `node:sqlite`, which needs no flag from Node 22.13 (below the API tester's floor). */
+export declare function nodeSqliteDriver(): Promise<SqliteDriver>;
+export interface D1Config {
+    accountId: string;
+    databaseId: string;
+    apiToken: string;
+}
+/**
+ * Cloudflare D1 over its HTTP query API.
+ *
+ * Every call is a network round trip to a shared, persistent database — which is the point. A
+ * store that only ever ran against an in-process engine cannot show what happens when writes
+ * take milliseconds to become visible, when the engine is someone else's build, or when two
+ * runs share one database.
+ */
+export declare function d1Driver(config: D1Config): SqliteDriver;
+//# sourceMappingURL=sqlite-driver.d.ts.map

package/dist/api/reference/stores/sqlite-driver.js

@@ -0,0 +1,100 @@
+/**
+ * How the SQLite-dialect store reaches an engine.
+ *
+ * The store builds SQL; the driver runs it. Splitting them buys the thing an in-process database
+ * cannot give: a *networked* SQLite, where every statement is a round trip, results arrive as
+ * decoded JSON rather than native values, and the engine is a different build with different
+ * compile-time flags. Cloudflare D1 leaves double-quoted-string fallback ON, which `node:sqlite`
+ * compiles off — so a DDL/read naming mismatch is an error on one and silent wrong data on the
+ * other. Only a real D1 can demonstrate which of those a given check survives.
+ *
+ * `node:sqlite` is imported dynamically and only by its own driver. Importing it at module scope
+ * aborts any process on a Node that lacks it (one built without SQLite, or older than 22.13, when it
+ * still needed `--experimental-sqlite`), which has taken down the CLI and the Postgres path once each.
+ */
+/** In-process SQLite via `node:sqlite`, which needs no flag from Node 22.13 (below the API tester's floor). */
+export async function nodeSqliteDriver() {
+    const { DatabaseSync } = await import("node:sqlite");
+    const db = new DatabaseSync(":memory:");
+    db.exec("PRAGMA foreign_keys = OFF");
+    /* Default SQLite LIKE is case-insensitive for ASCII, which makes `ilike` vs `like`
+     * indistinguishable. Honor the grammar's distinction the way Postgres does. */
+    db.exec("PRAGMA case_sensitive_like = ON");
+    return {
+        async all(sql, args) {
+            return db.prepare(sql).all(...args);
+        },
+        async close() {
+            db.close();
+        },
+        dqs: false,
+        engine: "sqlite",
+        async exec(sql) {
+            db.exec(sql);
+        },
+        async run(sql, args) {
+            db.prepare(sql).run(...args);
+        },
+    };
+}
+/**
+ * Cloudflare D1 over its HTTP query API.
+ *
+ * Every call is a network round trip to a shared, persistent database — which is the point. A
+ * store that only ever ran against an in-process engine cannot show what happens when writes
+ * take milliseconds to become visible, when the engine is someone else's build, or when two
+ * runs share one database.
+ */
+export function d1Driver(config) {
+    const endpoint = `https://api.cloudflare.com/client/v4/accounts/${config.accountId}/d1/database/${config.databaseId}/query`;
+    async function send(sql, params) {
+        const response = await fetch(endpoint, {
+            body: JSON.stringify({ params: params.map(encode), sql }),
+            headers: {
+                authorization: `Bearer ${config.apiToken}`,
+                "content-type": "application/json",
+            },
+            method: "POST",
+        });
+        const body = (await response.json());
+        if (!response.ok || !body.success) {
+            const detail = body.errors?.map((error) => `${error.code}: ${error.message}`).join("; ") ?? `HTTP ${response.status}`;
+            /* Deliberately a plain Error, not SqlError: a transport or quota failure is not the
+             * backend rejecting the caller's input, and dressing it up as a 400 would let an
+             * outage read as a well-behaved validation response. */
+            throw new Error(`D1 query failed (${detail}) for: ${sql.slice(0, 160)}`);
+        }
+        return body.result?.[0]?.results ?? [];
+    }
+    return {
+        async all(sql, args) {
+            return send(sql, args);
+        },
+        async close() {
+            /* Stateless HTTP — nothing to release. Table teardown is the store's job. */
+        },
+        /* Verified against a live D1, not assumed: `SELECT "no_such_col"` returns the string
+         * "no_such_col" for every row, where node:sqlite raises "no such column". */
+        dqs: true,
+        engine: "d1",
+        async exec(sql) {
+            await send(sql, []);
+        },
+        async run(sql, args) {
+            await send(sql, args);
+        },
+    };
+}
+/**
+ * D1 binds parameters as JSON, so a value's JSON type is its storage class. Booleans have no
+ * SQLite representation and would arrive as `true`/`false` literals; the store already narrows
+ * to 0/1 before binding, and this is the backstop for anything that slips past.
+ */
+function encode(value) {
+    if (value === null)
+        return null;
+    if (value instanceof Uint8Array)
+        return Buffer.from(value).toString("base64");
+    return value;
+}
+//# sourceMappingURL=sqlite-driver.js.map

package/dist/api/reference/stores/sqlite.d.ts

@@ -0,0 +1,58 @@
+/**
+ * SQLite-backed storage for the reference backend.
+ *
+ * The in-memory store evaluates the query AST in JavaScript, which quietly sidesteps what breaks
+ * real APIs: collation, type affinity, and result order when a sort has no total order. Running
+ * the same predicates through a real engine is what makes a check that passes here mean something.
+ *
+ * The engine is supplied as a driver, so the same SQL runs in-process via `node:sqlite` and
+ * remotely against Cloudflare D1. That second target is not redundancy: D1 is a different build
+ * with different compile flags, reached over the network, backed by a database that persists
+ * between runs — three properties an in-process store cannot exhibit.
+ */
+import type { DefectSet } from "../defects/defect-set.ts";
+import type { EntityDef } from "../model/types.ts";
+import type { SelectPlan } from "../query-types.ts";
+import type { Row, Store } from "../store-api.ts";
+import type { SqliteDriver } from "./sqlite-driver.ts";
+/** The tables a store keeps: which entities, under which name prefix. */
+export interface SqlTables {
+    prefix?: string;
+    entities?: readonly EntityDef[];
+}
+export declare class SqlStore implements Store {
+    private readonly flavor;
+    private readonly defects;
+    private readonly db;
+    private readonly prefix;
+    private readonly entities;
+    private constructor();
+    /**
+     * Schema creation is a set of round trips on a networked engine, so it cannot live in a
+     * constructor. `prefix` isolates one run's tables from another's on a shared database.
+     */
+    static create(defects: DefectSet, driver: SqliteDriver, { prefix, entities }?: SqlTables): Promise<SqlStore>;
+    close(): Promise<void>;
+    private ddl;
+    /** The stored column for a field — diverges from the declared name only under the defect. */
+    private physical;
+    insert(entity: EntityDef, record: Row): Promise<Row>;
+    /**
+     * Explicit column list, as production code writes it.
+     *
+     * `SELECT *` would paper over a DDL/read naming mismatch; naming columns is what lets
+     * SQLite's double-quoted-string fallback surface — an unresolvable "name" silently becomes
+     * the literal 'name' rather than an error. See COLUMN_NAME_MISMATCH.
+     */
+    private selectList;
+    byId(entity: EntityDef, id: string | number): Promise<Row | null>;
+    update(entity: EntityDef, id: string | number, patch: Row): Promise<Row | null>;
+    remove(entity: EntityDef, id: string | number): Promise<void>;
+    select(entity: EntityDef, plan: SelectPlan): Promise<Row[]>;
+    /**
+     * Converts stored values back to their declared shape. SQLite has no boolean type, so a
+     * field declared boolean comes back as 0/1 and would fail its own response schema.
+     */
+    private decode;
+}
+//# sourceMappingURL=sqlite.d.ts.map