@chipmobilesdk/rn-local-db 0.1.0

package/src/sqlite/adapter.ts

@@ -0,0 +1,26 @@
+/**
+ * The on-device adapter.
+ *
+ * Deliberately a seam rather than an implementation. Everything it composes
+ * lives in `adapter/`, `migration/`, `artifacts/`, and this directory, so the
+ * in-memory adapter can be held to the same contract by the same conformance
+ * suite (FR-092) without either one being the "real" version the other
+ * approximates.
+ *
+ * Reached only through the lazy require in `adapter/index.ts`, so a consumer
+ * that runs the in-memory adapter in tests never loads the native peers.
+ */
+
+import type { StorageAdapter } from '../contract/adapter';
+import { deleteDatabase, deleteScopeData, resetScope } from '../adapter/deletion';
+import { openSqliteDatabase, type OpenOptions } from '../adapter/lifecycle';
+
+export function createSqliteAdapter(options: OpenOptions = {}): StorageAdapter {
+	return {
+		name: 'sqlite',
+		open: config => openSqliteDatabase(config, options),
+		deleteScopeData,
+		deleteDatabase,
+		resetScope,
+	};
+}

package/src/sqlite/batch.ts

@@ -0,0 +1,232 @@
+/**
+ * Batch writes: many operations, one atomic unit, one outcome (FR-028).
+ *
+ * Every statement is resolved before any of them runs. That ordering is the
+ * point: a conflict or a missing record is reported with the database still
+ * untouched, so "the batch failed" and "the batch was partly applied" are
+ * never the same event. The statements then go to the engine's own
+ * `executeBatch`, which wraps them in a single transaction — the batch is
+ * atomic because SQLite makes it atomic, not because this file is careful.
+ *
+ * Resolution keeps an overlay of what earlier operations in the same batch
+ * did, so `insert` followed by `update` on the same id resolves against the
+ * batch's own effect rather than against the database as it was before it.
+ */
+
+import { DiagnosticCodes } from '../contract/errors';
+import type { WriteOutcome } from '../contract/record';
+import type { CollectionSchema } from '../contract/schema';
+import type { BatchOperation, BatchOutcome } from '../contract/transaction';
+import { raise } from '../diagnostics/errors';
+import { assertBatchWithinBudget, assertRecordWithinBudget } from '../query/budgets';
+import { collectionTable, hasSoftDelete } from '../schema/declare';
+import type { Connection } from './connection';
+import type { SqlValue } from './native';
+import { insertColumns, updateAssignments } from './row-codec';
+
+export type BatchContext = {
+	connection: Connection;
+	/** Raises CONFIG_INVALID for a collection the schema never declared. */
+	schemaFor(name: string): CollectionSchema;
+	now(): number;
+};
+
+type Command = [string, SqlValue[]];
+
+function quoted(schema: CollectionSchema): string {
+	return `"${collectionTable(schema.name)}"`;
+}
+
+function insertCommand(
+	schema: CollectionSchema,
+	id: string,
+	data: Parameters<typeof insertColumns>[2],
+	now: number,
+): Command {
+	const { columns, values } = insertColumns(schema, id, data, now);
+	return [
+		`INSERT INTO ${quoted(schema)} (${columns
+			.map(name => `"${name}"`)
+			.join(', ')}) VALUES (${columns.map(() => '?').join(', ')})`,
+		values,
+	];
+}
+
+function updateCommand(
+	schema: CollectionSchema,
+	id: string,
+	data: Parameters<typeof updateAssignments>[1],
+	now: number,
+	restore: boolean,
+): Command {
+	const { columns, values } = updateAssignments(schema, data, now);
+	const assignments = columns.map(name => `"${name}" = ?`);
+	if (restore && hasSoftDelete(schema)) {
+		assignments.push('deleted_at = NULL');
+	}
+	return [`UPDATE ${quoted(schema)} SET ${assignments.join(', ')} WHERE id = ?`, [...values, id]];
+}
+
+type Resolver = {
+	schema: CollectionSchema;
+	now: number;
+	/** Existence as this batch has left it so far, not as the database was. */
+	exists(id: string): Promise<boolean>;
+	stage(id: string, present: boolean): void;
+};
+
+type Resolved = { command: Command; outcome: WriteOutcome };
+
+function conflict(schema: CollectionSchema, id: string): never {
+	raise(DiagnosticCodes.RECORD_CONFLICT, {
+		message: 'record already exists',
+		detail: { collection: schema.name, recordId: id },
+	});
+}
+
+function missing(schema: CollectionSchema, id: string): never {
+	raise(DiagnosticCodes.RECORD_NOT_FOUND, {
+		message: 'record not found',
+		detail: { collection: schema.name, recordId: id },
+	});
+}
+
+async function resolveInsert(
+	resolver: Resolver,
+	operation: Extract<BatchOperation, { type: 'insert' }>,
+): Promise<Resolved> {
+	const { schema, now } = resolver;
+	assertRecordWithinBudget(schema.name, operation.record.data);
+	if (await resolver.exists(operation.record.id)) {
+		conflict(schema, operation.record.id);
+	}
+	resolver.stage(operation.record.id, true);
+	return {
+		command: insertCommand(schema, operation.record.id, operation.record.data, now),
+		outcome: { operation: 'created', id: operation.record.id },
+	};
+}
+
+async function resolveUpdate(
+	resolver: Resolver,
+	operation: Extract<BatchOperation, { type: 'update' }>,
+): Promise<Resolved> {
+	const { schema, now } = resolver;
+	assertRecordWithinBudget(schema.name, operation.data);
+	if (!(await resolver.exists(operation.id))) {
+		missing(schema, operation.id);
+	}
+	return {
+		command: updateCommand(schema, operation.id, operation.data, now, false),
+		outcome: { operation: 'updated', id: operation.id },
+	};
+}
+
+async function resolveUpsert(
+	resolver: Resolver,
+	operation: Extract<BatchOperation, { type: 'upsert' }>,
+): Promise<Resolved> {
+	const { schema, now } = resolver;
+	assertRecordWithinBudget(schema.name, operation.record.data);
+	const present = await resolver.exists(operation.record.id);
+	resolver.stage(operation.record.id, true);
+	return {
+		command: present
+			? updateCommand(schema, operation.record.id, operation.record.data, now, true)
+			: insertCommand(schema, operation.record.id, operation.record.data, now),
+		outcome: { operation: present ? 'updated' : 'created', id: operation.record.id },
+	};
+}
+
+async function resolveDelete(
+	resolver: Resolver,
+	operation: Extract<BatchOperation, { type: 'delete' }>,
+): Promise<Resolved> {
+	const { schema } = resolver;
+	if (!(await resolver.exists(operation.id))) {
+		missing(schema, operation.id);
+	}
+	resolver.stage(operation.id, false);
+	return {
+		command: [`DELETE FROM ${quoted(schema)} WHERE id = ?`, [operation.id]],
+		outcome: { operation: 'deleted', id: operation.id },
+	};
+}
+
+async function resolveSoftDelete(
+	resolver: Resolver,
+	operation: Extract<BatchOperation, { type: 'softDelete' }>,
+): Promise<Resolved> {
+	const { schema, now } = resolver;
+	if (!hasSoftDelete(schema)) {
+		raise(DiagnosticCodes.CONFIG_INVALID, {
+			message: 'collection does not declare soft delete',
+			detail: { collection: schema.name },
+		});
+	}
+	if (!(await resolver.exists(operation.id))) {
+		missing(schema, operation.id);
+	}
+	resolver.stage(operation.id, false);
+	return {
+		command: [`UPDATE ${quoted(schema)} SET deleted_at = ? WHERE id = ?`, [now, operation.id]],
+		outcome: { operation: 'deleted', id: operation.id },
+	};
+}
+
+function resolveOperation(resolver: Resolver, operation: BatchOperation): Promise<Resolved> {
+	switch (operation.type) {
+		case 'insert':
+			return resolveInsert(resolver, operation);
+		case 'update':
+			return resolveUpdate(resolver, operation);
+		case 'upsert':
+			return resolveUpsert(resolver, operation);
+		case 'delete':
+			return resolveDelete(resolver, operation);
+		case 'softDelete':
+			return resolveSoftDelete(resolver, operation);
+		default:
+			raise(DiagnosticCodes.CONFIG_INVALID, { message: 'unsupported batch operation' });
+	}
+}
+
+export async function runBatch(
+	context: BatchContext,
+	operations: BatchOperation[],
+): Promise<BatchOutcome> {
+	assertBatchWithinBudget(operations.length);
+
+	const commands: Command[] = [];
+	const outcomes: WriteOutcome[] = [];
+	const overlay = new Map<string, boolean>();
+
+	for (const operation of operations) {
+		const schema = context.schemaFor(operation.collection);
+		const resolver: Resolver = {
+			schema,
+			now: context.now(),
+			async exists(id) {
+				const staged = overlay.get(`${schema.name}:${id}`);
+				if (staged !== undefined) {
+					return staged;
+				}
+				const result = await context.connection.execute(
+					`SELECT 1 AS present FROM ${quoted(schema)} WHERE id = ? AND deleted_at IS NULL`,
+					[id],
+				);
+				return result.rows.length > 0;
+			},
+			stage(id, present) {
+				overlay.set(`${schema.name}:${id}`, present);
+			},
+		};
+
+		const resolved = await resolveOperation(resolver, operation);
+		commands.push(resolved.command);
+		outcomes.push(resolved.outcome);
+	}
+
+	await context.connection.executeBatch(commands);
+	return { applied: outcomes.length, outcomes };
+}

package/src/sqlite/catalog.ts

@@ -0,0 +1,108 @@
+/**
+ * The catalog: one registry per logical database, listing the scopes that
+ * exist.
+ *
+ * This is the only structure that spans scopes, so it is deliberately the
+ * smallest thing that answers the questions the package must answer without
+ * opening every scope file. It holds a digest, timestamps, and two posture
+ * flags — **no raw scope components** (FR-014), so a device with full disk
+ * access cannot mine it for identities or tenant names even though the
+ * catalog itself is never encrypted.
+ *
+ * The `deleting` flag is the load-bearing part. It is written before a scope
+ * deletion begins and cleared last, so a crash at any point leaves the
+ * interruption visible on the next open. Clearing it first would make an
+ * interrupted deletion look complete — the exact failure FR-063 exists to
+ * prevent.
+ */
+
+import type { ScopeDeletionState } from '../contract/scope';
+import type { Connection } from './connection';
+import { num, text } from './values';
+
+export type CatalogEntry = {
+	scopeKey: string;
+	createdAt: number;
+	deletionState: ScopeDeletionState;
+	backupPosture: 'excluded' | 'included';
+	encrypted: boolean;
+};
+
+const CREATE_SCOPES = `CREATE TABLE IF NOT EXISTS scopes (
+  scope_key      TEXT PRIMARY KEY,
+  created_at     INTEGER NOT NULL,
+  deletion_state TEXT NOT NULL,
+  backup_posture TEXT NOT NULL,
+  encrypted      INTEGER NOT NULL
+)`;
+
+export async function ensureCatalog(connection: Connection): Promise<void> {
+	await connection.execute(CREATE_SCOPES);
+}
+
+export async function readEntry(
+	connection: Connection,
+	scopeKey: string,
+): Promise<CatalogEntry | null> {
+	const result = await connection.execute(
+		'SELECT scope_key, created_at, deletion_state, backup_posture, encrypted FROM scopes WHERE scope_key = ?',
+		[scopeKey],
+	);
+	const row = result.rows[0];
+	if (!row) {
+		return null;
+	}
+	return {
+		scopeKey: text(row.scope_key),
+		createdAt: num(row.created_at),
+		deletionState: text(row.deletion_state) as ScopeDeletionState,
+		backupPosture: text(row.backup_posture) as 'excluded' | 'included',
+		encrypted: num(row.encrypted) === 1,
+	};
+}
+
+export async function listEntries(connection: Connection): Promise<CatalogEntry[]> {
+	const result = await connection.execute(
+		'SELECT scope_key, created_at, deletion_state, backup_posture, encrypted FROM scopes',
+	);
+	return result.rows.map(row => ({
+		scopeKey: text(row.scope_key),
+		createdAt: num(row.created_at),
+		deletionState: text(row.deletion_state) as ScopeDeletionState,
+		backupPosture: text(row.backup_posture) as 'excluded' | 'included',
+		encrypted: num(row.encrypted) === 1,
+	}));
+}
+
+export async function registerScope(
+	connection: Connection,
+	entry: CatalogEntry,
+): Promise<void> {
+	await connection.execute(
+		`INSERT INTO scopes (scope_key, created_at, deletion_state, backup_posture, encrypted)
+		 VALUES (?, ?, ?, ?, ?)
+		 ON CONFLICT(scope_key) DO UPDATE SET
+		   deletion_state = excluded.deletion_state,
+		   backup_posture = excluded.backup_posture,
+		   encrypted = excluded.encrypted`,
+		[
+			entry.scopeKey,
+			entry.createdAt,
+			entry.deletionState,
+			entry.backupPosture,
+			entry.encrypted ? 1 : 0,
+		],
+	);
+}
+
+export async function markDeleting(connection: Connection, scopeKey: string): Promise<void> {
+	await connection.execute('UPDATE scopes SET deletion_state = ? WHERE scope_key = ?', [
+		'deleting',
+		scopeKey,
+	]);
+}
+
+/** Cleared last, on purpose. See the note at the top of this file. */
+export async function clearScope(connection: Connection, scopeKey: string): Promise<void> {
+	await connection.execute('DELETE FROM scopes WHERE scope_key = ?', [scopeKey]);
+}

package/src/sqlite/connection.ts

@@ -0,0 +1,205 @@
+/**
+ * One connection per database file.
+ *
+ * Two things about this file carry design weight:
+ *
+ * **Scope isolation is the file boundary.** A connection is opened against
+ * one scope's `data.db`, whose directory is named by the scope digest and
+ * never by the components (FR-014). No SQL this package could generate — and
+ * none a future bug could generate — reaches another scope's rows, because
+ * they are in a file this connection never opened (research.md R2).
+ *
+ * **A transaction owns the connection while it runs.** `execute` routes to
+ * the in-flight transaction rather than around it. That is what makes an
+ * attachment reference written during a transaction roll back with it
+ * (FR-072); routing around would leave the reference behind and the artifact
+ * orphaned with no record of why.
+ */
+
+import { DiagnosticCodes } from '../contract/errors';
+import { raise } from '../diagnostics/errors';
+import { raiseNative } from '../diagnostics/map-native';
+import { fileSystem } from '../platform/fs';
+import {
+	engine,
+	type ExecuteResult,
+	type NativeDatabase,
+	type NativeTransaction,
+	type SqlValue,
+} from './native';
+
+export type Executor = {
+	execute(sql: string, params?: SqlValue[]): Promise<ExecuteResult>;
+};
+
+/**
+ * The executor a transaction body runs against, plus the one control it
+ * needs. `rollback` is handed to the body rather than returned from
+ * `transaction`, so an explicit abort cannot outlive the transaction it
+ * belongs to.
+ */
+export type TransactionExecutor = Executor & {
+	rollback(): Promise<void>;
+};
+
+export type Connection = Executor & {
+	readonly path: string;
+	readonly encrypted: boolean;
+	transaction<R>(fn: (tx: TransactionExecutor) => Promise<R>): Promise<R>;
+	executeBatch(commands: [string, SqlValue[]?][]): Promise<void>;
+	/** Full-database check, for the diagnostics surface. Never run at open. */
+	integrityCheck(): Promise<boolean>;
+	close(): Promise<void>;
+};
+
+export type OpenConnectionOptions = {
+	/** Absolute path to the database file, already inside the managed area. */
+	path: string;
+	encryptionKey?: string;
+};
+
+function splitPath(path: string): { location: string; name: string } {
+	const index = path.lastIndexOf('/');
+	return index === -1
+		? { location: '', name: path }
+		: { location: path.slice(0, index), name: path.slice(index + 1) };
+}
+
+export async function openConnection(options: OpenConnectionOptions): Promise<Connection> {
+	const { location, name } = splitPath(options.path);
+	const encrypted = options.encryptionKey !== undefined;
+
+	try {
+		await fileSystem().mkdir(location);
+	} catch (error) {
+		raiseNative(error, { operation: 'open' });
+	}
+
+	let database: NativeDatabase;
+	try {
+		database = engine().open({
+			name,
+			location,
+			// Passing the key only when encryption is on keeps an unencrypted
+			// database from being opened as an encrypted one with an empty key,
+			// which SQLCipher accepts and which would produce a file neither
+			// posture can reopen.
+			...(encrypted ? { encryptionKey: options.encryptionKey } : {}),
+		});
+	} catch (error) {
+		raiseNative(error, { operation: 'open', encrypted });
+	}
+
+	let closed = false;
+	let active: NativeTransaction | null = null;
+
+	const assertOpen = (): void => {
+		if (closed) {
+			raise(DiagnosticCodes.CLOSED_HANDLE, { message: 'connection is closed' });
+		}
+	};
+
+	const connection: Connection = {
+		path: options.path,
+		encrypted,
+
+		async execute(sql, params = []) {
+			assertOpen();
+			try {
+				// The in-flight transaction, when there is one. See the note at
+				// the top of this file.
+				return await (active ?? database).execute(sql, params);
+			} catch (error) {
+				raiseNative(error, {
+					operation: /^\s*select|^\s*pragma|^\s*explain/i.test(sql) ? 'read' : 'write',
+					encrypted,
+				});
+			}
+		},
+
+		async transaction(fn) {
+			assertOpen();
+			if (active) {
+				// Nested transactions would need savepoints and would let a
+				// partial rollback look like a full one.
+				raise(DiagnosticCodes.TRANSACTION_STATE, {
+					message: 'a transaction is already in flight on this connection',
+				});
+			}
+			try {
+				return await database.transaction(async tx => {
+					active = tx;
+					try {
+						return await fn({
+							execute: (sql, params = []) => tx.execute(sql, params),
+							rollback: async () => {
+								await tx.rollback();
+								// Cleared immediately: anything that runs after an
+								// abort must not be routed into a settled
+								// transaction and silently discarded.
+								active = null;
+							},
+						});
+					} finally {
+						active = null;
+					}
+				});
+			} catch (error) {
+				raiseNative(error, { operation: 'transaction', encrypted });
+			}
+		},
+
+		async executeBatch(commands) {
+			assertOpen();
+			try {
+				await database.executeBatch(commands);
+			} catch (error) {
+				raiseNative(error, { operation: 'write', encrypted });
+			}
+		},
+
+		async integrityCheck() {
+			assertOpen();
+			const result = await connection.execute('PRAGMA quick_check(1)');
+			const first = result.rows[0];
+			return first ? Object.values(first)[0] === 'ok' : false;
+		},
+
+		async close() {
+			if (closed) {
+				return;
+			}
+			closed = true;
+			try {
+				await database.close();
+			} catch {
+				// A close that fails leaves nothing for a caller to do, and
+				// reporting it would turn an orderly sign-out into an error.
+			}
+		},
+	};
+
+	// Write-ahead logging so a reader is not blocked by the writer — FR-045's
+	// "reads proceed while a write is in flight" is this pragma plus op-sqlite's
+	// single-writer serialization, not a lock this package maintains.
+	await connection.execute('PRAGMA journal_mode = WAL');
+	await connection.execute('PRAGMA foreign_keys = ON');
+	// Durability over speed: a half-written record after a crash is exactly
+	// what FR-039 promises never happens.
+	await connection.execute('PRAGMA synchronous = FULL');
+
+	return connection;
+}
+
+/**
+ * Confirm a freshly opened database is readable.
+ *
+ * Deliberately not `PRAGMA integrity_check`: that walks the whole file and
+ * would put open time far past the 150-millisecond budget on a large scope.
+ * One trivial read is enough to surface the failures that matter at open —
+ * a wrong key, a truncated file, a malformed header — because all three fail
+ * it, and the error mapping keeps them distinguishable (FR-076, FR-078).
+ */
+export async function assertReadable(connection: Connection): Promise<void> {
+	await connection.execute('SELECT count(*) AS n FROM sqlite_master');
+}

package/src/sqlite/index-coverage.ts

@@ -0,0 +1,53 @@
+/**
+ * "Is this query covered by an index?", answered by the engine rather than by
+ * inspection of the declarations (FR-037).
+ *
+ * Reading the schema would answer what the developer intended; `EXPLAIN QUERY
+ * PLAN` answers what SQLite will actually do, and the two diverge exactly
+ * where it matters — a filter on an indexed field that the planner declines
+ * because of a type mismatch or a leading wildcard still reports as "indexed"
+ * if you only read declarations.
+ *
+ * Exposed as a development-mode diagnostic. It runs an extra statement, so an
+ * app calling it on every list would pay for it.
+ */
+
+import type { IndexCoverageReport, Query, SortKey } from '../contract/query';
+import type { CollectionSchema } from '../contract/schema';
+import { collectionTable } from '../schema/declare';
+import type { Executor } from './connection';
+import { buildFilter, buildOrderBy } from './sql-builder';
+
+const SCAN = /\bSCAN\b/i;
+const USING_INDEX = /USING\s+(COVERING\s+)?INDEX\s+"?([A-Za-z0-9_]+)"?/i;
+
+export async function explainQuery(
+	executor: Executor,
+	schema: CollectionSchema,
+	query: Query | undefined,
+	sort: SortKey[],
+): Promise<IndexCoverageReport> {
+	const filter = buildFilter(query?.filter);
+	const table = collectionTable(schema.name);
+	const sql = `EXPLAIN QUERY PLAN SELECT id FROM "${table}" WHERE ${filter.sql} ORDER BY ${buildOrderBy(
+		sort,
+	)}`;
+
+	const result = await executor.execute(sql, filter.params);
+	const detail = result.rows
+		.map(row => String(row.detail ?? row.DETAIL ?? ''))
+		.filter(Boolean)
+		.join('; ');
+
+	const match = USING_INDEX.exec(detail);
+	return {
+		collection: schema.name,
+		usesIndex: match !== null,
+		indexName: match?.[2],
+		detail:
+			detail ||
+			(SCAN.test(detail)
+				? 'full table scan'
+				: 'the engine returned no plan for this query'),
+	};
+}