@vibesdotdev/localdb 0.0.2 → 1.0.0-rc.3

package/dist/core/open-connection.js

@@ -0,0 +1,70 @@
+import { CaughtFailureSchema } from '@vibesdotdev/kernel';
+import { isSqliteBusy } from "../driver/sqlite-driver.js";
+import { assertRuntimeLive } from "./live-runtime.js";
+import { attempt } from "./outcome.js";
+const STARTUP_TIMEOUT_MS = 5000;
+/** One startup attempt. Cancellation and configuration failures close the handle before returning. */
+function startOnce(runtime, open, configure, deadline, lifecycle) {
+    let db;
+    try {
+        assertRuntimeLive(runtime, 'connection startup', lifecycle);
+        const connection = open();
+        db = connection;
+        configure((sql) => {
+            assertRuntimeLive(runtime, 'connection startup', lifecycle);
+            const remaining = Math.max(0, Math.floor(deadline - lifecycle.now()));
+            connection.exec(`PRAGMA busy_timeout = ${remaining};`);
+            assertRuntimeLive(runtime, 'connection startup', lifecycle);
+            connection.exec(sql);
+        });
+        assertRuntimeLive(runtime, 'connection startup', lifecycle);
+        connection.exec(`PRAGMA busy_timeout = ${STARTUP_TIMEOUT_MS};`);
+        assertRuntimeLive(runtime, 'connection startup', lifecycle);
+        return { opened: true, db: connection };
+    }
+    catch (error) {
+        const opened = db;
+        return { opened: false, cause: error, cleanup: attempt(() => opened?.close()) };
+    }
+}
+/** Keep custody of a just-opened handle across the caller's async continuation. */
+export function assertOpenedConnectionLive(runtime, db, lifecycle = runtime.lifecycle) {
+    const live = attempt(() => assertRuntimeLive(runtime, 'connection startup', lifecycle));
+    if (!live.failed)
+        return;
+    const cleanup = attempt(() => db.close());
+    if (cleanup.failed) {
+        throw new AggregateError([live.cause, cleanup.cause], 'Database startup cancellation and cleanup failed', { cause: live.cause });
+    }
+    throw live.cause;
+}
+/**
+ * Foreground SQLite setup only: one five-second contention budget, with the
+ * calling lifecycle owning the wait and cancellation. Migrations and application
+ * statements never enter this policy.
+ */
+export async function openConfiguredDatabase(runtime, open, configure, lifecycle = runtime.lifecycle) {
+    // Capture the lifecycle: a reload dispatcher must not move this startup to a
+    // replacement generation while its original lifecycle is ending.
+    assertRuntimeLive(runtime, 'connection startup', lifecycle);
+    const deadline = lifecycle.now() + STARTUP_TIMEOUT_MS;
+    for (;;) {
+        assertRuntimeLive(runtime, 'connection startup', lifecycle);
+        const started = startOnce(runtime, open, configure, deadline, lifecycle);
+        if (started.opened)
+            return started.db;
+        if (started.cleanup.failed) {
+            throw new AggregateError([started.cause, started.cleanup.cause], 'Database startup and cleanup failed', {
+                cause: started.cause
+            });
+        }
+        const remaining = deadline - lifecycle.now();
+        if (!isSqliteBusy(CaughtFailureSchema.parse(started.cause)) || remaining <= 0)
+            throw started.cause;
+        await lifecycle.delay(Math.min(10, remaining), lifecycle.signal);
+        assertRuntimeLive(runtime, 'connection startup', lifecycle);
+        if (lifecycle.now() >= deadline)
+            throw started.cause;
+    }
+}
+//# sourceMappingURL=open-connection.js.map

package/dist/core/open-connection.js.map

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

package/dist/core/outcome.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Failure outcomes as values.
+ *
+ * A throw or a rejection becomes a value that carries its cause, so the owner
+ * decides what the failure means (report it, retain it for a retry, or rethrow
+ * it) and nothing can drop it. Runtime and Logging keep the same helpers
+ * private; LocalDB keeps its own until Runtime publishes one.
+ */
+/** What an operation produced, or the failure it raised. */
+export type Outcome<T> = {
+    readonly failed: false;
+    readonly value: T;
+} | {
+    readonly failed: true;
+    readonly cause: unknown;
+};
+/** Run a synchronous operation; a throw becomes a failed outcome carrying its cause. */
+export declare function attempt<T>(run: () => T): Outcome<T>;
+/** Observe an asynchronous operation; a rejection becomes a failed outcome carrying its cause. */
+export declare function settle<T>(operation: PromiseLike<T>): Promise<Outcome<T>>;
+//# sourceMappingURL=outcome.d.ts.map

package/dist/core/outcome.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"outcome.d.ts","sourceRoot":"","sources":["../../src/core/outcome.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,4DAA4D;AAC5D,MAAM,MAAM,OAAO,CAAC,CAAC,IAClB;IAAE,QAAQ,CAAC,MAAM,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAA;CAAE,GAC7C;IAAE,QAAQ,CAAC,MAAM,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAA;CAAE,CAAC;AAEtD,wFAAwF;AACxF,wBAAgB,OAAO,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAMnD;AAED,kGAAkG;AAClG,wBAAgB,MAAM,CAAC,CAAC,EAAE,SAAS,EAAE,WAAW,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAKxE"}

package/dist/core/outcome.js

@@ -0,0 +1,22 @@
+/**
+ * Failure outcomes as values.
+ *
+ * A throw or a rejection becomes a value that carries its cause, so the owner
+ * decides what the failure means (report it, retain it for a retry, or rethrow
+ * it) and nothing can drop it. Runtime and Logging keep the same helpers
+ * private; LocalDB keeps its own until Runtime publishes one.
+ */
+/** Run a synchronous operation; a throw becomes a failed outcome carrying its cause. */
+export function attempt(run) {
+    try {
+        return { failed: false, value: run() };
+    }
+    catch (cause) {
+        return { failed: true, cause };
+    }
+}
+/** Observe an asynchronous operation; a rejection becomes a failed outcome carrying its cause. */
+export function settle(operation) {
+    return Promise.resolve(operation).then((value) => ({ failed: false, value }), (cause) => ({ failed: true, cause }));
+}
+//# sourceMappingURL=outcome.js.map

package/dist/core/outcome.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"outcome.js","sourceRoot":"","sources":["../../src/core/outcome.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAOH,wFAAwF;AACxF,MAAM,UAAU,OAAO,CAAI,GAAY;IACtC,IAAI,CAAC;QACJ,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,GAAG,EAAE,EAAE,CAAC;IACxC,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QAChB,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC;IAChC,CAAC;AACF,CAAC;AAED,kGAAkG;AAClG,MAAM,UAAU,MAAM,CAAI,SAAyB;IAClD,OAAO,OAAO,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,IAAI,CACrC,CAAC,KAAK,EAAc,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,EACjD,CAAC,KAAK,EAAc,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAChD,CAAC;AACH,CAAC"}

package/dist/core/pool-api.d.ts

@@ -0,0 +1,19 @@
+import { type RuntimeRef } from '@vibesdotdev/kernel';
+import type { ConnectionPoolApi } from '../schemas/api.ts';
+import type { SqliteConnection } from '../driver/sqlite-driver.ts';
+/** Stateless compatibility facade. No ambient runtime or physical state. */
+export declare const connectionPool: {
+    forRuntime(runtime: RuntimeRef): Promise<ConnectionPoolApi>;
+    getConnection(runtime: RuntimeRef, path: string, consumer?: string): Promise<SqliteConnection>;
+    releaseConnection(runtime: RuntimeRef, path: string): void;
+    retain(runtime: RuntimeRef, path: string): void;
+    closeConnection(runtime: RuntimeRef, path: string, force?: boolean): boolean;
+    maintain(runtime: RuntimeRef, now?: number): void;
+    closeAll(runtime: RuntimeRef, retainedPaths?: ReadonlySet<string>): void;
+    getStats(runtime?: RuntimeRef): import("./connection-pool.ts").ConnectionStats;
+    withDatabasePathLock<T>(path: string, task: () => Promise<T>, runtime?: RuntimeRef): Promise<T>;
+    assertCanReplaceDatabase(runtime: RuntimeRef, path: string, ownedConnection?: SqliteConnection): void;
+    releaseOrphanedConnection(path: string, runtime?: RuntimeRef): boolean;
+    ownsConnection(path: string, db: SqliteConnection, runtime?: RuntimeRef): boolean;
+};
+//# sourceMappingURL=pool-api.d.ts.map

package/dist/core/pool-api.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pool-api.d.ts","sourceRoot":"","sources":["../../src/core/pool-api.ts"],"names":[],"mappings":"AAAA,OAAO,EAAmB,KAAK,UAAU,EAAE,MAAM,qBAAqB,CAAC;AACvE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAC3D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,4BAA4B,CAAC;AAqBnE,4EAA4E;AAC5E,eAAO,MAAM,cAAc;wBACA,UAAU,GAAG,OAAO,CAAC,iBAAiB,CAAC;2BAGpC,UAAU,QAAQ,MAAM,aAAa,MAAM;+BAG7C,UAAU,QAAQ,MAAM;oBAGnC,UAAU,QAAQ,MAAM;6BAGf,UAAU,QAAQ,MAAM;sBAG/B,UAAU,QAAQ,MAAM;sBAGxB,UAAU,kBAAkB,WAAW,CAAC,MAAM,CAAC;uBAG9C,UAAU;yBAGR,CAAC,QAAQ,MAAM,QAAQ,MAAM,OAAO,CAAC,CAAC,CAAC,YAAY,UAAU;sCAGhD,UAAU,QAAQ,MAAM,oBAAoB,gBAAgB;oCAG9D,MAAM,YAAY,UAAU;yBAGvC,MAAM,MAAM,gBAAgB,YAAY,UAAU;CAGvE,CAAC"}

package/dist/core/pool-api.js

@@ -0,0 +1,59 @@
+import { CapabilityError } from '@vibesdotdev/kernel';
+import { ownedPoolOf, tryOwnedPoolOf } from "./database.js";
+/** Legacy synchronous calls need an explicit, already activated owner. */
+function selected(runtime) {
+    if (!runtime) {
+        throw new CapabilityError('LocalDB pool access requires a runtime.', 'INVALID_INPUT', {
+            reason: 'localdb-runtime-required', retryable: false,
+            recoveryHint: 'Pass the calling runtime, or await connectionPool.forRuntime(runtime).'
+        });
+    }
+    const pool = tryOwnedPoolOf(runtime);
+    if (!pool) {
+        throw new CapabilityError('The runtime has no activated LocalDB pool.', 'UNAVAILABLE', {
+            reason: 'localdb-pool-unavailable', retryable: false,
+            recoveryHint: 'Compose the LocalDB plugin or await connectionPool.forRuntime(runtime).'
+        });
+    }
+    return pool;
+}
+/** Stateless compatibility facade. No ambient runtime or physical state. */
+export const connectionPool = {
+    async forRuntime(runtime) {
+        return ownedPoolOf(runtime);
+    },
+    async getConnection(runtime, path, consumer) {
+        return (await ownedPoolOf(runtime)).getConnection(runtime, path, consumer);
+    },
+    releaseConnection(runtime, path) {
+        selected(runtime).releaseConnection(runtime, path);
+    },
+    retain(runtime, path) {
+        selected(runtime).retain(runtime, path);
+    },
+    closeConnection(runtime, path, force = false) {
+        return selected(runtime).closeConnection(runtime, path, force);
+    },
+    maintain(runtime, now) {
+        selected(runtime).maintain(runtime, now);
+    },
+    closeAll(runtime, retainedPaths) {
+        selected(runtime).closeAll(runtime, retainedPaths);
+    },
+    getStats(runtime) {
+        return selected(runtime).getStats();
+    },
+    withDatabasePathLock(path, task, runtime) {
+        return selected(runtime).withDatabasePathLock(path, task);
+    },
+    assertCanReplaceDatabase(runtime, path, ownedConnection) {
+        selected(runtime).assertCanReplaceDatabase(runtime, path, ownedConnection);
+    },
+    releaseOrphanedConnection(path, runtime) {
+        return selected(runtime).releaseOrphanedConnection(path);
+    },
+    ownsConnection(path, db, runtime) {
+        return selected(runtime).ownsConnection(path, db);
+    }
+};
+//# sourceMappingURL=pool-api.js.map

package/dist/core/pool-api.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pool-api.js","sourceRoot":"","sources":["../../src/core/pool-api.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAmB,MAAM,qBAAqB,CAAC;AAGvE,OAAO,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAE5D,0EAA0E;AAC1E,SAAS,QAAQ,CAAC,OAAoB;IACrC,IAAI,CAAC,OAAO,EAAE,CAAC;QACd,MAAM,IAAI,eAAe,CAAC,yCAAyC,EAAE,eAAe,EAAE;YACrF,MAAM,EAAE,0BAA0B,EAAE,SAAS,EAAE,KAAK;YACpD,YAAY,EAAE,wEAAwE;SACtF,CAAC,CAAC;IACJ,CAAC;IACD,MAAM,IAAI,GAAG,cAAc,CAAC,OAAO,CAAC,CAAC;IACrC,IAAI,CAAC,IAAI,EAAE,CAAC;QACX,MAAM,IAAI,eAAe,CAAC,4CAA4C,EAAE,aAAa,EAAE;YACtF,MAAM,EAAE,0BAA0B,EAAE,SAAS,EAAE,KAAK;YACpD,YAAY,EAAE,yEAAyE;SACvF,CAAC,CAAC;IACJ,CAAC;IACD,OAAO,IAAI,CAAC;AACb,CAAC;AAED,4EAA4E;AAC5E,MAAM,CAAC,MAAM,cAAc,GAAG;IAC7B,KAAK,CAAC,UAAU,CAAC,OAAmB;QACnC,OAAO,WAAW,CAAC,OAAO,CAAC,CAAC;IAC7B,CAAC;IACD,KAAK,CAAC,aAAa,CAAC,OAAmB,EAAE,IAAY,EAAE,QAAiB;QACvE,OAAO,CAAC,MAAM,WAAW,CAAC,OAAO,CAAC,CAAC,CAAC,aAAa,CAAC,OAAO,EAAE,IAAI,EAAE,QAAQ,CAAC,CAAC;IAC5E,CAAC;IACD,iBAAiB,CAAC,OAAmB,EAAE,IAAY;QAClD,QAAQ,CAAC,OAAO,CAAC,CAAC,iBAAiB,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;IACpD,CAAC;IACD,MAAM,CAAC,OAAmB,EAAE,IAAY;QACvC,QAAQ,CAAC,OAAO,CAAC,CAAC,MAAM,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;IACzC,CAAC;IACD,eAAe,CAAC,OAAmB,EAAE,IAAY,EAAE,KAAK,GAAG,KAAK;QAC/D,OAAO,QAAQ,CAAC,OAAO,CAAC,CAAC,eAAe,CAAC,OAAO,EAAE,IAAI,EAAE,KAAK,CAAC,CAAC;IAChE,CAAC;IACD,QAAQ,CAAC,OAAmB,EAAE,GAAY;QACzC,QAAQ,CAAC,OAAO,CAAC,CAAC,QAAQ,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC;IAC1C,CAAC;IACD,QAAQ,CAAC,OAAmB,EAAE,aAAmC;QAChE,QAAQ,CAAC,OAAO,CAAC,CAAC,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC,CAAC;IACpD,CAAC;IACD,QAAQ,CAAC,OAAoB;QAC5B,OAAO,QAAQ,CAAC,OAAO,CAAC,CAAC,QAAQ,EAAE,CAAC;IACrC,CAAC;IACD,oBAAoB,CAAI,IAAY,EAAE,IAAsB,EAAE,OAAoB;QACjF,OAAO,QAAQ,CAAC,OAAO,CAAC,CAAC,oBAAoB,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;IAC3D,CAAC;IACD,wBAAwB,CAAC,OAAmB,EAAE,IAAY,EAAE,eAAkC;QAC7F,QAAQ,CAAC,OAAO,CAAC,CAAC,wBAAwB,CAAC,OAAO,EAAE,IAAI,EAAE,eAAe,CAAC,CAAC;IAC5E,CAAC;IACD,yBAAyB,CAAC,IAAY,EAAE,OAAoB;QAC3D,OAAO,QAAQ,CAAC,OAAO,CAAC,CAAC,yBAAyB,CAAC,IAAI,CAAC,CAAC;IAC1D,CAAC;IACD,cAAc,CAAC,IAAY,EAAE,EAAoB,EAAE,OAAoB;QACtE,OAAO,QAAQ,CAAC,OAAO,CAAC,CAAC,cAAc,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;IACnD,CAAC;CACD,CAAC"}

package/dist/core/slow-statement.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Slow-statement reporting for every pooled connection (C083b).
+ *
+ * WHY THIS EXISTS. SQLite's calls are synchronous, and the pool is one per
+ * process: a statement that runs for seconds holds the thread, so every other
+ * client of that process waits behind it with no progress to show. The pool
+ * already bounded the WAL and the transaction age, but nothing said WHICH
+ * statement cost the time — a `sample` stack names SQLite frames, and a
+ * caller's log names the tool, and neither names the table.
+ *
+ * WHAT IT REPORTS. The consumer that opened the connection, the database path,
+ * the statement's operation, the table it named, and how long it took. Every
+ * one of those is an identifier or a number the pool already holds: the
+ * consumer label is the value-free string the caller passed to
+ * `getConnection`, and the operation and table are read out of the statement's
+ * own keywords. Bound values, SQL text and result rows are never read, so a
+ * report cannot carry a row's contents.
+ *
+ * WHY IT IS NOT LOGGED FROM THE STATEMENT PATH. A report raised while a
+ * statement is unwinding would run on whatever runtime the pool last saw, which
+ * may have ended, and an observability path that can fail the operation it
+ * observes is worse than none. Reports are recorded here and drained by the
+ * pool's existing maintenance tick, which already reports on a live holder.
+ *
+ * The cost when nothing is slow is two `performance.now()` reads and one
+ * comparison per statement.
+ */
+import type { SqliteConnection } from '../driver/sqlite-driver.ts';
+/** A statement that took at least this many milliseconds is recorded. */
+export declare const SLOW_STATEMENT_MS = 250;
+/**
+ * Reports one drain window can hold. A workload that trips the threshold many
+ * times in 30 s is a fact about itself, not a reason to grow without bound: the
+ * pool logs how many it kept and how many it did not.
+ */
+export declare const SLOW_STATEMENT_REPORT_LIMIT = 100;
+/** What a statement does, by its leading keyword. */
+export type SqliteOperation = 'select' | 'insert' | 'update' | 'delete' | 'pragma' | 'transaction' | 'other';
+/** One recorded statement: what it did, which table it named, how long it took. Never its values. */
+export interface SlowStatementReport {
+    readonly operation: SqliteOperation;
+    /** The table the statement named, when it named one that is a bare identifier. */
+    readonly table?: string;
+    readonly elapsedMs: number;
+}
+/** One recorded statement's fields for a log line: the table only when it has one. */
+export interface SlowStatementFields {
+    operation: SqliteOperation;
+    table?: string;
+    elapsedMs: number;
+}
+/** A recorded report as its log fields, with the elapsed time rounded to whole milliseconds. */
+export declare function slowStatementFields(report: SlowStatementReport): SlowStatementFields;
+/** Where recorded reports wait for the pool's maintenance tick. */
+export interface SlowStatementRecorder {
+    /** Record one statement at or over the threshold. Drops, and counts, past {@link SLOW_STATEMENT_REPORT_LIMIT}. */
+    record(report: SlowStatementReport): void;
+    /** Take everything recorded since the last drain, oldest first, and how many were dropped. */
+    drain(): {
+        reports: SlowStatementReport[];
+        dropped: number;
+    };
+}
+/** What a statement does, by its leading keyword, and the table it named. */
+export interface StatementDescription {
+    readonly operation: SqliteOperation;
+    /** Absent when the statement named no table that is a bare identifier. */
+    readonly table?: string;
+}
+/** A statement's operation and, when it named one, its table. Reads keywords and identifiers only. */
+export declare function describeStatement(sql: string): StatementDescription;
+/** A recorder that keeps the first {@link SLOW_STATEMENT_REPORT_LIMIT} reports of a window and counts the rest. */
+export declare function createSlowStatementRecorder(limit?: number): SlowStatementRecorder;
+/**
+ * Wrap a connection so every statement on it is timed, and one at or over
+ * {@link SLOW_STATEMENT_MS} is recorded. Everything else is delegated, so the
+ * connection still satisfies the driver contract and still owns its own
+ * transactions: a slow statement is observed, never altered or retried.
+ */
+export declare function instrumentConnection(db: SqliteConnection, recorder: SlowStatementRecorder): SqliteConnection;
+//# sourceMappingURL=slow-statement.d.ts.map

package/dist/core/slow-statement.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"slow-statement.d.ts","sourceRoot":"","sources":["../../src/core/slow-statement.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,KAAK,EAEX,gBAAgB,EAKhB,MAAM,4BAA4B,CAAC;AAEpC,yEAAyE;AACzE,eAAO,MAAM,iBAAiB,MAAM,CAAC;AAErC;;;;GAIG;AACH,eAAO,MAAM,2BAA2B,MAAM,CAAC;AAE/C,qDAAqD;AACrD,MAAM,MAAM,eAAe,GAAG,QAAQ,GAAG,QAAQ,GAAG,QAAQ,GAAG,QAAQ,GAAG,QAAQ,GAAG,aAAa,GAAG,OAAO,CAAC;AAE7G,qGAAqG;AACrG,MAAM,WAAW,mBAAmB;IACnC,QAAQ,CAAC,SAAS,EAAE,eAAe,CAAC;IACpC,kFAAkF;IAClF,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC3B;AAED,sFAAsF;AACtF,MAAM,WAAW,mBAAmB;IACnC,SAAS,EAAE,eAAe,CAAC;IAC3B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;CAClB;AAED,gGAAgG;AAChG,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,mBAAmB,GAAG,mBAAmB,CAIpF;AAED,mEAAmE;AACnE,MAAM,WAAW,qBAAqB;IACrC,kHAAkH;IAClH,MAAM,CAAC,MAAM,EAAE,mBAAmB,GAAG,IAAI,CAAC;IAC1C,8FAA8F;IAC9F,KAAK,IAAI;QAAE,OAAO,EAAE,mBAAmB,EAAE,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;CAC7D;AA0BD,6EAA6E;AAC7E,MAAM,WAAW,oBAAoB;IACpC,QAAQ,CAAC,SAAS,EAAE,eAAe,CAAC;IACpC,0EAA0E;IAC1E,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,sGAAsG;AACtG,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,oBAAoB,CASnE;AAED,mHAAmH;AACnH,wBAAgB,2BAA2B,CAAC,KAAK,GAAE,MAAoC,GAAG,qBAAqB,CAe9G;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,EAAE,EAAE,gBAAgB,EAAE,QAAQ,EAAE,qBAAqB,GAAG,gBAAgB,CAyC5G"}

package/dist/core/slow-statement.js

@@ -0,0 +1,149 @@
+/**
+ * Slow-statement reporting for every pooled connection (C083b).
+ *
+ * WHY THIS EXISTS. SQLite's calls are synchronous, and the pool is one per
+ * process: a statement that runs for seconds holds the thread, so every other
+ * client of that process waits behind it with no progress to show. The pool
+ * already bounded the WAL and the transaction age, but nothing said WHICH
+ * statement cost the time — a `sample` stack names SQLite frames, and a
+ * caller's log names the tool, and neither names the table.
+ *
+ * WHAT IT REPORTS. The consumer that opened the connection, the database path,
+ * the statement's operation, the table it named, and how long it took. Every
+ * one of those is an identifier or a number the pool already holds: the
+ * consumer label is the value-free string the caller passed to
+ * `getConnection`, and the operation and table are read out of the statement's
+ * own keywords. Bound values, SQL text and result rows are never read, so a
+ * report cannot carry a row's contents.
+ *
+ * WHY IT IS NOT LOGGED FROM THE STATEMENT PATH. A report raised while a
+ * statement is unwinding would run on whatever runtime the pool last saw, which
+ * may have ended, and an observability path that can fail the operation it
+ * observes is worse than none. Reports are recorded here and drained by the
+ * pool's existing maintenance tick, which already reports on a live holder.
+ *
+ * The cost when nothing is slow is two `performance.now()` reads and one
+ * comparison per statement.
+ */
+/** A statement that took at least this many milliseconds is recorded. */
+export const SLOW_STATEMENT_MS = 250;
+/**
+ * Reports one drain window can hold. A workload that trips the threshold many
+ * times in 30 s is a fact about itself, not a reason to grow without bound: the
+ * pool logs how many it kept and how many it did not.
+ */
+export const SLOW_STATEMENT_REPORT_LIMIT = 100;
+/** A recorded report as its log fields, with the elapsed time rounded to whole milliseconds. */
+export function slowStatementFields(report) {
+    const fields = { operation: report.operation, elapsedMs: Math.round(report.elapsedMs) };
+    if (report.table !== undefined)
+        fields.table = report.table;
+    return fields;
+}
+/**
+ * The only token shape a reported table may take: a bare SQLite identifier.
+ * A quoted string literal (`'…'`), a JSON path (`'$.x'`) and a number all fail
+ * it, so a value can never be reported as a table name.
+ */
+const IDENTIFIER = /^[A-Za-z_][A-Za-z0-9_]*$/;
+/** A double-quoted or backticked identifier, unwrapped; anything else is refused. */
+function identifier(token) {
+    const unquoted = (token.length > 1 && (token.startsWith('"') || token.startsWith('`')) && token.endsWith(token[0]))
+        ? token.slice(1, -1)
+        : token;
+    return IDENTIFIER.test(unquoted) ? unquoted : undefined;
+}
+/** The first identifier after `keyword`, optionally schema-qualified, as a table name. */
+function tableAfter(sql, keyword) {
+    const match = new RegExp(`\\b${keyword}\\s+("[^"]+"|\`[^\`]+\`|[A-Za-z_][A-Za-z0-9_]*)(?:\\s*\\.\\s*("[^"]+"|\`[^\`]+\`|[A-Za-z_][A-Za-z0-9_]*))?`, 'i').exec(sql);
+    if (!match)
+        return undefined;
+    const second = match[2] ? identifier(match[2]) : undefined;
+    return second ?? identifier(match[1]);
+}
+/** A statement's operation and, when it named one, its table. Reads keywords and identifiers only. */
+export function describeStatement(sql) {
+    const text = sql.trim();
+    if (/^pragma\b/i.test(text))
+        return { operation: 'pragma' };
+    if (/^(begin|commit|rollback|savepoint|release)\b/i.test(text))
+        return { operation: 'transaction' };
+    if (/^(select|with)\b/i.test(text))
+        return { operation: 'select', table: tableAfter(text, 'FROM') };
+    if (/^insert\b/i.test(text))
+        return { operation: 'insert', table: tableAfter(text, 'INTO') };
+    if (/^update\b/i.test(text))
+        return { operation: 'update', table: tableAfter(text, 'UPDATE') };
+    if (/^delete\b/i.test(text))
+        return { operation: 'delete', table: tableAfter(text, 'FROM') };
+    return { operation: 'other' };
+}
+/** A recorder that keeps the first {@link SLOW_STATEMENT_REPORT_LIMIT} reports of a window and counts the rest. */
+export function createSlowStatementRecorder(limit = SLOW_STATEMENT_REPORT_LIMIT) {
+    const reports = [];
+    let dropped = 0;
+    return {
+        record(report) {
+            if (reports.length < limit)
+                reports.push(report);
+            else
+                dropped += 1;
+        },
+        drain() {
+            const taken = reports.splice(0, reports.length);
+            const takenDropped = dropped;
+            dropped = 0;
+            return { reports: taken, dropped: takenDropped };
+        }
+    };
+}
+/**
+ * Wrap a connection so every statement on it is timed, and one at or over
+ * {@link SLOW_STATEMENT_MS} is recorded. Everything else is delegated, so the
+ * connection still satisfies the driver contract and still owns its own
+ * transactions: a slow statement is observed, never altered or retried.
+ */
+export function instrumentConnection(db, recorder) {
+    const measure = (described, run) => {
+        const started = performance.now();
+        try {
+            return run();
+        }
+        finally {
+            const elapsedMs = performance.now() - started;
+            if (elapsedMs >= SLOW_STATEMENT_MS)
+                recorder.record({ ...described, elapsedMs });
+        }
+    };
+    return {
+        path: db.path,
+        get inTransaction() {
+            return db.inTransaction;
+        },
+        exec(sql) {
+            measure(describeStatement(sql), () => {
+                db.exec(sql);
+            });
+        },
+        prepare(sql) {
+            const statement = db.prepare(sql);
+            // Described once per prepare, not once per call: the hot path pays two
+            // clock reads and a comparison, never a parse.
+            const described = describeStatement(sql);
+            return {
+                all: (...params) => measure(described, () => statement.all(...params)),
+                get: (...params) => measure(described, () => statement.get(...params)),
+                run: (...params) => measure(described, () => statement.run(...params))
+            };
+        },
+        transaction(run, options) {
+            // Timed as a whole because COMMIT is where a transaction's cost lands,
+            // and no single statement reports it.
+            return measure({ operation: 'transaction' }, () => db.transaction(run, options));
+        },
+        close() {
+            db.close();
+        }
+    };
+}
+//# sourceMappingURL=slow-statement.js.map

package/dist/core/slow-statement.js.map

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

package/dist/core/wal-policy.d.ts

@@ -0,0 +1,86 @@
+/**
+ * WAL policy for every LocalDB connection (D-WAL).
+ *
+ * The 2026-08-31 and 2026-09-27 disk incidents were the same defect: a WAL
+ * held open by long-lived processes grew without bound (63 GB, then 37.6 GB)
+ * because the pool only ever issued `wal_checkpoint(PASSIVE)` on close and set
+ * no `journal_size_limit`. Those processes are expected to run, so the bound
+ * lives here, not in killing holders:
+ *
+ * - `journal_size_limit` caps the bytes a WAL is truncated back to whenever it
+ *   resets. It is enforced only at checkpoint boundaries, so it never ships
+ *   alone.
+ * - The pool makes ONE checkpoint attempt per idle window, never blocking:
+ *   the attempt runs with a zero busy timeout, so a reader or writer in
+ *   another process makes it return busy at once instead of parking the
+ *   event loop. The mode is `TRUNCATE`; after a busy attempt the next window
+ *   falls back to `RESTART`, then alternates. Busy attempts back off by
+ *   skipping whole windows (1, 2, 4, 8 …, capped) on the lifecycle-owned
+ *   tick — no second timer, no retry loop.
+ * - Every attempt's `(busy, log, checkpointed)` result is observed and
+ *   returned, so "the checkpoint ran" and "the checkpoint did anything" are
+ *   distinguishable.
+ *
+ * Nothing in this module (or the pool) ever deletes a raw `-wal` or `-shm`
+ * file: un-checkpointed rows live only in the WAL.
+ */
+import type { SqliteConnection } from '../driver/sqlite-driver.ts';
+/** Bytes the WAL is truncated back to when it resets. */
+export declare const WAL_JOURNAL_SIZE_LIMIT_BYTES: number;
+/** Busy timeout for a checkpoint attempt: zero, so an attempt never blocks. */
+export declare const WAL_CHECKPOINT_BUSY_TIMEOUT_MS = 0;
+/** Longest backoff after consecutive busy attempts, in maintenance windows. */
+export declare const WAL_MAX_BACKOFF_WINDOWS = 8;
+/** Consecutive busy outcomes on one connection before the pool reports starvation. */
+export declare const WAL_BUSY_STARVATION_THRESHOLD = 3;
+/** Longest a pooled connection may hold an open transaction across maintenance ticks. */
+export declare const MAX_TRANSACTION_AGE_MS = 60000;
+/** Period of the pool's lifecycle-owned maintenance tick (idle checkpoint, transaction bound, stale close). */
+export declare const WAL_MAINTENANCE_INTERVAL_MS = 30000;
+export type WalCheckpointMode = 'TRUNCATE' | 'RESTART';
+/** One `PRAGMA wal_checkpoint(<mode>)` result row. */
+export interface WalCheckpointAttempt {
+    mode: WalCheckpointMode;
+    /** 1 when the checkpoint could not obtain its locks within the busy window. */
+    busy: number;
+    /** Frames in the WAL, or -1 when the database is not in WAL mode. */
+    log: number;
+    /** Frames copied back into the database, or -1 when not in WAL mode. */
+    checkpointed: number;
+}
+export type WalCheckpointStatus = 
+/**
+ * Nothing left to bound: the WAL was fully checkpointed and reset (TRUNCATE
+ * also shrank the file), or it holds no committed frames at all (it is at
+ * its start, already cut back to `journal_size_limit`), even when another
+ * holder's open write transaction made the attempt report busy.
+ */
+'complete'
+/**
+ * Committed frames remain in the WAL and it could not be reset: a reader
+ * or writer elsewhere still holds it. Repeated, this is how a WAL grows.
+ */
+ | 'busy'
+/** The connection is not in WAL mode (e.g. `:memory:`); nothing to bound. */
+ | 'not-wal';
+export interface WalCheckpointOutcome extends WalCheckpointAttempt {
+    status: WalCheckpointStatus;
+}
+/** The mode for the attempt after `previous` came back busy: TRUNCATE falls back to RESTART, then alternates. */
+export declare function nextCheckpointMode(previous: WalCheckpointMode, status: WalCheckpointStatus): WalCheckpointMode;
+/** Windows to skip after `consecutiveBusy` busy attempts: 1, 2, 4, … capped at {@link WAL_MAX_BACKOFF_WINDOWS}. */
+export declare function checkpointBackoffWindows(consecutiveBusy: number): number;
+/** Returns the pragma statements that every LocalDB connection must run. */
+export declare function localDatabasePragmaStatements(): string[];
+/** Apply the connection pragmas every LocalDB connection carries. */
+export declare function applyLocalDatabasePragmas(exec: (sql: string) => void): void;
+/**
+ * One checkpoint attempt in `mode`, never blocking: the connection's busy
+ * timeout is zero for the attempt and restored on every exit path.
+ *
+ * Throws only when SQLite itself raises (a closed handle, or a checkpoint issued
+ * inside this connection's own open transaction) or answers no result row; a busy result is returned, not
+ * thrown, so the caller can observe, report and back off.
+ */
+export declare function checkpointWal(db: SqliteConnection, mode?: WalCheckpointMode): WalCheckpointOutcome;
+//# sourceMappingURL=wal-policy.d.ts.map

package/dist/core/wal-policy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wal-policy.d.ts","sourceRoot":"","sources":["../../src/core/wal-policy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAGH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,4BAA4B,CAAC;AAEnE,yDAAyD;AACzD,eAAO,MAAM,4BAA4B,QAAmB,CAAC;AAE7D,+EAA+E;AAC/E,eAAO,MAAM,8BAA8B,IAAI,CAAC;AAEhD,+EAA+E;AAC/E,eAAO,MAAM,uBAAuB,IAAI,CAAC;AAEzC,sFAAsF;AACtF,eAAO,MAAM,6BAA6B,IAAI,CAAC;AAE/C,yFAAyF;AACzF,eAAO,MAAM,sBAAsB,QAAS,CAAC;AAE7C,+GAA+G;AAC/G,eAAO,MAAM,2BAA2B,QAAS,CAAC;AAElD,MAAM,MAAM,iBAAiB,GAAG,UAAU,GAAG,SAAS,CAAC;AAEvD,sDAAsD;AACtD,MAAM,WAAW,oBAAoB;IACpC,IAAI,EAAE,iBAAiB,CAAC;IACxB,+EAA+E;IAC/E,IAAI,EAAE,MAAM,CAAC;IACb,qEAAqE;IACrE,GAAG,EAAE,MAAM,CAAC;IACZ,wEAAwE;IACxE,YAAY,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,MAAM,mBAAmB;AAC9B;;;;;GAKG;AACD,UAAU;AACZ;;;GAGG;GACD,MAAM;AACR,6EAA6E;GAC3E,SAAS,CAAC;AAEb,MAAM,WAAW,oBAAqB,SAAQ,oBAAoB;IACjE,MAAM,EAAE,mBAAmB,CAAC;CAC5B;AAED,iHAAiH;AACjH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,iBAAiB,EAAE,MAAM,EAAE,mBAAmB,GAAG,iBAAiB,CAG9G;AAED,mHAAmH;AACnH,wBAAgB,wBAAwB,CAAC,eAAe,EAAE,MAAM,GAAG,MAAM,CAGxE;AAED,4EAA4E;AAC5E,wBAAgB,6BAA6B,IAAI,MAAM,EAAE,CAiBxD;AAED,qEAAqE;AACrE,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,GAAG,IAAI,CAI3E;AAsBD;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,EAAE,EAAE,gBAAgB,EAAE,IAAI,GAAE,iBAA8B,GAAG,oBAAoB,CAS9G"}