@mailwoman/sqlite 9.2.0

package/out/sealed-build.js

@@ -0,0 +1,71 @@
+/**
+ * @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";
+/**
+ * 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(options) {
+    const tmpPath = `${options.out}.tmp-${process.pid}`;
+    let streamed;
+    {
+        await using kdb = new DatabaseClient(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(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;
+    }
+}
+//# sourceMappingURL=sealed-build.js.map

package/out/sealed-build.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sealed-build.js","sourceRoot":"","sources":["../lib/sealed-build.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAA;AAEhE,OAAO,EAAE,cAAc,EAAE,MAAM,SAAS,CAAA;AACxC,OAAO,EAAE,YAAY,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAA;AA8BhE;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB,CACxC,OAAyD;IAEzD,MAAM,OAAO,GAAG,GAAG,OAAO,CAAC,GAAG,QAAQ,OAAO,CAAC,GAAG,EAAE,CAAA;IAEnD,IAAI,QAA8B,CAAA;IAElC,CAAC;QACA,YAAY,GAAG,GAAG,IAAI,cAAc,CAAK,OAAO,CAAC,CAAA;QAEjD,IAAI,CAAC;YACJ,GAAG,CAAC,IAAI,CAAC,2BAA2B,CAAC,CAAA;YACrC,GAAG,CAAC,IAAI,CAAC,0BAA0B,CAAC,CAAA;YAEpC,MAAM,OAAO,CAAC,YAAY,CAAC,GAAG,CAAC,CAAA;YAE/B,QAAQ,GAAG,MAAM,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,CAAA;QACrC,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YAChB,MAAM,GAAG,CAAC,OAAO,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAA;YAC1C,MAAM,mBAAmB,CAAC,OAAO,CAAC,CAAA;YAElC,MAAM,KAAK,CAAA;QACZ,CAAC;IACF,CAAC;IAED,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;QAC5B,IAAI,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC;YACtB,MAAM,IAAI,KAAK,CAAC,wFAAwF,CAAC,CAAA;QAC1G,CAAC;QAED,IAAI,CAAC;YACJ,QAAQ,GAAG,MAAM,OAAO,CAAC,OAAO,CAAC,OAAO,CAAC,CAAA;QAC1C,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YAChB,MAAM,mBAAmB,CAAC,OAAO,CAAC,CAAA;YAElC,MAAM,KAAK,CAAA;QACZ,CAAC;IACF,CAAC;IAED,MAAM,GAAG,GAAG,IAAI,cAAc,CAAK,OAAO,CAAC,CAAA;IAE3C,IAAI,CAAC;QACJ,GAAG,CAAC,IAAI,CAAC,2BAA2B,CAAC,CAAA;QACrC,GAAG,CAAC,IAAI,CAAC,0BAA0B,CAAC,CAAA;QAEpC,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,MAAM,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAA;QAElD,GAAG,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAA;QAElB,MAAM,GAAG,CAAC,OAAO,EAAE,CAAA;QAEnB,MAAM,YAAY,CAAC,OAAO,CAAC,CAAA;QAC3B,MAAM,qBAAqB,CAAC,OAAO,EAAE,OAAO,CAAC,GAAG,CAAC,CAAA;QAEjD,OAAO,MAAM,CAAA;IACd,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QAChB,MAAM,GAAG,CAAC,OAAO,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAA;QAC1C,MAAM,mBAAmB,CAAC,OAAO,CAAC,CAAA;QAElC,MAAM,KAAK,CAAA;IACZ,CAAC;AACF,CAAC"}

package/out/sealed-db.d.ts

@@ -0,0 +1,74 @@
+/**
+ * @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";
+/**
+ * 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">;
+/**
+ * A write-mode open was attempted on a sealed (0444) data artifact.
+ */
+export declare class SealedArtifactError extends Error {
+    constructor(path: string);
+}
+/**
+ * True when the artifact exists and carries no write bits (the sealed state {@link sealDatabase} leaves).
+ */
+export declare function isSealed(path: string): Promise<boolean>;
+/**
+ * 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 declare function sealDatabase(path: string): Promise<void>;
+/**
+ * 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 declare function assertDatabaseIntegrity(db: IntegrityProbe, artifact: string): void;
+/**
+ * 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 declare function assertUnsealedForWrite(path: string): Promise<void>;
+/**
+ * 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 declare function swapDatabaseIntoPlace(tmpPath: string, finalPath: string): Promise<void>;
+export {};
+//# sourceMappingURL=sealed-db.d.ts.map

package/out/sealed-db.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sealed-db.d.ts","sourceRoot":"","sources":["../lib/sealed-db.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AAM/C;;;GAGG;AACH,KAAK,cAAc,GAAG,IAAI,CAAC,YAAY,EAAE,SAAS,CAAC,CAAA;AAYnD;;GAEG;AACH,qBAAa,mBAAoB,SAAQ,KAAK;gBACjC,IAAI,EAAE,MAAM;CAQxB;AAED;;GAEG;AACH,wBAAsB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAE7D;AAED;;;GAGG;AACH,wBAAsB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CA8B9D;AAED;;;;;;;;;GASG;AACH,wBAAgB,uBAAuB,CAAC,EAAE,EAAE,cAAc,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI,CAOlF;AAED;;;;;;;;;GASG;AACH,wBAAsB,sBAAsB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAExE;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,qBAAqB,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CA4B7F"}

package/out/sealed-db.js

@@ -0,0 +1,140 @@
+/**
+ * @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 { pathExists, statPath } from "@mailwoman/core/fs/readers";
+import { changeMode, movePath, removePath, removePathIfPresent } from "@mailwoman/core/fs/writers";
+import { basename } from "path-ts";
+/**
+ * `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() {
+    return process.getBuiltinModule("node:sqlite");
+}
+/**
+ * A write-mode open was attempted on a sealed (0444) data artifact.
+ */
+export class SealedArtifactError extends Error {
+    constructor(path) {
+        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) {
+    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) {
+    // A previously sealed artifact needs the write bit back for the journal-mode switch.
+    if (await isSealed(path)) {
+        await changeMode(path, 0o644);
+    }
+    let mode;
+    {
+        using db = new (sqlite().DatabaseSync)(path);
+        const checkpoint = db.prepare("PRAGMA wal_checkpoint(TRUNCATE)").get();
+        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();
+    }
+    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, artifact) {
+    const row = db.prepare("PRAGMA integrity_check").get();
+    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) {
+    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, finalPath) {
+    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);
+}
+//# sourceMappingURL=sealed-db.js.map

package/out/sealed-db.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sealed-db.js","sourceRoot":"","sources":["../lib/sealed-db.ts"],"names":[],"mappings":"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"}

package/out/sealed.d.ts

@@ -0,0 +1,27 @@
+/**
+ * @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";
+/**
+ * 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 declare function openBuiltClient<DB = Database>(path: string, opts?: {
+    write?: boolean;
+}): Promise<DatabaseClient<DB>>;
+//# sourceMappingURL=sealed.d.ts.map

package/out/sealed.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sealed.d.ts","sourceRoot":"","sources":["../lib/sealed.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,SAAS,CAAA;AACxC,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAA;AAGhD;;;;;;;GAOG;AACH,wBAAsB,eAAe,CAAC,EAAE,GAAG,QAAQ,EAClD,IAAI,EAAE,MAAM,EACZ,IAAI,GAAE;IAAE,KAAK,CAAC,EAAE,OAAO,CAAA;CAAO,GAC5B,OAAO,CAAC,cAAc,CAAC,EAAE,CAAC,CAAC,CAQ7B"}

package/out/sealed.js

@@ -0,0 +1,31 @@
+/**
+ * @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 { 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(path, opts = {}) {
+    if (opts.write) {
+        await assertUnsealedForWrite(path);
+        return new DatabaseClient(path);
+    }
+    return new DatabaseClient(path, { readOnly: true });
+}
+//# sourceMappingURL=sealed.js.map

package/out/sealed.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sealed.js","sourceRoot":"","sources":["../lib/sealed.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,SAAS,CAAA;AAExC,OAAO,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAA;AAEnD;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CACpC,IAAY,EACZ,OAA4B,EAAE;IAE9B,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC;QAChB,MAAM,sBAAsB,CAAC,IAAI,CAAC,CAAA;QAElC,OAAO,IAAI,cAAc,CAAK,IAAI,CAAC,CAAA;IACpC,CAAC;IAED,OAAO,IAAI,cAAc,CAAK,IAAI,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAA;AACxD,CAAC"}

package/out/tsconfig.test.tsbuildinfo

@@ -0,0 +1 @@
+{"root":["../test/unit/client.test.ts","../test/unit/introspection.test.ts","../test/unit/sealed-db.test.ts"],"version":"6.0.3"}

package/package.json

@@ -0,0 +1,172 @@
+{
+  "name": "@mailwoman/sqlite",
+  "version": "9.2.0",
+  "description": "The one way a Mailwoman SQLite connection is opened: a typed Kysely client over node:sqlite, plus the sealed-artifact lifecycle.",
+  "keywords": [
+    "kysely",
+    "sqlite"
+  ],
+  "license": "AGPL-3.0-only OR LicenseRef-Commercial",
+  "contributors": [
+    {
+      "name": "Teffen Ellis",
+      "email": "teffen@sister.software"
+    }
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/sister-software/mailwoman.git",
+    "directory": "packages/sqlite"
+  },
+  "files": [
+    "out/",
+    "*.ts",
+    "!*.test.ts",
+    "!test/**"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "imports": {
+    "#*": {
+      "types": "./out/*.d.ts",
+      "node": "./out/*.js",
+      "default": "./out/*.js"
+    }
+  },
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "types": "./out/index.d.ts",
+      "node": "./out/index.js",
+      "default": "./out/index.js"
+    },
+    "./client": {
+      "types": "./out/client.d.ts",
+      "node": "./out/client.js",
+      "default": "./out/client.js"
+    },
+    "./introspection": {
+      "types": "./out/introspection.d.ts",
+      "node": "./out/introspection.js",
+      "default": "./out/introspection.js"
+    },
+    "./dialect": {
+      "types": "./out/dialect.d.ts",
+      "node": "./out/dialect.js",
+      "default": "./out/dialect.js"
+    },
+    "./dialect-config": {
+      "types": "./out/dialect-config.d.ts",
+      "node": "./out/dialect-config.js",
+      "default": "./out/dialect-config.js"
+    },
+    "./sealed": {
+      "types": "./out/sealed.d.ts",
+      "node": "./out/sealed.js",
+      "default": "./out/sealed.js"
+    },
+    "./sealed-db": {
+      "types": "./out/sealed-db.d.ts",
+      "node": "./out/sealed-db.js",
+      "default": "./out/sealed-db.js"
+    },
+    "./database-schema": {
+      "types": "./out/database-schema.d.ts",
+      "node": "./out/database-schema.js",
+      "default": "./out/database-schema.js"
+    },
+    "./batched": {
+      "types": "./out/batched.d.ts",
+      "node": "./out/batched.js",
+      "default": "./out/batched.js"
+    },
+    "./schema-columns": {
+      "types": "./out/schema-columns.d.ts",
+      "node": "./out/schema-columns.js",
+      "default": "./out/schema-columns.js"
+    },
+    "./sealed-build": {
+      "types": "./out/sealed-build.d.ts",
+      "node": "./out/sealed-build.js",
+      "default": "./out/sealed-build.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public",
+    "exports": {
+      "./package.json": "./package.json",
+      ".": {
+        "types": "./out/index.d.ts",
+        "node": "./out/index.js",
+        "default": "./out/index.js"
+      },
+      "./client": {
+        "types": "./out/client.d.ts",
+        "node": "./out/client.js",
+        "default": "./out/client.js"
+      },
+      "./introspection": {
+        "types": "./out/introspection.d.ts",
+        "node": "./out/introspection.js",
+        "default": "./out/introspection.js"
+      },
+      "./dialect": {
+        "types": "./out/dialect.d.ts",
+        "node": "./out/dialect.js",
+        "default": "./out/dialect.js"
+      },
+      "./dialect-config": {
+        "types": "./out/dialect-config.d.ts",
+        "node": "./out/dialect-config.js",
+        "default": "./out/dialect-config.js"
+      },
+      "./sealed": {
+        "types": "./out/sealed.d.ts",
+        "node": "./out/sealed.js",
+        "default": "./out/sealed.js"
+      },
+      "./sealed-db": {
+        "types": "./out/sealed-db.d.ts",
+        "node": "./out/sealed-db.js",
+        "default": "./out/sealed-db.js"
+      },
+      "./database-schema": {
+        "types": "./out/database-schema.d.ts",
+        "node": "./out/database-schema.js",
+        "default": "./out/database-schema.js"
+      },
+      "./batched": {
+        "types": "./out/batched.d.ts",
+        "node": "./out/batched.js",
+        "default": "./out/batched.js"
+      },
+      "./schema-columns": {
+        "types": "./out/schema-columns.d.ts",
+        "node": "./out/schema-columns.js",
+        "default": "./out/schema-columns.js"
+      },
+      "./sealed-build": {
+        "types": "./out/sealed-build.d.ts",
+        "node": "./out/sealed-build.js",
+        "default": "./out/sealed-build.js"
+      }
+    },
+    "imports": {
+      "#*": {
+        "types": "./out/*.d.ts",
+        "node": "./out/*.js",
+        "default": "./out/*.js"
+      }
+    }
+  },
+  "dependencies": {
+    "kysely": "^0.29.5",
+    "path-ts": "^2.3.0"
+  },
+  "devDependencies": {
+    "@mailwoman/core": "9.2.0"
+  },
+  "engines": {
+    "node": ">=24.18.0"
+  }
+}