@chipmobilesdk/rn-local-db 0.2.0 → 0.2.1

package/src/testing/memory-adapter/index.ts

@@ -1,492 +1,510 @@
-/**
- * The in-memory adapter.
- *
- * Not a convenience: op-sqlite is native and unreachable from Jest, so this
- * is the only way the package's own guarantees are testable in CI
- * (research.md R8). Documented divergences are listed in the package README.
- */
-
-import { createTransactionQueue } from '../../sqlite/transaction-queue';
-import type {
-	AttachmentInput,
-	AttachmentReference,
-	AttachmentOwner,
-	ByteRange,
-	DeletionOutcome,
-	ReconciliationReport,
-} from '../../contract/attachment';
-import type { EffectivePosture } from '../../contract/backup';
-import type { DatabaseConfig, DatabaseTargetConfig, ScopeTargetConfig } 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 { BatchOperation, BatchOutcome, CollectionOps, Transaction } from '../../contract/transaction';
-import type { Attachments, DatabaseHandle, StorageAdapter } from '../../contract/adapter';
-import { acquireKey } from '../../crypto/key-provider';
-import { instrument } from '../../diagnostics/dev-log';
-import { raise } from '../../diagnostics/errors';
-import { assertValidAttachmentId } from '../../platform/location';
-import { assertBatchWithinBudget, assertArtifactWithinBudget } from '../../query/budgets';
-import { validateConfig } from '../../schema/validate-config';
-import { resolveScope } from '../../scope/validate';
-import { runMigrations } from './migrations';
-import { createMemoryCollection } from './collection';
-import {
-	collectionMap,
-	dropDatabase,
-	dropScope,
-	existingScopeStore,
-	scopeStoreFor,
-	type MemoryScopeStore,
-} from './store';
-import { throwIfFaulted } from '../faults';
-
-export type MemoryAdapterOptions = {
-	/** Fixed clock, so timestamp assertions are deterministic. */
-	now?: () => number;
-};
-
-function schemaIndex(collections: CollectionSchema[]): Map<string, CollectionSchema> {
-	return new Map(collections.map(collection => [collection.name, collection]));
-}
-
-function cloneCollections(
-	store: MemoryScopeStore,
-): Map<string, Map<string, { id: string; payload: string; createdAt?: number; updatedAt?: number; deletedAt?: number | null }>> {
-	const copy = new Map<string, Map<string, never>>();
-	for (const [name, rows] of store.collections) {
-		copy.set(name, new Map([...rows].map(([id, row]) => [id, { ...row } as never])));
-	}
-	return copy as never;
-}
-
-export function createMemoryAdapter(options: MemoryAdapterOptions = {}): StorageAdapter {
-	const now = options.now ?? (() => Date.now());
-
-	async function open(config: DatabaseConfig): Promise<DatabaseHandle> {
-		validateConfig(config);
-		throwIfFaulted('open');
-
-		const scope = resolveScope(config.scope);
-		const existing = existingScopeStore(config.name, scope.key);
-		if (existing?.deletionState === 'deleting') {
-			// A deletion that was interrupted must never look complete.
-			raise(DiagnosticCodes.SCOPE_DELETED, {
-				message: 'scope deletion was interrupted',
-				detail: { scopeKey: scope.key },
-			});
-		}
-
-		const store = scopeStoreFor(config.name, scope.key);
-		const encryptionRequested = config.encryption?.enabled === true;
-
-		if (store.schemaVersion > 0 && store.encrypted !== encryptionRequested) {
-			raise(DiagnosticCodes.ENCRYPTION_MISMATCH, {
-				message: 'encryption posture does not match the stored database',
-			});
-		}
-		if (encryptionRequested) {
-			// The same acquisition path the on-device adapter uses, so a locked
-			// keychain and a provider returning nothing stay as distinguishable
-			// here as they are on a phone (SC-020b). Released immediately: the
-			// in-memory store has nothing to encrypt with it.
-			const key = await acquireKey(config.encryption!, scope);
-			key.release();
-		}
-		store.encrypted = encryptionRequested;
-		store.backupIncluded = config.backup?.includeInPlatformBackup === true;
-
-		const schemas = schemaIndex(config.collections);
-		for (const collection of config.collections) {
-			collectionMap(store, collection.name);
-		}
-
-		await runMigrations(store, config, now);
-
-		let closed = false;
-		const assertOpen = (): void => {
-			if (closed) {
-				raise(DiagnosticCodes.CLOSED_HANDLE, { message: 'handle is closed' });
-			}
-			if (store.deletionState === 'deleting') {
-				raise(DiagnosticCodes.SCOPE_DELETED, {
-					message: 'scope was deleted beneath this handle',
-					detail: { scopeKey: scope.key },
-				});
-			}
-		};
-
-		/**
-		 * The same isolation the SQLite connection gives: a transaction holds the
-		 * handle until it settles, and work through the handle meanwhile waits
-		 * rather than landing inside the transaction's snapshot and vanishing
-		 * with its rollback. Only what the transaction hands out runs inside it.
-		 */
-		const queue = createTransactionQueue();
-		const queued = <O extends object>(ops: O): O =>
-			Object.fromEntries(
-				Object.entries(ops).map(([key, value]) => [
-					key,
-					typeof value === 'function'
-						? (...args: unknown[]) =>
-								queue.run(() => (value as (...a: unknown[]) => Promise<unknown>)(...args))
-						: value,
-				]),
-			) as O;
-
-		/** Artifact deletions held back until the transaction that caused them commits. */
-		type Deferred = { add(id: string): void };
-
-		/** FR-070 for the memory adapter, with the SQLite adapter's ordering and reporting. */
-		const cascadeFor = (collection: string, id: string, deferred?: Deferred): DeletionOutcome => {
-			const removedArtifacts: string[] = [];
-			for (const reference of [...store.attachments.values()]) {
-				if (reference.owner?.collection !== collection || reference.owner?.id !== id) continue;
-				store.attachments.delete(reference.id);
-				if (deferred) {
-					deferred.add(reference.id);
-				} else {
-					store.artifacts.delete(reference.id);
-				}
-				removedArtifacts.push(reference.id);
-			}
-			return { removedRecords: 0, removedArtifacts, orphanedReferences: [], failedRemovals: [] };
-		};
-
-		const rawCollectionFor = <T extends StorableRecordData>(
-			name: string,
-			deferred?: Deferred,
-		): CollectionOps<T> => {
-			assertOpen();
-			const schema = schemas.get(name);
-			if (!schema) {
-				raise(DiagnosticCodes.CONFIG_INVALID, {
-					message: 'collection is not declared',
-					detail: { collection: name },
-				});
-			}
-			const ops = instrument(
-				name,
-				'memory',
-				createMemoryCollection<T>({ store, schema, now, assertOpen }) as unknown as Record<
-					string,
-					(...args: never[]) => unknown
-				>,
-			) as unknown as CollectionOps<T>;
-			if (config.cascadeAttachments !== true) {
-				return ops;
-			}
-			return {
-				...ops,
-				async delete(id: string) {
-					const outcome = await ops.delete(id);
-					return { ...outcome, cascade: cascadeFor(name, id, deferred) };
-				},
-			};
-		};
-
-		const collectionFor = <T extends StorableRecordData>(name: string): CollectionOps<T> =>
-			queued(rawCollectionFor<T>(name));
-
-		const backupPosture: EffectivePosture = {
-			requested: store.backupIncluded ? 'included' : 'excluded',
-			observed: store.backupIncluded ? 'included' : 'excluded',
-			enforcedBy: 'package',
-		};
-
-		const rawAttachments = (deferred?: Deferred): Attachments => ({
-			async write(input: AttachmentInput): Promise<AttachmentReference> {
-				assertOpen();
-				throwIfFaulted('attachmentWrite');
-				assertValidAttachmentId(input.id);
-				const bytes = Buffer.from(input.content, 'base64');
-				assertArtifactWithinBudget(input.id, bytes.length);
-				const reference: AttachmentReference = {
-					id: input.id,
-					owner: input.owner,
-					contentType: input.contentType,
-					size: bytes.length,
-					createdAt: now(),
-				};
-				store.artifacts.set(input.id, input.content);
-				store.attachments.set(input.id, reference);
-				return reference;
-			},
-			async read(id: string, range?: ByteRange): Promise<string> {
-				assertOpen();
-				// No paths here to escape, but an id the device build would refuse
-				// has to be refused here too, or a consumer's passing tests stop
-				// predicting the device (FR-096).
-				assertValidAttachmentId(id);
-				const content = store.artifacts.get(id);
-				if (content === undefined) {
-					raise(DiagnosticCodes.ATTACHMENT_MISSING, {
-						message: 'artifact is missing',
-						detail: { attachmentId: id },
-					});
-				}
-				if (!range) {
-					return content;
-				}
-				const bytes = Buffer.from(content, 'base64');
-				return bytes.subarray(range.offset, range.offset + range.length).toString('base64');
-			},
-			async availability(id) {
-				assertOpen();
-				const reference = store.attachments.get(id);
-				if (!reference) {
-					return { id, state: 'missing' };
-				}
-				return store.artifacts.has(id)
-					? { id, state: 'available', size: reference.size }
-					: { id, state: 'missing' };
-			},
-			async remove(id: string): Promise<DeletionOutcome> {
-				assertOpen();
-				assertValidAttachmentId(id);
-				if (deferred) {
-					const hadReference = store.attachments.delete(id);
-					if (hadReference) deferred.add(id);
-					return {
-						removedRecords: 0,
-						removedArtifacts: hadReference ? [id] : [],
-						orphanedReferences: [],
-						failedRemovals: [],
-					};
-				}
-				const removed = store.artifacts.delete(id);
-				store.attachments.delete(id);
-				return {
-					removedRecords: 0,
-					removedArtifacts: removed ? [id] : [],
-					orphanedReferences: [],
-					failedRemovals: [],
-				};
-			},
-			async listFor(owner: AttachmentOwner): Promise<AttachmentReference[]> {
-				assertOpen();
-				return [...store.attachments.values()].filter(
-					reference =>
-						reference.owner?.collection === owner.collection &&
-						reference.owner?.id === owner.id,
-				);
-			},
-			async reconcile(reconcileOptions): Promise<ReconciliationReport> {
-				assertOpen();
-				const orphanedArtifacts = [...store.artifacts.keys()].filter(
-					id => !store.attachments.has(id),
-				);
-				const danglingReferences = [...store.attachments.keys()].filter(
-					id => !store.artifacts.has(id),
-				);
-				const removedArtifacts: string[] = [];
-				if (reconcileOptions?.removeOrphans) {
-					for (const id of orphanedArtifacts) {
-						store.artifacts.delete(id);
-						removedArtifacts.push(id);
-					}
-				}
-				return { orphanedArtifacts, danglingReferences, removedArtifacts };
-			},
-		});
-		const attachments = queued(rawAttachments());
-
-		/**
-		 * One transaction against the store. Snapshot-and-restore rather than a
-		 * write log: simpler to reason about, and rollback fidelity is what US4
-		 * tests. Runs only inside `exclusive`, so the snapshot never captures,
-		 * nor its restore erases, a write made from outside.
-		 */
-		const runTransaction = async <R>(fn: (tx: Transaction) => Promise<R>): Promise<R> => {
-			const snapshot = cloneCollections(store);
-			const attachmentSnapshot = new Map(store.attachments);
-			const pendingArtifactRemovals: string[] = [];
-			const deferred: Deferred = { add: id => pendingArtifactRemovals.push(id) };
-			let settled = false;
-
-			const assertLive = (): void => {
-				if (settled) {
-					raise(DiagnosticCodes.TRANSACTION_STATE, {
-						message: 'transaction already settled',
-					});
-				}
-			};
-			const rollback = (): void => {
-				store.collections = snapshot as never;
-				store.attachments = attachmentSnapshot;
-			};
-
-			// A collection taken from the transaction keeps refusing once it
-			// settles, as the SQLite executor does; otherwise a write after abort
-			// would land straight in the store.
-			const live = <O extends object>(ops: O): O =>
-				Object.fromEntries(
-					Object.entries(ops).map(([key, value]) => [
-						key,
-						typeof value === 'function'
-							? // Async so a refusal rejects, as the SQLite executor's does.
-								async (...args: unknown[]) => {
-									assertLive();
-									return (value as (...a: unknown[]) => unknown)(...args);
-								}
-							: value,
-					]),
-				) as O;
-
-			const tx: Transaction = {
-				collection: <T extends StorableRecordData>(name: string) => {
-					assertLive();
-					return live(rawCollectionFor<T>(name, deferred));
-				},
-				attachments: () => {
-					assertLive();
-					return rawAttachments(deferred);
-				},
-				async abort() {
-					assertLive();
-					settled = true;
-					rollback();
-				},
-			};
-
-			try {
-				const result = await fn(tx);
-				if (!settled) {
-					throwIfFaulted('commit');
-					settled = true;
-					// Committed: the artifacts whose references went may go too.
-					for (const id of pendingArtifactRemovals) {
-						store.artifacts.delete(id);
-					}
-				}
-				return result;
-			} catch (error) {
-				if (!settled) {
-					settled = true;
-					rollback();
-				}
-				throw error;
-			}
-		};
-
-		const handle: DatabaseHandle = {
-			scopeKey: scope.key,
-			schemaVersion: store.schemaVersion,
-			backupPosture,
-			isEncrypted: store.encrypted,
-			collection: collectionFor,
-
-			transaction<R>(fn: (tx: Transaction) => Promise<R>): Promise<R> {
-				assertOpen();
-				return queue.runTransaction(() => runTransaction(fn));
-			},
-
-			batch(operations: BatchOperation[]): Promise<BatchOutcome> {
-				assertOpen();
-				assertBatchWithinBudget(operations.length);
-				return queue.runTransaction(() =>
-					runTransaction(async (tx: Transaction) => {
-						const outcomes = [];
-						for (const operation of operations) {
-							const ops = tx.collection(operation.collection);
-							switch (operation.type) {
-								case 'insert':
-									outcomes.push(await ops.insert(operation.record));
-									break;
-								case 'update':
-									outcomes.push(await ops.update(operation.id, { data: operation.data }));
-									break;
-								case 'upsert':
-									outcomes.push(await ops.upsert(operation.record));
-									break;
-								case 'delete':
-									outcomes.push(await ops.delete(operation.id));
-									break;
-								case 'softDelete':
-									outcomes.push(await ops.softDelete(operation.id));
-									break;
-								default:
-									break;
-							}
-						}
-						return { applied: outcomes.length, outcomes };
-					}),
-				);
-			},
-
-			attachments: () => attachments,
-
-			async explain(collection: string, _query?: Query): Promise<IndexCoverageReport> {
-				assertOpen();
-				// Documented divergence: index declarations are validated but
-				// have no performance effect in memory (FR-096).
-				return {
-					collection,
-					usesIndex: false,
-					detail: 'memory adapter does not use indexes',
-				};
-			},
-
-			async close(): Promise<void> {
-				closed = true;
-			},
-		};
-
-		return handle;
-	}
-
-	/**
-	 * Backs both `deleteScopeData` and `resetScope`. They differ in intent and
-	 * in what they let a consumer conclude, not in what they do to the store —
-	 * keeping them as separate exported names is what makes the destructive one
-	 * impossible to call by accident.
-	 */
-	async function removeScope(config: ScopeTargetConfig): Promise<DeletionOutcome> {
-		const scope = resolveScope(config.scope);
-		const store = existingScopeStore(config.name, scope.key);
-		if (!store) {
-			// Deleting nothing is success, not an error (FR-062).
-			return {
-				scopeKey: scope.key,
-				removedRecords: 0,
-				removedArtifacts: [],
-				orphanedReferences: [],
-				failedRemovals: [],
-			};
-		}
-		store.deletionState = 'deleting';
-		let removedRecords = 0;
-		for (const rows of store.collections.values()) {
-			removedRecords += rows.size;
-		}
-		const removedArtifacts = [...store.artifacts.keys()];
-		dropScope(config.name, scope.key);
-		return {
-			scopeKey: scope.key,
-			removedRecords,
-			removedArtifacts,
-			orphanedReferences: [],
-			failedRemovals: [],
-		};
-	}
-
-	return {
-		name: 'memory',
-		open,
-		deleteScopeData: config => removeScope(config),
-		resetScope: config => removeScope(config),
-		async deleteDatabase(config: DatabaseTargetConfig): Promise<DeletionOutcome> {
-			dropDatabase(config.name);
-			return {
-				removedRecords: 0,
-				removedArtifacts: [],
-				orphanedReferences: [],
-				failedRemovals: [],
-			};
-		},
-	};
-}
-
-export { Budgets } from '../../contract/config';
-export { activeFaults } from '../faults';
+/**
+ * The in-memory adapter.
+ *
+ * Not a convenience: op-sqlite is native and unreachable from Jest, so this
+ * is the only way the package's own guarantees are testable in CI
+ * (research.md R8). Documented divergences are listed in the package README.
+ */
+
+import { createTransactionQueue } from '../../sqlite/transaction-queue';
+import type {
+	AttachmentInput,
+	AttachmentReference,
+	AttachmentOwner,
+	ByteRange,
+	DeletionOutcome,
+	ReconciliationReport,
+} from '../../contract/attachment';
+import type { EffectivePosture } from '../../contract/backup';
+import type {
+	DatabaseConfig,
+	DatabaseTargetConfig,
+	ScopeTargetConfig,
+} 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 {
+	BatchOperation,
+	BatchOutcome,
+	CollectionOps,
+	Transaction,
+} from '../../contract/transaction';
+import type { Attachments, DatabaseHandle, StorageAdapter } from '../../contract/adapter';
+import { acquireKey } from '../../crypto/key-provider';
+import { instrument } from '../../diagnostics/dev-log';
+import { raise } from '../../diagnostics/errors';
+import { assertValidAttachmentId } from '../../platform/location';
+import { assertBatchWithinBudget, assertArtifactWithinBudget } from '../../query/budgets';
+import { validateConfig } from '../../schema/validate-config';
+import { resolveScope } from '../../scope/validate';
+import { runMigrations } from './migrations';
+import { createMemoryCollection } from './collection';
+import {
+	collectionMap,
+	dropDatabase,
+	dropScope,
+	existingScopeStore,
+	scopeStoreFor,
+	type MemoryScopeStore,
+} from './store';
+import { throwIfFaulted } from '../faults';
+
+export type MemoryAdapterOptions = {
+	/** Fixed clock, so timestamp assertions are deterministic. */
+	now?: () => number;
+};
+
+function schemaIndex(collections: CollectionSchema[]): Map<string, CollectionSchema> {
+	return new Map(collections.map(collection => [collection.name, collection]));
+}
+
+function cloneCollections(store: MemoryScopeStore): Map<
+	string,
+	Map<
+		string,
+		{
+			id: string;
+			payload: string;
+			createdAt?: number;
+			updatedAt?: number;
+			deletedAt?: number | null;
+		}
+	>
+> {
+	const copy = new Map<string, Map<string, never>>();
+	for (const [name, rows] of store.collections) {
+		copy.set(name, new Map([...rows].map(([id, row]) => [id, { ...row } as never])));
+	}
+	return copy as never;
+}
+
+export function createMemoryAdapter(options: MemoryAdapterOptions = {}): StorageAdapter {
+	const now = options.now ?? (() => Date.now());
+
+	async function open(config: DatabaseConfig): Promise<DatabaseHandle> {
+		validateConfig(config);
+		throwIfFaulted('open');
+
+		const scope = resolveScope(config.scope);
+		const existing = existingScopeStore(config.name, scope.key);
+		if (existing?.deletionState === 'deleting') {
+			// A deletion that was interrupted must never look complete.
+			raise(DiagnosticCodes.SCOPE_DELETED, {
+				message: 'scope deletion was interrupted',
+				detail: { scopeKey: scope.key },
+			});
+		}
+
+		const store = scopeStoreFor(config.name, scope.key);
+		const encryptionRequested = config.encryption?.enabled === true;
+
+		if (store.schemaVersion > 0 && store.encrypted !== encryptionRequested) {
+			raise(DiagnosticCodes.ENCRYPTION_MISMATCH, {
+				message: 'encryption posture does not match the stored database',
+			});
+		}
+		if (encryptionRequested) {
+			// The same acquisition path the on-device adapter uses, so a locked
+			// keychain and a provider returning nothing stay as distinguishable
+			// here as they are on a phone (SC-020b). Released immediately: the
+			// in-memory store has nothing to encrypt with it.
+			const key = await acquireKey(config.encryption!, scope);
+			key.release();
+		}
+		store.encrypted = encryptionRequested;
+		store.backupIncluded = config.backup?.includeInPlatformBackup === true;
+
+		const schemas = schemaIndex(config.collections);
+		for (const collection of config.collections) {
+			collectionMap(store, collection.name);
+		}
+
+		await runMigrations(store, config, now);
+
+		let closed = false;
+		const assertOpen = (): void => {
+			if (closed) {
+				raise(DiagnosticCodes.CLOSED_HANDLE, { message: 'handle is closed' });
+			}
+			if (store.deletionState === 'deleting') {
+				raise(DiagnosticCodes.SCOPE_DELETED, {
+					message: 'scope was deleted beneath this handle',
+					detail: { scopeKey: scope.key },
+				});
+			}
+		};
+
+		/**
+		 * The same isolation the SQLite connection gives: a transaction holds the
+		 * handle until it settles, and work through the handle meanwhile waits
+		 * rather than landing inside the transaction's snapshot and vanishing
+		 * with its rollback. Only what the transaction hands out runs inside it.
+		 */
+		const queue = createTransactionQueue();
+		const queued = <O extends object>(ops: O): O =>
+			Object.fromEntries(
+				Object.entries(ops).map(([key, value]) => [
+					key,
+					typeof value === 'function'
+						? (...args: unknown[]) =>
+								queue.run(() => (value as (...a: unknown[]) => Promise<unknown>)(...args))
+						: value,
+				]),
+			) as O;
+
+		/** Artifact deletions held back until the transaction that caused them commits. */
+		type Deferred = { add(id: string): void };
+
+		/** FR-070 for the memory adapter, with the SQLite adapter's ordering and reporting. */
+		const cascadeFor = (collection: string, id: string, deferred?: Deferred): DeletionOutcome => {
+			const removedArtifacts: string[] = [];
+			for (const reference of [...store.attachments.values()]) {
+				if (reference.owner?.collection !== collection || reference.owner?.id !== id) continue;
+				store.attachments.delete(reference.id);
+				if (deferred) {
+					deferred.add(reference.id);
+				} else {
+					store.artifacts.delete(reference.id);
+				}
+				removedArtifacts.push(reference.id);
+			}
+			return { removedRecords: 0, removedArtifacts, orphanedReferences: [], failedRemovals: [] };
+		};
+
+		const rawCollectionFor = <T extends StorableRecordData>(
+			name: string,
+			deferred?: Deferred,
+		): CollectionOps<T> => {
+			assertOpen();
+			const schema = schemas.get(name);
+			if (!schema) {
+				raise(DiagnosticCodes.CONFIG_INVALID, {
+					message: 'collection is not declared',
+					detail: { collection: name },
+				});
+			}
+			const ops = instrument(
+				name,
+				'memory',
+				createMemoryCollection<T>({ store, schema, now, assertOpen }) as unknown as Record<
+					string,
+					(...args: never[]) => unknown
+				>,
+			) as unknown as CollectionOps<T>;
+			if (config.cascadeAttachments !== true) {
+				return ops;
+			}
+			return {
+				...ops,
+				async delete(id: string) {
+					const outcome = await ops.delete(id);
+					return { ...outcome, cascade: cascadeFor(name, id, deferred) };
+				},
+			};
+		};
+
+		const collectionFor = <T extends StorableRecordData>(name: string): CollectionOps<T> =>
+			queued(rawCollectionFor<T>(name));
+
+		const backupPosture: EffectivePosture = {
+			requested: store.backupIncluded ? 'included' : 'excluded',
+			observed: store.backupIncluded ? 'included' : 'excluded',
+			enforcedBy: 'package',
+		};
+
+		const rawAttachments = (deferred?: Deferred): Attachments => ({
+			async write(input: AttachmentInput): Promise<AttachmentReference> {
+				assertOpen();
+				throwIfFaulted('attachmentWrite');
+				assertValidAttachmentId(input.id);
+				const bytes = Buffer.from(input.content, 'base64');
+				assertArtifactWithinBudget(input.id, bytes.length);
+				const reference: AttachmentReference = {
+					id: input.id,
+					owner: input.owner,
+					contentType: input.contentType,
+					size: bytes.length,
+					createdAt: now(),
+				};
+				store.artifacts.set(input.id, input.content);
+				store.attachments.set(input.id, reference);
+				return reference;
+			},
+			async read(id: string, range?: ByteRange): Promise<string> {
+				assertOpen();
+				// No paths here to escape, but an id the device build would refuse
+				// has to be refused here too, or a consumer's passing tests stop
+				// predicting the device (FR-096).
+				assertValidAttachmentId(id);
+				const content = store.artifacts.get(id);
+				if (content === undefined) {
+					raise(DiagnosticCodes.ATTACHMENT_MISSING, {
+						message: 'artifact is missing',
+						detail: { attachmentId: id },
+					});
+				}
+				if (!range) {
+					return content;
+				}
+				const bytes = Buffer.from(content, 'base64');
+				return bytes.subarray(range.offset, range.offset + range.length).toString('base64');
+			},
+			async availability(id) {
+				assertOpen();
+				const reference = store.attachments.get(id);
+				if (!reference) {
+					return { id, state: 'missing' };
+				}
+				return store.artifacts.has(id)
+					? { id, state: 'available', size: reference.size }
+					: { id, state: 'missing' };
+			},
+			async remove(id: string): Promise<DeletionOutcome> {
+				assertOpen();
+				assertValidAttachmentId(id);
+				if (deferred) {
+					const hadReference = store.attachments.delete(id);
+					if (hadReference) deferred.add(id);
+					return {
+						removedRecords: 0,
+						removedArtifacts: hadReference ? [id] : [],
+						orphanedReferences: [],
+						failedRemovals: [],
+					};
+				}
+				const removed = store.artifacts.delete(id);
+				store.attachments.delete(id);
+				return {
+					removedRecords: 0,
+					removedArtifacts: removed ? [id] : [],
+					orphanedReferences: [],
+					failedRemovals: [],
+				};
+			},
+			async listFor(owner: AttachmentOwner): Promise<AttachmentReference[]> {
+				assertOpen();
+				return [...store.attachments.values()].filter(
+					reference =>
+						reference.owner?.collection === owner.collection && reference.owner?.id === owner.id,
+				);
+			},
+			async reconcile(reconcileOptions): Promise<ReconciliationReport> {
+				assertOpen();
+				const orphanedArtifacts = [...store.artifacts.keys()].filter(
+					id => !store.attachments.has(id),
+				);
+				const danglingReferences = [...store.attachments.keys()].filter(
+					id => !store.artifacts.has(id),
+				);
+				const removedArtifacts: string[] = [];
+				if (reconcileOptions?.removeOrphans) {
+					for (const id of orphanedArtifacts) {
+						store.artifacts.delete(id);
+						removedArtifacts.push(id);
+					}
+				}
+				return { orphanedArtifacts, danglingReferences, removedArtifacts };
+			},
+		});
+		const attachments = queued(rawAttachments());
+
+		/**
+		 * One transaction against the store. Snapshot-and-restore rather than a
+		 * write log: simpler to reason about, and rollback fidelity is what US4
+		 * tests. Runs only inside `exclusive`, so the snapshot never captures,
+		 * nor its restore erases, a write made from outside.
+		 */
+		const runTransaction = async <R>(fn: (tx: Transaction) => Promise<R>): Promise<R> => {
+			const snapshot = cloneCollections(store);
+			const attachmentSnapshot = new Map(store.attachments);
+			const pendingArtifactRemovals: string[] = [];
+			const deferred: Deferred = { add: id => pendingArtifactRemovals.push(id) };
+			let settled = false;
+
+			const assertLive = (): void => {
+				if (settled) {
+					raise(DiagnosticCodes.TRANSACTION_STATE, {
+						message: 'transaction already settled',
+					});
+				}
+			};
+			const rollback = (): void => {
+				store.collections = snapshot as never;
+				store.attachments = attachmentSnapshot;
+			};
+
+			// A collection taken from the transaction keeps refusing once it
+			// settles, as the SQLite executor does; otherwise a write after abort
+			// would land straight in the store.
+			const live = <O extends object>(ops: O): O =>
+				Object.fromEntries(
+					Object.entries(ops).map(([key, value]) => [
+						key,
+						typeof value === 'function'
+							? // Async so a refusal rejects, as the SQLite executor's does.
+								async (...args: unknown[]) => {
+									assertLive();
+									return (value as (...a: unknown[]) => unknown)(...args);
+								}
+							: value,
+					]),
+				) as O;
+
+			const tx: Transaction = {
+				collection: <T extends StorableRecordData>(name: string) => {
+					assertLive();
+					return live(rawCollectionFor<T>(name, deferred));
+				},
+				attachments: () => {
+					assertLive();
+					return rawAttachments(deferred);
+				},
+				async abort() {
+					assertLive();
+					settled = true;
+					rollback();
+				},
+			};
+
+			try {
+				const result = await fn(tx);
+				if (!settled) {
+					throwIfFaulted('commit');
+					settled = true;
+					// Committed: the artifacts whose references went may go too.
+					for (const id of pendingArtifactRemovals) {
+						store.artifacts.delete(id);
+					}
+				}
+				return result;
+			} catch (error) {
+				if (!settled) {
+					settled = true;
+					rollback();
+				}
+				throw error;
+			}
+		};
+
+		const handle: DatabaseHandle = {
+			scopeKey: scope.key,
+			schemaVersion: store.schemaVersion,
+			backupPosture,
+			isEncrypted: store.encrypted,
+			collection: collectionFor,
+
+			transaction<R>(fn: (tx: Transaction) => Promise<R>): Promise<R> {
+				assertOpen();
+				return queue.runTransaction(() => runTransaction(fn));
+			},
+
+			batch(operations: BatchOperation[]): Promise<BatchOutcome> {
+				assertOpen();
+				assertBatchWithinBudget(operations.length);
+				return queue.runTransaction(() =>
+					runTransaction(async (tx: Transaction) => {
+						const outcomes = [];
+						for (const operation of operations) {
+							const ops = tx.collection(operation.collection);
+							switch (operation.type) {
+								case 'insert':
+									outcomes.push(await ops.insert(operation.record));
+									break;
+								case 'update':
+									outcomes.push(await ops.update(operation.id, { data: operation.data }));
+									break;
+								case 'upsert':
+									outcomes.push(await ops.upsert(operation.record));
+									break;
+								case 'delete':
+									outcomes.push(await ops.delete(operation.id));
+									break;
+								case 'softDelete':
+									outcomes.push(await ops.softDelete(operation.id));
+									break;
+								default:
+									break;
+							}
+						}
+						return { applied: outcomes.length, outcomes };
+					}),
+				);
+			},
+
+			attachments: () => attachments,
+
+			async explain(collection: string, _query?: Query): Promise<IndexCoverageReport> {
+				assertOpen();
+				// Documented divergence: index declarations are validated but
+				// have no performance effect in memory (FR-096).
+				return {
+					collection,
+					usesIndex: false,
+					detail: 'memory adapter does not use indexes',
+				};
+			},
+
+			async close(): Promise<void> {
+				closed = true;
+			},
+		};
+
+		return handle;
+	}
+
+	/**
+	 * Backs both `deleteScopeData` and `resetScope`. They differ in intent and
+	 * in what they let a consumer conclude, not in what they do to the store —
+	 * keeping them as separate exported names is what makes the destructive one
+	 * impossible to call by accident.
+	 */
+	async function removeScope(config: ScopeTargetConfig): Promise<DeletionOutcome> {
+		const scope = resolveScope(config.scope);
+		const store = existingScopeStore(config.name, scope.key);
+		if (!store) {
+			// Deleting nothing is success, not an error (FR-062).
+			return {
+				scopeKey: scope.key,
+				removedRecords: 0,
+				removedArtifacts: [],
+				orphanedReferences: [],
+				failedRemovals: [],
+			};
+		}
+		store.deletionState = 'deleting';
+		let removedRecords = 0;
+		for (const rows of store.collections.values()) {
+			removedRecords += rows.size;
+		}
+		const removedArtifacts = [...store.artifacts.keys()];
+		dropScope(config.name, scope.key);
+		return {
+			scopeKey: scope.key,
+			removedRecords,
+			removedArtifacts,
+			orphanedReferences: [],
+			failedRemovals: [],
+		};
+	}
+
+	return {
+		name: 'memory',
+		open,
+		deleteScopeData: config => removeScope(config),
+		resetScope: config => removeScope(config),
+		async deleteDatabase(config: DatabaseTargetConfig): Promise<DeletionOutcome> {
+			dropDatabase(config.name);
+			return {
+				removedRecords: 0,
+				removedArtifacts: [],
+				orphanedReferences: [],
+				failedRemovals: [],
+			};
+		},
+	};
+}
+
+export { Budgets } from '../../contract/config';
+export { activeFaults } from '../faults';