@mailwoman/sqlite 9.2.0

package/lib/sealed-build.ts

@@ -0,0 +1,117 @@
+/**
+ * @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 { DatabaseClient } from "#client"
+import { sealDatabase, swapDatabaseIntoPlace } from "#sealed-db"
+
+export interface BuildSealedArtifactOptions<DB, Streamed, Result> {
+	/**
+	 * Where the sealed artifact lands. The build writes beside it and swaps.
+	 */
+	out: string
+	/**
+	 * 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).
+	 */
+	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.
+	 */
+	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.
+	 */
+	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.
+	 */
+	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>
+): Promise<Result> {
+	const tmpPath = `${options.out}.tmp-${process.pid}`
+
+	let streamed: Streamed | undefined
+
+	{
+		await using kdb = new DatabaseClient<DB>(tmpPath)
+
+		try {
+			kdb.exec("PRAGMA journal_mode = OFF")
+			kdb.exec("PRAGMA synchronous = OFF")
+
+			await options.createTables(kdb)
+
+			streamed = await options.ingest(kdb)
+		} catch (error) {
+			await kdb.destroy().catch(() => undefined)
+			await removePathIfPresent(tmpPath)
+
+			throw error
+		}
+	}
+
+	if (streamed === undefined) {
+		if (!options.batched) {
+			throw new Error("buildSealedArtifact: the in-process ingest deferred and no batched ingest was supplied")
+		}
+
+		try {
+			streamed = await options.batched(tmpPath)
+		} catch (error) {
+			await removePathIfPresent(tmpPath)
+
+			throw error
+		}
+	}
+
+	const kdb = new DatabaseClient<DB>(tmpPath)
+
+	try {
+		kdb.exec("PRAGMA journal_mode = OFF")
+		kdb.exec("PRAGMA synchronous = OFF")
+
+		const result = await options.finish(kdb, streamed)
+
+		kdb.exec("VACUUM")
+
+		await kdb.destroy()
+
+		await sealDatabase(tmpPath)
+		await swapDatabaseIntoPlace(tmpPath, options.out)
+
+		return result
+	} catch (error) {
+		await kdb.destroy().catch(() => undefined)
+		await removePathIfPresent(tmpPath)
+
+		throw error
+	}
+}

package/lib/sealed-db.ts

@@ -0,0 +1,170 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   The sealed-artifact invariant: every SQLite DB a build produces is a READ-ONLY asset. `sealDatabase`
+ *   is the last step of every builder — checkpoint, freeze the journal, chmod 0444. `openBuiltClient`
+ *   (`@mailwoman/sqlite/sealed`) is how anything opens a data artifact; a write-mode open of a sealed
+ *   file throws a NAMED error pointing at the rebuild command instead of a cryptic SQLITE_READONLY. Unsealing is deliberate and
+ *   manual (`chmod u+w`), never programmatic — rebuild, don't mutate.
+ *
+ *   `swapDatabaseIntoPlace` is the other half of that invariant — the atomic publish step AGENTS.md
+ *   specifies in prose ("build it successfully, then move the previous version to a temp directory,
+ *   and then move the new version into place"). It lives here because this module already owns the
+ *   built-artifact lifecycle, and because a rule the project states in prose and implements more than
+ *   once in code should be a function.
+ */
+
+import type { DatabaseSync } from "node:sqlite"
+
+import { pathExists, statPath } from "@mailwoman/core/fs/readers"
+import { changeMode, movePath, removePath, removePathIfPresent } from "@mailwoman/core/fs/writers"
+import { basename } from "path-ts"
+
+/**
+ * The one capability {@link assertDatabaseIntegrity} needs. Narrowing to it rather than naming a handle type lets a
+ * `DatabaseClient` satisfy the parameter with no import and no cast.
+ */
+type IntegrityProbe = Pick<DatabaseSync, "prepare">
+
+/**
+ * `node:sqlite` via {@link process.getBuiltinModule} — invisible to bundlers. A static import here would ride the
+ * `@mailwoman/core/utils` barrel into every consumer, and the docs' plugin loader (which transpiles `docusaurus.config`
+ * imports) can't resolve `node:sqlite` (CI: "Cannot find module 'sqlite'"). The builtin accessor keeps `node:sqlite`
+ * out of the static import graph with zero resolve surface.
+ */
+function sqlite(): typeof import("node:sqlite") {
+	return process.getBuiltinModule("node:sqlite")
+}
+
+/**
+ * A write-mode open was attempted on a sealed (0444) data artifact.
+ */
+export class SealedArtifactError extends Error {
+	constructor(path: string) {
+		super(
+			`${basename(path)} is a sealed read-only artifact — rebuild it via \`mailwoman gazetteer build …\`, ` +
+				`don't mutate it. (Deliberate unseal: chmod u+w — but prefer a rebuild.)`
+		)
+
+		this.name = "SealedArtifactError"
+	}
+}
+
+/**
+ * True when the artifact exists and carries no write bits (the sealed state {@link sealDatabase} leaves).
+ */
+export async function isSealed(path: string): Promise<boolean> {
+	return (await pathExists(path)) && ((await statPath(path)).mode & 0o222) === 0
+}
+
+/**
+ * Finalize a built DB: WAL-checkpoint → `journal_mode = DELETE` → remove `-wal`/`-shm` sidecars → `chmod 0o444`.
+ * Idempotent. Throws if the checkpoint cannot complete (another writer holds the DB).
+ */
+export async function sealDatabase(path: string): Promise<void> {
+	// A previously sealed artifact needs the write bit back for the journal-mode switch.
+	if (await isSealed(path)) {
+		await changeMode(path, 0o644)
+	}
+
+	let mode: { journal_mode: string }
+
+	{
+		using db = new (sqlite().DatabaseSync)(path)
+		const checkpoint = db.prepare("PRAGMA wal_checkpoint(TRUNCATE)").get() as { busy: number }
+
+		if (checkpoint.busy !== 0) {
+			throw new Error(`sealDatabase: WAL checkpoint busy on ${path} — close all writers first`)
+		}
+
+		mode = db.prepare("PRAGMA journal_mode = DELETE").get() as { journal_mode: string }
+	}
+
+	if (mode.journal_mode !== "delete") {
+		throw new Error(`sealDatabase: journal_mode switch failed on ${path} (still ${mode.journal_mode})`)
+	}
+
+	for (const sidecar of [`${path}-wal`, `${path}-shm`]) {
+		if (await pathExists(sidecar)) {
+			await removePath(sidecar)
+		}
+	}
+
+	await changeMode(path, 0o444)
+}
+
+/**
+ * Verify a freshly-built database is not corrupt, immediately before it is sealed and published.
+ *
+ * Belongs beside {@link sealDatabase} for the same reason `swapDatabaseIntoPlace` does: the check is part of the
+ * built-artifact lifecycle, and every builder was running it from its own copy. `integrity_check` answers with the
+ * single row `{ integrity_check: "ok" }` on a healthy file and one row per problem otherwise, so only the first matters
+ * — a builder that reads the column and compares it to `"ok"` has done the whole check.
+ *
+ * @throws When the database reports anything other than `ok`, naming the artifact and what SQLite said.
+ */
+export function assertDatabaseIntegrity(db: IntegrityProbe, artifact: string): void {
+	const row = db.prepare("PRAGMA integrity_check").get() as { integrity_check: string } | undefined
+	const verdict = row?.integrity_check
+
+	if (verdict !== "ok") {
+		throw new Error(`integrity_check failed on ${basename(artifact)}: ${verdict ?? "no result"}`)
+	}
+}
+
+/**
+ * Refuse a write-mode open of a sealed artifact, naming the rebuild command instead of letting SQLite answer
+ * `SQLITE_READONLY`.
+ *
+ * The open itself lives in `@mailwoman/sqlite/sealed` — `openBuiltClient`, which every caller uses. This half stays
+ * here because it is a filesystem predicate, and because this module reaches `node:sqlite` through
+ * {@link process.getBuiltinModule} to keep the `@mailwoman/core/utils` barrel free of it.
+ *
+ * @throws {SealedArtifactError} When `path` is sealed.
+ */
+export async function assertUnsealedForWrite(path: string): Promise<void> {
+	if (await isSealed(path)) throw new SealedArtifactError(path)
+}
+
+/**
+ * Atomically move a freshly-built database into its published location.
+ *
+ * The build writes to a temp path, so a mid-build crash never leaves a half-written DB at `finalPath`. This moves any
+ * prior version aside, slots the new one in, then drops the old — the previous file stays intact until the replacement
+ * is committed, and the `-wal`/`-shm` siblings of BOTH paths are cleared so a stale journal can never be paired with a
+ * new main file.
+ *
+ * Sealing (`sealDatabase`) happens on the temp file BEFORE the swap: a sealed artifact is what gets published, and 0444
+ * does not prevent a rename.
+ */
+export async function swapDatabaseIntoPlace(tmpPath: string, finalPath: string): Promise<void> {
+	const aside = `${finalPath}.old-${process.pid}`
+
+	if (await pathExists(finalPath)) {
+		await movePath(finalPath, aside)
+	}
+
+	for (const sfx of ["-wal", "-shm"]) {
+		await removePathIfPresent(finalPath + sfx)
+	}
+
+	try {
+		await movePath(tmpPath, finalPath)
+	} catch (error) {
+		// The prior version is already aside at this point — a failed forward rename must not leave
+		// the slot empty while a restorable artifact sits one rename away.
+		if ((await pathExists(aside)) && !(await pathExists(finalPath))) {
+			await movePath(aside, finalPath)
+		}
+
+		throw error
+	}
+
+	for (const sfx of ["-wal", "-shm"]) {
+		await removePathIfPresent(tmpPath + sfx)
+	}
+
+	await removePathIfPresent(aside)
+}

package/lib/sealed.ts

@@ -0,0 +1,38 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Opening a built data artifact.
+ *
+ *   This is the other half of the sealed-artifact invariant in `../utils/sealed-db.ts`: that module owns the
+ *   filesystem side (seal, unseal-refusal, atomic swap) and stays free of a static `node:sqlite` import, because it
+ *   rides the `@mailwoman/core/utils` barrel into consumers that cannot resolve one. The open lives here, where
+ *   `DatabaseClient` is already imported and the cost is paid. The open is asynchronous: the write branch awaits the
+ *   seal check against the filesystem before the handle is constructed.
+ */
+
+import { DatabaseClient } from "#client"
+import type { Database } from "#database-schema"
+import { assertUnsealedForWrite } from "#sealed-db"
+
+/**
+ * Open a built data artifact. Read-only by default; `write: true` is for builders working on UNsealed staging, and
+ * throws `SealedArtifactError` against a sealed file.
+ *
+ * Together with `new DatabaseClient(path)` this is the whole set of ways a connection comes into being. `DatabaseSync`
+ * is constructed in exactly one place, inside `DatabaseClient`, so no caller holds a raw handle and no database ends up
+ * described by two schemas.
+ */
+export async function openBuiltClient<DB = Database>(
+	path: string,
+	opts: { write?: boolean } = {}
+): Promise<DatabaseClient<DB>> {
+	if (opts.write) {
+		await assertUnsealedForWrite(path)
+
+		return new DatabaseClient<DB>(path)
+	}
+
+	return new DatabaseClient<DB>(path, { readOnly: true })
+}

package/out/batched.d.ts

@@ -0,0 +1,40 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Batched bulk-write transactions — the `COMMIT`/`BEGIN` cadence every streaming ingest repeats around its
+ *   raw prepared-statement loop.
+ */
+/**
+ * One open batched transaction over a connection.
+ */
+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.
+     */
+    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.
+     */
+    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.
+ */
+export declare function beginBatched(database: {
+    exec(sql: string): void;
+}, options: {
+    rowsPerCommit: number;
+}): BatchedTransaction;
+//# sourceMappingURL=batched.d.ts.map

package/out/batched.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"batched.d.ts","sourceRoot":"","sources":["../lib/batched.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH;;GAEG;AACH,MAAM,WAAW,kBAAkB;IAClC;;;OAGG;IACH,UAAU,IAAI,OAAO,CAAA;IACrB;;OAEG;IACH,MAAM,IAAI,IAAI,CAAA;IACd;;;;OAIG;IACH,eAAe,IAAI,IAAI,CAAA;CACvB;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAC3B,QAAQ,EAAE;IAAE,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,EACrC,OAAO,EAAE;IAAE,aAAa,EAAE,MAAM,CAAA;CAAE,GAChC,kBAAkB,CA6BpB"}

package/out/batched.js

@@ -0,0 +1,41 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Batched bulk-write transactions — the `COMMIT`/`BEGIN` cadence every streaming ingest repeats around its
+ *   raw prepared-statement loop.
+ */
+/**
+ * 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.
+ */
+export function beginBatched(database, options) {
+    let pending = 0;
+    database.exec("BEGIN");
+    return {
+        rowWritten() {
+            pending++;
+            if (pending < options.rowsPerCommit)
+                return false;
+            database.exec("COMMIT");
+            database.exec("BEGIN");
+            pending = 0;
+            return true;
+        },
+        commit() {
+            database.exec("COMMIT");
+        },
+        rollbackQuietly() {
+            try {
+                database.exec("ROLLBACK");
+            }
+            catch {
+                // The temp artifact is discarded either way.
+            }
+        },
+    };
+}
+//# sourceMappingURL=batched.js.map

package/out/batched.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"batched.js","sourceRoot":"","sources":["../lib/batched.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAuBH;;;;;GAKG;AACH,MAAM,UAAU,YAAY,CAC3B,QAAqC,EACrC,OAAkC;IAElC,IAAI,OAAO,GAAG,CAAC,CAAA;IAEf,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,CAAA;IAEtB,OAAO;QACN,UAAU;YACT,OAAO,EAAE,CAAA;YAET,IAAI,OAAO,GAAG,OAAO,CAAC,aAAa;gBAAE,OAAO,KAAK,CAAA;YAEjD,QAAQ,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAA;YACvB,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,CAAA;YAEtB,OAAO,GAAG,CAAC,CAAA;YAEX,OAAO,IAAI,CAAA;QACZ,CAAC;QACD,MAAM;YACL,QAAQ,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAA;QACxB,CAAC;QACD,eAAe;YACd,IAAI,CAAC;gBACJ,QAAQ,CAAC,IAAI,CAAC,UAAU,CAAC,CAAA;YAC1B,CAAC;YAAC,MAAM,CAAC;gBACR,6CAA6C;YAC9C,CAAC;QACF,CAAC;KACD,CAAA;AACF,CAAC"}

package/out/client.d.ts

@@ -0,0 +1,86 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ */
+import { DatabaseSync, type DatabaseSyncOptions, type FunctionOptions, type SQLInputValue, type SQLOutputValue, type StatementSync } from "node:sqlite";
+import { Kysely, type KyselyConfig } from "kysely";
+import { type PathBuilderLike } from "path-ts";
+import type { Database } from "#database-schema";
+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.
+ */
+export type RawStatements = Pick<DatabaseClient, "exec" | "prepare" | "function" | "destroy"> & Disposable;
+export declare class DatabaseClient<DB = Database> extends Kysely<DB> implements Disposable {
+    #private;
+    /**
+     * A memory-only database, for tests and other ephemeral work. The connection is open until the client is disposed.
+     */
+    static temp<DB = Database>(): DatabaseClient<DB>;
+    constructor(location: PathBuilderLike, options?: DatabaseSyncOptions, config?: Partial<KyselyConfig>);
+    constructor(database: DatabaseSync, config?: Partial<KyselyConfig>);
+    constructor(dialectConfig: SqliteDialectConfig, config?: Partial<KyselyConfig>);
+    /**
+     * 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.
+     */
+    exec(sql: string): void;
+    /**
+     * 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;
+    /**
+     * 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.
+     */
+    function(name: string, options: FunctionOptions, fn: (...args: SQLOutputValue[]) => SQLInputValue): void;
+    function(name: string, fn: (...args: SQLOutputValue[]) => SQLInputValue): void;
+    /**
+     * 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.
+     */
+    [Symbol.dispose](): void;
+}
+/**
+ * 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.
+ */
+export type { DatabaseSyncOptions, SQLInputValue, SQLOutputValue, StatementSync } from "node:sqlite";
+//# sourceMappingURL=client.d.ts.map

package/out/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../lib/client.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EACN,YAAY,EACZ,KAAK,mBAAmB,EACxB,KAAK,eAAe,EACpB,KAAK,aAAa,EAClB,KAAK,cAAc,EACnB,KAAK,aAAa,EAClB,MAAM,aAAa,CAAA;AAEpB,OAAO,EAAE,MAAM,EAAE,KAAK,YAAY,EAAE,MAAM,QAAQ,CAAA;AAClD,OAAO,EAAe,KAAK,eAAe,EAAE,MAAM,SAAS,CAAA;AAE3D,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAA;AAEhD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAA;AAE1D;;;;;;;;;;;;;;;;GAgBG;AACH;;;;;;;GAOG;AACH,MAAM,MAAM,aAAa,GAAG,IAAI,CAAC,cAAc,EAAE,MAAM,GAAG,SAAS,GAAG,UAAU,GAAG,SAAS,CAAC,GAAG,UAAU,CAAA;AAE1G,qBAAa,cAAc,CAAC,EAAE,GAAG,QAAQ,CAAE,SAAQ,MAAM,CAAC,EAAE,CAAE,YAAW,UAAU;;IAClF;;OAEG;WACW,IAAI,CAAC,EAAE,GAAG,QAAQ,KAAK,cAAc,CAAC,EAAE,CAAC;gBAM3C,QAAQ,EAAE,eAAe,EAAE,OAAO,CAAC,EAAE,mBAAmB,EAAE,MAAM,CAAC,EAAE,OAAO,CAAC,YAAY,CAAC;gBACxF,QAAQ,EAAE,YAAY,EAAE,MAAM,CAAC,EAAE,OAAO,CAAC,YAAY,CAAC;gBACtD,aAAa,EAAE,mBAAmB,EAAE,MAAM,CAAC,EAAE,OAAO,CAAC,YAAY,CAAC;IAuC9E;;;;;OAKG;IACH,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAIvB;;;;;;OAMG;IACH,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,aAAa;IAInC;;;;OAIG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,eAAe,EAAE,EAAE,EAAE,CAAC,GAAG,IAAI,EAAE,cAAc,EAAE,KAAK,aAAa,GAAG,IAAI;IACxG,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC,GAAG,IAAI,EAAE,cAAc,EAAE,KAAK,aAAa,GAAG,IAAI;IAe9E;;;;;;;;;;OAUG;IACH,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,IAAI;CAGxB;AAED;;;GAGG;AACH,YAAY,EAAE,mBAAmB,EAAE,aAAa,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,aAAa,CAAA"}

package/out/client.js

@@ -0,0 +1,85 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ */
+import { DatabaseSync, } from "node:sqlite";
+import { Kysely } from "kysely";
+import { PathBuilder } from "path-ts";
+import { SqliteDialect } from "#dialect";
+export class DatabaseClient extends Kysely {
+    /**
+     * A memory-only database, for tests and other ephemeral work. The connection is open until the client is disposed.
+     */
+    static temp() {
+        return new DatabaseClient(":memory:");
+    }
+    #database;
+    constructor(source, optionsOrConfig, config) {
+        let database;
+        let kyselyConfig;
+        if (typeof source === "string" || source instanceof PathBuilder) {
+            const location = source.toString();
+            const options = optionsOrConfig;
+            // node:sqlite checks the argument count, not the value: `new DatabaseSync(path, undefined)` throws.
+            const openArgs = options ? [location, options] : [location];
+            database = new DatabaseSync(...openArgs);
+            kyselyConfig = config;
+        }
+        else {
+            const dialectConfig = "database" in source ? source : { database: source };
+            if (typeof dialectConfig.database === "function") {
+                throw new TypeError("DatabaseClient needs an open connection: a lazy `() => Promise<DatabaseSync>` leaves `exec` and " +
+                    "`prepare` with nothing to reach. Pass the database path instead.");
+            }
+            database = dialectConfig.database;
+            kyselyConfig = optionsOrConfig;
+        }
+        super({
+            ...kyselyConfig,
+            dialect: new SqliteDialect({ database }),
+        });
+        this.#database = database;
+    }
+    /**
+     * 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.
+     */
+    exec(sql) {
+        this.#database.exec(sql);
+    }
+    /**
+     * 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) {
+        return this.#database.prepare(sql);
+    }
+    function(name, optionsOrFn, fn) {
+        if (typeof optionsOrFn === "function") {
+            this.#database.function(name, optionsOrFn);
+            return;
+        }
+        this.#database.function(name, optionsOrFn, fn);
+    }
+    /**
+     * 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.
+     */
+    [Symbol.dispose]() {
+        this.#database[Symbol.dispose]();
+    }
+}
+//# sourceMappingURL=client.js.map

package/out/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../lib/client.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EACN,YAAY,GAMZ,MAAM,aAAa,CAAA;AAEpB,OAAO,EAAE,MAAM,EAAqB,MAAM,QAAQ,CAAA;AAClD,OAAO,EAAE,WAAW,EAAwB,MAAM,SAAS,CAAA;AAG3D,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAA;AA8BxC,MAAM,OAAO,cAA8B,SAAQ,MAAU;IAC5D;;OAEG;IACI,MAAM,CAAC,IAAI;QACjB,OAAO,IAAI,cAAc,CAAK,UAAU,CAAC,CAAA;IAC1C,CAAC;IAEQ,SAAS,CAAc;IAKhC,YACC,MAA4D,EAC5D,eAA6D,EAC7D,MAA8B;QAE9B,IAAI,QAAsB,CAAA;QAC1B,IAAI,YAA+C,CAAA;QAEnD,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,MAAM,YAAY,WAAW,EAAE,CAAC;YACjE,MAAM,QAAQ,GAAG,MAAM,CAAC,QAAQ,EAAE,CAAA;YAClC,MAAM,OAAO,GAAG,eAAkD,CAAA;YAClE,oGAAoG;YACpG,MAAM,QAAQ,GAAmC,OAAO,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAA;YAE3F,QAAQ,GAAG,IAAI,YAAY,CAAC,GAAG,QAAQ,CAAC,CAAA;YACxC,YAAY,GAAG,MAAM,CAAA;QACtB,CAAC;aAAM,CAAC;YACP,MAAM,aAAa,GAAG,UAAU,IAAI,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,MAAM,EAAE,CAAA;YAE1E,IAAI,OAAO,aAAa,CAAC,QAAQ,KAAK,UAAU,EAAE,CAAC;gBAClD,MAAM,IAAI,SAAS,CAClB,kGAAkG;oBACjG,kEAAkE,CACnE,CAAA;YACF,CAAC;YAED,QAAQ,GAAG,aAAa,CAAC,QAAQ,CAAA;YACjC,YAAY,GAAG,eAAoD,CAAA;QACpE,CAAC;QAED,KAAK,CAAC;YACL,GAAG,YAAY;YACf,OAAO,EAAE,IAAI,aAAa,CAAC,EAAE,QAAQ,EAAE,CAAC;SACxC,CAAC,CAAA;QAEF,IAAI,CAAC,SAAS,GAAG,QAAQ,CAAA;IAC1B,CAAC;IAED;;;;;OAKG;IACH,IAAI,CAAC,GAAW;QACf,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,GAAG,CAAC,CAAA;IACzB,CAAC;IAED;;;;;;OAMG;IACH,OAAO,CAAC,GAAW;QAClB,OAAO,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,GAAG,CAAC,CAAA;IACnC,CAAC;IASD,QAAQ,CACP,IAAY,EACZ,WAA6E,EAC7E,EAAiD;QAEjD,IAAI,OAAO,WAAW,KAAK,UAAU,EAAE,CAAC;YACvC,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC,CAAA;YAE1C,OAAM;QACP,CAAC;QAED,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,IAAI,EAAE,WAAW,EAAE,EAAG,CAAC,CAAA;IAChD,CAAC;IAED;;;;;;;;;;OAUG;IACH,CAAC,MAAM,CAAC,OAAO,CAAC;QACf,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,OAAO,CAAC,EAAE,CAAA;IACjC,CAAC;CACD"}

package/out/database-schema.d.ts

@@ -0,0 +1,30 @@
+/**
+ * @copyright Sister Software
+ * @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).
+ */
+/**
+ * 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.
+ */
+export type Database = Record<string, never>;
+//# sourceMappingURL=database-schema.d.ts.map

package/out/database-schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"database-schema.d.ts","sourceRoot":"","sources":["../lib/database-schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH;;;;;;;GAOG;AACH,MAAM,MAAM,QAAQ,GAAG,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAAA"}

package/out/database-schema.js

@@ -0,0 +1,22 @@
+/**
+ * @copyright Sister Software
+ * @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).
+ */
+export {};
+//# sourceMappingURL=database-schema.js.map

package/out/database-schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"database-schema.js","sourceRoot":"","sources":["../lib/database-schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG"}