@chipmobilesdk/rn-local-db 0.1.0

package/src/artifacts/cascade.ts

@@ -0,0 +1,78 @@
+/**
+ * Cascading artifact removal.
+ *
+ * The package deletes the files, because the Q2 clarification made it the
+ * owner of them (FR-073c). That is the single riskiest thing this package
+ * does — POL-011(b)'s media-and-files row exists for it — so two rules hold
+ * without exception: every path goes through the boundary guard in
+ * `paths.ts`, and the outcome reports what was removed **and what could not
+ * be**, never a bare success (FR-071).
+ *
+ * A failed removal is reported rather than retried or swallowed. A file the
+ * package could not delete is still on disk holding the user's data, and an
+ * app that told them "deleted" would have said something untrue.
+ */
+
+import type { AttachmentOwner, DeletionOutcome } from '../contract/attachment';
+import { removeIfPresent } from '../platform/fs';
+import type { Executor } from '../sqlite/connection';
+import { artifactPath } from './paths';
+import {
+	deleteReference,
+	listReferences,
+	listReferencesFor,
+	type ArtifactContext,
+} from './store';
+
+async function removeAll(
+	context: ArtifactContext,
+	executor: Executor,
+	ids: string[],
+): Promise<DeletionOutcome> {
+	const removedArtifacts: string[] = [];
+	const failedRemovals: string[] = [];
+
+	for (const id of ids) {
+		// A file that was already gone counts as removed: the end state the
+		// caller asked for is the end state they got.
+		await removeIfPresent(artifactPath(context.layout, context.scopeKey, id));
+		removedArtifacts.push(id);
+		if (!(await deleteReference(executor, id))) {
+			failedRemovals.push(id);
+		}
+	}
+
+	return {
+		removedRecords: 0,
+		removedArtifacts,
+		orphanedReferences: [],
+		failedRemovals,
+	};
+}
+
+/** Everything belonging to one record, for the FR-070 cascade. */
+export async function cascadeForOwner(
+	context: ArtifactContext,
+	executor: Executor,
+	owner: AttachmentOwner,
+): Promise<DeletionOutcome> {
+	const references = await listReferencesFor(executor, owner);
+	return removeAll(
+		context,
+		executor,
+		references.map(reference => reference.id),
+	);
+}
+
+/** Everything in the scope, for scope deletion. */
+export async function cascadeAll(
+	context: ArtifactContext,
+	executor: Executor,
+): Promise<DeletionOutcome> {
+	const references = await listReferences(executor);
+	return removeAll(
+		context,
+		executor,
+		references.map(reference => reference.id),
+	);
+}

package/src/artifacts/paths.ts

@@ -0,0 +1,29 @@
+/**
+ * Every artifact path, resolved through one guard.
+ *
+ * POL-011(b) flags media-and-files as a risk precisely because this package
+ * deletes files from disk on cascade. The mitigation is structural rather
+ * than procedural: no code in `artifacts/` builds a path by string
+ * concatenation, and the one function that turns an attachment id into a path
+ * refuses anything escaping the managed root (FR-073, FR-073f).
+ *
+ * That is what makes SC-013a's filesystem tracing pass reliably rather than
+ * usually — there is no second path to audit.
+ */
+
+import { assertWithinManagedArea, type StorageLayout } from '../platform/location';
+
+export function artifactsDirectory(layout: StorageLayout, scopeKey: string): string {
+	return assertWithinManagedArea(layout, layout.scopeArtifactsPath(scopeKey));
+}
+
+export function artifactPath(
+	layout: StorageLayout,
+	scopeKey: string,
+	attachmentId: string,
+): string {
+	// `layout.artifactPath` already rejects an id that is not a safe single
+	// path segment; the guard then re-checks the assembled result, so a change
+	// to either one alone cannot open a hole.
+	return assertWithinManagedArea(layout, layout.artifactPath(scopeKey, attachmentId));
+}

package/src/artifacts/reconcile.ts

@@ -0,0 +1,63 @@
+/**
+ * Reconciliation: the two ways the database and the disk can disagree.
+ *
+ * An **orphaned artifact** is a file with no reference — left by a rolled-back
+ * transaction, or by a crash between the write and the insert. A **dangling
+ * reference** is the reverse: a row pointing at a file the operating system
+ * reclaimed, or the user deleted through a file manager.
+ *
+ * App-triggered only (FR-073d). A background sweep would run during a user's
+ * session without their knowledge, delete files it believes are orphans, and
+ * have no way to distinguish "orphan" from "written by a transaction that has
+ * not committed yet". Handing the trigger to the app makes that an explicit
+ * decision at a moment the app knows is quiet.
+ */
+
+import type { ReconciliationReport } from '../contract/attachment';
+import { fileSystem, removeIfPresent } from '../platform/fs';
+import { byteOrder } from '../query/compare';
+import type { Executor } from '../sqlite/connection';
+import { artifactPath, artifactsDirectory } from './paths';
+import { listReferences, type ArtifactContext } from './store';
+
+export type ReconcileOptions = {
+	/** Off by default: deleting a user's file is never an implied yes. */
+	removeOrphans?: boolean;
+};
+
+async function filesOnDisk(context: ArtifactContext): Promise<string[]> {
+	try {
+		return await fileSystem().readdir(artifactsDirectory(context.layout, context.scopeKey));
+	} catch {
+		// No directory means no artifacts, which is a valid answer rather than
+		// a failure — a scope that never wrote one never created it.
+		return [];
+	}
+}
+
+export async function reconcileArtifacts(
+	context: ArtifactContext,
+	executor: Executor,
+	options: ReconcileOptions = {},
+): Promise<ReconciliationReport> {
+	const references = await listReferences(executor);
+	const referenced = new Set(references.map(reference => reference.id));
+	const present = new Set(await filesOnDisk(context));
+
+	const orphanedArtifacts = [...present].filter(id => !referenced.has(id)).sort(byteOrder);
+	const danglingReferences = references
+		.filter(reference => !present.has(reference.id))
+		.map(reference => reference.id)
+		.sort(byteOrder);
+
+	const removedArtifacts: string[] = [];
+	if (options.removeOrphans) {
+		for (const id of orphanedArtifacts) {
+			if (await removeIfPresent(artifactPath(context.layout, context.scopeKey, id))) {
+				removedArtifacts.push(id);
+			}
+		}
+	}
+
+	return { orphanedArtifacts, danglingReferences, removedArtifacts };
+}

package/src/artifacts/store.ts

@@ -0,0 +1,323 @@
+/**
+ * Artifacts: the file on disk and the reference to it.
+ *
+ * The reference lives in the scope's own database, so a reference created
+ * inside a transaction rolls back with it (FR-072) — no bookkeeping required,
+ * because the connection routes through the transaction in flight.
+ *
+ * The file does not roll back. A filesystem write is not part of a SQL
+ * transaction and cannot be made part of one, so a rolled-back transaction
+ * leaves an artifact on disk with nothing pointing at it. That is not a bug
+ * to be engineered away; it is why reconciliation exists (FR-073d), and why
+ * the write order is deliberate: **the file completes first, then the
+ * reference**. The reverse order would produce a reference to a file that
+ * does not exist, which is the failure a consumer cannot recover from — it
+ * looks like data the app has and does not.
+ */
+
+import type {
+	AttachmentInput,
+	AttachmentOwner,
+	AttachmentReference,
+	ByteRange,
+	DeletionOutcome,
+} from '../contract/attachment';
+import { Budgets } from '../contract/config';
+import { DiagnosticCodes } from '../contract/errors';
+import { isStorageError, raise } from '../diagnostics/errors';
+import { throwIfFaulted } from '../diagnostics/faults';
+import { raiseNative } from '../diagnostics/map-native';
+import { fileSystem, removeIfPresent } from '../platform/fs';
+import type { StorageLayout } from '../platform/location';
+import { assertArtifactWithinBudget } from '../query/budgets';
+import {
+	HEADER_BYTES,
+	TAG_BYTES,
+	chunkOffset,
+	chunkPlaintextLength,
+	decodeHeader,
+	decryptChunk,
+	encodeHeader,
+	encryptChunk,
+	headerFor,
+} from '../crypto/chunked-cipher';
+import type { Executor } from '../sqlite/connection';
+import { maybeNum, num, text } from '../sqlite/values';
+import { artifactPath, artifactsDirectory } from './paths';
+
+const CREATE_ATTACHMENTS = `CREATE TABLE IF NOT EXISTS _attachments (
+  id               TEXT PRIMARY KEY,
+  owner_collection TEXT,
+  owner_id         TEXT,
+  content_type     TEXT NOT NULL,
+  size             INTEGER NOT NULL,
+  chunk_size       INTEGER,
+  chunk_count      INTEGER,
+  created_at       INTEGER NOT NULL
+)`;
+
+const CREATE_OWNER_INDEX =
+	'CREATE INDEX IF NOT EXISTS _attachments_owner ON _attachments (owner_collection, owner_id)';
+
+export type ArtifactContext = {
+	executor(): Executor;
+	layout: StorageLayout;
+	scopeKey: string;
+	/** Null when the database is unencrypted. */
+	artifactKey(attachmentId: string): Uint8Array | null;
+	now(): number;
+};
+
+export async function ensureAttachmentTable(executor: Executor): Promise<void> {
+	await executor.execute(CREATE_ATTACHMENTS);
+	await executor.execute(CREATE_OWNER_INDEX);
+}
+
+function toReference(row: Record<string, unknown>): AttachmentReference {
+	const reference: AttachmentReference = {
+		id: text(row.id),
+		contentType: text(row.content_type),
+		size: num(row.size),
+		createdAt: num(row.created_at),
+	};
+	if (row.owner_collection != null && row.owner_id != null) {
+		reference.owner = { collection: text(row.owner_collection), id: text(row.owner_id) };
+	}
+	const chunkSize = maybeNum(row.chunk_size);
+	if (chunkSize !== null) {
+		reference.chunkSize = chunkSize;
+		reference.chunkCount = num(row.chunk_count);
+	}
+	return reference;
+}
+
+export async function readReference(
+	executor: Executor,
+	id: string,
+): Promise<AttachmentReference | null> {
+	const result = await executor.execute('SELECT * FROM _attachments WHERE id = ?', [id]);
+	const row = result.rows[0];
+	return row ? toReference(row) : null;
+}
+
+export async function listReferences(executor: Executor): Promise<AttachmentReference[]> {
+	const result = await executor.execute('SELECT * FROM _attachments ORDER BY id ASC');
+	return result.rows.map(toReference);
+}
+
+export async function listReferencesFor(
+	executor: Executor,
+	owner: AttachmentOwner,
+): Promise<AttachmentReference[]> {
+	const result = await executor.execute(
+		'SELECT * FROM _attachments WHERE owner_collection = ? AND owner_id = ? ORDER BY id ASC',
+		[owner.collection, owner.id],
+	);
+	return result.rows.map(toReference);
+}
+
+async function insertReference(
+	executor: Executor,
+	reference: AttachmentReference,
+): Promise<void> {
+	await executor.execute(
+		`INSERT INTO _attachments
+		 (id, owner_collection, owner_id, content_type, size, chunk_size, chunk_count, created_at)
+		 VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+		 ON CONFLICT(id) DO UPDATE SET
+		   owner_collection = excluded.owner_collection,
+		   owner_id = excluded.owner_id,
+		   content_type = excluded.content_type,
+		   size = excluded.size,
+		   chunk_size = excluded.chunk_size,
+		   chunk_count = excluded.chunk_count,
+		   created_at = excluded.created_at`,
+		[
+			reference.id,
+			reference.owner?.collection ?? null,
+			reference.owner?.id ?? null,
+			reference.contentType,
+			reference.size,
+			reference.chunkSize ?? null,
+			reference.chunkCount ?? null,
+			reference.createdAt,
+		],
+	);
+}
+
+export async function deleteReference(executor: Executor, id: string): Promise<boolean> {
+	const result = await executor.execute('DELETE FROM _attachments WHERE id = ?', [id]);
+	return result.rowsAffected > 0;
+}
+
+async function writePlaintext(path: string, content: string): Promise<void> {
+	await fileSystem().writeFile(path, content, 'base64');
+}
+
+/**
+ * Encrypted write, one chunk in flight.
+ *
+ * The header goes down first because its contents — chunk size, chunk count,
+ * plaintext length — are all known from the input length before any
+ * encryption happens. Only the tags depend on the ciphertext, and they follow
+ * their own chunk, so the whole write is append-only and peak memory is one
+ * chunk regardless of artifact size (FR-107a).
+ */
+async function writeEncrypted(
+	path: string,
+	key: Uint8Array,
+	plaintext: Buffer,
+): Promise<{ chunkSize: number; chunkCount: number }> {
+	const header = headerFor(plaintext.length, Budgets.ARTIFACT_CHUNK_BYTES);
+	await fileSystem().writeFile(path, encodeHeader(header).toString('base64'), 'base64');
+
+	for (let index = 0; index < header.chunkCount; index += 1) {
+		const start = index * header.chunkSize;
+		const chunk = plaintext.subarray(start, start + chunkPlaintextLength(header, index));
+		await fileSystem().appendFile(
+			path,
+			encryptChunk(key, index, chunk).toString('base64'),
+			'base64',
+		);
+	}
+
+	return { chunkSize: header.chunkSize, chunkCount: header.chunkCount };
+}
+
+export async function writeArtifact(
+	context: ArtifactContext,
+	input: AttachmentInput,
+): Promise<AttachmentReference> {
+	throwIfFaulted('attachmentWrite');
+	const plaintext = Buffer.from(input.content, 'base64');
+	assertArtifactWithinBudget(input.id, plaintext.length);
+
+	const path = artifactPath(context.layout, context.scopeKey, input.id);
+	const key = context.artifactKey(input.id);
+
+	let chunking: { chunkSize: number; chunkCount: number } | undefined;
+	try {
+		await fileSystem().mkdir(artifactsDirectory(context.layout, context.scopeKey));
+		if (key) {
+			chunking = await writeEncrypted(path, key, plaintext);
+		} else {
+			await writePlaintext(path, input.content);
+		}
+	} catch (error) {
+		// A partial file with no reference is an orphan reconciliation can
+		// find; a reference to a partial file is data the app believes it has.
+		await removeIfPresent(path);
+		raiseNative(error, { operation: 'attachment' });
+	}
+
+	const reference: AttachmentReference = {
+		id: input.id,
+		contentType: input.contentType,
+		size: plaintext.length,
+		createdAt: context.now(),
+	};
+	if (input.owner) {
+		reference.owner = input.owner;
+	}
+	if (chunking) {
+		reference.chunkSize = chunking.chunkSize;
+		reference.chunkCount = chunking.chunkCount;
+	}
+
+	// Only now. See the note at the top of this file.
+	await insertReference(context.executor(), reference);
+	return reference;
+}
+
+async function readPlaintext(path: string, range?: ByteRange): Promise<string> {
+	if (!range) {
+		return fileSystem().readFile(path, 'base64');
+	}
+	return fileSystem().read(path, range.length, range.offset, 'base64');
+}
+
+async function readEncrypted(
+	path: string,
+	key: Uint8Array,
+	range?: ByteRange,
+): Promise<string> {
+	const headerBytes = Buffer.from(
+		await fileSystem().read(path, HEADER_BYTES, 0, 'base64'),
+		'base64',
+	);
+	const header = decodeHeader(headerBytes);
+
+	const from = range?.offset ?? 0;
+	const to = range ? Math.min(header.plaintextSize, from + range.length) : header.plaintextSize;
+	if (to <= from) {
+		return '';
+	}
+
+	const first = Math.floor(from / header.chunkSize);
+	const last = Math.floor((to - 1) / header.chunkSize);
+	const pieces: Buffer[] = [];
+
+	for (let index = first; index <= last; index += 1) {
+		const stored = Buffer.from(
+			await fileSystem().read(
+				path,
+				chunkPlaintextLength(header, index) + TAG_BYTES,
+				chunkOffset(header, index),
+				'base64',
+			),
+			'base64',
+		);
+		const decrypted = decryptChunk(key, index, stored);
+		const chunkStart = index * header.chunkSize;
+		pieces.push(
+			decrypted.subarray(
+				Math.max(0, from - chunkStart),
+				Math.min(decrypted.length, to - chunkStart),
+			),
+		);
+	}
+
+	return Buffer.concat(pieces).toString('base64');
+}
+
+export async function readArtifact(
+	context: ArtifactContext,
+	id: string,
+	range?: ByteRange,
+): Promise<string> {
+	const path = artifactPath(context.layout, context.scopeKey, id);
+	const key = context.artifactKey(id);
+	try {
+		return key ? await readEncrypted(path, key, range) : await readPlaintext(path, range);
+	} catch (error) {
+		// A typed error the package already classified — an unreadable header,
+		// a failing tag — says something more specific than "missing" and must
+		// survive. Anything else reaching here is the file not being there.
+		if (isStorageError(error)) {
+			throw error;
+		}
+		raise(DiagnosticCodes.ATTACHMENT_MISSING, {
+			message: 'artifact is missing',
+			detail: { attachmentId: id },
+			cause: error,
+		});
+	}
+}
+
+export async function removeArtifact(
+	context: ArtifactContext,
+	id: string,
+): Promise<DeletionOutcome> {
+	const path = artifactPath(context.layout, context.scopeKey, id);
+	const removed = await removeIfPresent(path);
+	const hadReference = await deleteReference(context.executor(), id);
+
+	return {
+		removedRecords: 0,
+		removedArtifacts: removed ? [id] : [],
+		// A reference with no file left behind is worth reporting rather than
+		// rounding up to success (FR-071).
+		orphanedReferences: !removed && hadReference ? [id] : [],
+		failedRemovals: [],
+	};
+}

package/src/contract/adapter.ts

@@ -0,0 +1,78 @@
+/**
+ * The interface every storage implementation satisfies.
+ *
+ * Two implementations exist: op-sqlite on device, and a pure-TypeScript
+ * in-memory one for tests. The second is not a convenience — op-sqlite is
+ * native and unreachable from Jest, so without it the package's own
+ * guarantees would be untestable in CI (research.md R8).
+ */
+
+import type {
+	AttachmentAvailability,
+	AttachmentInput,
+	AttachmentReference,
+	AttachmentOwner,
+	ByteRange,
+	DeletionOutcome,
+	ReconciliationReport,
+} from './attachment';
+import type { EffectivePosture } from './backup';
+import type { DatabaseConfig, DatabaseTargetConfig, ScopeTargetConfig } from './config';
+import type { FilterNode, IndexCoverageReport, Query, ResultPage } from './query';
+import type { RecordInput, StorableRecordData, StoredRecord, WriteOutcome } from './record';
+import type { BatchOperation, BatchOutcome, CollectionOps, Transaction } from './transaction';
+
+export type Attachments = {
+	write(input: AttachmentInput): Promise<AttachmentReference>;
+	read(id: string, range?: ByteRange): Promise<string>;
+	/** Never opens or decrypts the artifact (FR-073e, FR-107b). */
+	availability(id: string): Promise<AttachmentAvailability>;
+	remove(id: string): Promise<DeletionOutcome>;
+	listFor(owner: AttachmentOwner): Promise<AttachmentReference[]>;
+	/** App-triggered only; the package runs no background sweep. */
+	reconcile(options?: { removeOrphans?: boolean }): Promise<ReconciliationReport>;
+};
+
+export type DatabaseHandle = {
+	/** The scope hash. Never the components (FR-014). */
+	readonly scopeKey: string;
+	readonly schemaVersion: number;
+	readonly backupPosture: EffectivePosture;
+	readonly isEncrypted: boolean;
+
+	collection<T extends StorableRecordData = StorableRecordData>(
+		name: string,
+	): CollectionOps<T>;
+	transaction<R>(fn: (tx: Transaction) => Promise<R>): Promise<R>;
+	batch(operations: BatchOperation[]): Promise<BatchOutcome>;
+	attachments(): Attachments;
+	/** Development-mode index coverage answer (FR-037). */
+	explain(collection: string, query?: Query): Promise<IndexCoverageReport>;
+	close(): Promise<void>;
+};
+
+/**
+ * What an implementation must provide. Deliberately lower-level than the
+ * public surface: validation, budget checks, and error mapping happen once in
+ * `adapter/`, above this line, so both implementations share them.
+ */
+export type StorageAdapter = {
+	readonly name: 'sqlite' | 'memory';
+
+	open(config: DatabaseConfig): Promise<DatabaseHandle>;
+	deleteScopeData(config: ScopeTargetConfig): Promise<DeletionOutcome>;
+	deleteDatabase(config: DatabaseTargetConfig): Promise<DeletionOutcome>;
+	/** The FR-057a recovery path. Never reachable from open(). */
+	resetScope(config: ScopeTargetConfig): Promise<DeletionOutcome>;
+};
+
+export type {
+	CollectionOps,
+	FilterNode,
+	Query,
+	RecordInput,
+	ResultPage,
+	StoredRecord,
+	Transaction,
+	WriteOutcome,
+};

package/src/contract/attachment.ts

@@ -0,0 +1,72 @@
+/**
+ * Attachment references and the artifacts behind them.
+ *
+ * This package owns both halves. The consequence is that a filesystem write
+ * cannot be rolled back by a database transaction, which is why
+ * reconciliation exists (FR-073d) rather than being a nicety.
+ */
+
+export type AttachmentOwner = {
+	collection: string;
+	id: string;
+};
+
+export type AttachmentInput = {
+	id: string;
+	/** Absent means the attachment belongs to the scope rather than a record. */
+	owner?: AttachmentOwner;
+	contentType: string;
+	/** Base64 content. Written incrementally; never held whole when encrypted. */
+	content: string;
+};
+
+export type AttachmentReference = {
+	id: string;
+	owner?: AttachmentOwner;
+	contentType: string;
+	/** Plaintext byte length, <= 100 MB (FR-088). */
+	size: number;
+	createdAt: number;
+	/** Present only for encrypted artifacts (research.md R4). */
+	chunkSize?: number;
+	chunkCount?: number;
+};
+
+/**
+ * `undecryptable` is deliberately distinct from `missing`: one is data loss
+ * for that artifact, the other is a wrong key or a tampered file (FR-107c).
+ */
+export type AttachmentAvailabilityState =
+	| 'available'
+	| 'missing'
+	| 'inaccessible'
+	| 'undecryptable';
+
+export type AttachmentAvailability = {
+	id: string;
+	state: AttachmentAvailabilityState;
+	size?: number;
+};
+
+export type ByteRange = {
+	offset: number;
+	length: number;
+};
+
+/**
+ * Both directions of divergence between the database and the disk (FR-073d).
+ */
+export type ReconciliationReport = {
+	orphanedArtifacts: string[];
+	danglingReferences: string[];
+	removedArtifacts: string[];
+};
+
+/** Never a bare success (FR-065, FR-071). */
+export type DeletionOutcome = {
+	scopeKey?: string;
+	removedRecords: number;
+	removedArtifacts: string[];
+	orphanedReferences: string[];
+	failedRemovals: string[];
+};

package/src/contract/backup.ts

@@ -0,0 +1,28 @@
+/**
+ * Platform backup posture.
+ *
+ * The platforms are not symmetric, and this contract is where that becomes
+ * visible to the consumer rather than hidden. On iOS the package sets the
+ * exclusion attribute itself. On Android backup participation is declared in
+ * the app's manifest — build-time, app-owned, and unreachable from a library
+ * that authors no native code — so the package verifies and reports instead.
+ * See research.md R5.
+ */
+
+export type BackupConfig = {
+	/** Default false: excluded unless the app asks otherwise (FR-109). */
+	includeInPlatformBackup: boolean;
+};
+
+export type BackupPostureValue = 'excluded' | 'included' | 'unknown';
+
+export type EffectivePosture = {
+	/** What the app asked for. */
+	requested: Exclude<BackupPostureValue, 'unknown'>;
+	/** What the package can actually confirm on this platform. */
+	observed: BackupPostureValue;
+	/** iOS: the package. Android: the app's manifest. */
+	enforcedBy: 'package' | 'app-manifest';
+	/** Present when requested and observed disagree — the case that matters. */
+	warning?: string;
+};