@orkestrel/database 0.0.5 → 0.0.7

package/dist/src/browser/index.js

@@ -1,17 +1,18 @@
-import { DatabaseError, applyCriteria, compareValues, extractKey, isDriverMeta, matchesCriteria, migrateRows } from "../core/index.js";
-import { createIndexedDBDatabase, isIndexedDBError, range } from "@orkestrel/indexeddb";
+import { DatabaseError, applyQuery, bindRowKey, checkAbort, cloneDriverMetadata, cloneMigrationInput, compareValues, equalsValue, extractKey, isDatabaseError, isKey, matchesQuery, migrateRows, normalizeDriverSchema, planMigration, projectMigrationSchema, validatePage } from "../core/index.js";
+import { createIndexedDBDatabase, isIndexedDBError, rangeAboveKey, rangeBelowKey, rangeBetweenKeys, rangeExactKey, rangeFromKey, rangeToKey } from "@orkestrel/indexeddb";
 //#region src/browser/constants.ts
-var INDEXABLE_TYPES = /* @__PURE__ */ new Set([
+var INDEXABLE_STORAGE = /* @__PURE__ */ new Set([
 	"text",
 	"integer",
 	"real"
 ]);
-var META_STORE = "__meta__";
+var METADATA_STORE = "__metadata__";
 //#endregion
 //#region src/browser/helpers.ts
 /**
 * The `IDBKeyRange` a single {@link Condition} maps to, when its operator is one
-* of the six exact key comparisons over scalar operands — else `null`.
+* of the six exact key comparisons over scalar operands; otherwise
+* `undefined`.
 *
 * @remarks
 * Only the comparison operators (`equals`/`above`/`below`/`from`/`to`/`between`)
@@ -26,7 +27,7 @@ var META_STORE = "__meta__";
 * boolean) that is not a usable key. `between` additionally guards against a
 * REVERSED pair (`first > second`): native `IDBKeyRange.bound` throws a raw
 * `DataError` `DOMException` for a lower bound above the upper bound, so a
-* reversed pair returns `null` here (falls back to a full scan, which the
+* reversed pair returns `undefined` here (falls back to a full scan, which the
 * engine then correctly resolves to an empty result) rather than letting a
 * native exception escape untyped — the same defensive posture as every other
 * backend, which returns empty for a reversed/empty range instead of throwing.
@@ -35,18 +36,18 @@ var META_STORE = "__meta__";
 * to a (possibly lossy) range.
 *
 * @param condition - The condition to translate
-* @returns Its exact key range, or `null` when the operator/operands cannot push
+* @returns Its exact key range, or `undefined` when the operator/operands cannot push
 */
-function conditionRange(condition) {
+function conditionToRange(condition) {
 	const first = condition.values[0];
 	const second = condition.values[1];
 	switch (condition.operator) {
-		case "equals": return isKey(first) ? range.only(first) : null;
-		case "above": return isKey(first) ? range.above(first) : null;
-		case "below": return isKey(first) ? range.below(first) : null;
-		case "from": return isKey(first) ? range.from(first) : null;
-		case "to": return isKey(first) ? range.to(first) : null;
-		case "between": return isKey(first) && isKey(second) && compareValues(first, second) <= 0 ? range.between(first, second) : null;
+		case "equals": return isKey(first) ? rangeExactKey(first) : void 0;
+		case "above": return isKey(first) ? rangeAboveKey(first) : void 0;
+		case "below": return isKey(first) ? rangeBelowKey(first) : void 0;
+		case "from": return isKey(first) ? rangeFromKey(first) : void 0;
+		case "to": return isKey(first) ? rangeToKey(first) : void 0;
+		case "between": return isKey(first) && isKey(second) && compareValues(first, second) <= 0 ? rangeBetweenKeys(first, second) : void 0;
 		case "not":
 		case "like":
 		case "glob":
@@ -55,14 +56,11 @@ function conditionRange(condition) {
 		case "any":
 		case "none":
 		case "absent":
-		case "present": return null;
+		case "present": return;
 	}
 }
-function isKey(value) {
-	return typeof value === "string" || typeof value === "number";
-}
 /**
-* Plan an IndexedDB read for a {@link Criteria} — pick the index (or the primary
+* Plan an IndexedDB read for a {@link QueryInput} — pick the index (or the primary
 * store) and {@link IDBKeyRange} to narrow by, falling back to a full scan.
 *
 * @remarks
@@ -72,9 +70,9 @@ function isKey(value) {
 * (a row can match through a later condition the range would exclude), so any `or`
 * forces a full scan. Otherwise it scans the conditions in order and selects the
 * **first** one that is provably range-exact and backed by a key: a comparison
-* operator (`conditionRange`) over a single, orderable (`text`/`integer`/`real`)
-* column that is either the table's primary key (read the store directly, `index:
-* null`) or has a single-column secondary index (named exactly the column — read
+* operator (`conditionToRange`) over a single, orderable (`text`/`integer`/`real`)
+* column that is either the table's primary key (read the store directly with
+* `index` omitted) or has a single-column secondary index (named exactly the column — read
 * that index). A condition whose column is a nested {@link FieldPath} array
 * (descends a json value, not a key), is absent from the schema, is a non-orderable
 * type (`boolean`/`json`/`blob`), uses a non-comparison operator, or has a
@@ -100,19 +98,19 @@ function isKey(value) {
 * in the total order, so an absent/null-valued row can never satisfy them — the
 * index's silence on such a row is harmless (it was never going to match).
 * **Declared-type trust caveat:** this reasoning holds under the contract that
-* an {@link INDEXABLE_TYPES} column, once contract-validated at write time,
+* an {@link INDEXABLE_STORAGE} column, once contract-validated at write time,
 * holds only `string | number | null` (or is absent) — never some other
 * runtime value that could rank differently; a driver bypassing the write
 * contract (writing raw rows directly to the store) could defeat this
 * argument, but that is out of scope for a planner reading validated schema
 * metadata.
 *
-* When no condition qualifies the plan is a full scan (`{ index: null, range:
-* null }`) and the engine does everything. The plan is always a SUPERSET of the
+* When no condition qualifies the plan is a full scan (`{}`) and the engine
+* does everything. The plan is always a SUPERSET of the
 * matching rows — the only correctness contract — so the driver may safely run
 * the exact engine over it.
 *
-* @param criteria - The read specification (its `conditions` drive the plan), or
+* @param input - The read specification (its `conditions` drive the plan), or
 *   `undefined` for an unconditional read
 * @param schema - The table's schema — its `primary` key and column types
 * @param available - The secondary-index names that physically exist on the store
@@ -121,37 +119,28 @@ function isKey(value) {
 *
 * @example
 * ```ts
-* selectPlan({ conditions: [eq('id', 'u1')] }, schema, []) // { index: null, range: only('u1') }
+* selectPlan({ conditions: [eq('id', 'u1')] }, schema, []) // { range: only('u1') }
 * selectPlan({ conditions: [from('age', 18)] }, schema, ['age']) // { index: 'age', range: from(18) }
-* selectPlan({ conditions: [contains('name', 'a')] }, schema, []) // { index: null, range: null }
+* selectPlan({ conditions: [contains('name', 'a')] }, schema, []) // {}
 * ```
 */
-function selectPlan(criteria, schema, available) {
-	const conditions = criteria?.conditions ?? [];
-	if (conditions.slice(1).some((condition) => condition.connector === "or")) return {
-		index: null,
-		range: null
-	};
+function selectPlan(input, schema, available) {
+	const conditions = input?.conditions ?? [];
+	if (conditions.slice(1).some((condition) => condition.connector === "or")) return {};
 	for (const condition of conditions) {
 		if (typeof condition.column !== "string") continue;
 		const column = schema.columns.find((candidate) => candidate.name === condition.column);
-		if (column === void 0 || !INDEXABLE_TYPES.has(column.type)) continue;
-		const keyRange = conditionRange(condition);
-		if (keyRange === null) continue;
-		if (condition.column === schema.primary) return {
-			index: null,
-			range: keyRange
-		};
+		if (column === void 0 || !INDEXABLE_STORAGE.has(column.storage)) continue;
+		const range = conditionToRange(condition);
+		if (range === void 0) continue;
+		if (condition.column === schema.primary) return { range };
 		if (condition.operator === "below" || condition.operator === "to") continue;
 		if (available.includes(condition.column)) return {
 			index: condition.column,
-			range: keyRange
+			range
 		};
 	}
-	return {
-		index: null,
-		range: null
-	};
+	return {};
 }
 /**
 * Map a backend {@link IndexedDBError} to the portable `DatabaseError` taxonomy
@@ -162,17 +151,17 @@ function selectPlan(criteria, schema, available) {
 * `CONSTRAINT` (a unique-key violation) is a `CONFLICT` — the same code every
 * other backend uses for a duplicate key. `CLOSED`/`NOT_OPEN`/`INVALID` (the
 * connection is gone, never opened, or the native handle is stale) collapse to
-* `CLOSED`. `QUOTA` and `BLOCKED` are genuine infrastructure faults (`DRIVER`),
-* carrying a machine-readable `context.code` (`'QUOTA'` / `'BLOCKED'`) so a
-* caller can branch without parsing the message; `BLOCKED` additionally marks
-* `context.retryable: true` — a concurrent connection holding the database open
-* is a transient condition, not a permanent one. Every other code (`UPGRADE`
-* here — see {@link mapMigrationError} for the `migrate()`-only remapping to
-* `MIGRATION` — `ABORTED`, `NOT_FOUND`, `DATA`, `OPEN`, `INACTIVE`, `READONLY`,
-* `UNKNOWN`) is an unexpected infrastructure fault and maps to `DRIVER` — the
-* driver opens its own readwrite transactions, so a `READONLY` fault can only
-* mean the backend behaved unexpectedly. The original error is always
-* preserved as `context.cause` for diagnostics.
+* `CLOSED`. `QUOTA` is a genuine infrastructure fault (`DRIVER`) carrying a
+* machine-readable `context.code` so a caller can branch without parsing the
+* message. A blocked open or versionchange is nonterminal in the backend and
+* remains pending until the competing connection closes, so it never reaches
+* this error mapper. Every other code (`UPGRADE` here — see
+* {@link mapMigrationError} for the `migrate()`-only remapping to `MIGRATION` —
+* `ABORTED`, `NOT_FOUND`, `DATA`, `OPEN`, `INACTIVE`, `READONLY`, `UNKNOWN`) is
+* an unexpected infrastructure fault and maps to `DRIVER` — the driver opens
+* its own readwrite transactions, so a `READONLY` fault can only mean the
+* backend behaved unexpectedly. The original error is always preserved as
+* `context.cause` for diagnostics.
 *
 * @param error - The backend error to translate
 * @returns The portable `DatabaseError`
@@ -187,11 +176,6 @@ function mapIndexedDBError(error) {
 			cause: error,
 			code: "QUOTA"
 		});
-		case "BLOCKED": return new DatabaseError("DRIVER", error.message, {
-			cause: error,
-			code: "BLOCKED",
-			retryable: true
-		});
 		case "UPGRADE":
 		case "ABORTED":
 		case "NOT_FOUND":
@@ -246,13 +230,29 @@ function mapMigrationError(error) {
 *
 * @example
 * ```ts
-* deriveIndexName(['age']) // 'age'
-* deriveIndexName(['a', 'b']) // '2#1:a1:b'
+* deriveIndexedDBIndexName(['age']) // 'age'
+* deriveIndexedDBIndexName(['a', 'b']) // '2#1:a1:b'
 * ```
 */
-function deriveIndexName(columns) {
-	if (columns.length === 1) return columns[0];
-	return `${columns.length}#${columns.map((column) => `${column.length}:${column}`).join("")}`;
+function deriveIndexedDBIndexName(columns) {
+	const [column] = columns;
+	if (columns.length === 1 && column !== void 0) return column;
+	return `${columns.length}#${columns.map((part) => `${part.length}:${part}`).join("")}`;
+}
+/**
+* Project a table schema into the IndexedDB wrapper's store definition.
+*
+* @param schema - Portable table schema
+* @returns Store definition with declared indexes
+*/
+function schemaToStore(schema) {
+	return { indexes: schema.indexes.map((columns) => {
+		const [column] = columns;
+		return {
+			name: deriveIndexedDBIndexName(columns),
+			path: columns.length === 1 && column !== void 0 ? column : [...columns]
+		};
+	}) };
 }
 //#endregion
 //#region src/browser/drivers/IndexedDBDriver.ts
@@ -266,25 +266,27 @@ function deriveIndexName(columns) {
 * / `snapshot`) by delegating to the wrapper's typed store operations — it never
 * touches raw IndexedDB. Rows are stored with **out-of-line keys** (the database
 * passes the key explicitly, `store.set(row, key)`), so each table is declared as a
-* key-path-less store. The wrapper opens in **auto-managed** mode (no fixed
-* version), creating any missing store on demand, so a table added to the schema is
-* created on the next open with no manual version bump. The driver's bulk reads
-* (`scan` / `keys`) use the wrapper's native `getAll` / `getAllKeys`, and `snapshot`
-* rolls back through one atomic wrapper transaction.
+* key-path-less store. A fresh database opens in **auto-managed** mode (no fixed
+* version), creating missing declared stores on demand. Once metadata is persisted,
+* bootstrap captures the live stores and version, rejects a missing persisted store,
+* and pins the final open to that version so a competing versionchange cannot
+* silently recreate lost storage. The driver's bulk reads (`scan` / `keys`) use the
+* wrapper's native `getAll` / `getAllKeys`, and `snapshot` rolls back through one
+* atomic wrapper transaction.
 *
-* It also implements the optional native `records` / `count` / `stream` hooks
-* (AGENTS §21): `selectPlan` ({@link selectPlan}) turns the {@link Criteria} into a
+* It also implements the optional native `records` / `stream` hooks
+* (AGENTS §21): `selectPlan` ({@link selectPlan}) turns the {@link QueryInput} into a
 * key-range pushdown over the primary key or a single-column secondary index,
-* fetching a candidate **superset** that the core engine (`applyCriteria` /
-* `matchesCriteria`) then refines — so a native read is byte-identical to a full
+* fetching a candidate **superset** that the core engine (`applyQuery` /
+* `matchesQuery`) then refines — so a native read is byte-identical to a full
 * scan, just cheaper. Pushdown is conservative: only the exact-comparison
 * operators over orderable columns narrow to a range; everything else falls back
 * to a full scan + the engine.
 *
 * @remarks
-* This driver also implements `migrate` / `meta` / `stamp`. `meta` / `stamp`
-* persist the {@link DriverMeta} in a reserved out-of-line store,
-* {@link META_STORE} (`__meta__`) — excluded from a whole-store `snapshot`
+* This driver also implements `migrate` / `metadata` / `stamp`. `metadata` / `stamp`
+* persist the {@link DriverMetadata} in a reserved out-of-line store,
+* {@link METADATA_STORE} (`__metadata__`) — excluded from a whole-store `snapshot`
 * capture, since it is driver bookkeeping, not caller data. `migrate` applies a
 * {@link Migration} plan natively: IndexedDB schema DDL (creating/dropping a
 * store, creating/dropping an index) is legal only inside a versionchange
@@ -301,32 +303,67 @@ function deriveIndexName(columns) {
 * This unit deliberately OMITS `aggregate` / `transaction`. There is no native
 * `aggregate` (IndexedDB has no native SUM/AVG); the engine over the narrowed
 * `records` covers it. `transaction` is impossible here: the wrapper auto-commits
-* an `IDBTransaction` the moment control yields to a non-IDB `await`, so a
-* BEGIN-now / commit-or-rollback-later handle spanning arbitrary caller code
-* cannot be built on top of it — every atomic multi-op sequence in this driver
+* an `IDBTransaction` when control yields outside its request chain, so arbitrary
+* callback awaits cannot remain inside one native transaction. Every atomic
+* multi-operation sequence in this driver
 * (`snapshot`'s rollback) instead runs entirely inside ONE `db.write(...)` scope.
 */
 var IndexedDBDriver = class {
 	#name;
+	#identities = /* @__PURE__ */ new Map();
 	#schema = /* @__PURE__ */ new Map();
 	#database;
 	constructor(name) {
 		this.#name = name;
 	}
 	async open(schema) {
-		if (schema.some((table) => table.name === "__meta__")) throw new DatabaseError("VALIDATION", `open: table name '${META_STORE}' is reserved for driver metadata`, { table: META_STORE });
+		const owned = normalizeDriverSchema(schema);
+		if (owned.some((table) => table.name === "__metadata__")) throw new DatabaseError("VALIDATION", `open: table name '${METADATA_STORE}' is reserved for driver metadata`, { table: METADATA_STORE });
+		this.#database?.close();
+		this.#database = void 0;
+		this.#schema = /* @__PURE__ */ new Map();
 		try {
-			this.#database?.close();
+			const bootstrap = createIndexedDBDatabase({
+				name: this.#name,
+				stores: { [METADATA_STORE]: {} }
+			});
+			let persisted;
+			let stores = [];
+			let version = 0;
+			try {
+				await bootstrap.connect();
+				stores = bootstrap.stores;
+				version = bootstrap.version;
+				persisted = await this.#load(bootstrap);
+			} finally {
+				bootstrap.close();
+			}
+			if (persisted !== void 0) {
+				for (const table of persisted.schema) if (!stores.includes(table.name)) throw new DatabaseError("DRIVER", "Stored IndexedDB store is missing", {
+					name: this.#name,
+					store: table.name,
+					aspect: "missing"
+				});
+			}
 			const map = /* @__PURE__ */ new Map();
-			for (const table of schema) map.set(table.name, table);
+			for (const table of normalizeDriverSchema(persisted?.schema ?? owned)) map.set(table.name, table);
 			const database = createIndexedDBDatabase({
 				name: this.#name,
+				...persisted === void 0 ? {} : { version },
 				stores: this.#stores(map)
 			});
-			await database.connect();
-			this.#database = database;
+			try {
+				await database.connect();
+			} catch (error) {
+				database.close();
+				throw error;
+			}
+			const identities = this.#alignIdentities(map);
 			this.#schema = map;
+			this.#identities = identities;
+			this.#database = database;
 		} catch (error) {
+			this.#identities = /* @__PURE__ */ new Map();
 			throw this.#wrap(error);
 		}
 	}
@@ -341,26 +378,29 @@ var IndexedDBDriver = class {
 			throw this.#wrap(error);
 		}
 	}
-	async write(table, key, row) {
-		try {
-			await this.#store(table).set(row, key);
-		} catch (error) {
-			throw this.#wrap(error);
-		}
+	async write(table, key, row, options) {
+		const bound = bindRowKey(row, this.#table(table).primary, key);
+		await this.#mutate(table, options, async (store) => {
+			await store.set(bound, key);
+		});
 	}
-	async delete(table, key) {
-		try {
-			const store = this.#store(table);
-			const present = await store.has(key);
+	async insert(table, key, row, options) {
+		const bound = bindRowKey(row, this.#table(table).primary, key);
+		await this.#mutate(table, options, async (store) => {
+			await store.add(bound, key);
+		});
+	}
+	async delete(table, key, options) {
+		let present = false;
+		await this.#mutate(table, options, async (store) => {
+			present = await store.has(key);
 			await store.remove(key);
-			return present;
-		} catch (error) {
-			throw this.#wrap(error);
-		}
+		});
+		return present;
 	}
 	async keys(table) {
 		try {
-			return (await this.#store(table).keys()).filter((key) => typeof key === "string" || typeof key === "number");
+			return (await this.#store(table).keys()).filter(isKey);
 		} catch (error) {
 			throw this.#wrap(error);
 		}
@@ -379,42 +419,34 @@ var IndexedDBDriver = class {
 			throw this.#wrap(error);
 		}
 	}
-	async records(table, criteria) {
+	async records(table, input) {
+		validatePage(input);
 		try {
 			const schema = this.#table(table);
 			const store = this.#store(table);
-			const plan = selectPlan(criteria, schema, store.indexes);
-			return applyCriteria(await this.#candidates(store, schema, plan), criteria);
+			const plan = selectPlan(input, schema, store.indexes);
+			return applyQuery(await this.#candidates(store, schema, plan), input);
 		} catch (error) {
 			throw this.#wrap(error);
 		}
 	}
-	async count(table, criteria) {
-		try {
-			const schema = this.#table(table);
-			const store = this.#store(table);
-			const conditions = criteria.conditions ?? [];
-			if (conditions.length === 0) return await store.count();
-			const plan = selectPlan(criteria, schema, store.indexes);
-			if (conditions.length === 1 && plan.range !== null) return plan.index === null ? await store.count(plan.range) : await store.index(plan.index).count(plan.range);
-			return (plan.index === null ? await store.records(plan.range) : await store.index(plan.index).records(plan.range)).reduce((total, row) => matchesCriteria(row, conditions) ? total + 1 : total, 0);
-		} catch (error) {
-			throw this.#wrap(error);
-		}
+	stream(table, input) {
+		validatePage(input);
+		return this.#stream(table, input);
 	}
-	async *stream(table, criteria) {
+	async *#stream(table, input) {
 		try {
 			const schema = this.#table(table);
 			const store = this.#store(table);
-			const plan = selectPlan(criteria, schema, store.indexes);
-			const conditions = criteria.conditions ?? [];
-			const offset = criteria.offset ?? 0;
-			const limit = criteria.limit;
+			const plan = selectPlan(input, schema, store.indexes);
+			const conditions = input.conditions ?? [];
+			const offset = input.offset ?? 0;
+			const limit = input.limit;
 			let skipped = 0;
 			let yielded = 0;
 			for (const row of await this.#candidates(store, schema, plan)) {
 				if (limit !== void 0 && yielded >= limit) break;
-				if (!matchesCriteria(row, conditions)) continue;
+				if (!matchesQuery(row, conditions)) continue;
 				if (skipped < offset) {
 					skipped += 1;
 					continue;
@@ -429,29 +461,63 @@ var IndexedDBDriver = class {
 	async snapshot(tables) {
 		try {
 			const database = this.#require();
-			const names = tables ?? database.stores.filter((name) => name !== "__meta__");
+			const requested = tables ?? [...this.#schema.keys()];
+			const names = [...new Set(requested)].filter((name) => name !== "__metadata__" && this.#schema.has(name) && database.stores.includes(name));
 			const captured = /* @__PURE__ */ new Map();
 			if (names.length > 0) await database.read(names, async (transaction) => {
 				for (const name of names) {
+					const schema = this.#schema.get(name);
+					const identity = this.#identities.get(name);
+					if (schema === void 0 || identity === void 0) continue;
 					const store = transaction.store(name);
 					captured.set(name, {
+						identity,
 						keys: await store.keys(),
-						rows: await store.records()
+						rows: await store.records(),
+						schema
 					});
 				}
 			});
 			return async () => {
 				try {
 					const current = this.#require();
-					const restorable = names.filter((name) => current.stores.includes(name));
-					if (restorable.length === 0) return;
-					await current.write(restorable, async (transaction) => {
-						for (const name of restorable) {
-							const snapshot = captured.get(name);
-							if (snapshot === void 0) continue;
+					const replacements = /* @__PURE__ */ new Map();
+					for (const [name, snapshot] of captured) {
+						const schema = this.#schema.get(name);
+						if (schema === void 0 || this.#identities.get(name) !== snapshot.identity || !current.stores.includes(name)) continue;
+						const plan = planMigration([snapshot.schema], [schema]);
+						const migrated = migrateRows(snapshot.rows, plan.steps);
+						if (snapshot.keys.length !== snapshot.rows.length || migrated.length !== snapshot.rows.length) throw new DatabaseError("MIGRATION", "IndexedDB snapshot keys and rows have different cardinality", { table: name });
+						const keys = [];
+						const rows = [];
+						for (const [index, key] of snapshot.keys.entries()) {
+							const row = migrated[index];
+							if (!isKey(key) || row === void 0) throw new DatabaseError("MIGRATION", "IndexedDB snapshot row has no usable primary key", {
+								table: name,
+								column: schema.primary,
+								index
+							});
+							keys.push(key);
+							rows.push(bindRowKey(row, schema.primary, key));
+						}
+						replacements.set(name, {
+							keys,
+							rows
+						});
+					}
+					if (replacements.size === 0) return;
+					await current.write([...replacements.keys()], async (transaction) => {
+						for (const [name, replacement] of replacements) {
 							const store = transaction.store(name);
 							await store.clear();
-							for (let index = 0; index < snapshot.keys.length; index += 1) await store.set(snapshot.rows[index], snapshot.keys[index]);
+							for (const [index, key] of replacement.keys.entries()) {
+								const row = replacement.rows[index];
+								if (row === void 0 || key === void 0) throw new DatabaseError("DRIVER", "IndexedDB snapshot entry is incomplete", {
+									table: name,
+									index
+								});
+								await store.set(row, key);
+							}
 						}
 					});
 				} catch (error) {
@@ -463,34 +529,37 @@ var IndexedDBDriver = class {
 		}
 	}
 	/**
-	* Return the persisted {@link DriverMeta}, or `undefined` when the store has
+	* Return the persisted {@link DriverMetadata}, or `undefined` when the store has
 	* never been stamped.
 	*
 	* @remarks
-	* Reads `'meta'` from the reserved {@link META_STORE}, narrowing the
-	* structured-clone value with the core {@link isDriverMeta} guard (never
-	* asserted, AGENTS §14) — a missing or malformed record returns `undefined`,
-	* exactly like a fresh, never-stamped store.
+	* Reads `'metadata'` from the reserved {@link METADATA_STORE} in one readonly
+	* transaction that distinguishes key absence from a present `undefined`
+	* value. Only absence returns `undefined`; present malformed state fails
+	* closed with a payload-safe `DRIVER` error.
 	*
-	* @returns The last-stamped {@link DriverMeta}, or `undefined`
+	* @returns The last-stamped {@link DriverMetadata}, or `undefined`
 	*/
-	async meta() {
+	async metadata() {
 		try {
-			const record = await this.#require().store(META_STORE).get("meta");
-			if (!isDriverMeta(record)) return void 0;
-			return record;
+			return await this.#load(this.#require());
 		} catch (error) {
 			throw this.#wrap(error);
 		}
 	}
 	/**
-	* Persist `meta` verbatim for a later `meta()` to return.
+	* Persist an owned metadata snapshot for a later `metadata()` to return.
 	*
-	* @param meta - The {@link DriverMeta} to persist
+	* @param metadata - The {@link DriverMetadata} to persist
 	*/
-	async stamp(meta) {
+	async stamp(metadata) {
+		const database = this.#require();
+		const owned = cloneDriverMetadata(metadata);
 		try {
-			await this.#require().store(META_STORE).set({ ...meta }, "meta");
+			await database.store(METADATA_STORE).set({
+				version: owned.version,
+				schema: owned.schema
+			}, "metadata");
 		} catch (error) {
 			throw this.#wrap(error);
 		}
@@ -502,7 +571,7 @@ var IndexedDBDriver = class {
 	* @remarks
 	* IndexedDB schema DDL is legal only inside `onupgradeneeded`, so this closes
 	* the current connection and opens a FRESH one at `version + 1`, declaring
-	* every currently-known store (plus {@link META_STORE}) so nothing is lost,
+	* every currently-known store (plus {@link METADATA_STORE}) so nothing is lost,
 	* and applying `table.remove` / `index.add` / `index.remove` /
 	* `column.remove` inside `upgrade`. Every step's `table` is validated against
 	* the driver's own `#schema` BEFORE the reconnect — an unknown-table step
@@ -515,46 +584,154 @@ var IndexedDBDriver = class {
 	* `open` tracks, so subsequent pushdown planning and a later `migrate` /
 	* `open` see the new shape.
 	*
-	* @param plan - The migration plan to apply
+	* @param input - The migration plan and optional metadata stamp to apply atomically
 	*/
-	async migrate(plan) {
-		for (const step of plan.steps) if (step.operation !== "table.add" && !this.#schema.has(step.table)) throw new DatabaseError("MIGRATION", `migrate: unknown table '${step.table}'`, { table: step.table });
+	async migrate(input) {
 		const current = this.#require();
-		const version = current.version;
-		const schema = new Map(this.#schema);
-		this.#applySteps(schema, plan.steps);
-		current.close();
+		const owned = cloneMigrationInput(input);
+		const projected = projectMigrationSchema([...this.#schema.values()], owned.plan.steps);
+		if (owned.metadata !== void 0 && !equalsValue(normalizeDriverSchema(owned.metadata.schema), projected)) throw new DatabaseError("MIGRATION", "Migration metadata schema does not match the plan", {
+			projected,
+			metadata: owned.metadata.schema
+		});
+		const schema = new Map(projected.map((table) => [table.name, table]));
+		const identities = this.#projectIdentities(this.#identities, owned.plan.steps);
+		if (owned.plan.steps.length === 0) {
+			const metadata = owned.metadata;
+			if (metadata !== void 0) try {
+				await current.write(METADATA_STORE, async (transaction) => {
+					await transaction.store(METADATA_STORE).set({
+						version: metadata.version,
+						schema: metadata.schema
+					}, "metadata");
+				});
+			} catch (error) {
+				throw this.#wrap(error);
+			}
+			return;
+		}
 		try {
+			await current.connect();
+			const version = current.version;
+			current.close();
+			this.#database = void 0;
+			const added = new Set([...schema.keys()].filter((name) => !this.#schema.has(name)));
 			const database = createIndexedDBDatabase({
 				name: this.#name,
 				version: version + 1,
 				stores: this.#stores(schema),
-				upgrade: (context) => this.#upgrade(context, plan.steps)
+				upgrade: this.#upgrade.bind(this, owned, added)
 			});
-			await database.connect();
+			try {
+				await database.connect();
+			} catch (error) {
+				database.close();
+				throw error;
+			}
 			this.#database = database;
 			this.#schema = schema;
+			this.#identities = identities;
 		} catch (error) {
-			await this.#reopen();
-			throw isIndexedDBError(error) ? mapMigrationError(error) : error;
+			current.close();
+			this.#database = void 0;
+			const cause = this.#migrationError(error);
+			try {
+				await this.#reopen();
+			} catch (recoveryError) {
+				this.#database = void 0;
+				throw new DatabaseError("DRIVER", "IndexedDB migration and recovery failed", {
+					cause,
+					recovery: this.#recoveryError(recoveryError)
+				});
+			}
+			throw cause;
+		}
+	}
+	async #mutate(table, options, scope) {
+		const signal = options?.signal;
+		checkAbort(signal);
+		const cleanup = new AbortController();
+		let aborted = false;
+		try {
+			await this.#require().write(table, async (transaction) => {
+				checkAbort(signal);
+				signal?.addEventListener("abort", () => {
+					if (!transaction.active) return;
+					try {
+						transaction.abort();
+						aborted = true;
+					} catch {}
+				}, {
+					once: true,
+					signal: cleanup.signal
+				});
+				checkAbort(signal);
+				await scope(transaction.store(table));
+			});
+		} catch (error) {
+			if (aborted) checkAbort(signal);
+			throw this.#wrap(error);
+		} finally {
+			cleanup.abort();
 		}
 	}
 	#require() {
 		if (this.#database === void 0) throw new DatabaseError("CLOSED", `IndexedDB database '${this.#name}' is not open`, { name: this.#name });
 		return this.#database;
 	}
+	async #load(database) {
+		let present = false;
+		let value;
+		await database.read(METADATA_STORE, async (transaction) => {
+			const store = transaction.store(METADATA_STORE);
+			present = await store.has("metadata");
+			if (present) value = await store.get("metadata");
+		});
+		if (!present) return void 0;
+		try {
+			return cloneDriverMetadata(value);
+		} catch {
+			const cause = new DatabaseError("VALIDATION", "Stored IndexedDB metadata failed validation", { path: "metadata" });
+			throw new DatabaseError("DRIVER", "Stored IndexedDB metadata is invalid", {
+				name: this.#name,
+				store: METADATA_STORE,
+				key: "metadata",
+				cause
+			});
+		}
+	}
+	#migrationError(error) {
+		if (isDatabaseError(error)) return error;
+		if (isIndexedDBError(error)) return mapMigrationError(error);
+		return new DatabaseError("DRIVER", "IndexedDB migration failed", { cause: error });
+	}
+	#recoveryError(error) {
+		if (isDatabaseError(error)) return error;
+		if (isIndexedDBError(error)) return mapIndexedDBError(error);
+		return new DatabaseError("DRIVER", "IndexedDB recovery failed", { cause: error });
+	}
 	#wrap(error) {
 		return isIndexedDBError(error) ? mapIndexedDBError(error) : error;
 	}
 	#store(table) {
 		return this.#require().store(table);
 	}
+	#alignIdentities(schema) {
+		const aligned = /* @__PURE__ */ new Map();
+		for (const table of schema.values()) aligned.set(table.name, this.#identities.get(table.name) ?? {});
+		return aligned;
+	}
+	#projectIdentities(identities, steps) {
+		const projected = new Map(identities);
+		for (const step of steps) {
+			if (step.operation === "table.add") projected.set(step.table.name, {});
+			if (step.operation === "table.remove") projected.delete(step.table);
+		}
+		return projected;
+	}
 	#stores(schema) {
-		const stores = { [META_STORE]: {} };
-		for (const table of schema.values()) stores[table.name] = { indexes: table.indexes.map((columns) => ({
-			name: deriveIndexName(columns),
-			path: columns.length === 1 ? columns[0] : [...columns]
-		})) };
+		const stores = { [METADATA_STORE]: {} };
+		for (const table of schema.values()) stores[table.name] = schemaToStore(table);
 		return stores;
 	}
 	async #reopen() {
@@ -562,11 +739,16 @@ var IndexedDBDriver = class {
 			name: this.#name,
 			stores: this.#stores(this.#schema)
 		});
-		await database.connect();
-		this.#database = database;
+		try {
+			await database.connect();
+			this.#database = database;
+		} catch (error) {
+			database.close();
+			throw error;
+		}
 	}
 	async #candidates(store, schema, plan) {
-		if (plan.index === null) return store.records(plan.range);
+		if (plan.index === void 0) return store.records(plan.range);
 		const rows = [...await store.index(plan.index).records(plan.range)];
 		rows.sort((left, right) => compareValues(extractKey(left, schema.primary), extractKey(right, schema.primary)));
 		return rows;
@@ -576,75 +758,43 @@ var IndexedDBDriver = class {
 		if (schema === void 0) throw new DatabaseError("NOT_FOUND", `table '${name}' is not declared`, { table: name });
 		return schema;
 	}
-	#applySteps(schema, steps) {
-		const sameIndex = (left, right) => left.length === right.length && left.every((column, position) => column === right[position]);
-		for (const step of steps) switch (step.operation) {
+	async #upgrade(input, added, context) {
+		for (const name of added) if (name !== "__metadata__" && context.stores.includes(name)) context.drop(name);
+		for (const step of input.plan.steps) switch (step.operation) {
 			case "table.add":
-				if (!schema.has(step.table.name)) schema.set(step.table.name, step.table);
-				break;
-			case "table.remove":
-				schema.delete(step.table);
-				break;
-			case "column.add": {
-				const table = schema.get(step.table);
-				if (table !== void 0 && !table.columns.some((column) => column.name === step.column.name)) schema.set(step.table, {
-					...table,
-					columns: [...table.columns, step.column]
-				});
-				break;
-			}
-			case "column.remove": {
-				const table = schema.get(step.table);
-				if (table !== void 0) schema.set(step.table, {
-					...table,
-					columns: table.columns.filter((column) => column.name !== step.column)
-				});
-				break;
-			}
-			case "index.add": {
-				const table = schema.get(step.table);
-				if (table !== void 0) schema.set(step.table, {
-					...table,
-					indexes: [...table.indexes, step.index]
-				});
-				break;
-			}
-			case "index.remove": {
-				const table = schema.get(step.table);
-				if (table !== void 0) schema.set(step.table, {
-					...table,
-					indexes: table.indexes.filter((index) => !sameIndex(index, step.index))
-				});
+				context.create(step.table.name, schemaToStore(step.table));
 				break;
-			}
-		}
-	}
-	async #upgrade(context, steps) {
-		for (const step of steps) switch (step.operation) {
 			case "table.remove":
 				context.drop(step.table);
 				break;
 			case "index.add": {
-				const name = deriveIndexName(step.index);
-				const path = step.index.length === 1 ? step.index[0] : [...step.index];
-				context.transaction.objectStore(step.table).createIndex(name, path);
+				const name = deriveIndexedDBIndexName(step.index);
+				const [column] = step.index;
+				const path = step.index.length === 1 && column !== void 0 ? column : [...step.index];
+				context.index(step.table, {
+					name,
+					path
+				});
 				break;
 			}
 			case "index.remove":
-				context.transaction.objectStore(step.table).deleteIndex(deriveIndexName(step.index));
+				context.deindex(step.table, deriveIndexedDBIndexName(step.index));
 				break;
 			case "column.remove": {
 				let cursor = await context.store(step.table).cursor();
 				while (cursor !== null) {
 					const [migrated] = migrateRows([cursor.value], [step]);
+					if (migrated === void 0) throw new DatabaseError("MIGRATION", "migrate: transformed row is missing", { table: step.table });
 					await cursor.update(migrated);
 					cursor = await cursor.continue();
 				}
 				break;
 			}
-			case "table.add":
-			case "column.add": break;
 		}
+		if (input.metadata !== void 0) await context.store(METADATA_STORE).set({
+			version: input.metadata.version,
+			schema: input.metadata.schema
+		}, "metadata");
 	}
 };
 //#endregion
@@ -653,9 +803,9 @@ var IndexedDBDriver = class {
 * Create a persistent IndexedDB {@link DriverInterface} for the core database layer.
 *
 * @remarks
-* Pass it to `createDatabase` from `@orkestrel/database` to run the whole typed database +
-* relations stack against IndexedDB instead of memory — the `Database` / `Table` /
-* `Query` / relations API is unchanged; only where the bytes live changes. The
+* Pass it to `createDatabase` from `@orkestrel/database` to run the typed database
+* layer against IndexedDB instead of memory — the `Database` / `Table` / `Query`
+* API is unchanged; only where the bytes live changes. The
 * driver is built on the published `@orkestrel/indexeddb` wrapper in auto-managed
 * mode, so a table added to the `tables` map is created on the next open with no
 * version bump. This unit omits `transaction` / `aggregate` (see
@@ -681,6 +831,6 @@ function createIndexedDBDriver(name) {
 	return new IndexedDBDriver(name);
 }
 //#endregion
-export { INDEXABLE_TYPES, IndexedDBDriver, META_STORE, conditionRange, createIndexedDBDriver, deriveIndexName, isKey, mapIndexedDBError, mapMigrationError, selectPlan };
+export { INDEXABLE_STORAGE, IndexedDBDriver, METADATA_STORE, conditionToRange, createIndexedDBDriver, deriveIndexedDBIndexName, mapIndexedDBError, mapMigrationError, schemaToStore, selectPlan };
 
 //# sourceMappingURL=index.js.map