@mailwoman/sqlite 9.4.0 → 10.1.0

package/lib/batched.ts

@@ -3,7 +3,7 @@
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  *
- *   Batched bulk-write transactions — the `COMMIT`/`BEGIN` cadence every streaming ingest repeats around its
+ *   Batched bulk-write transactions — the `commit`/`begin` cadence every streaming ingest repeats around its
  *   raw prepared-statement loop.
  */
 
@@ -12,27 +12,21 @@
  */
 export interface BatchedTransaction {
 	/**
-	 * Record one written row. Every `rowsPerCommit` rows the open transaction is committed and a new one opened; answers
-	 * `true` on the call that committed, so a caller can hang a progress report off the boundary.
+	 * Record one written row, committing and reopening the transaction every `rowsPerCommit`
+	 * rows and answering `true` on the call that committed.
 	 */
 	rowWritten(): boolean
-	/**
-	 * Commit the open transaction — the ordinary end of an ingest loop.
-	 */
 	commit(): void
 	/**
-	 * Best-effort `ROLLBACK`, and it must never replace the real error: a build runs with the journal off (nothing is
-	 * ever published without the swap), so SQLite may refuse to unwind. What matters is that the caller sees WHY the
-	 * ingest stopped, not that a scratch file was tidied.
+	 * Best-effort `rollback` that must never replace the real error, so the caller
+	 * still sees why the ingest stopped.
 	 */
 	rollbackQuietly(): void
 }
 
 /**
- * Open a transaction that commits and reopens itself every `rowsPerCommit` written rows.
- *
- * The batch size is the caller's: a geometry table whose rows carry a blob wants a smaller transaction than a
- * fixed-width staging table, because a larger one grows the write-ahead file without improving throughput.
+ * Open a transaction that commits and reopens itself every `rowsPerCommit` written rows,
+ * with the batch size left to the caller.
  */
 export function beginBatched(
 	database: { exec(sql: string): void },

package/lib/client.ts

@@ -18,38 +18,23 @@ import { PathBuilder, type PathBuilderLike } from "path-ts"
 
 import type { Database } from "#database-schema"
 import { SqliteDialect } from "#dialect"
-import type { SqliteDialectConfig } from "#dialect-config"
+import type { SqliteDialectConfig } from "#dialect/config"
 
-/**
- * A SQLite client for one database file: a Kysely query builder over `node:sqlite`, plus the two raw statements Kysely
- * cannot express.
- *
- * The client opens the file. A caller says which file and which schema; it never builds the connection itself.
- *
- * ```ts
- * using kdb = new DatabaseClient<MySchema>("db.sqlite", { readOnly: true })
- * ```
- *
- * Handing that job to callers is what let one database be described by two schemas — the type argument here and a
- * second one on the handle — with nothing to make them agree. It also split ownership: `SqliteDriver.destroy()` closes
- * whatever connection it was given, so a shared handle has two owners and the first `destroy()` closes it under the
- * other. One construction gives one schema, one owner, and a lifetime `using` can end.
- *
- * `exec` and `prepare` reach the same connection for the work Kysely does not model. See `core/db/schema.ts`.
- */
 /**
  * A connection's non-Kysely surface: the statements Kysely does not model, plus ending the connection.
  *
- * Schema-agnostic by construction — none of these members mentions `DB` — so a `DatabaseClient<AnySchema>` satisfies it
- * and a helper need not name its caller's schema. That matters because Kysely is INVARIANT in `DB`: a parameter typed
- * `DatabaseClient` (the empty default) would reject every real client. This is the narrowing the
- * `mailwoman/no-database-handle-cast` rule prescribes, applied to the raw side.
+ * Schema-agnostic because Kysely is invariant in `DB`: a parameter typed
+ * `DatabaseClient` would reject every real client.
  */
 export type RawStatements = Pick<DatabaseClient, "exec" | "prepare" | "function" | "destroy"> & Disposable
 
+/**
+ * A SQLite client for one database file: a Kysely query builder over `node:sqlite`,
+ * plus the two raw statements Kysely cannot express.
+ */
 export class DatabaseClient<DB = Database> extends Kysely<DB> implements Disposable {
 	/**
-	 * A memory-only database, for tests and other ephemeral work. The connection is open until the client is disposed.
+	 * A memory-only database, for tests and other ephemeral work.
 	 */
 	public static temp<DB = Database>(): DatabaseClient<DB> {
 		return new DatabaseClient<DB>(":memory:")
@@ -71,7 +56,7 @@ export class DatabaseClient<DB = Database> extends Kysely<DB> implements Disposa
 		if (typeof source === "string" || source instanceof PathBuilder) {
 			const location = source.toString()
 			const options = optionsOrConfig as DatabaseSyncOptions | undefined
-			// node:sqlite checks the argument count, not the value: `new DatabaseSync(path, undefined)` throws.
+			// node:sqlite checks the argument count rather than the value: `new DatabaseSync(path, undefined)` throws.
 			const openArgs: [string, DatabaseSyncOptions?] = options ? [location, options] : [location]
 
 			database = new DatabaseSync(...openArgs)
@@ -99,10 +84,7 @@ export class DatabaseClient<DB = Database> extends Kysely<DB> implements Disposa
 	}
 
 	/**
-	 * Run a statement Kysely does not model: `PRAGMA`, `VACUUM`, `ANALYZE`, `ATTACH`, FTS5 virtual-table DDL.
-	 *
-	 * Not to be confused with Kysely's `execute()`, which runs a compiled query. This one takes SQL text and returns
-	 * nothing.
+	 * Run a statement Kysely does not model: `pragma`, `vacuum`, `analyze`, `attach`, FTS5 virtual-table DDL.
 	 */
 	exec(sql: string): void {
 		this.#database.exec(sql)
@@ -110,10 +92,6 @@ export class DatabaseClient<DB = Database> extends Kysely<DB> implements Disposa
 
 	/**
 	 * A prepared statement on this client's connection, for the bulk-write path.
-	 *
-	 * Kysely compiles per call, which a positional insert loop over millions of rows cannot afford. Reach for this only
-	 * there and in the other cases `AGENTS.md` lists as deliberately raw; everything cold goes through the query builder,
-	 * where the schema is checked.
 	 */
 	prepare(sql: string): StatementSync {
 		return this.#database.prepare(sql)
@@ -122,7 +100,8 @@ export class DatabaseClient<DB = Database> extends Kysely<DB> implements Disposa
 	/**
 	 * Register a user-defined SQL function on this client's connection, callable from any statement it runs.
 	 *
-	 * SQLite resolves the name at statement-compile time, so registration must precede the first query that uses it.
+	 * SQLite resolves the name at statement-compile time, so registration must
+	 * precede the first query that uses it.
 	 */
 	function(name: string, options: FunctionOptions, fn: (...args: SQLOutputValue[]) => SQLInputValue): void
 	function(name: string, fn: (...args: SQLOutputValue[]) => SQLInputValue): void
@@ -143,13 +122,8 @@ export class DatabaseClient<DB = Database> extends Kysely<DB> implements Disposa
 	/**
 	 * End the connection at scope exit, synchronously.
 	 *
-	 * `destroy()` is Kysely's teardown and returns a promise, which `Symbol.dispose` cannot await — calling it here would
-	 * return with the file still open, and the next thing to touch that path (a `sealDatabase`, a reader expecting a
-	 * finalized statement) would see a connection that should have been gone. `node:sqlite`'s `close()` is synchronous,
-	 * so `using` closes the file before the scope ends.
-	 *
-	 * Kysely's own driver state is not unwound here. It holds this one connection and nothing else, and a query issued
-	 * afterwards fails on the closed handle rather than on a pool that thinks it is alive.
+	 * `destroy()` returns a promise, so `Symbol.dispose` cannot call it.
+	 * `node:sqlite`'s `close()` is synchronous.
 	 */
 	[Symbol.dispose](): void {
 		this.#database[Symbol.dispose]()
@@ -157,7 +131,6 @@ export class DatabaseClient<DB = Database> extends Kysely<DB> implements Disposa
 }
 
 /**
- * The `node:sqlite` types a caller needs when it holds a statement or binds a value. Re-exported so nothing has to
- * reach past this package for them.
+ * The `node:sqlite` types a caller needs when it holds a statement or binds a value.
  */
 export type { DatabaseSyncOptions, SQLInputValue, SQLOutputValue, StatementSync } from "node:sqlite"

package/lib/database-schema.ts

@@ -3,28 +3,10 @@
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  *
- *   Shared `Database` typing for the Kysely client at `core/kysley/client.ts`.
- *
- *   This file intentionally ships an empty schema. Consumers that want compile-time table typing
- *   should extend `Kysely<TheirSchema>` directly rather than baking a schema into core — the WOF
- *   resolver (Phase 4.2), corpus adapters, and any future consumer all touch different tables.
- *
- *   The exported `Database` interface exists so `client.ts` has a target for `Kysely<Database>` and
- *   the boilerplate compiles without forcing a concrete schema commitment.
- *
- *   IT IS THE DEFAULT, NOT THE ONLY OPTION, and reading it as the only option is how `as never` gets written. Every
- *   table name typed against `Record<string, never>` IS `never`, so `insertInto("poi")` cannot compile and a caller
- *   who believes no alternative exists casts — which disarms not just that one check but every type-level guarantee
- *   anyone later adds to the table (#1757 has the worked case: a branded key column whose check a neighbouring
- *   `as never` had already defeated).
+ *   Default schema type for {@link DatabaseClient}; consumers supply their own table schema.
  */
 
 /**
- * Empty schema marker, and the DEFAULT type argument only.
- *
- * Consumers declare their own schema interface and pass it directly: `new Kysely<MySchema>({…})` or `new
- * DatabaseClient<MySchema>(…)`. `DatabaseClient<DB = Database>` is generic today, so this is available now — the
- * sentence here once deferred it to "Phase 4.2 work", which had already landed, and a reader who believed that had no
- * option but to cast.
+ * Empty schema marker used only as the generic default.
  */
 export type Database = Record<string, never>

package/lib/dialect.ts

@@ -16,7 +16,7 @@ import {
 	type QueryCompiler,
 } from "kysely"
 
-import type { SqliteDialectConfig } from "#dialect-config"
+import type { SqliteDialectConfig } from "#dialect/config"
 import { SqliteDriver } from "#driver"
 
 /**

package/lib/driver.ts

@@ -18,7 +18,7 @@ import {
 	SelectQueryNode,
 } from "kysely"
 
-import type { SqliteDialectConfig } from "#dialect-config"
+import type { SqliteDialectConfig } from "#dialect/config"
 
 class ConnectionMutex {
 	#promise?: Promise<void>
@@ -67,8 +67,8 @@ export class SqliteDriver implements Driver {
 	}
 
 	async acquireConnection(): Promise<DatabaseConnection> {
-		// SQLite only has one single connection. We use a mutex here to wait
-		// until the single connection has been released.
+		// SQLite only has one single connection.
+		// We use a mutex here to wait until the single connection has been released.
 		await this.#connectionMutex.lock()
 
 		// biome-ignore lint/style/noNonNullAssertion: :shrug:

package/lib/index.ts

@@ -5,11 +5,11 @@
  *
  *   The one way a Mailwoman SQLite connection comes into being.
  *
- *   `DatabaseClient` opens the file; `openBuiltClient` opens a built artifact with the seal check. A caller says which
- *   file and which schema and never constructs the connection, so one database carries one schema, one owner, and a
+ *   `DatabaseClient` opens the file; `openBuiltClient` opens a built artifact with the seal check. A caller specifies which
+ *   file and schema. It never constructs the connection, so one database has one schema, one owner and a
  *   lifetime `using` can end. `new DatabaseSync` appears once in this package and nowhere else in the repository.
  *
- *   It lives outside `@mailwoman/core` because it needs none of core's 11 MB of parser reference data — its whole
+ *   It lives outside `@mailwoman/core` because it needs none of core's 11 MB of parser reference data. Its whole
  *   dependency set is `kysely`. That is what lets the leaf lookups use it.
  */
 
@@ -17,9 +17,10 @@ export * from "#batched"
 export * from "#client"
 export * from "#database-schema"
 export * from "#dialect"
-export * from "#dialect-config"
+export * from "#dialect/config"
 export * from "#introspection"
+export * from "#lookup"
 export * from "#schema-columns"
 export * from "#sealed"
-export * from "#sealed-build"
-export * from "#sealed-db"
+export * from "#sealed/build"
+export * from "#sealed/db"

package/lib/introspection.ts

@@ -4,8 +4,8 @@
  * @author Teffen Ellis, et al.
  * @file Questions asked of `sqlite_master`.
  *
- *   ITS OWN SUBPATH ON PURPOSE — do not fold this into the package barrel. `@mailwoman/sqlite`'s root export
- *   reaches `node:sqlite`, and the docs demo bundles this package for the browser; importing the barrel to
+ *   its own subpath on purpose — do not fold this into the package barrel. `@mailwoman/sqlite`'s root export
+ *   reaches `node:sqlite`, and the docs demo bundles this package for the browser. importing the barrel to
  *   ask whether a table exists dragged the builtin into that graph. The split is what keeps these three
  *   pure-SQL questions reachable from a bundled consumer.
  */
@@ -13,14 +13,18 @@
 import type { DatabaseClient } from "#client"
 
 /**
- * Whether a TABLE named `name` exists. An index, view or trigger of that name answers `false`.
+ * Whether a table exists with the value in `name`.
+ *
+ * An index, view or trigger of that name answers `false`.
  */
 export function tableExists<DB>(db: DatabaseClient<DB>, name: string): boolean {
 	return Boolean(db.prepare("SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = ?").get(name))
 }
 
 /**
- * `COUNT(*)` over `table`. The name is interpolated, so it must come from the schema, never from input.
+ * `count(*)` over `table`.
+ *
+ * The name is interpolated, so it must come from the schema, never from input.
  */
 export function countRows<DB>(db: DatabaseClient<DB>, table: string): number {
 	const row = db.prepare(`SELECT COUNT(*) AS n FROM ${table}`).get() as { n?: number } | undefined
@@ -29,14 +33,16 @@ export function countRows<DB>(db: DatabaseClient<DB>, table: string): number {
 }
 
 /**
- * Whether an INDEX named `name` exists.
+ * Whether an index exists with the value in `name`.
  */
 export function indexExists<DB>(db: DatabaseClient<DB>, name: string): boolean {
 	return Boolean(db.prepare("SELECT 1 FROM sqlite_master WHERE type = 'index' AND name = ?").get(name))
 }
 
 /**
- * Every table name, sorted. Virtual tables are tables here, the way `sqlite_master` records them.
+ * Every table name, sorted.
+ *
+ * Virtual tables are tables here, the way `sqlite_master` records them.
  */
 export function listTables<DB>(db: DatabaseClient<DB>): string[] {
 	const rows = db.prepare("SELECT name FROM sqlite_master WHERE type = 'table' ORDER BY name").all() as Array<{
@@ -47,8 +53,9 @@ export function listTables<DB>(db: DatabaseClient<DB>): string[] {
 }
 
 /**
- * Whether `table` has a column named `column`. The table name is spliced into a PRAGMA, so it must come from the
- * schema, never from input.
+ * Whether `table` has a column with the value in `column`.
+ *
+ * The table name is spliced into a pragma, so it must come from the schema, never from input.
  */
 export function hasColumn<DB>(db: DatabaseClient<DB>, table: string, column: string): boolean {
 	const rows = db.prepare(`PRAGMA table_info(${table})`).all() as Array<{ name: string }>

package/lib/lookup.ts

@@ -0,0 +1,77 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   The shared shape of a reader over one SQLite artifact.
+ *   A lookup either opens the file it is given or adopts a connection already held by the caller.
+ *   and it closes on disposal only what it opened.
+ */
+
+import type { PathBuilderLike } from "path-ts"
+
+import { DatabaseClient, type DatabaseSyncOptions } from "#client"
+
+/**
+ * Where a lookup's connection comes from.
+ * Exactly one of the two fields is set.
+ */
+export interface SQLiteLookupOptions<DB> {
+	/**
+	 * The database file to open.
+	 * The lookup owns the connection and closes it on disposal.
+	 */
+	databasePath?: PathBuilderLike
+	/**
+	 * A connection the caller opened.
+	 * The lookup reads through it and leaves it open on disposal.
+	 */
+	database?: DatabaseClient<DB>
+}
+
+/**
+ * A reader over one SQLite database that owns only the connection it opened.
+ *
+ * A subclass passes its options to `super` and reads through `this.database`.
+ * It inherits the disposal that closes an opened file and leaves an adopted one unchanged.
+ *
+ * The connection is opened read-only unless the subclass passes its own open options.
+ */
+export abstract class SQLiteLookup<DB> implements Disposable {
+	readonly #database: DatabaseClient<DB>
+	/**
+	 * The connections this instance opened.
+	 *
+	 * An adopted connection is never a member, so disposal cannot reach it.
+	 */
+	readonly #owned = new DisposableStack()
+
+	protected constructor(source: SQLiteLookupOptions<DB>, openOptions: DatabaseSyncOptions = { readOnly: true }) {
+		if (source.database && source.databasePath) {
+			throw new Error(`${new.target.name}: pass either \`database\` or \`databasePath\`, not both`)
+		}
+
+		if (source.database) {
+			this.#database = source.database
+		} else if (source.databasePath) {
+			this.#database = this.#owned.use(new DatabaseClient<DB>(source.databasePath, openOptions))
+		} else {
+			throw new Error(`${new.target.name}: one of \`database\` or \`databasePath\` is required`)
+		}
+	}
+
+	/**
+	 * The connection this lookup reads through.
+	 */
+	protected get database(): DatabaseClient<DB> {
+		return this.#database
+	}
+
+	/**
+	 * Close the connection this lookup opened.
+	 * An adopted connection stays open for its owner.
+	 */
+	[Symbol.dispose](): void {
+		this.#owned[Symbol.dispose]()
+	}
+}

package/lib/schema-columns.ts

@@ -2,22 +2,21 @@
  * @copyright Sister Software
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
- *
- *   The column groups every polygon layer's schema repeats, as schema-builder helpers — so the
- *   `WITHOUT ROWID`-versus-blob discipline is stated once, beside the columns it governs.
  */
 
 import type { CreateTableBuilder, Kysely } from "kysely"
 
 /**
- * The slice of a Kysely handle a schema module's DDL touches. Kysely is invariant in its schema parameter, so naming
- * only the member the builders call lets a caller pass its own wider handle.
+ * The subset of a Kysely handle a schema module's DDL touches.
+ *
+ * Kysely is invariant in its schema parameter, so naming only this member lets
+ * a caller pass its own wider handle.
  */
 export type SchemaHandle<DB> = Pick<Kysely<DB>, "schema">
 
 /**
- * The precomputed bounding box every polygon table carries — truth tables and extent tables alike — in the order the
- * sealed artifacts store it.
+ * The precomputed bounding box every polygon table includes — truth tables
+ * and extent tables alike — in the order the sealed artifacts store it.
  */
 export function addBoundingBoxColumns<TB extends string, C extends string>(
 	builder: CreateTableBuilder<TB, C>
@@ -30,12 +29,12 @@ export function addBoundingBoxColumns<TB extends string, C extends string>(
 }
 
 /**
- * The unsimplified ring blob a polygon truth table carries, kept apart from {@link addBoundingBoxColumns} because one
- * layer stores its own ring-derived columns between the box and the blob, and the stored column order of a sealed
- * artifact is part of what its readers see.
+ * The unsimplified ring blob a polygon truth table stores, separate from
+ * {@link addBoundingBoxColumns} because one layer's stored column order between the box
+ * and the blob is part of what sealed-artifact readers see.
  *
- * A table taking this stays a PLAIN rowid table, never `WITHOUT ROWID`: the `rings` blob is exactly the payload
- * clustering into the B-tree penalizes — every index page becomes a geometry page.
+ * A table taking this stays a plain rowid table, never `without rowid`: the `rings`
+ * blob is exactly the payload clustering into the B-tree penalizes.
  */
 export function addRingsColumn<TB extends string, C extends string>(
 	builder: CreateTableBuilder<TB, C>
@@ -44,8 +43,8 @@ export function addRingsColumn<TB extends string, C extends string>(
 }
 
 /**
- * The precomputed bounding box plus the unsimplified ring blob every polygon truth table carries:
- * {@link addBoundingBoxColumns} then {@link addRingsColumn}, with nothing between them.
+ * The precomputed bounding box plus the unsimplified ring blob every polygon truth table includes:
+ * {@link addBoundingBoxColumns} then {@link addRingsColumn}, with no columns between them.
  */
 export function addRingGeometryColumns<TB extends string, C extends string>(
 	builder: CreateTableBuilder<TB, C>
@@ -54,12 +53,12 @@ export function addRingGeometryColumns<TB extends string, C extends string>(
 }
 
 /**
- * The cell-index columns every polygon summary tier carries: the 48-bit short cell, the resolution it was captured at
- * (a short cell does not name its own, and a mixed-resolution table cannot be probed without it), the key columns the
- * row names — one, or several in the order given, for a layer whose rows are keyed per scenario — and its containment.
+ * The cell-index columns every polygon summary tier includes: the 48-bit short cell,
+ * the resolution it was captured at, the key columns the row names and its containment.
  *
- * Small fixed-width rows probed by their exact primary key are the `WITHOUT ROWID` shape — the caller adds its own
- * primary-key constraint and the raw `without rowid` modifier, because the key differs per layer.
+ * Small fixed-width rows probed by their exact primary key are the `without rowid`
+ * shape. the caller adds its own primary-key constraint and the raw `without rowid`
+ * modifier because the key differs per layer.
  */
 export function addCellIndexColumns<TB extends string, C extends string, K extends string>(
 	builder: CreateTableBuilder<TB, C>,

package/lib/{sealed-build.ts → sealed/build.ts}

@@ -2,56 +2,45 @@
  * @copyright Sister Software
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
- *
- *   The sealed polygon-artifact build sequence: one temp file beside the destination, two handles, every
- *   cleanup path, then `VACUUM` → seal → atomic swap.
- *
- *   THE INGEST AND THE FINISH PHASES USE SEPARATE HANDLES, ALWAYS — including the in-process path, which does
- *   not need them separated. The batched path DOES: its children open the same file, so the parent's handle
- *   has to be closed across them, and a single shared handle silently becomes a closed one by the time the
- *   finish phase runs. Doing it one way in both paths is what puts the fixture suites on the same sequence a
- *   national build takes.
  */
 
 import { removePathIfPresent } from "@mailwoman/core/fs/writers"
+import type { PathBuilderLike } from "path-ts"
 
 import { DatabaseClient } from "#client"
-import { sealDatabase, swapDatabaseIntoPlace } from "#sealed-db"
+import { sealDatabase, swapDatabaseIntoPlace } from "#sealed/db"
 
 export interface BuildSealedArtifactOptions<DB, Streamed, Result> {
 	/**
-	 * Where the sealed artifact lands. The build writes beside it and swaps.
+	 * Where the sealed artifact lands.
 	 */
-	out: string
+	out: PathBuilderLike
 	/**
-	 * Create every table the build writes — the layer's own, the contract's, and any build-only scratch table (which the
-	 * finish phase drops before the artifact is sealed).
+	 * Create every table the build writes, including any build-only scratch table the finish phase drops.
 	 */
 	createTables: (database: DatabaseClient<DB>) => Promise<void>
 	/**
-	 * The in-process ingest, run under the FIRST handle. Return `undefined` to defer to {@link batched}; any writes made
-	 * before deferring (attribute preloads) are kept.
+	 * The in-process ingest, run under the first handle.
+	 *
+	 * Return `undefined` to defer to {@link batched}, keeping any writes made before deferring.
 	 */
 	ingest: (database: DatabaseClient<DB>) => Promise<Streamed | undefined>
 	/**
-	 * The bounded child-process ingest, run while the parent holds NO handle. Each child opens the temp file and appends;
-	 * chunks run one at a time, so there is exactly one writer at every instant.
+	 * The bounded child-process ingest, run while the parent holds no handle: each child opens the
+	 * temp file and appends one chunk at a time, so there is exactly one writer at every instant.
 	 */
 	batched?: (tmpPath: string) => Promise<Streamed>
 	/**
-	 * Post-ingest work under the SECOND handle: assertions over what was streamed, index/coverage/manifest writes,
-	 * dropping any scratch table. `VACUUM`, the seal and the swap follow; the artifact's on-disk size is measurable only
-	 * after this returns and the swap lands.
+	 * Post-ingest work under the second handle: assertions over what was streamed,
+	 * index/coverage/manifest writes, dropping any scratch table.
+	 *
+	 * The artifact's on-disk size is measurable only after this returns and the swap lands.
 	 */
 	finish: (database: DatabaseClient<DB>, streamed: Streamed) => Promise<Result>
 }
 
 /**
  * Run one sealed-artifact build.
- *
- * Every failure path removes the temp file: a failed build otherwise leaves a partial multi-gigabyte file whose name
- * carries this process's pid, so nothing would ever pick it up again — the difference between a retry loop that fails
- * and one that fills a disk.
  */
 export async function buildSealedArtifact<DB, Streamed, Result>(
 	options: BuildSealedArtifactOptions<DB, Streamed, Result>
@@ -61,7 +50,7 @@ export async function buildSealedArtifact<DB, Streamed, Result>(
 	let streamed: Streamed | undefined
 
 	{
-		await using kdb = new DatabaseClient<DB>(tmpPath)
+		using kdb = new DatabaseClient<DB>(tmpPath)
 
 		try {
 			kdb.exec("PRAGMA journal_mode = OFF")