@chipmobilesdk/rn-local-db 0.1.2 → 0.2.1

package/src/adapter/lifecycle.ts

@@ -1,444 +1,517 @@
-/**
- * Opening and closing a database.
- *
- * The order of operations here is the design, not an implementation detail:
- *
- * 1. **Validate everything first.** Configuration, scope, and the migration
- *    chain are checked before a file is touched, so a developer error is
- *    reported against an untouched database (FR-006, FR-053).
- * 2. **Consult the catalog before opening the scope file.** A posture
- *    mismatch is detectable there; discovering it from SQLCipher's "file is
- *    not a database" would report corruption for what is actually an app
- *    configuration change (FR-101).
- * 3. **Migrate before returning.** Nothing observes a half-migrated schema,
- *    because there is no handle to observe it with until the chain completes
- *    (FR-055). A failure returns no handle at all (FR-050).
- *
- * Scope is bound here and nowhere else. The handle carries its scope key and
- * no operation on it accepts a scope argument, so there is no `switchScope`
- * to misuse and no read that could address another scope (FR-008a, FR-015).
- * SC-002a's "a leak is not expressible" is this shape plus one file per
- * scope — not a check somewhere that could be forgotten.
- */
-
-import type { Attachments, DatabaseHandle } from '../contract/adapter';
-import type {
-	AttachmentInput,
-	AttachmentOwner,
-	ByteRange,
-	DeletionOutcome,
-	ReconciliationReport,
-} from '../contract/attachment';
-import type { EffectivePosture } from '../contract/backup';
-import type { DatabaseConfig } from '../contract/config';
-import { DiagnosticCodes } from '../contract/errors';
-import type { IndexCoverageReport, Query } from '../contract/query';
-import type { StorableRecordData } from '../contract/record';
-import type { CollectionSchema } from '../contract/schema';
-import type { ResolvedScope } from '../contract/scope';
-import type {
-	BatchOperation,
-	BatchOutcome,
-	CollectionOps,
-	Transaction,
-} from '../contract/transaction';
-import { artifactAvailability } from '../artifacts/availability';
-import { cascadeForOwner } from '../artifacts/cascade';
-import { reconcileArtifacts } from '../artifacts/reconcile';
-import {
-	ensureAttachmentTable,
-	listReferencesFor,
-	readArtifact,
-	removeArtifact,
-	writeArtifact,
-	type ArtifactContext,
-} from '../artifacts/store';
-import { deriveArtifactKey } from '../crypto/derive';
-import { acquireKey, type KeyHandle } from '../crypto/key-provider';
-import { isCipherAvailable } from '../crypto/provider';
-import { raise } from '../diagnostics/errors';
-import { instrument } from '../diagnostics/dev-log';
-import { throwIfFaulted } from '../diagnostics/faults';
-import { runMigrations } from '../migration/executor';
-import { effectivePostureFor } from '../platform/backup-android-verify';
-import { ensureManagedRoot, iosPosture } from '../platform/backup-ios';
-import { layoutFor, type StorageLayout } from '../platform/location';
-import { withStableTiebreaker } from '../query/sort';
-import { indexSchemas } from '../schema/declare';
-import { validateConfig } from '../schema/validate-config';
-import { resolveScope } from '../scope/validate';
-import { runBatch } from '../sqlite/batch';
-import { ensureCatalog, readEntry, registerScope } from '../sqlite/catalog';
-import { assertReadable, openConnection, type Connection } from '../sqlite/connection';
-import { explainQuery } from '../sqlite/index-coverage';
-import { isEncryptionAvailable } from '../sqlite/native';
-import { addColumnSql, createIndexSql, createTableSql } from '../sqlite/row-codec';
-import { runInTransaction } from '../sqlite/transactions';
-import { text } from '../sqlite/values';
-import { acquireHandleSlot, releaseHandleSlot } from './budgets';
-import { createSqlCollection } from './collection';
-import { clearScopeInvalidation, isScopeInvalidated } from './deletion';
-import { createTransaction } from './transaction';
-
-export type OpenOptions = {
-	now?: () => number;
-};
-
-/**
- * Bring the physical tables in line with the declared schema.
- *
- * Adding a column rather than recreating the table is what makes declaring a
- * new queryable field non-destructive: the payload already holds the value,
- * so the new column is backfilled from it and no record is rewritten by hand
- * (research.md R6).
- */
-async function ensureCollection(
-	connection: Connection,
-	schema: CollectionSchema,
-): Promise<void> {
-	await connection.execute(createTableSql(schema));
-
-	const info = await connection.execute(
-		`PRAGMA table_info("c_${schema.name}")`,
-	);
-	const present = new Set(info.rows.map(row => text(row.name)));
-
-	for (const field of schema.fields ?? []) {
-		const column = `f_${field.name}`;
-		if (present.has(column)) {
-			continue;
-		}
-		await connection.execute(addColumnSql(schema, field));
-		await connection.execute(
-			`UPDATE "c_${schema.name}" SET "${column}" = json_extract(payload, '$.${field.name}')`,
-		);
-	}
-
-	for (const statement of createIndexSql(schema)) {
-		await connection.execute(statement);
-	}
-}
-
-function resolveEncryption(config: DatabaseConfig): boolean {
-	if (config.encryption?.enabled !== true) {
-		return false;
-	}
-	// Writing plaintext to a file the app believes is encrypted is the one
-	// outcome worse than refusing to open (research.md R1a).
-	if (!isEncryptionAvailable()) {
-		raise(DiagnosticCodes.ENCRYPTION_UNAVAILABLE, {
-			message: 'encryption was requested but SQLCipher is not compiled into this build',
-		});
-	}
-	if (!isCipherAvailable()) {
-		raise(DiagnosticCodes.ENCRYPTION_UNAVAILABLE, {
-			message: 'encryption was requested but the cipher peer is not installed',
-		});
-	}
-	return true;
-}
-
-async function assertPostureMatches(
-	catalog: Connection,
-	scope: ResolvedScope,
-	encrypted: boolean,
-): Promise<void> {
-	const entry = await readEntry(catalog, scope.key);
-	if (!entry) {
-		return;
-	}
-	if (entry.deletionState === 'deleting') {
-		// An interrupted deletion is reported rather than opened over: the
-		// scope is neither present nor gone, and presenting it as healthy is
-		// the one answer FR-063 forbids. `deleteScopeData` finishes the job.
-		raise(DiagnosticCodes.SCOPE_DELETED, {
-			message: 'a previous deletion of this scope was interrupted',
-			detail: { scopeKey: scope.key },
-		});
-	}
-	if (entry.encrypted !== encrypted) {
-		// In-place conversion is not supported this phase (FR-103). Reporting
-		// the mismatch lets an app migrate deliberately; opening would either
-		// fail obscurely or write the wrong posture.
-		raise(DiagnosticCodes.ENCRYPTION_MISMATCH, {
-			message: 'encryption posture does not match the stored database',
-			detail: { scopeKey: scope.key },
-		});
-	}
-}
-
-export async function openSqliteDatabase(
-	config: DatabaseConfig,
-	options: OpenOptions = {},
-): Promise<DatabaseHandle> {
-	const now = options.now ?? (() => Date.now());
-
-	validateConfig(config);
-	throwIfFaulted('open');
-	const scope = resolveScope(config.scope);
-	const encrypted = resolveEncryption(config);
-	const includeInBackup = config.backup?.includeInPlatformBackup === true;
-
-	const layout: StorageLayout = layoutFor(config.name);
-	await ensureManagedRoot(layout, includeInBackup);
-
-	const catalog = await openConnection({ path: layout.catalogPath });
-	let key: KeyHandle | null = null;
-	let connection: Connection | null = null;
-	let released = false;
-
-	const releaseConnection = async (): Promise<void> => {
-		if (released || !connection) {
-			return;
-		}
-		released = true;
-		await connection.close();
-		releaseHandleSlot();
-	};
-
-	try {
-		await ensureCatalog(catalog);
-		await assertPostureMatches(catalog, scope, encrypted);
-
-		if (encrypted) {
-			key = await acquireKey(config.encryption!, scope);
-		}
-
-		acquireHandleSlot();
-		try {
-			connection = await openConnection({
-				path: layout.scopeDataPath(scope.key),
-				...(key ? { encryptionKey: key.value() } : {}),
-			});
-		} catch (error) {
-			releaseHandleSlot();
-			throw error;
-		}
-		await assertReadable(connection);
-
-		const schemas = indexSchemas(config.collections);
-		for (const schema of config.collections) {
-			await ensureCollection(connection, schema);
-		}
-		await ensureAttachmentTable(connection);
-
-		const scopeConnection = connection;
-		const schemaVersion = await runMigrations({
-			connection: scopeConnection,
-			config,
-			schemaFor: name => schemaFor(schemas, name),
-			now,
-			closeOnFailure: releaseConnection,
-		});
-
-		await registerScope(catalog, {
-			scopeKey: scope.key,
-			createdAt: now(),
-			deletionState: 'active',
-			backupPosture: includeInBackup ? 'included' : 'excluded',
-			encrypted,
-		});
-		await catalog.close();
-		clearScopeInvalidation(config.name, scope.key);
-
-		return buildHandle({
-			config,
-			connection: scopeConnection,
-			key,
-			layout,
-			now,
-			schemaVersion,
-			schemas,
-			scope,
-			posture: effectivePostureFor(layout, includeInBackup, iosPosture),
-		});
-	} catch (error) {
-		// No usable handle after a failed open (FR-002). Anything already
-		// acquired is released here rather than left for a caller who is about
-		// to be handed an exception instead of a handle.
-		key?.release();
-		await releaseConnection();
-		await catalog.close();
-		throw error;
-	}
-}
-
-function schemaFor(
-	schemas: ReadonlyMap<string, CollectionSchema>,
-	name: string,
-): CollectionSchema {
-	const schema = schemas.get(name);
-	if (!schema) {
-		raise(DiagnosticCodes.CONFIG_INVALID, {
-			message: 'collection is not declared',
-			detail: { collection: name },
-		});
-	}
-	return schema;
-}
-
-type HandleContext = {
-	config: DatabaseConfig;
-	connection: Connection;
-	key: KeyHandle | null;
-	layout: StorageLayout;
-	now(): number;
-	schemaVersion: number;
-	schemas: ReadonlyMap<string, CollectionSchema>;
-	scope: ResolvedScope;
-	posture: EffectivePosture;
-};
-
-function buildHandle(context: HandleContext): DatabaseHandle {
-	const { config, connection, layout, scope, schemas } = context;
-	let closed = false;
-
-	const assertUsable = (): void => {
-		if (closed) {
-			raise(DiagnosticCodes.CLOSED_HANDLE, { message: 'handle is closed' });
-		}
-		if (isScopeInvalidated(config.name, scope.key)) {
-			// The deletion did not wait for this handle, and this handle does
-			// not get to keep answering from data that is gone (FR-059a).
-			raise(DiagnosticCodes.SCOPE_DELETED, {
-				message: 'scope was deleted beneath this handle',
-				detail: { scopeKey: scope.key },
-			});
-		}
-	};
-
-	const artifacts: ArtifactContext = {
-		executor: () => connection,
-		layout,
-		scopeKey: scope.key,
-		artifactKey: attachmentId =>
-			context.key ? deriveArtifactKey(context.key.value(), scope.key, attachmentId) : null,
-		now: context.now,
-	};
-
-	const rawCollection = <T extends StorableRecordData>(name: string): CollectionOps<T> => {
-		assertUsable();
-		return instrument(
-			name,
-			'sqlite',
-			createSqlCollection<T>({
-				executor: () => connection,
-				schema: schemaFor(schemas, name),
-				now: context.now,
-				assertUsable,
-			}) as unknown as Record<string, (...args: never[]) => unknown>,
-		) as unknown as CollectionOps<T>;
-	};
-
-	/**
-	 * Record deletion optionally takes its artifacts with it (FR-070).
-	 *
-	 * Off unless the app asks: a package that deleted a user's files as a side
-	 * effect of a record delete would be making a decision that is not its to
-	 * make.
-	 */
-	const collectionFor = <T extends StorableRecordData>(name: string): CollectionOps<T> => {
-		const ops = rawCollection<T>(name);
-		if (config.cascadeAttachments !== true) {
-			return ops;
-		}
-		return {
-			...ops,
-			async delete(id: string) {
-				const outcome = await ops.delete(id);
-				await cascadeForOwner(artifacts, connection, { collection: name, id });
-				return outcome;
-			},
-		};
-	};
-
-	const attachments: Attachments = {
-		write(input: AttachmentInput) {
-			assertUsable();
-			return writeArtifact(artifacts, input);
-		},
-		read(id: string, range?: ByteRange) {
-			assertUsable();
-			return readArtifact(artifacts, id, range);
-		},
-		availability(id: string) {
-			assertUsable();
-			return artifactAvailability(artifacts, connection, id);
-		},
-		remove(id: string): Promise<DeletionOutcome> {
-			assertUsable();
-			return removeArtifact(artifacts, id);
-		},
-		listFor(owner: AttachmentOwner) {
-			assertUsable();
-			return listReferencesFor(connection, owner);
-		},
-		reconcile(options): Promise<ReconciliationReport> {
-			assertUsable();
-			return reconcileArtifacts(artifacts, connection, options);
-		},
-	};
-
-	const handle: DatabaseHandle = {
-		scopeKey: scope.key,
-		schemaVersion: context.schemaVersion,
-		backupPosture: context.posture,
-		isEncrypted: context.key !== null,
-
-		collection: collectionFor,
-
-		async transaction<R>(fn: (tx: Transaction) => Promise<R>): Promise<R> {
-			assertUsable();
-			return runInTransaction(connection, async tx => {
-				const managed = createTransaction({
-					collection: collectionFor,
-					rollback: () => tx.rollback(),
-				});
-				const result = await fn(managed.transaction);
-				if (!managed.isSettled()) {
-					throwIfFaulted('commit');
-				}
-				managed.settle();
-				return result;
-			});
-		},
-
-		batch(operations: BatchOperation[]): Promise<BatchOutcome> {
-			assertUsable();
-			return runBatch(
-				{
-					connection,
-					schemaFor: name => schemaFor(schemas, name),
-					now: context.now,
-				},
-				operations,
-			);
-		},
-
-		attachments: () => attachments,
-
-		explain(collection: string, query?: Query): Promise<IndexCoverageReport> {
-			assertUsable();
-			return explainQuery(
-				connection,
-				schemaFor(schemas, collection),
-				query,
-				withStableTiebreaker(query?.sort),
-			);
-		},
-
-		async close(): Promise<void> {
-			if (closed) {
-				return;
-			}
-			closed = true;
-			// The key goes first: a close that fails at the filesystem must not
-			// leave key material alive in a handle nobody can use (FR-098).
-			context.key?.release();
-			await connection.close();
-			releaseHandleSlot();
-		},
-	};
-
-	return handle;
-}
+/**
+ * Opening and closing a database.
+ *
+ * The order of operations here is the design, not an implementation detail:
+ *
+ * 1. **Validate everything first.** Configuration, scope, and the migration
+ *    chain are checked before a file is touched, so a developer error is
+ *    reported against an untouched database (FR-006, FR-053).
+ * 2. **Consult the catalog before opening the scope file.** A posture
+ *    mismatch is detectable there; discovering it from SQLCipher's "file is
+ *    not a database" would report corruption for what is actually an app
+ *    configuration change (FR-101).
+ * 3. **Migrate before returning.** Nothing observes a half-migrated schema,
+ *    because there is no handle to observe it with until the chain completes
+ *    (FR-055). A failure returns no handle at all (FR-050).
+ *
+ * Scope is bound here and nowhere else. The handle carries its scope key and
+ * no operation on it accepts a scope argument, so there is no `switchScope`
+ * to misuse and no read that could address another scope (FR-008a, FR-015).
+ * SC-002a's "a leak is not expressible" is this shape plus one file per
+ * scope — not a check somewhere that could be forgotten.
+ */
+
+import type { Attachments, DatabaseHandle } from '../contract/adapter';
+import type {
+	AttachmentInput,
+	AttachmentOwner,
+	ByteRange,
+	DeletionOutcome,
+	ReconciliationReport,
+} from '../contract/attachment';
+import type { EffectivePosture } from '../contract/backup';
+import type { DatabaseConfig } from '../contract/config';
+import { DiagnosticCodes } from '../contract/errors';
+import type { IndexCoverageReport, Query } from '../contract/query';
+import type { StorableRecordData } from '../contract/record';
+import type { CollectionSchema } from '../contract/schema';
+import type { ResolvedScope } from '../contract/scope';
+import type {
+	BatchOperation,
+	BatchOutcome,
+	CollectionOps,
+	Transaction,
+} from '../contract/transaction';
+import { artifactAvailability } from '../artifacts/availability';
+import { cascadeForOwner, unlinkArtifact, type DeferredUnlinks } from '../artifacts/cascade';
+import { reconcileArtifacts } from '../artifacts/reconcile';
+import {
+	ensureAttachmentTable,
+	listReferencesFor,
+	readArtifact,
+	removeArtifact,
+	writeArtifact,
+	type ArtifactContext,
+} from '../artifacts/store';
+import { deriveArtifactKey } from '../crypto/derive';
+import { acquireKey, type KeyHandle } from '../crypto/key-provider';
+import { isCipherAvailable } from '../crypto/provider';
+import { raise } from '../diagnostics/errors';
+import { instrument } from '../diagnostics/dev-log';
+import { throwIfFaulted } from '../diagnostics/faults';
+import { runMigrations } from '../migration/executor';
+import { effectivePostureFor } from '../platform/backup-android-verify';
+import { ensureManagedRoot, iosPosture } from '../platform/backup-ios';
+import { layoutFor, type StorageLayout } from '../platform/location';
+import { withStableTiebreaker } from '../query/sort';
+import { indexSchemas } from '../schema/declare';
+import { validateConfig } from '../schema/validate-config';
+import { resolveScope } from '../scope/validate';
+import { runBatch } from '../sqlite/batch';
+import { ensureCatalog, readEntry, registerScope } from '../sqlite/catalog';
+import {
+	assertReadable,
+	openConnection,
+	type Connection,
+	type Executor,
+} from '../sqlite/connection';
+import { explainQuery } from '../sqlite/index-coverage';
+import { isEncryptionAvailable } from '../sqlite/native';
+import {
+	addColumnSql,
+	createIndexSql,
+	createTableSql,
+	physicalIndexName,
+} from '../sqlite/row-codec';
+import { runInTransaction } from '../sqlite/transactions';
+import { text } from '../sqlite/values';
+import { acquireHandleSlot, releaseHandleSlot } from './budgets';
+import { createSqlCollection } from './collection';
+import { clearScopeInvalidation, isScopeInvalidated } from './deletion';
+import { createTransaction } from './transaction';
+
+export type OpenOptions = {
+	now?: () => number;
+};
+
+/**
+ * Bring the physical tables in line with the declared schema.
+ *
+ * Adding a column rather than recreating the table is what makes declaring a
+ * new queryable field non-destructive: the payload already holds the value,
+ * so the new column is backfilled from it and no record is rewritten by hand
+ * (research.md R6).
+ */
+async function ensureCollection(connection: Connection, schema: CollectionSchema): Promise<void> {
+	await connection.execute(createTableSql(schema));
+
+	const info = await connection.execute(`PRAGMA table_info("c_${schema.name}")`);
+	const present = new Set(info.rows.map(row => text(row.name)));
+
+	for (const field of schema.fields ?? []) {
+		const column = `f_${field.name}`;
+		if (present.has(column)) {
+			continue;
+		}
+		await connection.execute(addColumnSql(schema, field));
+		await connection.execute(
+			`UPDATE "c_${schema.name}" SET "${column}" = json_extract(payload, '$.${field.name}')`,
+		);
+	}
+
+	// Indexes created before 0.2.0 carry the bare declared name. Each one still
+	// attached to this table is dropped and recreated under its collection-scoped
+	// name; only indexes on this table are touched, and no row data moves.
+	const existing = await connection.execute(`PRAGMA index_list("c_${schema.name}")`);
+	const onTable = new Set(existing.rows.map(row => text(row.name)));
+	for (const index of schema.indexes ?? []) {
+		if (onTable.has(index.name) && index.name !== physicalIndexName(schema, index.name)) {
+			await connection.execute(`DROP INDEX IF EXISTS "${index.name}"`);
+		}
+	}
+
+	for (const statement of createIndexSql(schema)) {
+		await connection.execute(statement);
+	}
+}
+
+function resolveEncryption(config: DatabaseConfig): boolean {
+	if (config.encryption?.enabled !== true) {
+		return false;
+	}
+	// Writing plaintext to a file the app believes is encrypted is the one
+	// outcome worse than refusing to open (research.md R1a).
+	if (!isEncryptionAvailable()) {
+		raise(DiagnosticCodes.ENCRYPTION_UNAVAILABLE, {
+			message: 'encryption was requested but SQLCipher is not compiled into this build',
+		});
+	}
+	if (!isCipherAvailable()) {
+		raise(DiagnosticCodes.ENCRYPTION_UNAVAILABLE, {
+			message: 'encryption was requested but the cipher peer is not installed',
+		});
+	}
+	return true;
+}
+
+async function assertPostureMatches(
+	catalog: Connection,
+	scope: ResolvedScope,
+	encrypted: boolean,
+): Promise<void> {
+	const entry = await readEntry(catalog, scope.key);
+	if (!entry) {
+		return;
+	}
+	if (entry.deletionState === 'deleting') {
+		// An interrupted deletion is reported rather than opened over: the
+		// scope is neither present nor gone, and presenting it as healthy is
+		// the one answer FR-063 forbids. `deleteScopeData` finishes the job.
+		raise(DiagnosticCodes.SCOPE_DELETED, {
+			message: 'a previous deletion of this scope was interrupted',
+			detail: { scopeKey: scope.key },
+		});
+	}
+	if (entry.encrypted !== encrypted) {
+		// In-place conversion is not supported this phase (FR-103). Reporting
+		// the mismatch lets an app migrate deliberately; opening would either
+		// fail obscurely or write the wrong posture.
+		raise(DiagnosticCodes.ENCRYPTION_MISMATCH, {
+			message: 'encryption posture does not match the stored database',
+			detail: { scopeKey: scope.key },
+		});
+	}
+}
+
+export async function openSqliteDatabase(
+	config: DatabaseConfig,
+	options: OpenOptions = {},
+): Promise<DatabaseHandle> {
+	const now = options.now ?? (() => Date.now());
+
+	validateConfig(config);
+	throwIfFaulted('open');
+	const scope = resolveScope(config.scope);
+	const encrypted = resolveEncryption(config);
+	const includeInBackup = config.backup?.includeInPlatformBackup === true;
+
+	const layout: StorageLayout = layoutFor(config.name);
+	await ensureManagedRoot(layout, includeInBackup);
+
+	const catalog = await openConnection({ path: layout.catalogPath });
+	let key: KeyHandle | null = null;
+	let connection: Connection | null = null;
+	let released = false;
+
+	const releaseConnection = async (): Promise<void> => {
+		if (released || !connection) {
+			return;
+		}
+		released = true;
+		await connection.close();
+		releaseHandleSlot();
+	};
+
+	try {
+		await ensureCatalog(catalog);
+		await assertPostureMatches(catalog, scope, encrypted);
+
+		if (encrypted) {
+			key = await acquireKey(config.encryption!, scope);
+		}
+
+		acquireHandleSlot();
+		try {
+			connection = await openConnection({
+				path: layout.scopeDataPath(scope.key),
+				...(key ? { encryptionKey: key.value() } : {}),
+			});
+		} catch (error) {
+			releaseHandleSlot();
+			throw error;
+		}
+		await assertReadable(connection);
+
+		const schemas = indexSchemas(config.collections);
+		for (const schema of config.collections) {
+			await ensureCollection(connection, schema);
+		}
+		await ensureAttachmentTable(connection);
+
+		const scopeConnection = connection;
+		const schemaVersion = await runMigrations({
+			connection: scopeConnection,
+			config,
+			schemaFor: name => schemaFor(schemas, name),
+			now,
+			closeOnFailure: releaseConnection,
+		});
+
+		await registerScope(catalog, {
+			scopeKey: scope.key,
+			createdAt: now(),
+			deletionState: 'active',
+			backupPosture: includeInBackup ? 'included' : 'excluded',
+			encrypted,
+		});
+		await catalog.close();
+		clearScopeInvalidation(config.name, scope.key);
+
+		return buildHandle({
+			config,
+			connection: scopeConnection,
+			key,
+			layout,
+			now,
+			schemaVersion,
+			schemas,
+			scope,
+			posture: effectivePostureFor(layout, includeInBackup, iosPosture),
+		});
+	} catch (error) {
+		// No usable handle after a failed open (FR-002). Anything already
+		// acquired is released here rather than left for a caller who is about
+		// to be handed an exception instead of a handle.
+		key?.release();
+		await releaseConnection();
+		await catalog.close();
+		throw error;
+	}
+}
+
+function schemaFor(schemas: ReadonlyMap<string, CollectionSchema>, name: string): CollectionSchema {
+	const schema = schemas.get(name);
+	if (!schema) {
+		raise(DiagnosticCodes.CONFIG_INVALID, {
+			message: 'collection is not declared',
+			detail: { collection: name },
+		});
+	}
+	return schema;
+}
+
+type HandleContext = {
+	config: DatabaseConfig;
+	connection: Connection;
+	key: KeyHandle | null;
+	layout: StorageLayout;
+	now(): number;
+	schemaVersion: number;
+	schemas: ReadonlyMap<string, CollectionSchema>;
+	scope: ResolvedScope;
+	posture: EffectivePosture;
+};
+
+function buildHandle(context: HandleContext): DatabaseHandle {
+	const { config, connection, layout, scope, schemas } = context;
+	let closed = false;
+
+	const assertUsable = (): void => {
+		if (closed) {
+			raise(DiagnosticCodes.CLOSED_HANDLE, { message: 'handle is closed' });
+		}
+		if (isScopeInvalidated(config.name, scope.key)) {
+			// The deletion did not wait for this handle, and this handle does
+			// not get to keep answering from data that is gone (FR-059a).
+			raise(DiagnosticCodes.SCOPE_DELETED, {
+				message: 'scope was deleted beneath this handle',
+				detail: { scopeKey: scope.key },
+			});
+		}
+	};
+
+	// Everything below is built against an explicit executor: the connection for
+	// the handle, the transaction's own executor inside `transaction`. Nothing
+	// infers which one from the connection's state, which is how a write from
+	// outside used to be swallowed by an in-flight transaction (LDB-01).
+	const artifactsOn = (executor: Executor): ArtifactContext => ({
+		executor: () => executor,
+		layout,
+		scopeKey: scope.key,
+		artifactKey: attachmentId =>
+			context.key ? deriveArtifactKey(context.key.value(), scope.key, attachmentId) : null,
+		now: context.now,
+	});
+
+	const rawCollection = <T extends StorableRecordData>(
+		name: string,
+		executor: Executor,
+	): CollectionOps<T> => {
+		assertUsable();
+		return instrument(
+			name,
+			'sqlite',
+			createSqlCollection<T>({
+				executor: () => executor,
+				schema: schemaFor(schemas, name),
+				now: context.now,
+				assertUsable,
+			}) as unknown as Record<string, (...args: never[]) => unknown>,
+		) as unknown as CollectionOps<T>;
+	};
+
+	/**
+	 * Record deletion optionally takes its artifacts with it (FR-070).
+	 *
+	 * Off unless the app asks: a package that deleted a user's files as a side
+	 * effect of a record delete would be making a decision that is not its to
+	 * make. The outcome carries what was removed and what could not be.
+	 */
+	const collectionOn = <T extends StorableRecordData>(
+		name: string,
+		executor: Executor,
+		deferred?: DeferredUnlinks,
+	): CollectionOps<T> => {
+		const ops = rawCollection<T>(name, executor);
+		if (config.cascadeAttachments !== true) {
+			return ops;
+		}
+		return {
+			...ops,
+			async delete(id: string) {
+				const outcome = await ops.delete(id);
+				const cascade = await cascadeForOwner(
+					artifactsOn(executor),
+					executor,
+					{ collection: name, id },
+					deferred,
+				);
+				return { ...outcome, cascade };
+			},
+		};
+	};
+
+	const attachmentsOn = (executor: Executor, deferred?: DeferredUnlinks): Attachments => {
+		const artifacts = artifactsOn(executor);
+		return {
+			write(input: AttachmentInput) {
+				assertUsable();
+				return writeArtifact(artifacts, input);
+			},
+			read(id: string, range?: ByteRange) {
+				assertUsable();
+				return readArtifact(artifacts, id, range);
+			},
+			availability(id: string) {
+				assertUsable();
+				return artifactAvailability(artifacts, executor, id);
+			},
+			remove(id: string): Promise<DeletionOutcome> {
+				assertUsable();
+				return removeArtifact(artifacts, id, deferred);
+			},
+			listFor(owner: AttachmentOwner) {
+				assertUsable();
+				return listReferencesFor(executor, owner);
+			},
+			reconcile(options): Promise<ReconciliationReport> {
+				assertUsable();
+				return reconcileArtifacts(artifacts, executor, options);
+			},
+		};
+	};
+
+	const collectionFor = <T extends StorableRecordData>(name: string): CollectionOps<T> =>
+		collectionOn<T>(name, connection);
+	const attachments = attachmentsOn(connection);
+
+	const handle: DatabaseHandle = {
+		scopeKey: scope.key,
+		schemaVersion: context.schemaVersion,
+		backupPosture: context.posture,
+		isEncrypted: context.key !== null,
+
+		collection: collectionFor,
+
+		async transaction<R>(fn: (tx: Transaction) => Promise<R>): Promise<R> {
+			assertUsable();
+			const pendingUnlinks: string[] = [];
+			const deferred: DeferredUnlinks = { add: path => pendingUnlinks.push(path) };
+			let aborted = false;
+			const result = await runInTransaction(connection, async tx => {
+				const managed = createTransaction({
+					collection: name => collectionOn(name, tx, deferred),
+					attachments: () => attachmentsOn(tx, deferred),
+					rollback: async () => {
+						aborted = true;
+						await tx.rollback();
+					},
+				});
+				const value = await fn(managed.transaction);
+				if (!managed.isSettled()) {
+					throwIfFaulted('commit');
+				}
+				managed.settle();
+				return value;
+			});
+			// Committed (a thrown body never gets here). Only now are files whose
+			// references the transaction deleted safe to remove; one that cannot be
+			// removed stays on disk as an orphan reconciliation reports.
+			if (!aborted) {
+				for (const path of pendingUnlinks) {
+					await unlinkArtifact(path);
+				}
+			}
+			return result;
+		},
+
+		async batch(operations: BatchOperation[]): Promise<BatchOutcome> {
+			assertUsable();
+			const outcome = await runBatch(
+				{
+					connection,
+					schemaFor: name => schemaFor(schemas, name),
+					now: context.now,
+				},
+				operations,
+			);
+			if (config.cascadeAttachments !== true) {
+				return outcome;
+			}
+			// The batch has committed, so its hard deletes cascade exactly as a
+			// collection delete does. Skipping them left every attachment of a
+			// batch-deleted record behind as an orphan.
+			const artifacts = artifactsOn(connection);
+			const outcomes = [];
+			for (const [index, operation] of operations.entries()) {
+				const written = outcome.outcomes[index]!;
+				if (operation.type !== 'delete') {
+					outcomes.push(written);
+					continue;
+				}
+				const cascade = await cascadeForOwner(artifacts, connection, {
+					collection: operation.collection,
+					id: operation.id,
+				});
+				outcomes.push({ ...written, cascade });
+			}
+			return { ...outcome, outcomes };
+		},
+
+		attachments: () => attachments,
+
+		explain(collection: string, query?: Query): Promise<IndexCoverageReport> {
+			assertUsable();
+			return explainQuery(
+				connection,
+				schemaFor(schemas, collection),
+				query,
+				withStableTiebreaker(query?.sort),
+			);
+		},
+
+		async close(): Promise<void> {
+			if (closed) {
+				return;
+			}
+			closed = true;
+			// The key goes first: a close that fails at the filesystem must not
+			// leave key material alive in a handle nobody can use (FR-098).
+			context.key?.release();
+			await connection.close();
+			releaseHandleSlot();
+		},
+	};
+
+	return handle;
+}