@vibesdotdev/localdb 0.0.1 → 1.0.0-rc.2

package/dist/core/wal-policy.js

@@ -0,0 +1,115 @@
+/**
+ * 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 * as z from 'zod/v4';
+/** Bytes the WAL is truncated back to when it resets. */
+export const WAL_JOURNAL_SIZE_LIMIT_BYTES = 64 * 1024 * 1024;
+/** Busy timeout for a checkpoint attempt: zero, so an attempt never blocks. */
+export const WAL_CHECKPOINT_BUSY_TIMEOUT_MS = 0;
+/** Longest backoff after consecutive busy attempts, in maintenance windows. */
+export const WAL_MAX_BACKOFF_WINDOWS = 8;
+/** Consecutive busy outcomes on one connection before the pool reports starvation. */
+export const WAL_BUSY_STARVATION_THRESHOLD = 3;
+/** Longest a pooled connection may hold an open transaction across maintenance ticks. */
+export const MAX_TRANSACTION_AGE_MS = 60_000;
+/** Period of the pool's lifecycle-owned maintenance tick (idle checkpoint, transaction bound, stale close). */
+export const WAL_MAINTENANCE_INTERVAL_MS = 30_000;
+/** The mode for the attempt after `previous` came back busy: TRUNCATE falls back to RESTART, then alternates. */
+export function nextCheckpointMode(previous, status) {
+    if (status !== 'busy')
+        return 'TRUNCATE';
+    return previous === 'TRUNCATE' ? 'RESTART' : 'TRUNCATE';
+}
+/** Windows to skip after `consecutiveBusy` busy attempts: 1, 2, 4, … capped at {@link WAL_MAX_BACKOFF_WINDOWS}. */
+export function checkpointBackoffWindows(consecutiveBusy) {
+    if (consecutiveBusy <= 0)
+        return 0;
+    return Math.min(WAL_MAX_BACKOFF_WINDOWS, 2 ** (consecutiveBusy - 1));
+}
+/** Returns the pragma statements that every LocalDB connection must run. */
+export function localDatabasePragmaStatements() {
+    return [
+        // Must run before the first table is created. On an existing file this is
+        // a no-op until a full VACUUM; `storage/retention/reclaim.ts` adopts those.
+        // Without it, DELETE returns zero disk: freed pages sit on the freelist.
+        // `incremental` rather than `full` keeps the per-commit write cost off the
+        // hot path; `PRAGMA incremental_vacuum` returns pages on demand.
+        'PRAGMA auto_vacuum = INCREMENTAL;',
+        // Readers don't block writers, writers don't block readers.
+        'PRAGMA journal_mode = WAL;',
+        // Bounds the WAL's on-disk bytes whenever it resets (D-WAL).
+        `PRAGMA journal_size_limit = ${WAL_JOURNAL_SIZE_LIMIT_BYTES};`,
+        'PRAGMA foreign_keys = ON;',
+        // NORMAL is safe with WAL and much faster.
+        'PRAGMA synchronous = NORMAL;',
+        'PRAGMA temp_store = MEMORY;'
+    ];
+}
+/** Apply the connection pragmas every LocalDB connection carries. */
+export function applyLocalDatabasePragmas(exec) {
+    for (const stmt of localDatabasePragmaStatements()) {
+        exec(stmt);
+    }
+}
+/** `PRAGMA wal_checkpoint(<mode>)`'s one result row. */
+const CheckpointRowSchema = z.object({ busy: z.number(), log: z.number(), checkpointed: z.number() });
+/** `PRAGMA busy_timeout`'s one result row. */
+const BusyTimeoutRowSchema = z.object({ timeout: z.number() });
+function runCheckpoint(db, mode) {
+    const row = CheckpointRowSchema.parse(db.prepare(`PRAGMA wal_checkpoint(${mode});`).get());
+    return { mode, busy: row.busy, log: row.log, checkpointed: row.checkpointed };
+}
+function classify(attempt) {
+    if (attempt.log === -1)
+        return 'not-wal';
+    // No committed frames: a busy result here only means another holder's
+    // write transaction had the lock. There is nothing to checkpoint or bound.
+    if (attempt.log === 0)
+        return 'complete';
+    if (attempt.busy !== 0 || attempt.checkpointed < attempt.log)
+        return 'busy';
+    return 'complete';
+}
+/**
+ * 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 function checkpointWal(db, mode = 'TRUNCATE') {
+    const previous = BusyTimeoutRowSchema.parse(db.prepare('PRAGMA busy_timeout;').get());
+    db.exec(`PRAGMA busy_timeout = ${WAL_CHECKPOINT_BUSY_TIMEOUT_MS};`);
+    try {
+        const attempt = runCheckpoint(db, mode);
+        return { ...attempt, status: classify(attempt) };
+    }
+    finally {
+        db.exec(`PRAGMA busy_timeout = ${previous.timeout};`);
+    }
+}
+//# sourceMappingURL=wal-policy.js.map

package/dist/core/wal-policy.js.map

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

package/dist/dev.localdb.cli-group.descriptor.d.ts

@@ -3,7 +3,7 @@
  *
  * Groups LocalDB development commands under `vibes dev localdb`.
  */
-import type { CLIGroupAssetDescriptor } from '@vibesdotdev/cli/schemas/types';
+import type { CLIGroupAssetDescriptor } from '@vibesdotdev/kernel/schemas/asset';
 declare const descriptor: CLIGroupAssetDescriptor;
 export default descriptor;
 //# sourceMappingURL=dev.localdb.cli-group.descriptor.d.ts.map

package/dist/dev.localdb.cli-group.descriptor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dev.localdb.cli-group.descriptor.d.ts","sourceRoot":"","sources":["../src/dev.localdb.cli-group.descriptor.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,gCAAgC,CAAC;AAE9E,QAAA,MAAM,UAAU,EAAE,uBASjB,CAAC;AAEF,eAAe,UAAU,CAAC"}
+{"version":3,"file":"dev.localdb.cli-group.descriptor.d.ts","sourceRoot":"","sources":["../src/dev.localdb.cli-group.descriptor.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,mCAAmC,CAAC;AAEjF,QAAA,MAAM,UAAU,EAAE,uBASjB,CAAC;AAEF,eAAe,UAAU,CAAC"}

package/dist/dev.localdb.context.descriptor.d.ts

@@ -12,10 +12,24 @@ declare const _default: {
     hardware?: string[] | undefined;
     enabled?: boolean | undefined;
     priority?: number | undefined;
+    capabilityId?: string | undefined;
     requiredContext?: string[] | undefined;
     optionalContext?: string[] | undefined;
-    config?: Record<string, unknown> | undefined;
+    retention?: string | {
+        reason: string;
+        maxAgeDays?: number | undefined;
+        maxEntries?: number | undefined;
+        maxBytes?: number | undefined;
+        cascadeFrom?: string | undefined;
+        ageField?: string | undefined;
+        enforcedBy?: string | undefined;
+    } | undefined;
+    valueKind?: "data" | "service" | undefined;
     valueSchema?: unknown;
+    config?: {
+        sources: ("literal" | "workspace" | "floor")[];
+        subset?: true | undefined;
+    } | undefined;
 };
 export default _default;
 //# sourceMappingURL=dev.localdb.context.descriptor.d.ts.map

package/dist/dev.localdb.context.descriptor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dev.localdb.context.descriptor.d.ts","sourceRoot":"","sources":["../src/dev.localdb.context.descriptor.ts"],"names":[],"mappings":"AAAA;;;;GAIG;;;;;;;;;;;;;;;AAIH,wBAIG"}
+{"version":3,"file":"dev.localdb.context.descriptor.d.ts","sourceRoot":"","sources":["../src/dev.localdb.context.descriptor.ts"],"names":[],"mappings":"AAAA;;;;GAIG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAIH,wBAIG"}

package/dist/dev.localdb.context.descriptor.js

@@ -3,7 +3,7 @@
  *
  * Provides LocalDB API for dev commands and workflows.
  */
-import { createContextDescriptor } from '@vibesdotdev/runtime';
+import { createContextDescriptor } from '@vibesdotdev/kernel';
 export default createContextDescriptor({
     id: 'dev/localdb',
     description: 'LocalDB API for managing local SQLite databases.',

package/dist/dev.localdb.context.descriptor.js.map

@@ -1 +1 @@
-{"version":3,"file":"dev.localdb.context.descriptor.js","sourceRoot":"","sources":["../src/dev.localdb.context.descriptor.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,uBAAuB,EAAE,MAAM,sBAAsB,CAAC;AAE/D,eAAe,uBAAuB,CAAC;IACtC,EAAE,EAAE,aAAa;IACjB,WAAW,EAAE,kDAAkD;IAC/D,QAAQ,EAAE,CAAC,UAAU,CAAC;CACtB,CAAC,CAAC"}
+{"version":3,"file":"dev.localdb.context.descriptor.js","sourceRoot":"","sources":["../src/dev.localdb.context.descriptor.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,uBAAuB,EAAE,MAAM,qBAAqB,CAAC;AAE9D,eAAe,uBAAuB,CAAC;IACtC,EAAE,EAAE,aAAa;IACjB,WAAW,EAAE,kDAAkD;IAC/D,QAAQ,EAAE,CAAC,UAAU,CAAC;CACtB,CAAC,CAAC"}

package/dist/dev.localdb.context.impl.consumer.d.ts

@@ -1,9 +1,16 @@
 /**
  * Dev LocalDB Context Implementation (Consumer)
+ *
+ * Resolves to the runtime's owned `localdb` runtime/client — the same
+ * semantic owner every other caller on this runtime sees — instead of
+ * constructing another manager.
  */
-import type { LocaldbApi } from './schemas/api';
-declare const _default: {
-    provide: () => Promise<LocaldbApi>;
-};
-export default _default;
+import type { KindContext, RuntimeDescriptor } from '@vibesdotdev/kernel';
+import type { LocaldbApi } from './schemas/api.ts';
+/** The kernel re-evaluates context values per call; the client stays cached per runtime. */
+export default class LocaldbContext {
+    private readonly context;
+    constructor(_descriptor: RuntimeDescriptor, context: KindContext);
+    provide(): Promise<LocaldbApi>;
+}
 //# sourceMappingURL=dev.localdb.context.impl.consumer.d.ts.map

package/dist/dev.localdb.context.impl.consumer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dev.localdb.context.impl.consumer.d.ts","sourceRoot":"","sources":["../src/dev.localdb.context.impl.consumer.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;;mBAG5B,OAAO,CAAC,UAAU,CAAC;;AADvC,wBAKE"}
+{"version":3,"file":"dev.localdb.context.impl.consumer.d.ts","sourceRoot":"","sources":["../src/dev.localdb.context.impl.consumer.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAE1E,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAEnD,4FAA4F;AAC5F,MAAM,CAAC,OAAO,OAAO,cAAc;IACU,OAAO,CAAC,QAAQ,CAAC,OAAO;gBAAxD,WAAW,EAAE,iBAAiB,EAAmB,OAAO,EAAE,WAAW;IACjF,OAAO,IAAI,OAAO,CAAC,UAAU,CAAC;CAG9B"}

package/dist/dev.localdb.context.impl.consumer.js

@@ -1,10 +1,19 @@
 /**
  * Dev LocalDB Context Implementation (Consumer)
+ *
+ * Resolves to the runtime's owned `localdb` runtime/client — the same
+ * semantic owner every other caller on this runtime sees — instead of
+ * constructing another manager.
  */
-export default {
-    provide: async () => {
-        const { localdb } = await import('./index.js');
-        return localdb;
+import { resolveLocaldbClient } from "./core/database.js";
+/** The kernel re-evaluates context values per call; the client stays cached per runtime. */
+export default class LocaldbContext {
+    context;
+    constructor(_descriptor, context) {
+        this.context = context;
     }
-};
+    provide() {
+        return resolveLocaldbClient(this.context.runtime);
+    }
+}
 //# sourceMappingURL=dev.localdb.context.impl.consumer.js.map

package/dist/dev.localdb.context.impl.consumer.js.map

@@ -1 +1 @@
-{"version":3,"file":"dev.localdb.context.impl.consumer.js","sourceRoot":"","sources":["../src/dev.localdb.context.impl.consumer.ts"],"names":[],"mappings":"AAAA;;GAEG;AAIH,eAAe;IACd,OAAO,EAAE,KAAK,IAAyB,EAAE;QACxC,MAAM,EAAE,OAAO,EAAE,GAAG,MAAM,MAAM,CAAC,SAAS,CAAC,CAAC;QAC5C,OAAO,OAAO,CAAC;IAChB,CAAC;CACD,CAAC"}
+{"version":3,"file":"dev.localdb.context.impl.consumer.js","sourceRoot":"","sources":["../src/dev.localdb.context.impl.consumer.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAG1D,4FAA4F;AAC5F,MAAM,CAAC,OAAO,OAAO,cAAc;IAC2B;IAA7D,YAAY,WAA8B,EAAmB,OAAoB;QAApB,YAAO,GAAP,OAAO,CAAa;IAAG,CAAC;IACrF,OAAO;QACN,OAAO,oBAAoB,CAAC,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;IACnD,CAAC;CACD"}

package/dist/driver/sqlite-driver.base.d.ts

@@ -0,0 +1,107 @@
+/**
+ * The shared provider side of LocalDB's SQLite driver kind
+ * (`localdb/sqlite-driver`, `./sqlite-driver`): the base each host's driver
+ * composes (`./sqlite-driver/base`).
+ *
+ * Every untrusted input a driver reads (the open request, bound parameters,
+ * SQL text) goes through one guard here, and every host failure is classified
+ * here into a typed `CapabilityError`, so every host refuses alike. The
+ * transaction runner is here too. Nothing here reads a host API: a host lends
+ * its path rules and file facts (`SqliteDriverHost`) to the two guards that
+ * need them, and each host package keeps its own SQLite binding.
+ */
+import { CapabilityError, type CaughtFailure, type ValueFreeFailure } from '@vibesdotdev/kernel';
+import * as z from 'zod/v4';
+import { type SqliteBinding, type SqliteFailureCondition, type SqliteOpenOptions, type SqliteRow, type SqliteTransactionOptions, type SqliteValue } from './sqlite-driver.ts';
+import type { SqliteDriverHost, SqliteFailureDescription, SqliteHostFailure, SqliteOpenRequest, SqliteTransactionTarget } from '../schemas/sqlite-driver-base.ts';
+export { LOCALDB_SQLITE_DRIVER_KIND, SQLITE_DRIVER_REFUSALS, sqliteDriverKind, type SqliteBinding, type SqliteConnection, type SqliteDriver, type SqliteOpenOptions, type SqliteRow, type SqliteRunResult, type SqliteStatement, type SqliteTransactionOptions, type SqliteValue } from './sqlite-driver.ts';
+export type { SqliteDriverHost, SqliteFailureDescription, SqliteHostFailure, SqliteOpenRequest, SqliteTransactionTarget } from '../schemas/sqlite-driver-base.ts';
+/** The in-memory database name SQLite reserves. */
+export declare const SQLITE_MEMORY_PATH = ":memory:";
+/** Put a redacted failure's bounded facts in public details without retaining the thrown value. */
+export declare function sqliteFailureFacts(prefix: string, failure: ValueFreeFailure): {
+    [x: string]: string;
+};
+/** A driver refusal containing only the contract's fixed, bounded facts. */
+export declare class SqliteDriverFailure extends CapabilityError {
+    constructor(failure: SqliteFailureDescription);
+}
+/** Construct a cause-free driver refusal from the contract's fixed facts. */
+export declare function sqliteDriverFailure(failure: SqliteFailureDescription): CapabilityError;
+/**
+ * Read an open request once. `path` is `:memory:` or a path the host calls
+ * absolute (`host.isAbsolutePath`); `options` is absent or an object whose
+ * `create`/`readonly` fields are booleans when present. Any other value — a
+ * throwing getter, a Proxy (revoked included), a non-string path, or Zod
+ * failing while it reads — refuses the fixed `INVALID_INPUT
+ * sqlite-open-invalid` without retaining the hostile value or thrown error.
+ */
+export declare function readSqliteOpenRequest(host: SqliteDriverHost, path: string, options?: SqliteOpenOptions): SqliteOpenRequest;
+/**
+ * Read positional parameters once. Each is a {@link SqliteBinding} (numbers
+ * finite; booleans bind as 1 or 0); bytes are copied (a Proxy over a `Uint8Array` passes `instanceof`
+ * but cannot be copied, and refuses). Anything else refuses `INVALID_INPUT
+ * sqlite-binding-invalid` naming the position.
+ */
+export declare function readSqliteParams(params: readonly SqliteBinding[]): SqliteValue[];
+/** Read SQL text once: a string, or `INVALID_INPUT sqlite-sql-invalid`. */
+export declare function readSqliteSql(sql: string): string;
+/** The primary result code of an (extended) SQLite result code. */
+export declare function primaryResultCode(errcode: number): number;
+/** The text a host SQLite error carries: bounded, read only to classify it, never repeated. */
+export declare const SqliteHostErrorSchema: z.ZodObject<{
+    message: z.ZodString;
+}, z.core.$strip>;
+/**
+ * Read a host SQLite error once without trusting its prototype, getters or
+ * message. Only an integer result code and bounded text used for fixed
+ * classification leave this function; the host error itself never does.
+ */
+export declare function readSqliteHostFailure(failure: CaughtFailure, codeField: 'errcode' | 'errno'): SqliteHostFailure;
+/** Merge any failure encountered while reading host fields into bounded refusal details. */
+export declare function sqliteHostFailureDetails(host: SqliteHostFailure, details?: Readonly<Record<string, number | string>>): Readonly<Record<string, number | string>> | undefined;
+/**
+ * The fixed condition a failed statement hit, from SQLite's extended result
+ * code and (only to classify it) SQLite's text; the text itself is dropped.
+ */
+export declare function sqliteFailureConditionOf(errcode: number | undefined, sqliteText: string | undefined): SqliteFailureCondition | undefined;
+/**
+ * Describe a failed statement by its SQLite result code (`undefined` when the
+ * host error carries none) and SQLite's text, read only to classify it into a
+ * fixed `details.condition`: `SQLITE_BUSY`/`SQLITE_LOCKED` are `CONFLICT
+ * sqlite-busy` (retryable), anything else `INTERNAL sqlite-statement-failed`;
+ * `details.errcode` is the primary code.
+ */
+export declare function describeStatementFailure(errcode: number | undefined, sqliteText?: string): SqliteFailureDescription;
+/**
+ * Describe a failed host open: busy is `sqlite-busy`; anything else is
+ * `UNAVAILABLE sqlite-open-failed`. Only the filesystem preflight below may
+ * classify a path as `sqlite-database-missing`.
+ */
+export declare function describeOpenFailure(_request: SqliteOpenRequest, errcode: number | undefined): SqliteFailureDescription;
+/** `NOT_FOUND sqlite-database-missing`: the request did not allow creating a missing file. */
+export declare const DATABASE_MISSING: SqliteFailureDescription;
+/**
+ * Prove a non-creating open names an existing filesystem entry, through the
+ * host's `statPath`. Only the filesystem's missing-path conditions (ENOENT,
+ * ENOTDIR) become `sqlite-database-missing`;
+ * denied, malformed and I/O failures remain `sqlite-open-failed`.
+ */
+export declare function requireExistingSqliteFile(host: SqliteDriverHost, request: SqliteOpenRequest): void;
+/** `UNAVAILABLE sqlite-connection-closed`. */
+export declare const CONNECTION_CLOSED: SqliteFailureDescription;
+/** `INTERNAL sqlite-close-failed`. */
+export declare const CLOSE_FAILED: SqliteFailureDescription;
+/** A row the host returned, as a plain object (Node returns null-prototype rows). */
+export declare function plainRow<TRow extends SqliteRow>(row: TRow): TRow;
+/**
+ * The one transaction runner every host uses: BEGIN (IMMEDIATE when asked), run, COMMIT; ROLLBACK and
+ * rethrow when `run` throws or SQLite refuses the COMMIT. Inside an open
+ * transaction it uses a savepoint (`SAVEPOINT`, `RELEASE`; `ROLLBACK TO` then
+ * `RELEASE` on a throw). `run` is synchronous: a Promise result is rolled
+ * back and refused `INVALID_INPUT sqlite-transaction-async`, because the work
+ * it stands for would run after the commit. A rollback that itself fails is
+ * reported as one fixed, cause-free refusal; neither host failure escapes.
+ */
+export declare function runSqliteTransaction<T>(target: SqliteTransactionTarget, savepoint: string, run: () => T, options?: SqliteTransactionOptions): T;
+//# sourceMappingURL=sqlite-driver.base.d.ts.map

package/dist/driver/sqlite-driver.base.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sqlite-driver.base.d.ts","sourceRoot":"","sources":["../../src/driver/sqlite-driver.base.ts"],"names":[],"mappings":"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"}