@orkestrel/database 0.0.18 → 0.0.19

package/dist/src/core/index.cjs

@@ -1,7 +1,7 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 let _orkestrel_contract = require("@orkestrel/contract");
 let _orkestrel_emitter = require("@orkestrel/emitter");
-//#region src/core/constants.ts
+// src/core/constants.ts
 /**
 * Supplies the primary-key column, `'id'`, assumed when {@link PrimaryMap} does not name one.
 *
@@ -100,8 +100,7 @@ var CONFORMANCE_POSTS_SCHEMA = Object.freeze({
 * what a later phase opens.
 */
 var CONFORMANCE_SCHEMA = Object.freeze([CONFORMANCE_USERS_SCHEMA, CONFORMANCE_POSTS_SCHEMA]);
-//#endregion
-//#region src/core/errors.ts
+// src/core/errors.ts
 /**
 * Represents an error thrown by the database layer.
 *
@@ -123,6 +122,7 @@ var DatabaseError = class extends Error {
 	context;
 	constructor(code, message, context) {
 		super(message);
+		_orkestrel_contract.INTRINSICS.define(this, Symbol.for("@orkestrel/database.DatabaseError"), { value: this });
 		this.name = "DatabaseError";
 		this.code = code;
 		if (context !== void 0) this.context = context;
@@ -131,6 +131,11 @@ var DatabaseError = class extends Error {
 /**
 * Narrows an unknown caught value to a {@link DatabaseError}.
 *
+* @remarks
+* Accepts branded instances and subclasses across package copies and module formats.
+* Requires the declared code and context shape. Refuses look-alikes and transparent
+* proxies without requiring an exact `name`.
+*
 * @param value - The value to test (typically a `catch` binding)
 * @returns True if `value` is a {@link DatabaseError}; false otherwise
 *
@@ -144,10 +149,17 @@ var DatabaseError = class extends Error {
 * ```
 */
 function isDatabaseError(value) {
-	return (0, _orkestrel_contract.isInstance)(value, DatabaseError);
+	return (0, _orkestrel_contract.holds)(() => {
+		if (!(0, _orkestrel_contract.isInstance)(value, Error) || _orkestrel_contract.INTRINSICS.prototype(value) === Error.prototype) return false;
+		const brand = _orkestrel_contract.INTRINSICS.describe(value, Symbol.for("@orkestrel/database.DatabaseError"));
+		if (brand === void 0 || brand.value !== value) return false;
+		const code = _orkestrel_contract.INTRINSICS.reflect.read(value, "code");
+		if (code !== "CLOSED" && code !== "NOT_FOUND" && code !== "CONFLICT" && code !== "VALIDATION" && code !== "ABORTED" && code !== "MIGRATION" && code !== "CONFORMANCE" && code !== "DRIVER") return false;
+		const context = _orkestrel_contract.INTRINSICS.reflect.read(value, "context");
+		return context === void 0 || (0, _orkestrel_contract.isObject)(context) || (0, _orkestrel_contract.isFunction)(context);
+	});
 }
-//#endregion
-//#region src/core/validators.ts
+// src/core/validators.ts
 /**
 * Checks whether a value is a usable database key.
 *
@@ -292,8 +304,7 @@ function isMigrationInput(value) {
 		return (keys.length === 1 || keys.length === 2) && keys.includes("plan") && (keys.length === 1 || keys.includes("metadata")) && isMigration(input.plan) && (input.metadata === void 0 || isDriverMetadata(input.metadata));
 	});
 }
-//#endregion
-//#region src/core/cloners.ts
+// src/core/cloners.ts
 /**
 * Clones unknown driver metadata into a distinct deeply frozen snapshot.
 *
@@ -366,8 +377,7 @@ function cloneMigrationInput(value) {
 		});
 	}
 }
-//#endregion
-//#region src/core/helpers.ts
+// src/core/helpers.ts
 /**
 * Validates the paging fields of a portable query.
 *
@@ -470,7 +480,7 @@ function equalsValue(left, right) {
 			else prior.add(currentRight);
 			if (leftArray && rightArray) {
 				if (currentLeft.length !== currentRight.length) return false;
-				for (let index = 0; index < currentLeft.length; index += 1) {
+				for (const index of Array.prototype.keys.call(currentLeft)) {
 					const leftOwn = Object.hasOwn(currentLeft, index);
 					if (leftOwn !== Object.hasOwn(currentRight, index)) return false;
 					if (leftOwn) pending.push([currentLeft[index], currentRight[index]]);
@@ -493,6 +503,27 @@ function equalsValue(left, right) {
 	}
 }
 /**
+* Checks whether a fixed-length wildcard segment matches a value at an offset.
+*
+* @remarks
+* Compares UTF-16 code units: `single` matches any one unit, and every other segment
+* unit matches itself. An offset that leaves the segment outside the value fails.
+*
+* @param value - The value to read
+* @param segment - The segment, holding no any-run wildcard
+* @param at - The value offset the segment starts at
+* @param single - The single-char wildcard char
+* @returns True if every segment unit matches the value unit at its offset; false otherwise
+*
+* @example
+* ```ts
+* matchesWildcardSegment('hello', 'l_o', 2, '_') // true
+* ```
+*/
+function matchesWildcardSegment(value, segment, at, single) {
+	return at >= 0 && at + segment.length <= value.length && segment.split("").every((unit, offset) => unit === single || unit === value[at + offset]);
+}
+/**
 * Matches a value against a wildcard pattern in linear time — the shared, ReDoS-safe
 * engine behind {@link matchesLikePattern} and {@link matchesGlobPattern}.
 *
@@ -501,19 +532,20 @@ function equalsValue(left, right) {
 * `.*` segments separated by literals, matched against a long non-matching input, blow
 * up super-linearly — and JS has no atomic groups / possessive quantifiers to bound it,
 * while a `LIKE` / `GLOB` pattern is a caller-supplied operand this package cannot
-* trust. So this builds no regex. It runs the classic greedy two-pointer wildcard match:
-* the `any` wildcard records its position and, on a later mismatch, backtracks only to
-* that last `any` (letting it absorb one more char) — so the work is O(value × pattern),
-* never the exponential / polynomial backtracking a regex would do. The pattern length
-* is capped at {@link MAX_PATTERN_LENGTH} (a `VALIDATION` {@link DatabaseError} over it),
-* bounding the pattern factor so a match stays linear in the value length whatever the
-* pattern.
+* trust. This builds no regex. It splits the pattern on `any` into fixed-length
+* segments, anchors the first at the value's start and the last at its end, and places
+* each middle segment at its leftmost match after the one before it, which is the only
+* placement a match needs, so the work is O(value × pattern) at worst, never the
+* exponential / polynomial backtracking a regex would do. The pattern length is capped
+* at {@link MAX_PATTERN_LENGTH} (a `VALIDATION` {@link DatabaseError} over it), bounding
+* the pattern factor so a match stays linear in the value length whatever the pattern.
 *
 * The `any` wildcard matches any run (including empty); `single` matches exactly one
-* char; every other pattern char matches itself literally (a pattern `.` / `(` / `\` is
-* a literal — the regex-metacharacter hazard is gone with the regex). `any` is tested
-* before a literal match, so a value that literally contains the wildcard char never
-* shadows the wildcard. Case folding is applied to both sides when `fold` is set.
+* UTF-16 code unit; every other pattern char matches itself literally (a pattern `.` /
+* `(` / `\` is a literal — the regex-metacharacter hazard is gone with the regex). The
+* pattern splits on `any` before any literal comparison, so a value that literally
+* contains the wildcard char never shadows the wildcard. Case folding is applied to
+* both sides when `fold` is set.
 *
 * @param value - The value to test
 * @param pattern - The wildcard pattern
@@ -530,27 +562,17 @@ function matchesWildcardPattern(value, pattern, any, single, fold) {
 	});
 	const haystack = fold ? value.toLowerCase() : value;
 	const needle = fold ? pattern.toLowerCase() : pattern;
-	let vi = 0;
-	let pi = 0;
-	let star = -1;
-	let mark = 0;
-	while (vi < haystack.length) {
-		const pc = pi < needle.length ? needle[pi] : void 0;
-		if (pc === any) {
-			star = pi;
-			mark = vi;
-			pi += 1;
-		} else if (pc !== void 0 && (pc === single || pc === haystack[vi])) {
-			vi += 1;
-			pi += 1;
-		} else if (star !== -1) {
-			pi = star + 1;
-			mark += 1;
-			vi = mark;
-		} else return false;
-	}
-	while (pi < needle.length && needle[pi] === any) pi += 1;
-	return pi === needle.length;
+	const segments = any.length === 1 ? needle.split(any) : [needle];
+	const head = segments[0] ?? "";
+	const tail = segments.at(-1) ?? "";
+	if (segments.length === 1) return haystack.length === head.length && matchesWildcardSegment(haystack, head, 0, single);
+	const end = haystack.length - tail.length;
+	if (end < head.length || !matchesWildcardSegment(haystack, head, 0, single) || !matchesWildcardSegment(haystack, tail, end, single)) return false;
+	return segments.slice(1, -1).reduce((from, segment) => {
+		if (from === void 0) return void 0;
+		const at = segment.includes(single) ? new Array(Math.max(0, end - segment.length - from + 1)).keys().map((offset) => from + offset).find((candidate) => matchesWildcardSegment(haystack, segment, candidate, single)) : haystack.indexOf(segment, from);
+		return at === void 0 || at < 0 || at + segment.length > end ? void 0 : at + segment.length;
+	}, head.length) !== void 0;
 }
 /**
 * Matches a value against a SQL `LIKE` pattern, folding case.
@@ -656,16 +678,10 @@ function matchesCondition(row, condition) {
 * @returns True if the row satisfies the combined conditions; false otherwise
 */
 function matchesQuery(row, conditions) {
-	let result = true;
-	let seeded = false;
-	for (const condition of conditions) {
+	return Iterator.from(conditions).reduce((previous, condition) => {
 		const match = matchesCondition(row, condition);
-		if (!seeded) {
-			result = match;
-			seeded = true;
-		} else result = condition.connector === "or" ? result || match : result && match;
-	}
-	return result;
+		return previous === void 0 ? match : condition.connector === "or" ? previous || match : previous && match;
+	}, void 0) ?? true;
 }
 /**
 * Filters rows by a list of conditions — the shared basis for a table's count
@@ -728,15 +744,13 @@ function sortRows(rows, order) {
 */
 function applyQuery(rows, input) {
 	validatePage(input);
-	let result = rows;
 	const conditions = input?.conditions;
-	if (conditions !== void 0 && conditions.length > 0) result = result.filter((row) => matchesQuery(row, conditions));
+	const filtered = conditions !== void 0 && conditions.length > 0 ? rows.filter((row) => matchesQuery(row, conditions)) : rows;
 	const order = input?.order;
-	if (order !== void 0 && order.length > 0) result = sortRows(result, order);
+	const sorted = order !== void 0 && order.length > 0 ? sortRows(filtered, order) : filtered;
 	const offset = input?.offset ?? 0;
 	const limit = input?.limit;
-	if (offset > 0 || limit !== void 0) result = result.slice(offset, limit !== void 0 ? offset + limit : void 0);
-	return result;
+	return offset > 0 || limit !== void 0 ? sorted.slice(offset, limit !== void 0 ? offset + limit : void 0) : sorted;
 }
 /**
 * Computes an aggregate over a column across rows.
@@ -754,20 +768,17 @@ function applyQuery(rows, input) {
 */
 function computeAggregate(rows, operation, column) {
 	if (operation === "count") return rows.length;
-	const numbers = [];
-	for (const row of rows) {
-		if (!(0, _orkestrel_contract.isRecord)(row)) continue;
+	const numbers = Iterator.from(rows).flatMap((row) => {
+		if (!(0, _orkestrel_contract.isRecord)(row)) return [];
 		const value = (0, _orkestrel_contract.parseNumber)((0, _orkestrel_contract.resolveField)(row, column));
-		if (value !== void 0) numbers.push(value);
-	}
+		return value === void 0 ? [] : [value];
+	}).toArray();
 	if (numbers.length === 0) return void 0;
 	if (operation === "sum" || operation === "average") {
 		const total = numbers.reduce((sum, value) => sum + value, 0);
 		return operation === "average" ? total / numbers.length : total;
 	}
-	let result = operation === "minimum" ? Number.POSITIVE_INFINITY : Number.NEGATIVE_INFINITY;
-	for (const value of numbers) result = operation === "minimum" ? Math.min(result, value) : Math.max(result, value);
-	return result;
+	return numbers.reduce((result, value) => operation === "minimum" ? Math.min(result, value) : Math.max(result, value), operation === "minimum" ? Number.POSITIVE_INFINITY : Number.NEGATIVE_INFINITY);
 }
 /**
 * Reads a row's primary key from a column, when it is a usable {@link Key}.
@@ -978,14 +989,12 @@ function planMigration(deployed, declared, from = 0, to = 1) {
 		from,
 		to
 	});
-	let beforeSchema;
-	let targetSchema;
-	try {
-		beforeSchema = normalizeDriverSchema(deployed);
-		targetSchema = normalizeDriverSchema(declared);
-	} catch (error) {
-		throw new DatabaseError("MIGRATION", "Migration schema is invalid", { cause: error });
-	}
+	const schemas = (0, _orkestrel_contract.attempt)(() => ({
+		before: normalizeDriverSchema(deployed),
+		target: normalizeDriverSchema(declared)
+	}));
+	if (!schemas.success) throw new DatabaseError("MIGRATION", "Migration schema is invalid", { cause: schemas.error });
+	const { before: beforeSchema, target: targetSchema } = schemas.value;
 	const deployedByName = new Map(beforeSchema.map((table) => [table.name, table]));
 	const declaredByName = new Map(targetSchema.map((table) => [table.name, table]));
 	const steps = [];
@@ -1071,18 +1080,16 @@ function planMigration(deployed, declared, from = 0, to = 1) {
 * @returns A fresh owned final schema
 */
 function projectMigrationSchema(schema, steps) {
-	let owned;
-	let projectedSteps;
-	try {
-		owned = normalizeDriverSchema(schema);
-		projectedSteps = cloneMigrationInput({ plan: {
+	const captured = (0, _orkestrel_contract.attempt)(() => ({
+		owned: normalizeDriverSchema(schema),
+		steps: cloneMigrationInput({ plan: {
 			from: 0,
 			to: 1,
 			steps
-		} }).plan.steps;
-	} catch (error) {
-		throw new DatabaseError("MIGRATION", "Migration input is invalid", { cause: error });
-	}
+		} }).plan.steps
+	}));
+	if (!captured.success) throw new DatabaseError("MIGRATION", "Migration input is invalid", { cause: captured.error });
+	const { owned, steps: projectedSteps } = captured.value;
 	const tables = new Map(owned.map((table) => [table.name, table]));
 	for (const step of projectedSteps) {
 		if (step.operation === "table.add") {
@@ -1391,10 +1398,8 @@ async function* scanDriver(factory) {
 			name: "Grace",
 			age: 40
 		})]);
-		let fulfilled = 0;
-		let conflicted = 0;
-		for (const outcome of outcomes) if (outcome.status === "fulfilled") fulfilled += 1;
-		else if (isDatabaseError(outcome.reason) && outcome.reason.code === "CONFLICT") conflicted += 1;
+		const fulfilled = outcomes.filter((outcome) => outcome.status === "fulfilled").length;
+		const conflicted = outcomes.filter((outcome) => outcome.status === "rejected" && isDatabaseError(outcome.reason) && outcome.reason.code === "CONFLICT").length;
 		const keys = await driver.keys("users");
 		await driver.close();
 		if (fulfilled !== 1 || conflicted !== 1 || !equalsValue(keys, ["u1"])) yield {
@@ -1470,32 +1475,17 @@ async function* scanDriver(factory) {
 		});
 		const controller = new AbortController();
 		controller.abort("conformance abort");
-		let writeError;
-		let insertError;
-		let deleteError;
-		try {
-			await driver.write("users", "u2", {
-				id: "u2",
-				name: "Grace",
-				age: 40
-			}, { signal: controller.signal });
-		} catch (error) {
-			writeError = error;
-		}
-		try {
-			await driver.insert("users", "u2", {
-				id: "u2",
-				name: "Grace",
-				age: 40
-			}, { signal: controller.signal });
-		} catch (error) {
-			insertError = error;
-		}
-		try {
-			await driver.delete("users", "u1", { signal: controller.signal });
-		} catch (error) {
-			deleteError = error;
-		}
+		const writeError = await captureFailure(() => driver.write("users", "u2", {
+			id: "u2",
+			name: "Grace",
+			age: 40
+		}, { signal: controller.signal }));
+		const insertError = await captureFailure(() => driver.insert("users", "u2", {
+			id: "u2",
+			name: "Grace",
+			age: 40
+		}, { signal: controller.signal }));
+		const deleteError = await captureFailure(() => driver.delete("users", "u1", { signal: controller.signal }));
 		const keys = await driver.keys("users");
 		await driver.close();
 		if (!isDatabaseError(writeError) || writeError.code !== "ABORTED" || !isDatabaseError(insertError) || insertError.code !== "ABORTED" || !isDatabaseError(deleteError) || deleteError.code !== "ABORTED" || !equalsValue(keys, ["u1"])) yield {
@@ -1805,19 +1795,15 @@ async function* scanDriver(factory) {
 			};
 			break migratePhase;
 		}
-		let caught;
-		try {
-			await driver.migrate({ plan: {
-				from: 0,
-				to: 1,
-				steps: [{
-					operation: "table.remove",
-					table: "ghost"
-				}]
-			} });
-		} catch (error) {
-			caught = error;
-		}
+		const migrate = driver.migrate.bind(driver);
+		const caught = await captureFailure(() => migrate({ plan: {
+			from: 0,
+			to: 1,
+			steps: [{
+				operation: "table.remove",
+				table: "ghost"
+			}]
+		} }));
 		await driver.close();
 		if (!isDatabaseError(caught) || caught.code !== "MIGRATION") yield {
 			check: "migrate-unknown-table",
@@ -2114,8 +2100,23 @@ async function auditDriver(factory) {
 	for await (const finding of scanDriver(factory)) findings.push(finding);
 	return findings;
 }
-//#endregion
-//#region src/core/ScopedIterator.ts
+/**
+* Captures the exact rejection or synchronous throw from a driver conformance operation.
+*
+* @example
+* ```ts
+* await captureFailure(() => Promise.reject('refused')) // 'refused'
+* ```
+*/
+async function captureFailure(operation) {
+	try {
+		await operation();
+		return;
+	} catch (error) {
+		return error;
+	}
+}
+// src/core/ScopedIterator.ts
 /**
 * Forms the internal continuation admission boundary for one scoped async iterable.
 *
@@ -2194,8 +2195,7 @@ var ScopedIterator = class {
 		} catch {}
 	}
 };
-//#endregion
-//#region src/core/TransactionScope.ts
+// src/core/TransactionScope.ts
 /**
 * Forms the internal lifetime boundary for one database transaction callback.
 *
@@ -2208,8 +2208,7 @@ var ScopedIterator = class {
 var TransactionScope = class {
 	#operations = /* @__PURE__ */ new Set();
 	#accepting = true;
-	#failed = false;
-	#error;
+	#failure;
 	get accepting() {
 		return this.#accepting;
 	}
@@ -2222,21 +2221,17 @@ var TransactionScope = class {
 		} catch (error) {
 			return Promise.reject(error);
 		}
-		let promise;
-		try {
-			promise = operation();
-		} catch (error) {
-			promise = Promise.reject(error);
-		}
+		const outcome = (0, _orkestrel_contract.attempt)(operation);
+		const promise = outcome.success ? outcome.value : Promise.reject(outcome.error);
 		this.#operations.add(promise);
 		promise.then(() => {
 			this.#operations.delete(promise);
 		}, (error) => {
 			this.#operations.delete(promise);
-			if (!this.#failed) {
-				this.#failed = true;
-				this.#error = error;
-			}
+			this.#failure ??= {
+				success: false,
+				error
+			};
 		});
 		return promise;
 	}
@@ -2248,11 +2243,10 @@ var TransactionScope = class {
 	}
 	async drain() {
 		while (this.#operations.size > 0) await Promise.allSettled(this.#operations);
-		if (this.#failed) throw this.#error;
+		if (this.#failure !== void 0 && !this.#failure.success) throw this.#failure.error;
 	}
 };
-//#endregion
-//#region src/core/DatabaseContext.ts
+// src/core/DatabaseContext.ts
 /**
 * Owns the internal shared state behind every typed view of one database.
 *
@@ -2269,7 +2263,7 @@ var DatabaseContext = class {
 	#emitter;
 	#operations = /* @__PURE__ */ new Set();
 	#schema = [];
-	#transaction;
+	#transactions = /* @__PURE__ */ new Set();
 	#status = "idle";
 	#ready;
 	#failure;
@@ -2296,7 +2290,7 @@ var DatabaseContext = class {
 		return this.#name;
 	}
 	get accepting() {
-		return this.#status !== "closed" && this.#transaction === void 0;
+		return this.#status !== "closed" && this.#transactions.size === 0;
 	}
 	get status() {
 		return this.#status;
@@ -2306,7 +2300,7 @@ var DatabaseContext = class {
 	}
 	register(schema) {
 		if (this.#status === "closed") throw new DatabaseError("CLOSED", `Database '${this.#name}' is closed`, { name: this.#name });
-		if (this.#ready !== void 0 || this.#transaction !== void 0) throw new DatabaseError("CONFLICT", `Database '${this.#name}' cannot import tables after opening has started`, {
+		if (this.#ready !== void 0 || this.#transactions.size !== 0) throw new DatabaseError("CONFLICT", `Database '${this.#name}' cannot import tables after opening has started`, {
 			name: this.#name,
 			status: this.#status
 		});
@@ -2360,12 +2354,8 @@ var DatabaseContext = class {
 		} catch (error) {
 			return Promise.reject(error);
 		}
-		let promise;
-		try {
-			promise = operation();
-		} catch (error) {
-			promise = Promise.reject(error);
-		}
+		const outcome = (0, _orkestrel_contract.attempt)(operation);
+		const promise = outcome.success ? outcome.value : Promise.reject(outcome.error);
 		this.#operations.add(promise);
 		promise.then(() => {
 			this.#operations.delete(promise);
@@ -2377,44 +2367,40 @@ var DatabaseContext = class {
 	async transaction(scope, options) {
 		checkAbort(options?.signal);
 		this.#admit();
-		const token = {};
-		this.#transaction = token;
+		const lifetime = new TransactionScope();
+		this.#transactions.add(lifetime);
 		try {
 			await this.#drain();
 			await this.connect();
 			if (this.#driver.transaction !== void 0) {
-				const rejection = {
-					rejected: false,
-					error: void 0,
-					marker: {}
-				};
+				const rejection = new AbortController();
 				try {
 					const value = await this.#driver.transaction(async (storage) => {
 						this.#emitter.emit("transaction");
-						const outcome = await scope(storage, new TransactionScope());
+						const outcome = await scope(storage, lifetime);
 						if (!outcome.success) {
-							rejection.rejected = true;
-							rejection.error = outcome.error;
-							throw rejection.marker;
+							rejection.abort(outcome);
+							throw rejection.signal;
 						}
 						return outcome.value;
 					});
 					this.#emitter.emit("commit");
 					return value;
 				} catch (error) {
-					if (rejection.rejected) {
-						if (Object.is(error, rejection.marker)) {
-							this.#emitter.emit("rollback", rejection.error);
-							throw rejection.error;
+					const failure = rejection.signal.reason;
+					if (rejection.signal.aborted && (0, _orkestrel_contract.isRecord)(failure) && failure.success === false) {
+						if (Object.is(error, rejection.signal)) {
+							this.#emitter.emit("rollback", failure.error);
+							throw failure.error;
 						}
-						throw this.#rollbackError(rejection.error, error);
+						throw this.#rollbackError(failure.error, error);
 					}
 					throw error;
 				}
 			}
 			const rollback = await this.#driver.snapshot();
 			this.#emitter.emit("transaction");
-			const outcome = await scope(this.#driver, new TransactionScope());
+			const outcome = await scope(this.#driver, lifetime);
 			if (outcome.success) {
 				this.#emitter.emit("commit");
 				return outcome.value;
@@ -2427,7 +2413,7 @@ var DatabaseContext = class {
 			this.#emitter.emit("rollback", outcome.error);
 			throw outcome.error;
 		} finally {
-			if (this.#transaction === token) this.#transaction = void 0;
+			this.#transactions.delete(lifetime);
 		}
 	}
 	async migrate(deployed, options) {
@@ -2451,11 +2437,11 @@ var DatabaseContext = class {
 	}
 	#admit() {
 		if (this.#status === "closed") throw new DatabaseError("CLOSED", `Database '${this.#name}' is closed`, { name: this.#name });
-		if (this.#transaction !== void 0) throw new DatabaseError("CONFLICT", `Database '${this.#name}' has an active transaction`, { name: this.#name });
+		if (this.#transactions.size !== 0) throw new DatabaseError("CONFLICT", `Database '${this.#name}' has an active transaction`, { name: this.#name });
 		if (this.#failure !== void 0) throw this.#failure.error;
 	}
 	#outside() {
-		if (this.#transaction !== void 0) throw new DatabaseError("CONFLICT", `Database '${this.#name}' has an active transaction`, { name: this.#name });
+		if (this.#transactions.size !== 0) throw new DatabaseError("CONFLICT", `Database '${this.#name}' has an active transaction`, { name: this.#name });
 	}
 	async #drain() {
 		if (this.#operations.size === 0) return;
@@ -2536,8 +2522,7 @@ var DatabaseContext = class {
 		});
 	}
 };
-//#endregion
-//#region src/core/Cursor.ts
+// src/core/Cursor.ts
 /**
 * Walks a table's rows forward for bulk in-place mutation.
 *
@@ -2557,12 +2542,14 @@ var Cursor = class {
 	#index = -1;
 	#value;
 	#closed = false;
-	constructor(keys, read, update, remove, track) {
+	#initial;
+	constructor(keys, read, update, remove, track, initial = false) {
 		this.#keys = keys;
 		this.#read = read;
 		this.#update = update;
 		this.#remove = remove;
 		this.#track = track;
+		this.#initial = initial;
 	}
 	get value() {
 		return this.#value;
@@ -2574,6 +2561,13 @@ var Cursor = class {
 		return this.#closed || this.#index >= this.#keys.length;
 	}
 	next() {
+		if (this.#initial) {
+			const initial = this.#queue(() => this.#advance());
+			initial.then(() => {
+				this.#initial = false;
+			}, () => {});
+			return initial;
+		}
 		return this.#track(() => this.#queue(() => this.#advance()));
 	}
 	update(changes) {
@@ -2630,8 +2624,33 @@ var Cursor = class {
 		return result;
 	}
 };
-//#endregion
-//#region src/core/Query.ts
+// src/core/StreamPage.ts
+/**
+* Tracks the matching-row position of one streaming page.
+*
+* @example
+* ```ts
+* const page = new StreamPage(1)
+* page.next() // false
+* page.next() // true
+* page.count // 1
+* ```
+*/
+var StreamPage = class {
+	#offset;
+	#position = 0;
+	constructor(offset) {
+		this.#offset = offset;
+	}
+	get count() {
+		return Math.max(0, this.#position - this.#offset);
+	}
+	next() {
+		this.#position += 1;
+		return this.#position > this.#offset;
+	}
+};
+// src/core/Query.ts
 /**
 * Builds a read against one table through a fluent chain.
 *
@@ -2708,23 +2727,11 @@ var Query = class {
 			}, options);
 			return;
 		}
-		const offset = this.#offset ?? 0;
-		let matched = 0;
-		let yielded = 0;
+		const page = new StreamPage(this.#offset ?? 0);
 		for await (const row of this.#table.scan({ conditions: this.#conditions }, options)) {
-			if (this.#limit !== void 0 && yielded >= this.#limit) break;
-			let matches = true;
-			for (const predicate of this.#filters) if (!predicate(row)) {
-				matches = false;
-				break;
-			}
-			if (!matches) continue;
-			if (matched < offset) {
-				matched += 1;
-				continue;
-			}
-			matched += 1;
-			yielded += 1;
+			if (this.#limit !== void 0 && page.count >= this.#limit) break;
+			if (!Iterator.from(this.#filters).every((predicate) => predicate(row))) continue;
+			if (!page.next()) continue;
 			yield row;
 		}
 	}
@@ -2733,9 +2740,7 @@ var Query = class {
 		return this.#table.records({ conditions: this.#conditions }).then((fetched) => computeAggregate(this.#filtered(fetched), operation, column));
 	}
 	#filtered(rows) {
-		let result = rows;
-		for (const predicate of this.#filters) result = result.filter(predicate);
-		return result;
+		return Iterator.from(this.#filters).reduce((result, predicate) => result.filter(predicate), rows);
 	}
 	#page(rows) {
 		const offset = this.#offset ?? 0;
@@ -2743,8 +2748,7 @@ var Query = class {
 		return rows.slice(offset, this.#limit === void 0 ? void 0 : offset + this.#limit);
 	}
 };
-//#endregion
-//#region src/core/Table.ts
+// src/core/Table.ts
 /**
 * Exposes typed keyed CRUD plus fluent query and cursor access over a driver.
 *
@@ -2865,9 +2869,7 @@ var Table = class {
 			const conditions = input?.conditions;
 			const candidate = conditions === void 0 ? {} : { conditions };
 			const rows = await this.#driver.records?.(this.#name, candidate) ?? filterRows(await this.#collect(), conditions ?? []);
-			let count = 0;
-			for (const row of rows) if (this.#guard(row)) count += 1;
-			return count;
+			return Iterator.from(rows).reduce((count, row) => count + (this.#guard(row) ? 1 : 0), 0);
 		});
 	}
 	/**
@@ -2959,10 +2961,8 @@ var Table = class {
 	cursor() {
 		return this.#track(async () => {
 			await this.#ready();
-			let initializing = true;
-			const cursor = new Cursor(await this.#driver.keys(this.#name), (key) => this.#readCursor(key), (key, changes) => this.#updateCursor(key, changes), (key) => this.#deleteCursor(key), (operation) => initializing ? operation() : this.#track(operation));
+			const cursor = new Cursor(await this.#driver.keys(this.#name), (key) => this.#readCursor(key), (key, changes) => this.#updateCursor(key, changes), (key) => this.#deleteCursor(key), (operation) => this.#track(operation), true);
 			await cursor.next();
-			initializing = false;
 			return cursor;
 		});
 	}
@@ -2972,14 +2972,13 @@ var Table = class {
 		const conditions = input?.conditions;
 		const offset = input?.offset ?? 0;
 		const limit = input?.limit;
-		let matched = 0;
-		let yielded = 0;
+		const page = new StreamPage(offset);
 		const iterator = (this.#driver.stream === void 0 ? this.#driver.scan(this.#name) : this.#driver.stream(this.#name, conditions === void 0 ? {} : { conditions }))[Symbol.asyncIterator]();
 		try {
 			while (true) {
 				await this.#ready();
 				checkAbort(options?.signal);
-				if (limit !== void 0 && yielded >= limit) return;
+				if (limit !== void 0 && page.count >= limit) return;
 				const step = await iterator.next();
 				await this.#ready();
 				checkAbort(options?.signal);
@@ -2988,12 +2987,7 @@ var Table = class {
 				if (conditions !== void 0 && conditions.length > 0 && !matchesQuery(row, conditions)) continue;
 				const narrowed = this.#cast(row);
 				if (narrowed === void 0) continue;
-				if (matched < offset) {
-					matched += 1;
-					continue;
-				}
-				matched += 1;
-				yielded += 1;
+				if (!page.next()) continue;
 				yield narrowed;
 			}
 		} finally {
@@ -3156,8 +3150,7 @@ var Table = class {
 		return this.#scope === void 0 ? operation() : this.#scope.track(operation);
 	}
 };
-//#endregion
-//#region src/core/DatabaseTransaction.ts
+// src/core/DatabaseTransaction.ts
 /**
 * Binds a table-only database view to one driver transaction scope.
 *
@@ -3193,8 +3186,7 @@ var DatabaseTransaction = class {
 		return new Table(() => Promise.resolve(), this.#driver, name, key, contract, this.#generate, this.#error, void 0, this.#scope);
 	}
 };
-//#endregion
-//#region src/core/Database.ts
+// src/core/Database.ts
 /**
 * Exposes a typed view over one shared internal lifecycle and storage context.
 *
@@ -3321,8 +3313,7 @@ var Database = class Database {
 		return database;
 	}
 };
-//#endregion
-//#region src/core/drivers/MemoryDriver.ts
+// src/core/drivers/MemoryDriver.ts
 /**
 * Implements the reference {@link DriverInterface} — nested maps, no I/O.
 *
@@ -3594,19 +3585,14 @@ var MemoryDriver = class {
 		const conditions = input.conditions;
 		const offset = input.offset ?? 0;
 		const limit = input.limit;
-		let skipped = 0;
-		let yielded = 0;
+		const page = new StreamPage(offset);
 		for (const key of this.#ordered(table)) {
-			if (limit !== void 0 && yielded >= limit) return;
+			if (limit !== void 0 && page.count >= limit) return;
 			const row = store.get(key);
 			if (row === void 0) continue;
 			if (conditions !== void 0 && conditions.length > 0 && !matchesQuery(row, conditions)) continue;
-			if (skipped < offset) {
-				skipped += 1;
-				continue;
-			}
+			if (!page.next()) continue;
 			yield structuredClone(row);
-			yielded += 1;
 		}
 	}
 	#store(table) {
@@ -3616,8 +3602,7 @@ var MemoryDriver = class {
 		return store;
 	}
 };
-//#endregion
-//#region src/core/factories.ts
+// src/core/factories.ts
 /**
 * Creates a database over a driver and a declared `tables` schema.
 *
@@ -3673,8 +3658,7 @@ function createDatabase(options) {
 function createMemoryDriver() {
 	return new MemoryDriver();
 }
-//#endregion
-//#region src/core/DriverIterator.ts
+// src/core/DriverIterator.ts
 /**
 * Forms the internal continuation boundary for a root driver async iterator.
 *
@@ -3789,7 +3773,6 @@ var DriverIterator = class {
 		} catch {}
 	}
 };
-//#endregion
 exports.CONFORMANCE_POSTS_SCHEMA = CONFORMANCE_POSTS_SCHEMA;
 exports.CONFORMANCE_SCHEMA = CONFORMANCE_SCHEMA;
 exports.CONFORMANCE_USERS_SCHEMA = CONFORMANCE_USERS_SCHEMA;
@@ -3799,9 +3782,11 @@ exports.DatabaseError = DatabaseError;
 exports.DriverIterator = DriverIterator;
 exports.MAX_PATTERN_LENGTH = MAX_PATTERN_LENGTH;
 exports.MemoryDriver = MemoryDriver;
+exports.StreamPage = StreamPage;
 exports.applyQuery = applyQuery;
 exports.auditDriver = auditDriver;
 exports.bindRowKey = bindRowKey;
+exports.captureFailure = captureFailure;
 exports.checkAbort = checkAbort;
 exports.cloneDriverMetadata = cloneDriverMetadata;
 exports.cloneDriverSchema = cloneDriverSchema;
@@ -3829,6 +3814,7 @@ exports.matchesGlobPattern = matchesGlobPattern;
 exports.matchesLikePattern = matchesLikePattern;
 exports.matchesQuery = matchesQuery;
 exports.matchesWildcardPattern = matchesWildcardPattern;
+exports.matchesWildcardSegment = matchesWildcardSegment;
 exports.migrateRows = migrateRows;
 exports.normalizeDriverSchema = normalizeDriverSchema;
 exports.planMigration = planMigration;