@orkestrel/database 0.0.1

package/dist/src/server/index.cjs

@@ -0,0 +1,1014 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+let node_crypto = require("node:crypto");
+let _src_core = require("../core/index.js");
+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";
+}
+/**
+* Determine whether a value is a non-null object.
+*
+* @remarks
+* `true` for arrays, class instances, plain objects, `Map`, `Set`, etc. — use
+* {@link isRecord} when you need a plain-record check.
+*/
+function isObject(value) {
+	return typeof value === "object" && value !== null;
+}
+/**
+* Determine whether a value is a plain record (object literal or null-prototype),
+* not an array or class instance.
+*
+* @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);
+}
+/**
+* Invoke a callback and capture its outcome as a {@link Result}, never letting
+* a throw escape.
+*
+* @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`
+*
+* @example
+* ```ts
+* const outcome = attempt(() => predicate(value))
+* return outcome.success && outcome.value
+* ```
+*/
+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)
+		};
+	}
+}
+//#endregion
+//#region src/server/helpers.ts
+/**
+* Generate a fresh unique key — a v4 UUID string, backed by `node:crypto`.
+*
+* @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.
+*
+* @returns A new UUID string
+*
+* @example
+* ```ts
+* const db = createDatabase({ driver, tables, key: generateKey })
+* ```
+*/
+function generateKey() {
+	return (0, node_crypto.randomUUID)();
+}
+/**
+* Map a portable {@link ColumnType} to its SQLite column type.
+*
+* @remarks
+* `text` / `json` → `TEXT` (JSON is stored as text and read back with
+* `json_extract` for nested-field queries); `integer` / `boolean` → `INTEGER`
+* (a boolean stores `1` / `0`); `real` → `REAL`; `blob` → `BLOB`. No `NOT NULL`
+* is ever emitted — the contract validates required-ness; the database is just
+* storage (AGENTS §14, the typed layer above imposes the shape).
+*
+* @param type - The portable column type
+* @returns The SQLite column type keyword
+*
+* @example
+* ```ts
+* columnSQL('integer') // 'INTEGER'
+* columnSQL('json') // 'TEXT'
+* ```
+*/
+function columnSQL(type) {
+	switch (type) {
+		case "text":
+		case "json": return "TEXT";
+		case "integer":
+		case "boolean": return "INTEGER";
+		case "real": return "REAL";
+		case "blob": return "BLOB";
+	}
+}
+/**
+* Quote a SQL identifier (a table or column name) so any characters are literal.
+*
+* @remarks
+* Wraps the name in double quotes and doubles any embedded quote — the standard
+* SQL identifier-quoting that lets a column named `order` or `from` be referenced
+* safely. Identifiers cannot be bound as parameters, so they are quoted instead.
+*
+* @param identifier - The raw identifier
+* @returns The double-quoted identifier
+*
+* @example
+* ```ts
+* quote('order') // '"order"'
+* ```
+*/
+function quote(identifier) {
+	return "\"" + identifier.replaceAll("\"", "\"\"") + "\"";
+}
+/**
+* Compile a {@link FieldPath} to the SQL expression that reads it.
+*
+* @remarks
+* A single string is ONE column — `quote(path)`. An array descends a JSON column:
+* the first element is the (quoted) column, the rest a `json_extract` path
+* (`json_extract("payload", '$.user.id')`), matching the guide's nested-field
+* examples (simple identifier keys). The string's value is never split on `.`
+* (AGENTS — `FieldPath` semantics): a dotted string is one column literally.
+*
+* @param path - The field path (a column, or a column + nested keys)
+* @returns The SQL expression selecting the value
+*
+* @example
+* ```ts
+* fieldColumn('payload') // '"payload"'
+* fieldColumn(['payload', 'user', 'id']) // 'json_extract("payload", \'$.user.id\')'
+* ```
+*/
+function fieldColumn(path) {
+	if (isString(path)) return quote(path);
+	const rest = path.slice(1).map((key) => "." + key.replaceAll("'", "''")).join("");
+	return "json_extract(" + quote(path[0]) + ", '$" + rest + "')";
+}
+/**
+* Compile an {@link AggregateFunction} over a {@link FieldPath} to its SQL
+* aggregate expression — the SELECT body the SQLite driver's native `aggregate`
+* runs.
+*
+* @remarks
+* `count` → `COUNT(*)` (counting all matched ROWS, not non-null column values —
+* mirroring the engine's `computeAggregate('count')`, which is `rows.length`); the
+* numeric aggregates wrap the column's read expression (a flat column, or a nested
+* `json_extract` path) in `SUM` / `AVG` / `MIN` / `MAX`. Over zero matched rows
+* `COUNT(*)` is `0` and the numeric aggregates are SQL `NULL` (→ `undefined`),
+* matching the engine.
+*
+* @param operation - The aggregate to compute
+* @param column - The column (or nested path) to aggregate
+* @returns The SQL aggregate expression
+*
+* @example
+* ```ts
+* aggregateSQL('count', 'age') // 'COUNT(*)'
+* aggregateSQL('sum', 'age') // 'SUM("age")'
+* aggregateSQL('average', ['payload', 'score']) // 'AVG(json_extract("payload", \'$.score\'))'
+* ```
+*/
+function aggregateSQL(operation, column) {
+	switch (operation) {
+		case "count": return "COUNT(*)";
+		case "sum": return "SUM(" + fieldColumn(column) + ")";
+		case "average": return "AVG(" + fieldColumn(column) + ")";
+		case "minimum": return "MIN(" + fieldColumn(column) + ")";
+		case "maximum": return "MAX(" + fieldColumn(column) + ")";
+	}
+}
+/**
+* Encode a JS value to its stored {@link SQLiteValue} for a column's type.
+*
+* @remarks
+* The forward half of the bridge, total (AGENTS §14): a value that does not fit
+* its column's storage type encodes to `null` rather than throwing. A `boolean`
+* column stores `1` / `0` (and `null` / `undefined` → `null`); a `json` column
+* stores `JSON.stringify` (or `null` for `null` / `undefined`); `integer` /
+* `real` keep a `number` / `bigint`, else `null`; `text` keeps a `string`, else
+* `null`; `blob` keeps a `Uint8Array`, else `null`. Narrowed with `typeof` /
+* `instanceof`, never `as`.
+*
+* @param value - The JS value to store
+* @param type - The column's portable storage type
+* @returns The value SQLite stores
+*
+* @example
+* ```ts
+* encodeValue(true, 'boolean') // 1
+* encodeValue({ a: 1 }, 'json') // '{"a":1}'
+* ```
+*/
+function encodeValue(value, type) {
+	switch (type) {
+		case "boolean": return value === void 0 || value === null ? null : value === true ? 1 : 0;
+		case "json": return value === void 0 || value === null ? null : JSON.stringify(value);
+		case "integer":
+		case "real": return typeof value === "number" || typeof value === "bigint" ? value : null;
+		case "text": return typeof value === "string" ? value : null;
+		case "blob": return value instanceof Uint8Array ? value : null;
+	}
+}
+/**
+* Decode a stored {@link SQLiteValue} back to its JS value for a column's type —
+* the exact inverse of {@link encodeValue}.
+*
+* @remarks
+* A `boolean` column reads `1` / `0` back to `true` / `false` (a stored `null`
+* → `undefined`); a `json` column `JSON.parse`s a string (anything else →
+* `undefined`); every other type passes the value through, mapping a stored
+* `NULL` to `undefined`. NULL decodes to `undefined` so {@link decodeRow} can
+* omit absent columns.
+*
+* @param value - The stored SQLite value
+* @param type - The column's portable storage type
+* @returns The decoded JS value (`undefined` for a stored `NULL`)
+*
+* @example
+* ```ts
+* decodeValue(1, 'boolean') // true
+* decodeValue('{"a":1}', 'json') // { a: 1 }
+* ```
+*/
+function decodeValue(value, type) {
+	switch (type) {
+		case "boolean": return value === null ? void 0 : value !== 0;
+		case "json": return typeof value === "string" ? JSON.parse(value) : void 0;
+		default: return value === null ? void 0 : value;
+	}
+}
+/**
+* Encode a whole {@link Row} to a {@link SQLiteRow} by its table's schema.
+*
+* @remarks
+* Encodes each declared column's value with {@link encodeValue}; columns the row
+* does not carry encode from `undefined` (so they store `null`). Only the
+* schema's columns appear in the result — an extra row key is dropped.
+*
+* @param row - The JS row to store
+* @param schema - The table's schema
+* @returns The storable SQLite row
+*
+* @example
+* ```ts
+* encodeRow({ id: 'u1', active: true }, schema) // { id: 'u1', active: 1, ... }
+* ```
+*/
+function encodeRow(row, schema) {
+	const result = {};
+	for (const column of schema.columns) result[column.name] = encodeValue(row[column.name], column.type);
+	return result;
+}
+/**
+* Decode a stored {@link SQLiteRow} back to a {@link Row} by its table's schema.
+*
+* @remarks
+* Decodes each declared column with {@link decodeValue} and **omits** any column
+* whose decoded value is `undefined` — so an absent / `NULL` optional column does
+* not surface as `{ bio: undefined }`, matching how the contract's optional
+* columns expect absence. A known, documented edge: a non-optional `nullableShape`
+* column storing `null` round-trips to absent (a `null` cell decodes to
+* `undefined`, and an `undefined` value is omitted).
+*
+* @param row - The stored SQLite row
+* @param schema - The table's schema
+* @returns The decoded JS row (absent columns omitted)
+*
+* @example
+* ```ts
+* decodeRow({ id: 'u1', active: 1, bio: null }, schema) // { id: 'u1', active: true }
+* ```
+*/
+function decodeRow(row, schema) {
+	const result = {};
+	for (const column of schema.columns) {
+		const decoded = decodeValue(row[column.name], column.type);
+		if (decoded !== void 0) result[column.name] = decoded;
+	}
+	return result;
+}
+/**
+* Project a {@link TableSchema} to the `CREATE TABLE IF NOT EXISTS` statement a
+* SQLite driver's `open` issues for it.
+*
+* @remarks
+* Each column compiles to `<quoted name> <columnSQL(type)>`; the statement ends
+* with `PRIMARY KEY (<quoted primary>)`. No `NOT NULL` is emitted — the contract
+* validates required-ness, the database is just storage (AGENTS §14).
+*
+* @param schema - The table's schema
+* @returns The `CREATE TABLE IF NOT EXISTS …` statement
+*
+* @example
+* ```ts
+* schemaToTable(schema)
+* // 'CREATE TABLE IF NOT EXISTS "users" ("id" TEXT, "age" INTEGER, PRIMARY KEY ("id"))'
+* ```
+*/
+function schemaToTable(schema) {
+	const columns = schema.columns.map((column) => quote(column.name) + " " + columnSQL(column.type));
+	return "CREATE TABLE IF NOT EXISTS " + quote(schema.name) + " (" + columns.join(", ") + ", PRIMARY KEY (" + quote(schema.primary) + "))";
+}
+/**
+* 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.
+*
+* @param schema - The table's schema
+* @returns One `CREATE INDEX IF NOT EXISTS …` statement per declared index
+*
+* @example
+* ```ts
+* schemaToIndexes(schema)
+* // ['CREATE INDEX IF NOT EXISTS "idx_users_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(", ") + ")");
+}
+//#endregion
+//#region src/server/compilers.ts
+/**
+* Escape `\`, `%`, and `_` (each with a leading `\`) so a `starts` / `ends`
+* operand is matched literally under the `LIKE … ESCAPE '\'` clause.
+*
+* @param text - The raw operand text
+* @returns The text with LIKE metacharacters escaped
+*
+* @example
+* ```ts
+* escapeLike('50%_off') // '50\\%\\_off'
+* ```
+*/
+function escapeLike(text) {
+	return text.replaceAll("\\", "\\\\").replaceAll("%", "\\%").replaceAll("_", "\\_");
+}
+/**
+* The declared storage type of a flat (string) column, read from the schema.
+*
+* @param column - The column name
+* @param schema - The table's schema
+* @returns The column's {@link ColumnType}, or `undefined` if the schema does not carry it
+*
+* @example
+* ```ts
+* declaredType('age', schema) // 'integer'
+* ```
+*/
+function declaredType(column, schema) {
+	return schema.columns.find((candidate) => candidate.name === column)?.type;
+}
+/**
+* The storage type a nested (`json_extract`) operand encodes as, derived from its
+* RUNTIME value — NOT `json`.
+*
+* @remarks
+* `json_extract` returns the unquoted, natively-typed scalar (a JSON boolean as
+* `1` / `0`, a number as-is, a string as-is), so the operand must encode to that
+* same scalar to compare. A boolean → `'boolean'` (→ `1` / `0`); a number →
+* `'integer'` / `'real'`; a bigint → `'integer'`; a string → `'text'`; `null` /
+* `undefined` → `'text'` (encodes to `null`); an object / array → `'json'` (the
+* edge of comparing against a json subtree).
+*
+* @param value - The runtime operand value
+* @returns The {@link ColumnType} to encode it as
+*
+* @example
+* ```ts
+* valueType(true) // 'boolean'
+* valueType(9) // 'integer'
+* ```
+*/
+function valueType(value) {
+	if (typeof value === "boolean") return "boolean";
+	if (typeof value === "number") return Number.isInteger(value) ? "integer" : "real";
+	if (typeof value === "bigint") return "integer";
+	if (typeof value === "object" && value !== null) return "json";
+	return "text";
+}
+/**
+* Compile one condition to its `<column> <operator>` SQL fragment and the params
+* it binds.
+*
+* @remarks
+* Every operand is run through `encodeValue`, so a bound value matches the SQL
+* the column side compiles to. A flat column encodes operands with its DECLARED
+* schema type (a flat `json` column → `JSON.stringify`); a nested `FieldPath`
+* 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.
+*
+* @param condition - The condition to compile
+* @param schema - The table's schema (for declared column types)
+* @returns The SQL fragment and its bound parameters
+*
+* @example
+* ```ts
+* fragment({ column: 'age', operator: 'above', values: [18], connector: 'and' }, schema)
+* // { sql: '"age" > ?', 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 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);
+	switch (condition.operator) {
+		case "equals":
+			if (nullOperand) return {
+				sql: column + " IS NULL",
+				params: []
+			};
+			return {
+				sql: column + " = ?",
+				params: [encode(first)]
+			};
+		case "not":
+			if (nullOperand) return {
+				sql: column + " IS NOT NULL",
+				params: []
+			};
+			return {
+				sql: column + " != ?",
+				params: [encode(first)]
+			};
+		case "above": return {
+			sql: column + " > ?",
+			params: [encode(first)]
+		};
+		case "below": return {
+			sql: column + " < ?",
+			params: [encode(first)]
+		};
+		case "from": return {
+			sql: column + " >= ?",
+			params: [encode(first)]
+		};
+		case "to": return {
+			sql: column + " <= ?",
+			params: [encode(first)]
+		};
+		case "between": return {
+			sql: column + " BETWEEN ? AND ?",
+			params: [encode(first), encode(second)]
+		};
+		case "like": return {
+			sql: column + " LIKE ?",
+			params: [encode(first)]
+		};
+		case "glob": return {
+			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 "any":
+			if (condition.values.length === 0) return {
+				sql: "0",
+				params: []
+			};
+			return {
+				sql: column + " IN (" + condition.values.map(() => "?").join(", ") + ")",
+				params: condition.values.map(encode)
+			};
+		case "none":
+			if (condition.values.length === 0) return {
+				sql: "1",
+				params: []
+			};
+			return {
+				sql: column + " NOT IN (" + condition.values.map(() => "?").join(", ") + ")",
+				params: condition.values.map(encode)
+			};
+		case "absent": return {
+			sql: column + " IS NULL",
+			params: []
+		};
+		case "present": return {
+			sql: column + " IS NOT NULL",
+			params: []
+		};
+	}
+}
+/**
+* Fold the conditions into one WHERE clause, parenthesizing progressively
+* left-to-right so the grouping matches the engine's `matchesCriteria` fold.
+*
+* @remarks
+* The first condition's connector is ignored, per the {@link Condition} types.
+*
+* @param conditions - The conditions to fold
+* @param schema - The table's schema
+* @returns The `WHERE …` clause and its bound parameters, or an empty clause for zero conditions
+*
+* @example
+* ```ts
+* compileWhere([{ column: 'age', operator: 'from', values: [18], connector: 'and' }], schema)
+* // { sql: 'WHERE "age" >= ?', params: [18] }
+* ```
+*/
+function compileWhere(conditions, schema) {
+	if (conditions.length === 0) return {
+		sql: "",
+		params: []
+	};
+	const head = fragment(conditions[0], schema);
+	let clause = head.sql;
+	const params = [...head.params];
+	for (let index = 1; index < conditions.length; index += 1) {
+		const next = fragment(conditions[index], schema);
+		const operator = conditions[index].connector === "or" ? "OR" : "AND";
+		clause = "(" + clause + " " + operator + " " + next.sql + ")";
+		params.push(...next.params);
+	}
+	return {
+		sql: "WHERE " + clause,
+		params
+	};
+}
+/**
+* Compile the ORDER BY clause from the order terms, always ending with the
+* primary key as the final determinant.
+*
+* @remarks
+* The native `records` read then resolves ties in key order, matching a
+* primary-key-ordered `scan` and the core engine's stable `sortRows` over a
+* key-ordered scan (and IndexedDB's key-ordered reads), so a native read equals
+* the scan path (AGENTS §21 / §22 native ↔ engine parity). SQLite without an
+* `ORDER BY` returns rowid (insertion) order, and an explicit order alone breaks
+* ties by rowid too — both diverge from every key-ordered backend. The
+* tie-breaker is ASCENDING regardless of the explicit directions: the engine's
+* stable sort runs over key-ascending input, so equal rows stay in
+* ascending-key order whichever way the explicit terms point. Skipped when the
+* primary is already an explicit order term (no double-append).
+*
+* @param order - The explicit order terms, or `undefined`
+* @param schema - The table's schema (for the primary key)
+* @returns The `ORDER BY …` clause, or an empty string when there is nothing to order by
+*
+* @example
+* ```ts
+* compileOrder([{ column: 'age', direction: 'descending' }], schema)
+* // 'ORDER BY "age" DESC, "id"'
+* ```
+*/
+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));
+	return terms.length === 0 ? "" : "ORDER BY " + terms.join(", ");
+}
+/**
+* Compile the LIMIT / OFFSET clause.
+*
+* @remarks
+* An offset without a limit uses `LIMIT -1` (SQLite's "no limit") so OFFSET is
+* still honored.
+*
+* @param limit - The maximum row count, or `undefined`
+* @param offset - The row count to skip, or `undefined`
+* @returns The `LIMIT …` clause and its bound parameters, or an empty clause when neither is set
+*
+* @example
+* ```ts
+* compilePage(undefined, 5) // { sql: 'LIMIT -1 OFFSET ?', params: [5] }
+* ```
+*/
+function compilePage(limit, offset) {
+	if (limit !== void 0 && offset !== void 0) return {
+		sql: "LIMIT ? OFFSET ?",
+		params: [limit, offset]
+	};
+	if (limit !== void 0) return {
+		sql: "LIMIT ?",
+		params: [limit]
+	};
+	if (offset !== void 0) return {
+		sql: "LIMIT -1 OFFSET ?",
+		params: [offset]
+	};
+	return {
+		sql: "",
+		params: []
+	};
+}
+/**
+* Compile a {@link Criteria} into the SQL clause that follows a table name, with
+* its bound parameters in clause order.
+*
+* @remarks
+* The driver's native `records` / `count` path: it assembles
+* `[where, orderBy, limitOffset]` (each possibly empty) into one clause so a
+* `SELECT * FROM <table> <clause>` runs the whole read in the engine instead of
+* over a JS `scan`. The WHERE fold is parenthesized **left-to-right** to mirror
+* the core engine's `matchesCriteria` (not SQL's native AND-over-OR precedence),
+* so a native and an engine read return identical rows. Each operand is encoded
+* via `encodeValue`: a flat column uses its declared schema type, while a nested
+* `FieldPath` (a `json_extract` read) encodes each operand as the native scalar
+* the extract returns — derived from the operand's runtime type — so it compares.
+* The 15 operators map per the databases guide's operator table, with
+* `starts` / `ends` using `LIKE … ESCAPE '\'` and an empty `any` / `none` list
+* collapsing to a constant. A `undefined` criteria (or one with no parts)
+* compiles to an empty clause.
+*
+* @param criteria - The read specification, or `undefined` for all rows
+* @param schema - The table's schema (column types for operand encoding)
+* @returns The SQL tail and its bound parameters
+*
+* @example
+* ```ts
+* compileCriteria({ conditions: [{ column: 'age', operator: 'from', values: [18], connector: 'and' }] }, schema)
+* // { sql: 'WHERE "age" >= ? ORDER BY "id"', params: [18] }
+* ```
+*/
+function compileCriteria(criteria, schema) {
+	const where = compileWhere(criteria?.conditions ?? [], schema);
+	const orderBy = compileOrder(criteria?.order, schema);
+	const page = compilePage(criteria?.limit, criteria?.offset);
+	return {
+		sql: [
+			where.sql,
+			orderBy,
+			page.sql
+		].filter((part) => part !== "").join(" "),
+		params: [...where.params, ...page.params]
+	};
+}
+//#endregion
+//#region src/server/drivers/JSONDriver.ts
+/**
+* A persistent {@link DriverInterface} backed by a single JSON file — the
+* reference {@link MemoryDriver} plus file load / flush.
+*
+* @remarks
+* A decorator, not a reimplementation: every primitive delegates to an inner
+* {@link MemoryDriver}, so querying, key-order `scan` / `keys`, and capture-replay
+* `snapshot` are inherited unchanged — this layer adds only persistence. `open`
+* loads the file into memory; every mutation (`write` / `delete` / `clear`) flushes
+* the whole store back. The file is one JSON object, `{ meta?: DriverMeta, tables: {
+* [name]: rows } }` — `meta` is present only once the store has been `stamp`ed
+* (an unstamped store serializes the old `{ tables }` shape, preserving
+* backward compatibility); a per-table array of rows, each row carrying its own
+* primary (the table contract), so the key is recovered on load with
+* {@link extractKey} and the file need not store it. The parsed JSON crosses the
+* boundary as `unknown` and is narrowed with {@link isRecord} / {@link extractKey},
+* never asserted (AGENTS §14): a missing, corrupt, or wrong-shaped file starts
+* empty rather than throwing, and a malformed row (or malformed `meta`) is
+* skipped/dropped rather than thrown on. It is scan-only — it implements none of
+* the optional native `records` / `count` / `aggregate` hooks, so the core engine
+* over `scan` answers every query. For development, small datasets, and portable /
+* inspectable data; for large or concurrent workloads reach for a SQLite-backed
+* driver.
+*
+* A failure in the write path ({@link JSONDriver.#serialize} — `mkdir` /
+* `writeFile` / `rename`) is wrapped and rethrown as `DatabaseError` `DRIVER`,
+* carrying the target `path` in its context; the read path ({@link
+* JSONDriver.#load}) tolerance above is a separate, deliberate contract and is
+* never touched by this wrapping.
+*/
+var JSONDriver = class {
+	#path;
+	#memory = new _src_core.MemoryDriver();
+	#schema = [];
+	#meta;
+	#flushCount = 0;
+	#chain = Promise.resolve();
+	#deferring = false;
+	constructor(path) {
+		this.#path = path;
+	}
+	async open(schema) {
+		this.#schema = schema;
+		await this.#memory.open(schema);
+		await this.#load();
+	}
+	async close() {
+		await this.#memory.close();
+	}
+	async read(table, key) {
+		return this.#memory.read(table, key);
+	}
+	async write(table, key, row) {
+		await this.#memory.write(table, key, row);
+		if (!this.#deferring) await this.#flush();
+	}
+	async delete(table, key) {
+		const removed = await this.#memory.delete(table, key);
+		if (!this.#deferring) await this.#flush();
+		return removed;
+	}
+	keys(table) {
+		return this.#memory.keys(table);
+	}
+	scan(table) {
+		return this.#memory.scan(table);
+	}
+	/**
+	* Natively filtered lazy iteration — delegates to the inner {@link MemoryDriver}.
+	*
+	* @remarks
+	* Semantics are the memory driver's own: `criteria.conditions` filters, `offset`
+	* / `limit` page lazily, and `criteria.order` is ignored (streaming yields key
+	* order; sorted output is `records()`'s job).
+	*
+	* @param table - The table to stream
+	* @param criteria - The filter / offset / limit to apply lazily
+	*/
+	stream(table, criteria) {
+		return this.#memory.stream(table, criteria);
+	}
+	async clear(table) {
+		await this.#memory.clear(table);
+		if (!this.#deferring) await this.#flush();
+	}
+	/**
+	* Begin a native transaction — flush-coalescing over the inner {@link MemoryDriver}.
+	*
+	* @remarks
+	* Single-writer: throws `DatabaseError` `CONFLICT` if a transaction is already
+	* active — this driver does not support nesting. On begin, captures the inner
+	* memory rollback thunk via `#memory.snapshot()` and suppresses per-mutation
+	* `#flush` — `write` / `delete` / `clear` still mutate memory but no longer
+	* touch the file, so N mutations under the handle cost ONE file write instead
+	* of N. `commit()` releases the suppression and performs that one atomic
+	* `#flush()`, persisting the transaction's net state. `rollback()` restores
+	* memory via the captured snapshot thunk, then `#flush()`s so the file reflects
+	* the restored state. Outside a transaction, behavior is unchanged — every
+	* mutation flushes on its own. Calling `commit` / `rollback` a second time (on
+	* either method, in either order) throws `DatabaseError` `CONFLICT`.
+	*
+	* @returns A {@link TransactionInterface} handle to `commit` or `rollback`
+	*/
+	async transaction() {
+		if (this.#deferring) throw new _src_core.DatabaseError("CONFLICT", "A transaction is already active on this driver", {});
+		const rollback = await this.#memory.snapshot();
+		this.#deferring = true;
+		let settled = false;
+		return {
+			commit: async () => {
+				if (settled) throw new _src_core.DatabaseError("CONFLICT", "Transaction already settled", {});
+				settled = true;
+				this.#deferring = false;
+				await this.#flush();
+			},
+			rollback: async () => {
+				if (settled) throw new _src_core.DatabaseError("CONFLICT", "Transaction already settled", {});
+				settled = true;
+				await rollback();
+				this.#deferring = false;
+				await this.#flush();
+			}
+		};
+	}
+	async snapshot(tables) {
+		const rollback = await this.#memory.snapshot(tables);
+		return async () => {
+			await rollback();
+			await this.#flush();
+		};
+	}
+	async meta() {
+		return this.#meta;
+	}
+	/**
+	* Persist `meta` verbatim for a later `meta()` to return.
+	*
+	* @remarks
+	* Respects the same defer-flush suppression as `write` / `delete` / `clear`
+	* (see {@link JSONDriver.transaction} @remarks) — stamping inside an active
+	* transaction updates memory but does not flush until the transaction settles.
+	*
+	* @param meta - The {@link DriverMeta} to persist
+	*/
+	async stamp(meta) {
+		this.#meta = meta;
+		if (!this.#deferring) await this.#flush();
+	}
+	/**
+	* Apply a {@link Migration} plan by delegating to the inner {@link MemoryDriver},
+	* then persist the migrated state.
+	*
+	* @remarks
+	* The inner `MemoryDriver.migrate` applies each step (adding/removing tables,
+	* adding/removing columns from stored rows, no-op index steps) and throws
+	* `DatabaseError` `MIGRATION` for a step referencing an unknown table — that
+	* error propagates untouched. `table.add` / `table.remove` steps also update
+	* this driver's own declared `#schema`, mirroring the bookkeeping `open` does,
+	* so a subsequent `#flush` / `#load` round-trip includes (or drops) the table.
+	* A successful migration ends with one atomic `#flush()` so the new state
+	* survives a close and reopen. A multi-step plan applies its steps
+	* sequentially and is NOT atomic — a failure partway through a plan leaves
+	* the earlier steps already applied.
+	*
+	* @param plan - The migration plan to apply
+	*/
+	async migrate(plan) {
+		await this.#memory.migrate?.(plan);
+		let schema = this.#schema;
+		for (const step of plan.steps) if (step.operation === "table.add") schema = schema.some((table) => table.name === step.table.name) ? schema : [...schema, step.table];
+		else if (step.operation === "table.remove") schema = schema.filter((table) => table.name !== step.table);
+		this.#schema = schema;
+		await this.#flush();
+	}
+	async #load() {
+		let raw;
+		try {
+			raw = await (0, node_fs_promises.readFile)(this.#path, "utf-8");
+		} catch {
+			return;
+		}
+		let parsed;
+		try {
+			parsed = JSON.parse(raw);
+		} catch {
+			return;
+		}
+		if (!isRecord(parsed) || !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;
+				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
+			};
+		}
+	}
+	async #flush() {
+		const next = this.#chain.then(() => this.#serialize());
+		this.#chain = next.catch(() => {});
+		await next;
+	}
+	async #serialize() {
+		const tables = {};
+		for (const table of this.#schema) {
+			const rows = [];
+			for await (const row of this.#memory.scan(table.name)) rows.push(row);
+			tables[table.name] = rows;
+		}
+		this.#flushCount += 1;
+		const temp = `${this.#path}.${process.pid}.${this.#flushCount}.tmp`;
+		const payload = this.#meta === void 0 ? { tables } : {
+			meta: this.#meta,
+			tables
+		};
+		try {
+			await (0, node_fs_promises.mkdir)((0, node_path.dirname)(this.#path), { recursive: true });
+			await (0, node_fs_promises.writeFile)(temp, JSON.stringify(payload, null, 2), "utf-8");
+			await (0, node_fs_promises.rename)(temp, this.#path);
+		} catch (error) {
+			await (0, node_fs_promises.rm)(temp, { force: true }).catch(() => {});
+			throw new _src_core.DatabaseError("DRIVER", "Failed to persist the database file", {
+				path: this.#path,
+				cause: error
+			});
+		}
+	}
+};
+//#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 +
+* 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
+* the file, every mutation flushes the whole store back, and querying runs through
+* the core engine over `scan` (it is scan-only — no native `records` / `count` /
+* `aggregate`). A missing, corrupt, or wrong-shaped file starts empty rather than
+* throwing.
+*
+* @param path - The JSON file path data is loaded from and flushed to
+* @returns A {@link DriverInterface} backed by a JSON file
+*
+* @example
+* ```ts
+* import { createDatabase } from '@orkestrel/database'
+* import { stringShape } from '@orkestrel/contract'
+* import { createJSONDriver } from '@orkestrel/database/server'
+*
+* const db = createDatabase({
+* 	driver: createJSONDriver('data/app.json'),
+* 	tables: { users: { id: stringShape(), name: stringShape() } },
+* })
+* await db.table('users').set({ id: 'u1', name: 'Ada' }) // persisted to app.json
+* ```
+*/
+function createJSONDriver(path) {
+	return new JSONDriver(path);
+}
+//#endregion
+exports.JSONDriver = JSONDriver;
+exports.aggregateSQL = aggregateSQL;
+exports.columnSQL = columnSQL;
+exports.compileCriteria = compileCriteria;
+exports.compileOrder = compileOrder;
+exports.compilePage = compilePage;
+exports.compileWhere = compileWhere;
+exports.createJSONDriver = createJSONDriver;
+exports.declaredType = declaredType;
+exports.decodeRow = decodeRow;
+exports.decodeValue = decodeValue;
+exports.encodeRow = encodeRow;
+exports.encodeValue = encodeValue;
+exports.escapeLike = escapeLike;
+exports.fieldColumn = fieldColumn;
+exports.fragment = fragment;
+exports.generateKey = generateKey;
+exports.quote = quote;
+exports.schemaToIndexes = schemaToIndexes;
+exports.schemaToTable = schemaToTable;
+exports.valueType = valueType;
+
+//# sourceMappingURL=index.cjs.map