@chipmobilesdk/rn-local-db 0.1.1 → 0.2.0

package/CHANGELOG.md

@@ -2,6 +2,56 @@
 
 All notable changes to `@chipmobilesdk/rn-local-db` are recorded here. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this package follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.2.0] — 2026-11-01
+
+Fixes a data-loss defect in transactions and attachment handling that failed on every
+Hermes device. **One behaviour change needs a code change** (see Changed).
+
+### Fixed
+
+- **A write from outside a transaction is no longer lost with its rollback.** The
+  connection routed every statement into whatever transaction was in flight, so a write
+  from another screen or a background sync while a transaction ran was rolled back with
+  it, and a reader outside saw uncommitted data. Each handle now queues work behind a
+  running transaction; only the executor the transaction hands out reaches it. The
+  memory adapter isolates the same way, so conformance now catches a regression. After
+  `tx.abort()` the body's remaining statements are refused instead of running in
+  autocommit.
+- **Attachments work on Hermes.** Writes and reads used Node's global `Buffer`, which
+  Hermes does not have. Byte handling is now `Uint8Array` with a self-contained base64
+  codec; the encrypted file format is unchanged.
+- **A batch upsert over a soft-deleted record restores it**, and a batch insert over one
+  conflicts — the collection API's rules. The batch used to issue an INSERT and fail the
+  whole batch on the primary key.
+- **Index names are scoped to their collection.** Two collections declaring an index of
+  the same name used to get only the first one, a UNIQUE constraint included. Existing
+  indexes are renamed on the next open; no data moves. `explain()` still reports the
+  declared name.
+- **Deleting an encrypted scope no longer needs its key.** A failing or destroyed key
+  failed the call after the scope was marked, leaving it stuck in `deleting`. The data is
+  deleted and the outcome sets `recordCountUnavailable`.
+- **Cascaded attachment removal is transaction-safe and reported.** Inside a
+  transaction, files are removed only after it commits, so a rollback no longer leaves a
+  reference to a deleted file. The reference is deleted before the file, a file that
+  could not be removed is reported in `failedRemovals`, batch deletes cascade, and the
+  memory adapter implements cascading.
+
+### Changed
+
+- **Needs a code change:** inside a transaction body, write attachments through
+  `tx.attachments()` (new) instead of `handle.attachments()`. The handle's call now waits
+  for the transaction; awaited from inside the body it is refused with
+  `TRANSACTION_STATE` after 10 seconds and the transaction rolls back, instead of
+  hanging. The same applies to `handle.collection()`, which inside a transaction was
+  already documented as a mistake.
+- `MigrationContext` no longer includes `attachments()`.
+
+### Added
+
+- `Transaction.attachments()`.
+- `WriteOutcome.cascade` on a delete when `cascadeAttachments` is on.
+- `DeletionOutcome.recordCountUnavailable`.
+
 ## [0.1.0] — 2026-08-01
 
 First release. New package, no existing consumers, no migration burden.

package/README.md

@@ -1,13 +1,13 @@
 # @chipmobilesdk/rn-local-db
 
-Offline-first, scope-isolated local storage for ChipMobileSdk apps.
-
-> **License:** `UNLICENSED`. Published publicly for use by the owner's
-> applications; no open-source license is granted.
-
-- **Version**: `0.1.0`
-- **Entrypoints**: `@chipmobilesdk/rn-local-db` and the test-only
-  `@chipmobilesdk/rn-local-db/testing`
+Offline-first, scope-isolated local storage for ChipMobileSdk apps.
+
+> **License:** `UNLICENSED`. Published publicly for use by the owner's
+> applications; no open-source license is granted.
+
+- **Version**: `0.2.0`
+- **Entrypoints**: `@chipmobilesdk/rn-local-db` and the test-only
+  `@chipmobilesdk/rn-local-db/testing`
 
 Structured records, queries a list screen can actually use, transactions with real rollback, versioned migrations that fail loudly, an explicit deletion lifecycle, package-owned file attachments, opt-in encryption at rest, and typed diagnostics that never carry the user's data.
 
@@ -28,9 +28,9 @@ Structured records, queries a list screen can actually use, transactions with re
 - [Attachments](#attachments)
 - [Encryption](#encryption)
 - [Backup posture](#backup-posture)
-- [Diagnostics](#diagnostics)
-- [Public API](#public-api)
-- [Testing against the in-memory adapter](#testing-against-the-in-memory-adapter)
+- [Diagnostics](#diagnostics)
+- [Public API](#public-api)
+- [Testing against the in-memory adapter](#testing-against-the-in-memory-adapter)
 - [Budgets](#budgets)
 - [Compatibility](#compatibility)
 - [What this package stores, and where](#what-this-package-stores-and-where)
@@ -42,8 +42,8 @@ Structured records, queries a list screen can actually use, transactions with re
 ```sh
 npm install @chipmobilesdk/rn-local-db
 npm install @op-engineering/op-sqlite @dr.pogodin/react-native-fs
-# Only if you will enable encryption:
-npm install react-native-quick-crypto
+# Only if you will enable encryption (quick-base64 is quick-crypto's native peer):
+npm install react-native-quick-crypto react-native-quick-base64
 cd ios && pod install
 ```
 
@@ -264,6 +264,8 @@ await handle.transaction(async tx => {
 
 Reads inside a transaction see that transaction's own writes; reads outside do not until it commits. A settled transaction rejects further use with `TRANSACTION_STATE`, so cleanup code cannot accidentally write outside the rollback it was meant to be part of.
 
+**Inside the body, use what `tx` hands you** — `tx.collection()` and `tx.attachments()`. Work issued through the handle while a transaction runs waits for it to finish and then runs on its own; it never joins the transaction, so a rollback cannot take an unrelated write with it. A body that awaits the handle's own `collection()` or `attachments()` would be waiting on itself, so after 10 seconds that call is refused with `TRANSACTION_STATE` and the transaction rolls back instead of hanging.
+
 A transaction never spans two scopes — with one database file per scope, that is a type error rather than a runtime check.
 
 ```ts
@@ -354,7 +356,7 @@ Every one returns a `DeletionOutcome` rather than a bare success — what was re
 
 If a deletion is interrupted — a force-quit, a battery death — the next open reports `SCOPE_DELETED` rather than presenting the scope as healthy. Call `deleteScopeData` again to finish it.
 
-A handle whose scope is deleted beneath it reports `SCOPE_DELETED` on its next use. The deletion does not wait for it.
+A handle whose scope is deleted beneath it reports `SCOPE_DELETED` on its next use. The deletion does not wait for it, and nothing revives it: open a new handle and rebuild whatever was built on the old one. An app that retries through the dead handle gets the same error every time, which reaches the user as a screen that only relaunching can fix.
 
 ---
 
@@ -376,13 +378,13 @@ await attachments.read('photo-1');                        // whole
 await attachments.read('photo-1', { offset: 0, length: 4096 }); // a range
 await attachments.availability('photo-1');                // never opens the file
 await attachments.listFor({ collection: 'notes', id: 'n1' });
-await attachments.remove('photo-1');
-```
-
-`AttachmentInput.content` is one complete base64 string. The current public
-write contract therefore requires the app to hold the encoded payload, and the
-native adapter decodes that full string before processing encrypted chunks.
-Use range reads to avoid loading an entire stored artifact when consuming it.
+await attachments.remove('photo-1');
+```
+
+`AttachmentInput.content` is one complete base64 string. The current public
+write contract therefore requires the app to hold the encoded payload, and the
+native adapter decodes that full string before processing encrypted chunks.
+Use range reads to avoid loading an entire stored artifact when consuming it.
 
 **Availability** answers from `stat()` and, for an encrypted artifact, the 22-byte header — never a content byte and never a decryption. A gallery showing fifty thumbnails does not decrypt fifty files to ask whether they are there.
 
@@ -440,12 +442,12 @@ const handle = await openDatabase({
 
 The provider receives the resolved scope so you can key per identity — which is what makes destroying one identity's key a meaningful answer to a deletion request, rather than a gesture that leaves the data readable under a shared key.
 
-**Records** are protected by SQLCipher. **Artifacts** use chunked AES-256-GCM:
-256 KB chunks, a per-artifact subkey derived with HKDF, and an authentication
-tag per chunk. Encryption and range decryption operate by chunk, but the
-current write API first decodes the complete base64 input. Peak write memory is
-therefore not flat in artifact size; size large media before passing it to this
-version.
+**Records** are protected by SQLCipher. **Artifacts** use chunked AES-256-GCM:
+256 KB chunks, a per-artifact subkey derived with HKDF, and an authentication
+tag per chunk. Encryption and range decryption operate by chunk, but the
+current write API first decodes the complete base64 input. Peak write memory is
+therefore not flat in artifact size; size large media before passing it to this
+version.
 
 A key-provider failure while the device is locked is an **expected condition**, not a bug:
 
@@ -570,33 +572,33 @@ try {
 setDiagnosticLogger(event => console.log(event.operation, event.durationMs, event.count));
 ```
 
-Operation names, durations, counts, and outcome codes. There is deliberately no path that accepts a payload, and the logger is inert in production builds.
-
----
-
-## Public API
-
-Production code imports only from `@chipmobilesdk/rn-local-db`:
-
-- Lifecycle: `openDatabase`, `deleteScopeData`, `resetScope`, `deleteDatabase`
-- Handle contract: `DatabaseHandle`, `CollectionOps`, `Transaction`,
-  `Attachments`, `StorageAdapter`, plus batch/transaction result types
-- Configuration and isolation: database/target/scope descriptors, collection
-  schema, migrations, encryption/key provider, and backup posture types
-- Records and queries: record/value/write types, filter/sort/page/query types,
-  `IndexCoverageReport`, and `Budgets`
-- Attachments: input/reference/owner/range/availability/deletion/reconciliation
-  types
-- Diagnostics: `StorageError`, `DiagnosticCodes`, `DiagnosticCode`, `isCode`,
-  `isStorageError`, `setDiagnosticLogger`, `DiagnosticLogger`
-
-Tests import `createMemoryAdapter`, reset/seed/fault helpers, and the conformance
-suite only from `@chipmobilesdk/rn-local-db/testing`. Other package paths are
-private and unsupported.
-
----
-
-## Testing against the in-memory adapter
+Operation names, durations, counts, and outcome codes. There is deliberately no path that accepts a payload, and the logger is inert in production builds.
+
+---
+
+## Public API
+
+Production code imports only from `@chipmobilesdk/rn-local-db`:
+
+- Lifecycle: `openDatabase`, `deleteScopeData`, `resetScope`, `deleteDatabase`
+- Handle contract: `DatabaseHandle`, `CollectionOps`, `Transaction`,
+  `Attachments`, `StorageAdapter`, plus batch/transaction result types
+- Configuration and isolation: database/target/scope descriptors, collection
+  schema, migrations, encryption/key provider, and backup posture types
+- Records and queries: record/value/write types, filter/sort/page/query types,
+  `IndexCoverageReport`, and `Budgets`
+- Attachments: input/reference/owner/range/availability/deletion/reconciliation
+  types
+- Diagnostics: `StorageError`, `DiagnosticCodes`, `DiagnosticCode`, `isCode`,
+  `isStorageError`, `setDiagnosticLogger`, `DiagnosticLogger`
+
+Tests import `createMemoryAdapter`, reset/seed/fault helpers, and the conformance
+suite only from `@chipmobilesdk/rn-local-db/testing`. Other package paths are
+private and unsupported.
+
+---
+
+## Testing against the in-memory adapter
 
 ```ts
 import { createMemoryAdapter, resetMemoryAdapter } from '@chipmobilesdk/rn-local-db/testing';
@@ -680,7 +682,7 @@ Four are **hard limits** with a typed error. The rest are soft: exceeding them i
 | iOS | 15.1+ |
 | `@op-engineering/op-sqlite` | >= 17.1.0 |
 | `@dr.pogodin/react-native-fs` | >= 2.39.2 |
-| `react-native-quick-crypto` | >= 1.0.0 — **optional**, only for encryption |
+| `react-native-quick-crypto` | >= 1.0.0 — **optional**, only for encryption. Its own peer `react-native-quick-base64` must also be in the **app's** `dependencies`: autolinking compiles only what the app declares, and without it the first encrypted attachment fails with `'QuickBase64' could not be found` |
 
 **Storage location**: app-private documents directory, under `chipmobilesdk-localdb/`.
 **Backup mechanism**: `NSURLIsExcludedFromBackupKey` on iOS; `dataExtractionRules` / `fullBackupContent` on Android.
@@ -706,21 +708,21 @@ Written for the privacy disclosure a consuming app has to make.
 
 **Deletion**: `deleteScopeData` removes one scope's records and artifacts and reports what it removed. That satisfies a deletion request for the data this package stores. It does **not** guarantee anything about residual data outside the package: filesystem free-space is not overwritten, and platform backups already taken are unaffected. If the scope was encrypted with a per-identity key, destroying that key — which your app controls — is what makes any residue unreadable.
 
-**Your remaining obligations**: this package collects nothing and declares nothing on your behalf. If your app stores health, financial, or other sensitive categories in it, those categories are yours to declare in App Privacy and Data Safety.
-
----
-
-## Demo and validation
-
-The demo app exposes ten `src/screens/LocalDb*Screen.tsx` scenarios and uses
-the testing entrypoint's memory adapter so the UI can run without native
-database setup. Run from the repository root:
-
-```bash
-npm run typecheck:local-db
-npm run pack:local-db
-npm run validate:local-db
-```
-
-Physical-device SQLCipher, backup, corruption, and large-artifact evidence are
-separate release gates; the memory demo does not prove those native behaviors.
+**Your remaining obligations**: this package collects nothing and declares nothing on your behalf. If your app stores health, financial, or other sensitive categories in it, those categories are yours to declare in App Privacy and Data Safety.
+
+---
+
+## Demo and validation
+
+The demo app exposes ten `src/screens/LocalDb*Screen.tsx` scenarios and uses
+the testing entrypoint's memory adapter so the UI can run without native
+database setup. Run from the repository root:
+
+```bash
+npm run typecheck:local-db
+npm run pack:local-db
+npm run validate:local-db
+```
+
+Physical-device SQLCipher, backup, corruption, and large-artifact evidence are
+separate release gates; the memory demo does not prove those native behaviors.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@chipmobilesdk/rn-local-db",
-	"version": "0.1.1",
+	"version": "0.2.0",
 	"private": false,
 	"license": "UNLICENSED",
 	"main": "src/index.ts",

package/skills/sdk-rn-local-db/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: sdk-rn-local-db
-description: "Offline SQLite storage via @chipmobilesdk/rn-local-db: schemas, scoped data, queries, transactions, migrations, attachments, encryption. Use when persisting data locally, writing a migration, or handling sign-out data retention."
+description: "Offline SQLite storage via @chipmobilesdk/rn-local-db: schemas, scoped data, queries, transactions, migrations, attachments, encryption. Use when persisting data locally, writing a migration, deleting a user's data, or handling sign-out data retention."
 metadata:
   package: "@chipmobilesdk/rn-local-db"
   packageVersion: "0.1.0"
@@ -33,12 +33,20 @@ Two concepts cause most of the bugs in this package. Do not skip them:
 Read `## The scope model` and `## Records and the four value conditions` in the README
 before designing a schema.
 
-## Sign-out is not deletion
+## Deletion, sign-out, and dead handles
 
 The README has a dedicated section (`## Deletion, and why sign-out is not deletion`).
 Treat any "clear data on logout" requirement as a design question answered by that
 section, not by deleting the database file.
 
+`deleteScopeData` and `deleteDatabase` are module-level and do not wait for open
+handles. **After either, open a NEW handle and rebuild everything derived from the
+old one** — repositories, providers, the screen behind a retry button. The old handle
+raises `SCOPE_DELETED` (or `CLOSED_HANDLE` if the app closed it first) on every call,
+so a Retry wired to it can never succeed: the app stays broken until the process
+restarts. An interrupted deletion instead reports `SCOPE_DELETED` from the next
+`openDatabase` — call `deleteScopeData` again to finish it, then open.
+
 ## Public API
 
 `setDiagnosticLogger`, `Budgets`, and types `DiagnosticLogger`, `DiagnosticCode` are
@@ -53,7 +61,7 @@ surfaces are large — enumerate them from
 | Need | Section |
 |---|---|
 | Install and native setup | `## Install` |
-| Data ownership / sign-out | `## The scope model`, `## Deletion, and why sign-out is not deletion` |
+| Data ownership / sign-out / deleting it all | `## The scope model`, `## Deletion, and why sign-out is not deletion` |
 | Defining tables | `## Declaring a schema` |
 | Null vs missing vs unset | `## Records and the four value conditions` |
 | Reading data | `## Queries` |

package/src/adapter/deletion.ts

@@ -85,7 +85,7 @@ async function countRecords(
 	layout: StorageLayout,
 	scopeKey: string,
 	encryptionKey: string | undefined,
-): Promise<number> {
+): Promise<number | undefined> {
 	let connection: Connection | null = null;
 	try {
 		connection = await openConnection({
@@ -103,7 +103,9 @@ async function countRecords(
 		}
 		return total;
 	} catch {
-		return 0;
+		// Unknown, not zero: a report that said "0 records" about a scope it
+		// could not open would understate what was deleted.
+		return undefined;
 	} finally {
 		await connection?.close();
 	}
@@ -145,14 +147,25 @@ async function removeScope(config: ScopeTargetConfig): Promise<DeletionOutcome>
 
 		const removedArtifacts = await artifactIdsOnDisk(layout, scope.key);
 
-		// The key is needed to count what is being removed, not to remove it.
-		// It is released the moment the count is done, whatever happened.
-		const keyHandle = config.encryption?.enabled
-			? await acquireKey(config.encryption, scope)
-			: null;
-		let removedRecords: number;
+		// The key is needed to count what is being removed, not to remove it,
+		// so a key provider that fails — or a key already destroyed for this
+		// identity, which FR-104 encourages — costs the count, never the
+		// deletion. Until 0.2.0 it failed the whole call after the scope was
+		// already marked, leaving it stuck in `deleting`.
+		let keyHandle: Awaited<ReturnType<typeof acquireKey>> | null = null;
+		if (config.encryption?.enabled) {
+			try {
+				keyHandle = await acquireKey(config.encryption, scope);
+			} catch {
+				keyHandle = null;
+			}
+		}
+		let counted: number | undefined;
 		try {
-			removedRecords = await countRecords(layout, scope.key, keyHandle?.value());
+			counted =
+				config.encryption?.enabled && keyHandle === null
+					? undefined
+					: await countRecords(layout, scope.key, keyHandle?.value());
 		} finally {
 			keyHandle?.release();
 		}
@@ -176,7 +189,8 @@ async function removeScope(config: ScopeTargetConfig): Promise<DeletionOutcome>
 
 		return {
 			scopeKey: scope.key,
-			removedRecords,
+			removedRecords: counted ?? 0,
+			...(counted === undefined ? { recordCountUnavailable: true } : {}),
 			removedArtifacts,
 			orphanedReferences: [],
 			failedRemovals,

package/src/adapter/lifecycle.ts

@@ -43,7 +43,7 @@ import type {
 	Transaction,
 } from '../contract/transaction';
 import { artifactAvailability } from '../artifacts/availability';
-import { cascadeForOwner } from '../artifacts/cascade';
+import { cascadeForOwner, unlinkArtifact, type DeferredUnlinks } from '../artifacts/cascade';
 import { reconcileArtifacts } from '../artifacts/reconcile';
 import {
 	ensureAttachmentTable,
@@ -69,10 +69,15 @@ import { validateConfig } from '../schema/validate-config';
 import { resolveScope } from '../scope/validate';
 import { runBatch } from '../sqlite/batch';
 import { ensureCatalog, readEntry, registerScope } from '../sqlite/catalog';
-import { assertReadable, openConnection, type Connection } from '../sqlite/connection';
+import { assertReadable, openConnection, type Connection, type Executor } from '../sqlite/connection';
 import { explainQuery } from '../sqlite/index-coverage';
 import { isEncryptionAvailable } from '../sqlite/native';
-import { addColumnSql, createIndexSql, createTableSql } from '../sqlite/row-codec';
+import {
+	addColumnSql,
+	createIndexSql,
+	createTableSql,
+	physicalIndexName,
+} from '../sqlite/row-codec';
 import { runInTransaction } from '../sqlite/transactions';
 import { text } from '../sqlite/values';
 import { acquireHandleSlot, releaseHandleSlot } from './budgets';
@@ -114,6 +119,17 @@ async function ensureCollection(
 		);
 	}
 
+	// 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);
 	}
@@ -307,22 +323,29 @@ function buildHandle(context: HandleContext): DatabaseHandle {
 		}
 	};
 
-	const artifacts: ArtifactContext = {
-		executor: () => connection,
+	// 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): CollectionOps<T> => {
+	const rawCollection = <T extends StorableRecordData>(
+		name: string,
+		executor: Executor,
+	): CollectionOps<T> => {
 		assertUsable();
 		return instrument(
 			name,
 			'sqlite',
 			createSqlCollection<T>({
-				executor: () => connection,
+				executor: () => executor,
 				schema: schemaFor(schemas, name),
 				now: context.now,
 				assertUsable,
@@ -335,10 +358,14 @@ function buildHandle(context: HandleContext): DatabaseHandle {
 	 *
 	 * 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.
+	 * make. The outcome carries what was removed and what could not be.
 	 */
-	const collectionFor = <T extends StorableRecordData>(name: string): CollectionOps<T> => {
-		const ops = rawCollection<T>(name);
+	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;
 		}
@@ -346,39 +373,51 @@ function buildHandle(context: HandleContext): DatabaseHandle {
 			...ops,
 			async delete(id: string) {
 				const outcome = await ops.delete(id);
-				await cascadeForOwner(artifacts, connection, { collection: name, id });
-				return outcome;
+				const cascade = await cascadeForOwner(
+					artifactsOn(executor),
+					executor,
+					{ collection: name, id },
+					deferred,
+				);
+				return { ...outcome, cascade };
 			},
 		};
 	};
 
-	const attachments: Attachments = {
-		write(input: AttachmentInput) {
-			assertUsable();
-			return writeArtifact(artifacts, input);
-		},
-		read(id: string, range?: ByteRange) {
-			assertUsable();
-			return readArtifact(artifacts, id, range);
-		},
-		availability(id: string) {
-			assertUsable();
-			return artifactAvailability(artifacts, connection, id);
-		},
-		remove(id: string): Promise<DeletionOutcome> {
-			assertUsable();
-			return removeArtifact(artifacts, id);
-		},
-		listFor(owner: AttachmentOwner) {
-			assertUsable();
-			return listReferencesFor(connection, owner);
-		},
-		reconcile(options): Promise<ReconciliationReport> {
-			assertUsable();
-			return reconcileArtifacts(artifacts, connection, options);
-		},
+	const 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,
@@ -389,23 +428,39 @@ function buildHandle(context: HandleContext): DatabaseHandle {
 
 		async transaction<R>(fn: (tx: Transaction) => Promise<R>): Promise<R> {
 			assertUsable();
-			return runInTransaction(connection, async tx => {
+			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: collectionFor,
-					rollback: () => tx.rollback(),
+					collection: name => collectionOn(name, tx, deferred),
+					attachments: () => attachmentsOn(tx, deferred),
+					rollback: async () => {
+						aborted = true;
+						await tx.rollback();
+					},
 				});
-				const result = await fn(managed.transaction);
+				const value = await fn(managed.transaction);
 				if (!managed.isSettled()) {
 					throwIfFaulted('commit');
 				}
 				managed.settle();
-				return result;
+				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;
 		},
 
-		batch(operations: BatchOperation[]): Promise<BatchOutcome> {
+		async batch(operations: BatchOperation[]): Promise<BatchOutcome> {
 			assertUsable();
-			return runBatch(
+			const outcome = await runBatch(
 				{
 					connection,
 					schemaFor: name => schemaFor(schemas, name),
@@ -413,6 +468,27 @@ function buildHandle(context: HandleContext): DatabaseHandle {
 				},
 				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,

package/src/adapter/transaction.ts

@@ -18,10 +18,12 @@
 import { DiagnosticCodes } from '../contract/errors';
 import type { StorableRecordData } from '../contract/record';
 import type { CollectionOps, Transaction } from '../contract/transaction';
+import type { Attachments } from '../contract/adapter';
 import { raise } from '../diagnostics/errors';
 
 export type TransactionHost = {
 	collection<T extends StorableRecordData>(name: string): CollectionOps<T>;
+	attachments(): Attachments;
 	rollback(): Promise<void>;
 };
 
@@ -48,6 +50,10 @@ export function createTransaction(host: TransactionHost): ManagedTransaction {
 			assertLive();
 			return host.collection<T>(name);
 		},
+		attachments(): Attachments {
+			assertLive();
+			return host.attachments();
+		},
 		async abort(): Promise<void> {
 			assertLive();
 			settled = true;