@orkestrel/database 0.0.1 → 0.0.2

package/dist/src/server/index.cjs

@@ -1,128 +1,189 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+let _orkestrel_contract = require("@orkestrel/contract");
 let node_crypto = require("node:crypto");
-let _src_core = require("../core/index.js");
+let _src_core = require("../core/index.cjs");
 let node_fs_promises = require("node:fs/promises");
 let node_path = require("node:path");
-Object.freeze([
-	"null",
-	"boolean",
-	"object",
-	"array",
-	"number",
-	"integer",
-	"string"
-]);
-/** Determine whether a value is a string. */
-function isString(value) {
-	return typeof value === "string";
-}
-/** Determine whether a value is a boolean. */
-function isBoolean(value) {
-	return typeof value === "boolean";
-}
+let _orkestrel_sqlite = require("@orkestrel/sqlite");
+//#region src/server/helpers.ts
 /**
-* Determine whether a value is a non-null object.
+* Generate a fresh unique key — a v4 UUID string, backed by `node:crypto`.
 *
 * @remarks
-* `true` for arrays, class instances, plain objects, `Map`, `Set`, etc. — use
-* {@link isRecord} when you need a plain-record check.
+* Supply this as {@link import('@orkestrel/database').DatabaseOptions.key} so a table mints
+* a key when a written row lacks its primary-key value. Strings work as keys on
+* every backend; supply your own key values directly to use numeric keys instead.
+*
+* @returns A new UUID string
+*
+* @example
+* ```ts
+* const db = createDatabase({ driver, tables, key: generateKey })
+* ```
 */
-function isObject(value) {
-	return typeof value === "object" && value !== null;
+function generateKey() {
+	return (0, node_crypto.randomUUID)();
 }
 /**
-* Determine whether a value is a plain record (object literal or null-prototype),
-* not an array or class instance.
+* The declared {@link ColumnType}s whose SQL EQUALITY comparisons (`equals` /
+* `not` / `any` / `none`) and `starts` / `ends` compiles are provably
+* engine-exact under declared-type trust — `text` / `integer` / `real` /
+* `boolean`; a `json` or `blob` column always refines instead.
 *
 * @remarks
-* Use instead of {@link isObject} to distinguish a plain `{}` /
-* `Object.create(null)` from arrays, `Date`, `Map`, etc. The prototype-chain
-* test is realm-agnostic: rather than comparing against the current realm's
-* `Object.prototype` (which a plain object from another `vm.Context`, iframe,
-* or worker would fail), it accepts any value whose prototype is `null`, OR
-* whose prototype's own prototype is `null` — the shape every plain object
-* has in every realm, since `Object.prototype` itself always sits one step
-* above `null`. Arrays and class instances are still rejected: an array's
-* prototype chain runs through `Array.prototype` before `null`, and a class
-* instance's runs through the class's own prototype. The whole body runs
-* inside `attempt` (AGENTS §14) so a revoked `Proxy` or a hostile
-* `getPrototypeOf` trap cannot escape as a thrown error.
-*/
-function isRecord(value) {
-	const outcome = attempt(() => {
-		if (!isObject(value) || isArray(value)) return false;
-		const prototype = Object.getPrototypeOf(value);
-		return prototype === null || Object.getPrototypeOf(prototype) === null;
-	});
-	return outcome.success && outcome.value;
-}
-/** Determine whether a value is an array. */
-function isArray(value) {
-	return Array.isArray(value);
-}
+* This set governs equality and prefix/suffix matching only. RANGE
+* comparisons (`above` / `below` / `from` / `to` / `between`) and `ORDER BY`
+* are exact for `integer` / `real` / `boolean` but NOT for `text`: compiled
+* SQL orders/ranges under SQLite's default BINARY collation, which compares
+* TEXT byte-for-byte as UTF-8 — equivalent to Unicode CODE-POINT order —
+* while the core engine's `compareValues` orders JS strings with `<`, which
+* compares UTF-16 CODE-UNIT order. The two orders diverge for supplementary-
+* plane characters (code points ≥ U+10000, e.g. many emoji): a lead surrogate
+* (`\uD800`–`\uDBFF`) sorts BELOW ``–`￿` in code-unit order, while
+* its code point sorts ABOVE them. So `isExactCondition`'s range family and
+* `isExactOrder` exclude `text`, refining through the core engine instead. A
+* future opt-in "trusted collation" mode (the caller vouches the column's
+* values are BMP-only, or a custom SQLite collation matching `compareValues`
+* is registered) could restore native text ranges/ordering.
+*/
+var EXACT_COLUMN_TYPES = [
+	"text",
+	"integer",
+	"real",
+	"boolean"
+];
 /**
-* Invoke a callback and capture its outcome as a {@link Result}, never letting
-* a throw escape.
+* The declared {@link ColumnType}s whose SQL RANGE comparisons
+* (`above` / `below` / `from` / `to` / `between`) and `ORDER BY` compiles are
+* provably engine-exact — `integer` / `real` / `boolean` only. `text` is
+* excluded: see {@link EXACT_COLUMN_TYPES}'s remarks for the BINARY-collation
+* (code-point) vs. JS `<` (code-unit) divergence on supplementary-plane
+* characters.
+*/
+var EXACT_RANGE_COLUMN_TYPES = [
+	"integer",
+	"real",
+	"boolean"
+];
+/**
+* Whether a value's runtime type matches a column's declared exact type —
+* the operand side of the declared-type-trust proof.
 *
 * @remarks
-* The single sanctioned never-throw boundary for the guards (AGENTS §14). The
-* `whereOf`, `lazyOf`, and `transformOf` combinators invoke caller-supplied
-* callbacks *inside* a guard body, yet a guard must NEVER throw — it returns a
-* `boolean`. This converts a throwing callback into a `Failure` so the
-* surrounding guard can treat it as a non-match instead of propagating the
-* exception, written once and shared rather than copy-pasted as ad-hoc
-* `try`/`catch`.
-*
-* @param callback - The callback to invoke with no arguments
-* @returns A `Success` carrying the return value, or a `Failure` carrying the
-*          thrown reason normalised to an `Error`
+* `text` ↔ string, `integer` / `real` ↔ FINITE number (`NaN` / `±Infinity`
+* fail), `boolean` ↔ boolean. Backs {@link isExactCondition}'s operand checks.
+*
+* @param value - The condition operand to test
+* @param type - The column's declared portable type
+* @returns `true` when the operand's runtime type matches the declared type
 *
 * @example
 * ```ts
-* const outcome = attempt(() => predicate(value))
-* return outcome.success && outcome.value
+* matchesDeclaredType('Ada', 'text') // true
+* matchesDeclaredType(Number.NaN, 'integer') // false — only finite numbers
 * ```
 */
-function attempt(callback) {
-	try {
-		return {
-			success: true,
-			value: callback()
-		};
-	} catch (reason) {
-		if (reason instanceof Error) return {
-			success: false,
-			error: reason
-		};
-		let message = "Unknown thrown value";
-		try {
-			message = String(reason);
-		} catch {}
-		return {
-			success: false,
-			error: new Error(message)
-		};
-	}
+function matchesDeclaredType(value, type) {
+	if (type === "text") return (0, _orkestrel_contract.isString)(value);
+	if (type === "boolean") return (0, _orkestrel_contract.isBoolean)(value);
+	return (0, _orkestrel_contract.isFiniteNumber)(value);
 }
-//#endregion
-//#region src/server/helpers.ts
 /**
-* Generate a fresh unique key — a v4 UUID string, backed by `node:crypto`.
+* Whether one {@link Condition} compiles to SQL that is PROVABLY identical to
+* the core engine's `matchesCondition` for every value its column's declared
+* type can store.
 *
 * @remarks
-* Supply this as {@link import('@src/core').DatabaseOptions.key} so a table mints
-* a key when a written row lacks its primary-key value. Strings work as keys on
-* every backend; supply your own key values directly to use numeric keys instead.
+* `false` for a nested `FieldPath` (an array), a column absent from `schema`,
+* or a column whose declared type is not `text` / `integer` / `real` /
+* `boolean` (a `json` / `blob` column) — EXCEPT `absent` / `present`, which
+* compile to `IS NULL` / `IS NOT NULL` and match `decodeRow`'s "a stored NULL
+* decodes to `undefined`" rule for every column type, so they are exact
+* regardless of declared type. `equals` / `not` require a operand matching the
+* column's declared type (a `null` / `undefined` operand is never exact here —
+* `encodeRow` stores both an explicit `null` and an absent field as SQL NULL,
+* so native `IS NULL` semantics cannot match the engine's `deepEqual`-over-
+* decoded-rows truth). `above` / `below` / `from` / `to` / `between` are exact
+* ONLY for a declared type in {@link EXACT_RANGE_COLUMN_TYPES} (`integer` /
+* `real` / `boolean`) — a `text` column's range conditions REFINE, because
+* SQLite's default BINARY collation orders TEXT by Unicode CODE POINT while
+* the core engine's `compareValues` orders JS strings by UTF-16 CODE UNIT,
+* and the two diverge for supplementary-plane characters (see
+* {@link EXACT_COLUMN_TYPES}'s remarks for the full rationale).
+* `any` / `none` require a NON-EMPTY list where every element matches (an empty
+* list is exact under neither: the engine's `any([])` matches nothing while
+* `none([])` matches everything, and SQL `IN ()` is a syntax error) — these
+* stay exact on `text` (byte equality is collation-independent and engine-
+* identical). `starts` / `ends` are exact only on a `text` column with a
+* string operand (case-sensitive `substr` compile, see {@link fragment}) —
+* likewise collation-independent. `like` / `glob` are NEVER exact — SQLite
+* `LIKE` folds case ASCII-only against the engine's Unicode fold, and `GLOB`
+* has character classes the engine treats literally.
+*
+* @param condition - The condition to test
+* @param schema - The table's schema
+* @returns Whether `condition` is exact
+*/
+function isExactCondition(condition, schema) {
+	if (!(0, _orkestrel_contract.isString)(condition.column)) return false;
+	const column = schema.columns.find((candidate) => candidate.name === condition.column);
+	if (column === void 0) return false;
+	if (condition.operator === "absent" || condition.operator === "present") return true;
+	if (!EXACT_COLUMN_TYPES.some((type) => type === column.type)) return false;
+	const first = condition.values[0];
+	const second = condition.values[1];
+	switch (condition.operator) {
+		case "equals":
+		case "not": return matchesDeclaredType(first, column.type);
+		case "above":
+		case "below":
+		case "from":
+		case "to": return EXACT_RANGE_COLUMN_TYPES.some((type) => type === column.type) && matchesDeclaredType(first, column.type);
+		case "between": return EXACT_RANGE_COLUMN_TYPES.some((type) => type === column.type) && matchesDeclaredType(first, column.type) && matchesDeclaredType(second, column.type);
+		case "any":
+		case "none": return condition.values.length > 0 && condition.values.every((value) => matchesDeclaredType(value, column.type));
+		case "starts":
+		case "ends": return column.type === "text" && (0, _orkestrel_contract.isString)(first);
+		case "like":
+		case "glob": return false;
+	}
+}
+/**
+* Whether one {@link Order} term's column compiles to an `ORDER BY` that
+* matches the engine's {@link import('@src/core').sortRows} exactly.
 *
-* @returns A new UUID string
+* @remarks
+* `false` for a nested `FieldPath`, a column absent from `schema`, or a
+* declared type outside {@link EXACT_RANGE_COLUMN_TYPES} (`integer` / `real` /
+* `boolean`). `text` is NOT exact here: SQLite's default BINARY collation
+* orders TEXT by Unicode code point while the core engine's `compareValues`
+* orders JS strings by UTF-16 code unit, and the two diverge for
+* supplementary-plane characters (see {@link EXACT_COLUMN_TYPES}'s remarks) —
+* a `text` order term REFINES through the core engine instead.
+*
+* @param order - The order term to test
+* @param schema - The table's schema
+* @returns Whether `order` is exact
+*/
+function isExactOrder(order, schema) {
+	if (!(0, _orkestrel_contract.isString)(order.column)) return false;
+	const column = schema.columns.find((candidate) => candidate.name === order.column);
+	if (column === void 0) return false;
+	return EXACT_RANGE_COLUMN_TYPES.some((type) => type === column.type);
+}
+/**
+* Whether a whole {@link Criteria} is exact — every condition and every order
+* term is exact. `limit` / `offset` never affect exactness (SQL `LIMIT` /
+* `OFFSET` are always engine-identical).
 *
-* @example
-* ```ts
-* const db = createDatabase({ driver, tables, key: generateKey })
-* ```
+* @param criteria - The criteria to test
+* @param schema - The table's schema
+* @returns Whether every part of `criteria` is exact
 */
-function generateKey() {
-	return (0, node_crypto.randomUUID)();
+function isExactCriteria(criteria, schema) {
+	const conditions = criteria.conditions ?? [];
+	const order = criteria.order ?? [];
+	return conditions.every((condition) => isExactCondition(condition, schema)) && order.every((term) => isExactOrder(term, schema));
 }
 /**
 * Map a portable {@link ColumnType} to its SQLite column type.
@@ -192,7 +253,7 @@ function quote(identifier) {
 * ```
 */
 function fieldColumn(path) {
-	if (isString(path)) return quote(path);
+	if ((0, _orkestrel_contract.isString)(path)) return quote(path);
 	const rest = path.slice(1).map((key) => "." + key.replaceAll("'", "''")).join("");
 	return "json_extract(" + quote(path[0]) + ", '$" + rest + "')";
 }
@@ -362,12 +423,40 @@ function schemaToTable(schema) {
 	return "CREATE TABLE IF NOT EXISTS " + quote(schema.name) + " (" + columns.join(", ") + ", PRIMARY KEY (" + quote(schema.primary) + "))";
 }
 /**
+* Build a collision-free SQL index name for a table + column-group index —
+* shared by {@link schemaToIndexes} (an `open`-time `CREATE INDEX`) and
+* {@link stepToSQL}'s `index.add` / `index.remove` (a migration-time DDL),
+* so a plan-built index name always matches one `open` would have created.
+*
+* @remarks
+* A naive `idx_<table>_<cols joined by _>` is AMBIGUOUS: table `'a_b'` with
+* column `'c'` and table `'a'` with columns `['b', 'c']` both produce
+* `idx_a_b_c`. This encodes each part (the table name, then each column name)
+* length-prefixed (`<len>_<part>`) so the boundary between parts is always
+* unambiguous, however the names themselves are punctuated.
+*
+* @param table - The table name
+* @param columns - The index's column names, in order
+* @returns The deterministic, collision-free index identifier (unquoted)
+*
+* @example
+* ```ts
+* indexName('users', ['name']) // 'idx_5_users_4_name'
+* indexName('a_b', ['c']) // 'idx_3_a_b_1_c'
+* indexName('a', ['b', 'c']) // 'idx_1_a_1_b_1_c'
+* ```
+*/
+function indexName(table, columns) {
+	return "idx_" + [table, ...columns].map((part) => String(part.length) + "_" + part).join("_");
+}
+/**
 * Project a {@link TableSchema} to the `CREATE INDEX IF NOT EXISTS` statements a
 * SQLite driver's `open` issues for its declared indexes.
 *
 * @remarks
-* One statement per index group; the index name is `idx_<table>_<columns joined
-* by _>`, matching the driver's naming so a repeated `open` is idempotent.
+* One statement per index group; the index name is built by {@link indexName}
+* (collision-free and deterministic), matching the driver's naming so a
+* repeated `open` is idempotent.
 *
 * @param schema - The table's schema
 * @returns One `CREATE INDEX IF NOT EXISTS …` statement per declared index
@@ -375,15 +464,114 @@ function schemaToTable(schema) {
 * @example
 * ```ts
 * schemaToIndexes(schema)
-* // ['CREATE INDEX IF NOT EXISTS "idx_users_name" ON "users" ("name")']
+* // ['CREATE INDEX IF NOT EXISTS "idx_5_users_4_name" ON "users" ("name")']
 * ```
 */
 function schemaToIndexes(schema) {
-	return schema.indexes.map((group) => "CREATE INDEX IF NOT EXISTS " + quote("idx_" + schema.name + "_" + group.join("_")) + " ON " + quote(schema.name) + " (" + group.map(quote).join(", ") + ")");
+	return schema.indexes.map((group) => "CREATE INDEX IF NOT EXISTS " + quote(indexName(schema.name, group)) + " ON " + quote(schema.name) + " (" + group.map(quote).join(", ") + ")");
+}
+/**
+* Project one {@link MigrationStep} to the DDL statement(s) a SQLite driver's
+* `migrate` executes for it.
+*
+* @remarks
+* `table.add` emits the `CREATE TABLE` plus one `CREATE INDEX` per declared
+* index (via {@link schemaToTable} / {@link schemaToIndexes}); `table.remove`
+* emits `DROP TABLE IF EXISTS`; `column.add` / `column.remove` emit `ALTER
+* TABLE … ADD COLUMN` / `… DROP COLUMN`; `index.add` / `index.remove` emit
+* `CREATE INDEX IF NOT EXISTS` / `DROP INDEX IF EXISTS`, naming the index the
+* same way `schemaToIndexes` does (`idx_<table>_<columns joined by _>`) so a
+* plan-built index matches one `open` would have created. Whether the named
+* table actually exists is the caller's concern (a driver's `migrate` checks
+* its own declared schema before running these statements) — this projection
+* is pure and never inspects live state.
+*
+* @param step - The migration step to project
+* @returns The DDL statement(s) that apply the step
+*
+* @example
+* ```ts
+* stepToSQL({ operation: 'column.remove', table: 'users', column: 'legacy' })
+* // ['ALTER TABLE "users" DROP COLUMN "legacy"']
+* ```
+*/
+function stepToSQL(step) {
+	switch (step.operation) {
+		case "table.add": return [schemaToTable(step.table), ...schemaToIndexes(step.table)];
+		case "table.remove": return ["DROP TABLE IF EXISTS " + quote(step.table)];
+		case "column.add": return ["ALTER TABLE " + quote(step.table) + " ADD COLUMN " + quote(step.column.name) + " " + columnSQL(step.column.type)];
+		case "column.remove": return ["ALTER TABLE " + quote(step.table) + " DROP COLUMN " + quote(step.column)];
+		case "index.add": return ["CREATE INDEX IF NOT EXISTS " + quote(indexName(step.table, step.index)) + " ON " + quote(step.table) + " (" + step.index.map(quote).join(", ") + ")"];
+		case "index.remove": return ["DROP INDEX IF EXISTS " + quote(indexName(step.table, step.index))];
+	}
+}
+/**
+* Project one {@link MigrationStep} onto its table's declared {@link TableSchema}
+* — the bookkeeping counterpart to {@link stepToSQL} (which projects the DDL a
+* driver's `migrate` runs against the live database).
+*
+* @remarks
+* `column.add` / `column.remove` add / filter the named column;
+* `index.add` / `index.remove` add / filter the matching index group (an exact
+* ordered match on `index`). `table.add` / `table.remove` act on a WHOLE
+* schema map rather than one table's shape, so they are the caller's concern
+* (a driver's `migrate` applies them directly against its table map) — passed
+* here, they return `schema` unchanged.
+*
+* @param schema - The table's current declared schema
+* @param step - The migration step to project onto it
+* @returns The table's schema after the step
+*
+* @example
+* ```ts
+* stepToSchema(schema, { operation: 'column.remove', table: 'users', column: 'legacy' })
+* // schema with the 'legacy' column dropped from `columns`
+* ```
+*/
+function stepToSchema(schema, step) {
+	switch (step.operation) {
+		case "column.add": return {
+			...schema,
+			columns: [...schema.columns, step.column]
+		};
+		case "column.remove": return {
+			...schema,
+			columns: schema.columns.filter((column) => column.name !== step.column)
+		};
+		case "index.add": return {
+			...schema,
+			indexes: [...schema.indexes, step.index]
+		};
+		case "index.remove": return {
+			...schema,
+			indexes: schema.indexes.filter((group) => !(group.length === step.index.length && group.every((name, position) => name === step.index[position])))
+		};
+		case "table.add":
+		case "table.remove": return schema;
+	}
 }
 //#endregion
 //#region src/server/compilers.ts
 /**
+* Compile a NESTED {@link FieldPath} to the `json_type(<col>, <path>)` SQL
+* expression — the {@link fieldColumn} `json_extract` sibling used to tell a
+* PRESENT JSON `null` apart from an ABSENT path (both read back as SQL `NULL`
+* through `json_extract`, but `json_type` reports `'null'` for the former and
+* SQL `NULL` for the latter).
+*
+* @param path - The nested field path (a column plus its JSON keys)
+* @returns The SQL expression reading the value's JSON type
+*
+* @example
+* ```ts
+* jsonTypeColumn(['payload', 'user', 'id']) // "json_type(\"payload\", '$.user.id')"
+* ```
+*/
+function jsonTypeColumn(path) {
+	const rest = path.slice(1).map((key) => "." + key.replaceAll("'", "''")).join("");
+	return "json_type(" + quote(path[0]) + ", '$" + rest + "')";
+}
+/**
 * Escape `\`, `%`, and `_` (each with a leading `\`) so a `starts` / `ends`
 * operand is matched literally under the `LIKE … ESCAPE '\'` clause.
 *
@@ -443,7 +631,7 @@ function valueType(value) {
 }
 /**
 * Compile one condition to its `<column> <operator>` SQL fragment and the params
-* it binds.
+* it binds — engine-exact under SQL's three-valued NULL logic.
 *
 * @remarks
 * Every operand is run through `encodeValue`, so a bound value matches the SQL
@@ -452,10 +640,53 @@ function valueType(value) {
 * encodes each operand as the NATIVE scalar `json_extract` returns, derived from
 * the operand's runtime type (per-operand, since `between` / `any` / `none` can
 * mix types). `any` / `none` collapse an empty list to a constant (`0` matches
-* nothing, `1` matches all) with no params. A nested field with a null/undefined
-* operand under `equals` / `not` compiles to `IS NULL` / `IS NOT NULL` (no bound
-* param) instead of `= ?` / `!= ?`, matching the engine's treatment of a
-* present-but-null nested value.
+* nothing, `1` matches all) with no params.
+*
+* The core engine's total order ranks `undefined` (rank 0) BELOW `null`
+* (rank 1) (see `compareValues`), so a MISSING/`NULL` column MATCHES
+* `below` / `to` / a scalar `not` / `none` — the opposite of raw SQL, where a
+* comparison against `NULL` is `NULL` (excluded). This fragment replicates the
+* engine exactly. Truth table (`value` = the engine's decoded field read; a
+* FLAT column's stored `NULL` decodes to `undefined` per `decodeRow`, so a
+* flat `value` is NEVER a present `null` — only a NESTED path can be
+* present-but-`null`):
+*
+* ```text
+* operator            | value=undefined (absent)      | value=null (nested only) | value=scalar
+* --------------------|--------------------------------|---------------------------|-------------
+* equals, first=null  | no match                       | MATCH                     | no match
+* equals, first=X     | no match                       | no match                  | value===X
+* not, first=null     | MATCH (flat: unconditionally;  | no match                  | MATCH
+*                     |   nested: absent still matches)|                           |
+* not, first=X        | MATCH                          | MATCH                     | value!==X
+* below/to, first=X   | MATCH (rank 0 < rank(X))       | MATCH (rank 1 < rank(X))  | rank compare
+* none, list=[…]       | MATCH (no scalar rank-equal)   | MATCH                     | not-in-list
+* any, list=[…]        | no match                       | no match                  | in-list
+* above/from/between  | no match                       | no match                  | rank compare
+* like/glob/starts/…  | no match (not a string)        | no match                  | string test
+* present              | false                          | false                     | true
+* absent                | true                           | true                      | false
+* ```
+*
+* Because a flat column's `NULL` always decodes to `undefined`, `equals`
+* against a `null` operand needs no special flat compilation (`col = ?`
+* binding a `NULL` param is already always-false in SQL, matching "no match"
+* above) — but flat `not` against `null` must match EVERY row (both the
+* absent and the scalar rows), which `col != ? OR col IS NULL` cannot express
+* (it only catches the `IS NULL` row), so a flat `not`-with-`null`-operand
+* compiles to the constant `1`.
+*
+* A NESTED path can be present-but-`null` (a stored JSON `null`), which
+* `json_extract` reads back as SQL `NULL` — indistinguishable from an ABSENT
+* path. `json_type(col, path)` disambiguates them (`'null'` for present-null,
+* SQL `NULL` for absent), so nested `equals` / `not` against a `null` operand
+* compile through `json_type` instead of `IS NULL` / `IS NOT NULL`.
+*
+* Every other MATCH-on-null-or-absent row is expressed uniformly (flat and
+* nested alike) as `(<column> <op> ? OR <column> IS NULL)` — for a nested
+* path, `json_extract` already collapses BOTH absent and present-null to SQL
+* `NULL`, so `IS NULL` catches both in one clause; for a flat column there is
+* only the absent case to catch.
 *
 * @param condition - The condition to compile
 * @param schema - The table's schema (for declared column types)
@@ -465,20 +696,23 @@ function valueType(value) {
 * ```ts
 * fragment({ column: 'age', operator: 'above', values: [18], connector: 'and' }, schema)
 * // { sql: '"age" > ?', params: [18] }
+* fragment({ column: 'age', operator: 'below', values: [18], connector: 'and' }, schema)
+* // { sql: '("age" < ? OR "age" IS NULL)', params: [18] }
 * ```
 */
 function fragment(condition, schema) {
 	const column = fieldColumn(condition.column);
-	const nested = !isString(condition.column);
-	const declared = isString(condition.column) ? declaredType(condition.column, schema) : void 0;
+	const nested = !(0, _orkestrel_contract.isString)(condition.column);
+	const declared = (0, _orkestrel_contract.isString)(condition.column) ? declaredType(condition.column, schema) : void 0;
 	const encode = (value) => encodeValue(value, nested ? valueType(value) : declared ?? "json");
 	const first = condition.values[0];
 	const second = condition.values[1];
-	const nullOperand = nested && (first === null || first === void 0);
+	const nullOperand = first === null || first === void 0;
+	const jsonType = !(0, _orkestrel_contract.isString)(condition.column) ? jsonTypeColumn(condition.column) : "";
 	switch (condition.operator) {
 		case "equals":
-			if (nullOperand) return {
-				sql: column + " IS NULL",
+			if (nullOperand && nested) return {
+				sql: jsonType + " = 'null'",
 				params: []
 			};
 			return {
@@ -486,12 +720,18 @@ function fragment(condition, schema) {
 				params: [encode(first)]
 			};
 		case "not":
-			if (nullOperand) return {
-				sql: column + " IS NOT NULL",
-				params: []
-			};
+			if (nullOperand) {
+				if (nested) return {
+					sql: "(" + jsonType + " IS NULL OR " + jsonType + " != 'null')",
+					params: []
+				};
+				return {
+					sql: "1",
+					params: []
+				};
+			}
 			return {
-				sql: column + " != ?",
+				sql: "(" + column + " != ? OR " + column + " IS NULL)",
 				params: [encode(first)]
 			};
 		case "above": return {
@@ -499,7 +739,7 @@ function fragment(condition, schema) {
 			params: [encode(first)]
 		};
 		case "below": return {
-			sql: column + " < ?",
+			sql: "(" + column + " < ? OR " + column + " IS NULL)",
 			params: [encode(first)]
 		};
 		case "from": return {
@@ -507,7 +747,7 @@ function fragment(condition, schema) {
 			params: [encode(first)]
 		};
 		case "to": return {
-			sql: column + " <= ?",
+			sql: "(" + column + " <= ? OR " + column + " IS NULL)",
 			params: [encode(first)]
 		};
 		case "between": return {
@@ -522,14 +762,30 @@ function fragment(condition, schema) {
 			sql: column + " GLOB ?",
 			params: [encode(first)]
 		};
-		case "starts": return {
-			sql: column + " LIKE ? ESCAPE '\\'",
-			params: [(isString(first) ? escapeLike(first) : "") + "%"]
-		};
-		case "ends": return {
-			sql: column + " LIKE ? ESCAPE '\\'",
-			params: ["%" + (isString(first) ? escapeLike(first) : "")]
-		};
+		case "starts": {
+			const text = (0, _orkestrel_contract.isString)(first) ? first : "";
+			if (text === "") return {
+				sql: "typeof(" + column + ") = 'text'",
+				params: []
+			};
+			const length = Array.from(text).length;
+			return {
+				sql: "(typeof(" + column + ") = 'text' AND substr(" + column + ", 1, " + length + ") = ?)",
+				params: [encode(first)]
+			};
+		}
+		case "ends": {
+			const text = (0, _orkestrel_contract.isString)(first) ? first : "";
+			if (text === "") return {
+				sql: "typeof(" + column + ") = 'text'",
+				params: []
+			};
+			const length = Array.from(text).length;
+			return {
+				sql: "(typeof(" + column + ") = 'text' AND substr(" + column + ", -" + length + ") = ?)",
+				params: [encode(first)]
+			};
+		}
 		case "any":
 			if (condition.values.length === 0) return {
 				sql: "0",
@@ -545,7 +801,7 @@ function fragment(condition, schema) {
 				params: []
 			};
 			return {
-				sql: column + " NOT IN (" + condition.values.map(() => "?").join(", ") + ")",
+				sql: "(" + column + " NOT IN (" + condition.values.map(() => "?").join(", ") + ") OR " + column + " IS NULL)",
 				params: condition.values.map(encode)
 			};
 		case "absent": return {
@@ -564,6 +820,10 @@ function fragment(condition, schema) {
 *
 * @remarks
 * The first condition's connector is ignored, per the {@link Condition} types.
+* Every fragment (see {@link fragment}'s truth table) replicates the core
+* engine's total order EXACTLY under SQL's three-valued NULL logic, so this
+* clause matches `applyCriteria` row-for-row over the same table — a native
+* `records` / `count` read never disagrees with a scan-and-filter fallback.
 *
 * @param conditions - The conditions to fold
 * @param schema - The table's schema
@@ -622,7 +882,7 @@ function compileWhere(conditions, schema) {
 */
 function compileOrder(order, schema) {
 	const terms = (order ?? []).map((term) => fieldColumn(term.column) + (term.direction === "descending" ? " DESC" : " ASC"));
-	if (!(order ?? []).some((term) => isString(term.column) && term.column === schema.primary)) terms.push(quote(schema.primary));
+	if (!(order ?? []).some((term) => (0, _orkestrel_contract.isString)(term.column) && term.column === schema.primary)) terms.push(quote(schema.primary));
 	return terms.length === 0 ? "" : "ORDER BY " + terms.join(", ");
 }
 /**
@@ -702,6 +962,18 @@ function compileCriteria(criteria, schema) {
 	};
 }
 //#endregion
+//#region src/server/constants.ts
+/**
+* The reserved metadata table the {@link SQLiteDriver} creates on `open` to
+* persist its stamped `DriverMeta` (`version` + declared schema JSON) — the
+* SQLite realization of the `meta` / `stamp` driver hooks.
+*
+* @remarks
+* A single-row table (`id = 1`). A user table named `_meta` collides with the
+* reservation — the caller's concern to avoid, documented on the driver class.
+*/
+var META_TABLE = "_meta";
+//#endregion
 //#region src/server/drivers/JSONDriver.ts
 /**
 * A persistent {@link DriverInterface} backed by a single JSON file — the
@@ -890,38 +1162,19 @@ var JSONDriver = class {
 		} catch {
 			return;
 		}
-		if (!isRecord(parsed) || !isRecord(parsed.tables)) return;
+		if (!(0, _orkestrel_contract.isRecord)(parsed) || !(0, _orkestrel_contract.isRecord)(parsed.tables)) return;
 		const tables = parsed.tables;
 		for (const table of this.#schema) {
 			const rows = tables[table.name];
 			if (!Array.isArray(rows)) continue;
 			for (const entry of rows) {
-				if (!isRecord(entry)) continue;
+				if (!(0, _orkestrel_contract.isRecord)(entry)) continue;
 				const key = (0, _src_core.extractKey)(entry, table.primary);
 				if (key === void 0) continue;
 				await this.#memory.write(table.name, key, entry);
 			}
 		}
-		const COLUMN_TYPES = [
-			"text",
-			"integer",
-			"real",
-			"boolean",
-			"json",
-			"blob"
-		];
-		const isColumnType = (value) => isString(value) && COLUMN_TYPES.some((type) => type === value);
-		const isColumnSchema = (value) => isRecord(value) && isString(value.name) && isColumnType(value.type) && isBoolean(value.nullable);
-		const isIndexGroup = (value) => isArray(value) && value.every(isString);
-		const isTableSchema = (value) => isRecord(value) && isString(value.name) && isString(value.primary) && isArray(value.columns) && value.columns.every(isColumnSchema) && isArray(value.indexes) && value.indexes.every(isIndexGroup);
-		if (isRecord(parsed.meta)) {
-			const version = parsed.meta.version;
-			const schema = parsed.meta.schema;
-			if (typeof version === "number" && Number.isFinite(version) && isArray(schema) && schema.every(isTableSchema)) this.#meta = {
-				version,
-				schema
-			};
-		}
+		if ((0, _src_core.isDriverMeta)(parsed.meta)) this.#meta = parsed.meta;
 	}
 	async #flush() {
 		const next = this.#chain.then(() => this.#serialize());
@@ -955,12 +1208,390 @@ var JSONDriver = class {
 	}
 };
 //#endregion
+//#region src/server/drivers/SQLiteDriver.ts
+/**
+* The SQLite {@link DriverInterface} — the server-native, trusted-mode backend
+* built on the published `@orkestrel/sqlite` synchronous wrapper.
+*
+* @remarks
+* A thin adapter: it implements the storage primitives the core database layer
+* needs by delegating to the wrapper's prepared statements — it never touches
+* raw `node:sqlite`. `open` issues `CREATE TABLE IF NOT EXISTS` with real typed
+* columns (mapped from each {@link TableSchema}'s portable column types) and a
+* `PRIMARY KEY`, plus a `CREATE INDEX IF NOT EXISTS` per declared index (both
+* reopen-safe), and readies a reserved `_meta` single-row table `meta()` /
+* `stamp()` read and write — **a user table named `_meta` collides with it**;
+* avoid the name. Rows cross the boundary through the codecs in `helpers.ts`
+* (`json` columns store / parse JSON text, a `boolean` stores `1` / `0`), so the
+* typed layer above imposes the exact shape (AGENTS §14). `write` is an
+* `INSERT OR REPLACE` upsert — the `Table` layer detects a `CONFLICT` via a
+* prior `has`, so this never translates a constraint error; a backend
+* `SQLiteError` otherwise propagates unchanged. Querying, ordering, paging, and
+* aggregation are native: `records` / `count` / `stream` compile a `Criteria`
+* to SQL with `compileCriteria`, and `aggregate` runs a SQL
+* `COUNT`/`SUM`/`AVG`/`MIN`/`MAX` (via `aggregateSQL`) over the same compiled
+* WHERE. `transaction` wraps native `BEGIN` / `COMMIT` / `ROLLBACK` with
+* double-settle guards. `migrate` runs the plan's projected DDL
+* ({@link import('../helpers.js').stepToSQL}) inside whichever native
+* transaction is active: joined into an already-open `transaction()` handle
+* when one exists (the core's versioned reconcile path wraps migrate + stamp
+* in one native `BEGIN`, and node:sqlite rejects a nested `BEGIN`), or inside
+* its own `database.transaction` otherwise — a mid-plan failure rolls back
+* atomically either way, an improvement over the non-atomic `MemoryDriver` /
+* `JSONDriver` migrate; a step referencing an undeclared table throws
+* `DatabaseError` `MIGRATION` before any DDL for that step runs. `snapshot` is
+* capture-replay (SELECT the
+* named tables' rows, replay via DELETE + INSERT OR REPLACE inside a native
+* transaction on rollback) rather than a SQL `SAVEPOINT`, since the core
+* `transaction` calls the rollback thunk only on failure with no commit-on-
+* success signal — a long-lived `SAVEPOINT` would leave the connection
+* uncommitted (lost on close). Every backend interaction runs through `#guard`,
+* which maps a thrown backend `SQLiteError` (or any unexpected non-`SQLiteError`
+* throw) to a typed {@link DatabaseError} — never a raw backend error escapes
+* `DriverInterface`: `CONSTRAINT` → `CONFLICT`, the wrapper's own `CLOSED` →
+* `CLOSED`, `BUSY` (a locked database that outlasted the configured `timeout`)
+* → a retryable `DRIVER` (`context.retryable` is `true`), and `UNKNOWN` / any
+* other throw → `DRIVER`. The original error is preserved as `context.cause`.
+* A `DatabaseError` this driver throws directly (`CLOSED` from the `#require`
+* gate, `NOT_FOUND` from `#table`, `MIGRATION` from a migration-plan fault)
+* passes through `#guard` unchanged, never re-wrapped.
+*/
+var SQLiteDriver = class {
+	#path;
+	#options;
+	#database;
+	#schema = /* @__PURE__ */ new Map();
+	#transacting = false;
+	constructor(path, options) {
+		this.#path = path;
+		this.#options = options ?? {};
+	}
+	async open(schema) {
+		if (schema.some((table) => table.name === "_meta")) throw new _src_core.DatabaseError("VALIDATION", `A declared table cannot be named '${META_TABLE}' — it is reserved for driver metadata`, { table: META_TABLE });
+		this.#guard(() => {
+			this.#database?.close();
+			const database = (0, _orkestrel_sqlite.createSQLiteDatabase)({
+				path: this.#path,
+				readonly: this.#options.readonly,
+				timeout: this.#options.timeout,
+				foreignKeys: this.#options.foreignKeys
+			});
+			database.connect();
+			for (const [name, value] of Object.entries(this.#options.pragmas ?? {})) database.pragma(name, value);
+			const map = /* @__PURE__ */ new Map();
+			for (const table of schema) {
+				map.set(table.name, table);
+				database.exec(schemaToTable(table));
+				for (const sql of schemaToIndexes(table)) database.exec(sql);
+			}
+			database.exec("CREATE TABLE IF NOT EXISTS " + quote(META_TABLE) + " (\"id\" INTEGER, \"version\" INTEGER, \"schema\" TEXT, PRIMARY KEY (\"id\"))");
+			this.#schema = map;
+			this.#database = database;
+		});
+	}
+	async close() {
+		this.#database?.close();
+		this.#database = void 0;
+	}
+	async read(table, key) {
+		const schema = this.#table(table);
+		return this.#guard(() => {
+			const row = this.#require().prepare("SELECT * FROM " + quote(table) + " WHERE " + quote(schema.primary) + " = ?").get([this.#key(key, schema)]);
+			return row === void 0 ? void 0 : decodeRow(row, schema);
+		});
+	}
+	async write(table, key, row) {
+		const schema = this.#table(table);
+		this.#guard(() => {
+			const encoded = encodeRow({
+				...row,
+				[schema.primary]: key
+			}, schema);
+			const names = schema.columns.map((column) => column.name);
+			const values = names.map((name) => encoded[name]);
+			this.#require().prepare("INSERT OR REPLACE INTO " + quote(table) + " (" + names.map(quote).join(", ") + ") VALUES (" + names.map(() => "?").join(", ") + ")").run(values);
+		});
+	}
+	async delete(table, key) {
+		const schema = this.#table(table);
+		return this.#guard(() => {
+			return this.#require().prepare("DELETE FROM " + quote(table) + " WHERE " + quote(schema.primary) + " = ?").run([this.#key(key, schema)]).changes > 0;
+		});
+	}
+	async keys(table) {
+		const schema = this.#table(table);
+		return this.#guard(() => {
+			const primary = quote(schema.primary);
+			const rows = this.#require().prepare("SELECT " + primary + " FROM " + quote(table) + " ORDER BY " + primary).all();
+			const keys = [];
+			for (const row of rows) {
+				const value = row[schema.primary];
+				if (typeof value === "string" || typeof value === "number") keys.push(value);
+			}
+			return keys;
+		});
+	}
+	async *scan(table) {
+		const schema = this.#table(table);
+		const iterator = this.#guard(() => this.#require().prepare("SELECT * FROM " + quote(table) + " ORDER BY " + quote(schema.primary)).iterate())[Symbol.iterator]();
+		while (true) {
+			const step = this.#guard(() => iterator.next());
+			if (step.done === true) return;
+			yield this.#guard(() => decodeRow(step.value, schema));
+		}
+	}
+	async clear(table) {
+		this.#table(table);
+		this.#guard(() => {
+			this.#require().prepare("DELETE FROM " + quote(table)).run();
+		});
+	}
+	async records(table, criteria) {
+		const schema = this.#table(table);
+		if (isExactCriteria(criteria, schema)) return this.#guard(() => {
+			const { sql, params } = compileCriteria(criteria, schema);
+			return this.#require().prepare("SELECT * FROM " + quote(table) + (sql === "" ? "" : " " + sql)).all(params).map((row) => decodeRow(row, schema));
+		});
+		const rows = [];
+		for await (const row of this.scan(table)) rows.push(row);
+		return (0, _src_core.applyCriteria)(rows, criteria);
+	}
+	async count(table, criteria) {
+		const schema = this.#table(table);
+		const conditions = criteria.conditions ?? [];
+		if (conditions.every((condition) => isExactCondition(condition, schema))) return this.#guard(() => {
+			const { sql, params } = compileWhere(conditions, schema);
+			const value = this.#require().prepare("SELECT COUNT(*) AS count FROM " + quote(table) + (sql === "" ? "" : " " + sql)).get(params)?.count;
+			return typeof value === "number" || typeof value === "bigint" ? Number(value) : 0;
+		});
+		const rows = [];
+		for await (const row of this.scan(table)) rows.push(row);
+		return (0, _src_core.filterRows)(rows, conditions).length;
+	}
+	async aggregate(table, operation, column, criteria) {
+		const schema = this.#table(table);
+		const conditions = criteria.conditions ?? [];
+		const conditionsExact = conditions.every((condition) => isExactCondition(condition, schema));
+		const columnExact = operation === "count" || (0, _orkestrel_contract.isString)(column) && schema.columns.some((candidate) => candidate.name === column && (candidate.type === "integer" || candidate.type === "real"));
+		if (conditionsExact && columnExact) return this.#guard(() => {
+			const { sql, params } = compileWhere(conditions, schema);
+			const value = this.#require().prepare("SELECT " + aggregateSQL(operation, column) + " AS value FROM " + quote(table) + (sql === "" ? "" : " " + sql)).get(params)?.value;
+			return value === null || value === void 0 ? void 0 : Number(value);
+		});
+		const rows = [];
+		for await (const row of this.scan(table)) rows.push(row);
+		return (0, _src_core.computeAggregate)((0, _src_core.filterRows)(rows, conditions), operation, column);
+	}
+	async *stream(table, criteria) {
+		const schema = this.#table(table);
+		const conditions = criteria.conditions ?? [];
+		if (conditions.every((condition) => isExactCondition(condition, schema))) {
+			const compiled = compileCriteria({
+				conditions,
+				limit: criteria.limit,
+				offset: criteria.offset
+			}, schema);
+			for (const row of this.#require().prepare("SELECT * FROM " + quote(table) + (compiled.sql === "" ? "" : " " + compiled.sql)).iterate(compiled.params)) yield decodeRow(row, schema);
+			return;
+		}
+		const offset = criteria.offset ?? 0;
+		const limit = criteria.limit;
+		let skipped = 0;
+		let yielded = 0;
+		for await (const row of this.scan(table)) {
+			if (limit !== void 0 && yielded >= limit) return;
+			if (conditions.length > 0 && !(0, _src_core.matchesCriteria)(row, conditions)) continue;
+			if (skipped < offset) {
+				skipped += 1;
+				continue;
+			}
+			yield row;
+			yielded += 1;
+		}
+	}
+	/**
+	* Begin a native transaction — real `BEGIN`, `COMMIT`, `ROLLBACK`.
+	*
+	* @remarks
+	* Calling `commit` or `rollback` a second time (on either method, in either
+	* order) throws `DatabaseError` `CONFLICT`.
+	*
+	* @returns A {@link TransactionInterface} handle to `commit` or `rollback`
+	*/
+	async transaction() {
+		const database = this.#require();
+		this.#guard(() => database.exec("BEGIN"));
+		let settled = false;
+		this.#transacting = true;
+		return {
+			commit: async () => {
+				if (settled) throw new _src_core.DatabaseError("CONFLICT", "Transaction already settled", {});
+				settled = true;
+				this.#transacting = false;
+				this.#guard(() => database.exec("COMMIT"));
+			},
+			rollback: async () => {
+				if (settled) throw new _src_core.DatabaseError("CONFLICT", "Transaction already settled", {});
+				settled = true;
+				this.#transacting = false;
+				this.#guard(() => database.exec("ROLLBACK"));
+			}
+		};
+	}
+	/**
+	* Apply a {@link Migration} plan by executing each step's projected DDL
+	* ({@link import('../helpers.js').stepToSQL}).
+	*
+	* @remarks
+	* Atomicity is provided by whichever native transaction is active: when
+	* this driver's own `transaction()` hook already has a handle open (the
+	* core's versioned reconcile / migrate path joins migrate + stamp under
+	* one native `BEGIN`), the plan's DDL runs directly inside that enclosing
+	* transaction — a mid-plan failure propagates out and the CALLER's
+	* `commit`/`rollback` provides atomicity. node:sqlite (and SQLite
+	* generally) rejects a nested `BEGIN`, so this driver must never open a
+	* second native transaction while one is already open. Otherwise (no
+	* enclosing transaction), `migrate` wraps the plan in its own native
+	* `database.transaction` — atomic on its own: a mid-plan failure rolls
+	* back every DDL statement already applied by the plan. A step
+	* referencing a table not in this driver's declared schema (and that is
+	* not itself a `table.add`) throws `DatabaseError` `MIGRATION` before any
+	* DDL for that step runs, propagating out of whichever transaction is
+	* active (which rolls back on a throw).
+	*
+	* @param plan - The migration plan to apply
+	*/
+	async migrate(plan) {
+		const database = this.#require();
+		const schema = new Map(this.#schema);
+		this.#guard(() => {
+			if (this.#transacting) this.#applyPlan(database, plan, schema);
+			else database.transaction(() => this.#applyPlan(database, plan, schema));
+		});
+		this.#schema = schema;
+	}
+	/**
+	* Read the persisted {@link DriverMeta} from the reserved `_meta` table.
+	*
+	* @returns The last-stamped `DriverMeta`, or `undefined` when never stamped
+	*   (or the stored row is malformed)
+	*/
+	async meta() {
+		const row = this.#guard(() => this.#require().prepare("SELECT \"version\", \"schema\" FROM " + quote(META_TABLE) + " WHERE \"id\" = 1").get());
+		if (row === void 0) return void 0;
+		const version = row.version;
+		const text = row.schema;
+		if (typeof text !== "string") return void 0;
+		if (typeof version !== "number" && typeof version !== "bigint") return void 0;
+		let parsed;
+		try {
+			parsed = JSON.parse(text);
+		} catch {
+			return;
+		}
+		const candidate = {
+			version: Number(version),
+			schema: parsed
+		};
+		if (!(0, _src_core.isDriverMeta)(candidate)) return void 0;
+		return candidate;
+	}
+	/**
+	* Persist `meta` verbatim (as JSON) into the reserved `_meta` table's single
+	* row.
+	*
+	* @param meta - The {@link DriverMeta} to persist
+	*/
+	async stamp(meta) {
+		this.#guard(() => {
+			this.#require().prepare("INSERT OR REPLACE INTO " + quote(META_TABLE) + " (\"id\", \"version\", \"schema\") VALUES (1, ?, ?)").run([meta.version, JSON.stringify(meta.schema)]);
+		});
+	}
+	async snapshot(tables) {
+		const database = this.#require();
+		const names = tables ?? [...this.#schema.keys()];
+		const captured = /* @__PURE__ */ new Map();
+		for (const name of names) {
+			const schema = this.#schema.get(name);
+			if (schema === void 0) continue;
+			captured.set(name, {
+				names: schema.columns.map((column) => column.name),
+				rows: database.prepare("SELECT * FROM " + quote(name)).all()
+			});
+		}
+		return async () => {
+			const current = this.#require();
+			current.transaction(() => {
+				for (const [name, snapshot] of captured) {
+					current.exec("DELETE FROM " + quote(name));
+					const statement = current.prepare("INSERT OR REPLACE INTO " + quote(name) + " (" + snapshot.names.map(quote).join(", ") + ") VALUES (" + snapshot.names.map(() => "?").join(", ") + ")");
+					for (const row of snapshot.rows) statement.run(snapshot.names.map((column) => row[column]));
+				}
+			});
+		};
+	}
+	#guard(run) {
+		try {
+			return run();
+		} catch (error) {
+			if (error instanceof _src_core.DatabaseError) throw error;
+			if ((0, _orkestrel_sqlite.isSQLiteError)(error)) {
+				if (error.code === "CONSTRAINT") throw new _src_core.DatabaseError("CONFLICT", error.message, {
+					cause: error,
+					code: error.code
+				});
+				if (error.code === "CLOSED") throw new _src_core.DatabaseError("CLOSED", error.message, {
+					cause: error,
+					code: error.code
+				});
+				if (error.code === "BUSY") throw new _src_core.DatabaseError("DRIVER", error.message, {
+					cause: error,
+					code: error.code,
+					retryable: true
+				});
+				throw new _src_core.DatabaseError("DRIVER", error.message, {
+					cause: error,
+					code: error.code
+				});
+			}
+			throw new _src_core.DatabaseError("DRIVER", error instanceof Error ? error.message : String(error), { cause: error });
+		}
+	}
+	#require() {
+		if (this.#database === void 0) throw new _src_core.DatabaseError("CLOSED", `SQLite database '${this.#path}' is not open`, { path: this.#path });
+		return this.#database;
+	}
+	#table(name) {
+		this.#require();
+		const schema = this.#schema.get(name);
+		if (schema === void 0) throw new _src_core.DatabaseError("NOT_FOUND", `Table '${name}' is not in the schema`, { table: name });
+		return schema;
+	}
+	#key(key, schema) {
+		const primary = schema.columns.find((column) => column.name === schema.primary);
+		return encodeValue(key, primary === void 0 ? "text" : primary.type);
+	}
+	#applyPlan(database, plan, schema) {
+		for (const step of plan.steps) {
+			const table = step.operation === "table.add" ? step.table.name : step.table;
+			if (step.operation !== "table.add" && !schema.has(table)) throw new _src_core.DatabaseError("MIGRATION", `migrate: unknown table '${table}'`, { table });
+			for (const sql of stepToSQL(step)) database.exec(sql);
+			if (step.operation === "table.add") schema.set(step.table.name, step.table);
+			else if (step.operation === "table.remove") schema.delete(step.table);
+			else {
+				const existing = schema.get(table);
+				if (existing !== void 0) schema.set(table, stepToSchema(existing, step));
+			}
+		}
+	}
+};
+//#endregion
 //#region src/server/factories.ts
 /**
 * Create a persistent JSON-file {@link DriverInterface} for the core database layer.
 *
 * @remarks
-* Pass it to `createDatabase` from `@src/core` to run the whole typed database +
+* Pass it to `createDatabase` from `@orkestrel/database` to run the whole typed database +
 * relations stack against a single JSON file instead of memory — the `Database` /
 * `Table` / `Query` / relations API is unchanged; only where the bytes live changes.
 * The driver is the reference `MemoryDriver` plus JSON-file persistence: `open` loads
@@ -988,8 +1619,51 @@ var JSONDriver = class {
 function createJSONDriver(path) {
 	return new JSONDriver(path);
 }
+/**
+* Create a trusted-mode SQLite {@link DriverInterface} for the core database layer.
+*
+* @remarks
+* Pass it to `createDatabase` from `@orkestrel/database` to run the whole typed database +
+* relations stack against a real SQLite database — the `Database` / `Table` /
+* `Query` / relations API is unchanged; only where the bytes live changes. Built
+* on the published `@orkestrel/sqlite` synchronous wrapper: `open` issues real
+* typed `CREATE TABLE` / `CREATE INDEX` statements (reopen-safe) plus a reserved
+* `_meta` table for `meta()` / `stamp()` — avoid naming a table `_meta`.
+* Querying, paging, and aggregation run natively (`records` / `count` /
+* `aggregate` / `stream`); `transaction` and `migrate` use real `BEGIN` /
+* `COMMIT` / `ROLLBACK`, so `migrate` is atomic even mid-plan.
+*
+* @param options - A bare database file path (`':memory:'` by default, for
+*   back-compat), or a full {@link SQLiteDriverOptions} bag (`path`,
+*   `readonly`, `timeout`, `foreignKeys`, `pragmas`)
+* @returns A {@link DriverInterface} backed by SQLite
+*
+* @example
+* ```ts
+* import { createDatabase } from '@orkestrel/database'
+* import { stringShape } from '@orkestrel/contract'
+* import { createSQLiteDriver } from '@orkestrel/database/server'
+*
+* const db = createDatabase({
+* 	driver: createSQLiteDriver('data/app.sqlite'),
+* 	tables: { users: { id: stringShape(), name: stringShape() } },
+* })
+* await db.table('users').set({ id: 'u1', name: 'Ada' }) // persisted to app.sqlite
+*
+* // Or with options:
+* createSQLiteDriver({ path: 'data/app.sqlite', pragmas: { journal_mode: 'WAL' } })
+* ```
+*/
+function createSQLiteDriver(options = ":memory:") {
+	const resolved = (0, _orkestrel_contract.isString)(options) ? { path: options } : options;
+	return new SQLiteDriver(resolved.path ?? ":memory:", resolved);
+}
 //#endregion
+exports.EXACT_COLUMN_TYPES = EXACT_COLUMN_TYPES;
+exports.EXACT_RANGE_COLUMN_TYPES = EXACT_RANGE_COLUMN_TYPES;
 exports.JSONDriver = JSONDriver;
+exports.META_TABLE = META_TABLE;
+exports.SQLiteDriver = SQLiteDriver;
 exports.aggregateSQL = aggregateSQL;
 exports.columnSQL = columnSQL;
 exports.compileCriteria = compileCriteria;
@@ -997,6 +1671,7 @@ exports.compileOrder = compileOrder;
 exports.compilePage = compilePage;
 exports.compileWhere = compileWhere;
 exports.createJSONDriver = createJSONDriver;
+exports.createSQLiteDriver = createSQLiteDriver;
 exports.declaredType = declaredType;
 exports.decodeRow = decodeRow;
 exports.decodeValue = decodeValue;
@@ -1006,9 +1681,17 @@ exports.escapeLike = escapeLike;
 exports.fieldColumn = fieldColumn;
 exports.fragment = fragment;
 exports.generateKey = generateKey;
+exports.indexName = indexName;
+exports.isExactCondition = isExactCondition;
+exports.isExactCriteria = isExactCriteria;
+exports.isExactOrder = isExactOrder;
+exports.jsonTypeColumn = jsonTypeColumn;
+exports.matchesDeclaredType = matchesDeclaredType;
 exports.quote = quote;
 exports.schemaToIndexes = schemaToIndexes;
 exports.schemaToTable = schemaToTable;
+exports.stepToSQL = stepToSQL;
+exports.stepToSchema = stepToSchema;
 exports.valueType = valueType;
 
 //# sourceMappingURL=index.cjs.map