@chipmobilesdk/rn-local-db 0.3.0 → 0.4.0

package/src/adapter/handle.ts

@@ -0,0 +1,311 @@
+/**
+ * The handle an open returns: collections, transactions, batches and
+ * attachments over one connection, bound to one scope.
+ *
+ * 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).
+ */
+
+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 {
+	listReferencesFor,
+	readArtifact,
+	removeArtifact,
+	writeArtifact,
+	type ArtifactContext,
+} from '../artifacts/store';
+import { deriveArtifactKey } from '../crypto/derive';
+import type { KeyHandle } from '../crypto/key-provider';
+import { raise } from '../diagnostics/errors';
+import { instrument } from '../diagnostics/dev-log';
+import { throwIfFaulted } from '../diagnostics/faults';
+import type { StorageLayout } from '../platform/location';
+import { withStableTiebreaker } from '../query/sort';
+import { runBatch } from '../sqlite/batch';
+import type { Connection, Executor } from '../sqlite/connection';
+import { explainQuery } from '../sqlite/index-coverage';
+import { runInTransaction } from '../sqlite/transactions';
+import { releaseHandleSlot } from './budgets';
+import { createSqlCollection } from './collection';
+import { isScopeInvalidated, registerOpenHandle } from './deletion';
+import { createTransaction } from './transaction';
+
+export 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;
+}
+
+export type HandleContext = {
+	config: DatabaseConfig;
+	connection: Connection;
+	key: KeyHandle | null;
+	layout: StorageLayout;
+	now(): number;
+	schemaVersion: number;
+	schemas: ReadonlyMap<string, CollectionSchema>;
+	scope: ResolvedScope;
+	posture: EffectivePosture;
+};
+
+export function buildHandle(context: HandleContext): DatabaseHandle {
+	const { config, connection, layout, scope, schemas } = context;
+	let closed = false;
+	// Set when a deletion took the connection away rather than the app closing it.
+	let revoked = false;
+
+	const releaseNative = async (): Promise<void> => {
+		// 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();
+	};
+
+	const unregister = registerOpenHandle(config.name, scope.key, async () => {
+		if (closed) {
+			return;
+		}
+		closed = true;
+		revoked = true;
+		await releaseNative();
+	});
+
+	const assertUsable = (): void => {
+		if (closed && !revoked) {
+			raise(DiagnosticCodes.CLOSED_HANDLE, { message: 'handle is closed' });
+		}
+		if (revoked || 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,
+			}),
+		);
+	};
+
+	/**
+	 * 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;
+			unregister();
+			await releaseNative();
+		},
+	};
+
+	return handle;
+}

package/src/adapter/lifecycle.ts

@@ -14,127 +14,36 @@
  *    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.
+ * The handle itself is built in `handle.ts`.
  */
 
-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 { DatabaseHandle } from '../contract/adapter';
 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 { assertReadable, openConnection, type Connection } from '../sqlite/connection';
 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';
+import { clearScopeInvalidation } from './deletion';
+import { buildHandle, schemaFor } from './handle';
+import { syncSchema } from './schema-sync';
 
 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;
@@ -233,10 +142,8 @@ export async function openSqliteDatabase(
 		await assertReadable(connection);
 
 		const schemas = indexSchemas(config.collections);
-		for (const schema of config.collections) {
-			await ensureCollection(connection, schema);
-		}
-		await ensureAttachmentTable(connection);
+		// No DDL at all when the declaration is the one already applied (LDB-07).
+		const schema = await syncSchema(connection, config);
 
 		const scopeConnection = connection;
 		const schemaVersion = await runMigrations({
@@ -245,7 +152,9 @@ export async function openSqliteDatabase(
 			schemaFor: name => schemaFor(schemas, name),
 			now,
 			closeOnFailure: releaseConnection,
+			ledgerReady: schema.unchanged,
 		});
+		await schema.record();
 
 		await registerScope(catalog, {
 			scopeKey: scope.key,
@@ -278,240 +187,3 @@ export async function openSqliteDatabase(
 		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;
-}