wolbarg 0.5.6 → 0.5.7

package/dist/index.d.cts

@@ -371,6 +371,10 @@ interface ConcurrencyConfig$1 {
     baseBackoffMs?: number;
     maxBackoffMs?: number;
     lockTimeoutMs?: number;
+    /** Total lock-wait + retry budget in ms. */
+    lockDeadlineMs?: number;
+    /** Use multi-process-oriented defaults when many OS processes share one DB file. */
+    multiProcess?: boolean;
 }
 /** Transparent embedding cache configuration. */
 interface EmbeddingCacheConfig {
@@ -2149,7 +2153,7 @@ interface WolbargOptionsBase {
     organization: string;
     /**
      * Storage provider instance or config.
-     * Prefer `database` in docs; `storage` remains fully supported.
+     * Prefer `storage: sqlite(...)` / `postgres(...)` in docs; `database` remains supported.
      */
     storage?: StorageInput;
     /**
@@ -2896,10 +2900,6 @@ declare class GraphCheckpointNotSupportedError extends WolbargError {
  */
 declare function wrapOperationError(operation: string, error: unknown): WolbargError;
 
-/**
- * Public factory helpers for storage, telemetry, checkpoints, and graph providers (v0.5.5).
- */
-
 /**
  * Create a SQLite {@link StorageProvider} from a filesystem path or `:memory:`.
  *
@@ -2911,7 +2911,9 @@ declare function wrapOperationError(operation: string, error: unknown): WolbargE
  * wolbarg({ organization: "acme", storage: sqlite("./memory.db"), embedding: ... })
  * ```
  */
-declare function sqlite(connectionString: string): StorageProvider;
+declare function sqlite(connectionString: string, options?: {
+    concurrency?: ConcurrencyConfig$1;
+}): StorageProvider;
 /**
  * Create a SQLite storage **config object** (for `database` / `init` options).
  *
@@ -3046,6 +3048,16 @@ interface ConcurrencyConfig {
     maxBackoffMs?: number;
     /** SQLite busy_timeout pragma in ms. Default: 5000 */
     lockTimeoutMs?: number;
+    /**
+     * Hard ceiling for total lock-wait + retry budget in ms.
+     * Default: lockTimeoutMs * (maxRetries + 1).
+     */
+    lockDeadlineMs?: number;
+    /**
+     * When true, use multi-process-oriented defaults (higher busy_timeout / retries)
+     * unless the caller overrides individual fields.
+     */
+    multiProcess?: boolean;
 }
 
 /**
@@ -3082,6 +3094,20 @@ declare class SqliteStorageProvider implements StorageProvider {
     private transactionDepth;
     /** Incrementing counter for deterministic savepoint names. */
     private savepointCounter;
+    /**
+     * Serializes top-level write transactions on the single SQLite connection.
+     * SQLite is single-writer; serializing in-process avoids SQLITE_BUSY churn
+     * AND prevents interleaved BEGIN/SAVEPOINT state corruption when many async
+     * callers share one connection (see "no such savepoint" class of bugs).
+     */
+    private readonly writeMutex;
+    /**
+     * Async-context flag: true while executing inside a top-level write
+     * transaction held by this provider. Used so writes issued from within an
+     * ambient transaction (e.g. compress()) join that ACID unit, WITHOUT
+     * mistaking the coalescer's own flush window for an ambient transaction.
+     */
+    private readonly txContext;
     /** Hot in-process ANN for blob backend (sqlite-vec unavailable platforms). */
     private memoryIndex;
     private memoryIndexDirty;
@@ -3115,6 +3141,8 @@ declare class SqliteStorageProvider implements StorageProvider {
     setRetryLogger(fn: ((msg: string) => void) | null): void;
     /** Open the database, run migrations, and prepare statements. */
     open(): Promise<void>;
+    /** Single open attempt — connect, apply pragmas, migrate, prepare. */
+    private openOnce;
     /** Drain pending inserts, optimize, and close the SQLite connection. */
     close(): Promise<void>;
     /**
@@ -3320,6 +3348,8 @@ declare class PostgresStorageProvider implements StorageProvider {
     private insertFlushScheduled;
     private insertFlushTimer;
     private insertFlushInFlight;
+    /** Per-provider TX context — never share across PostgresStorageProvider instances. */
+    private readonly txStore;
     /**
      * @param options - Connection string, pool size, and durability flags.
      */

package/dist/index.d.ts

@@ -371,6 +371,10 @@ interface ConcurrencyConfig$1 {
     baseBackoffMs?: number;
     maxBackoffMs?: number;
     lockTimeoutMs?: number;
+    /** Total lock-wait + retry budget in ms. */
+    lockDeadlineMs?: number;
+    /** Use multi-process-oriented defaults when many OS processes share one DB file. */
+    multiProcess?: boolean;
 }
 /** Transparent embedding cache configuration. */
 interface EmbeddingCacheConfig {
@@ -2149,7 +2153,7 @@ interface WolbargOptionsBase {
     organization: string;
     /**
      * Storage provider instance or config.
-     * Prefer `database` in docs; `storage` remains fully supported.
+     * Prefer `storage: sqlite(...)` / `postgres(...)` in docs; `database` remains supported.
      */
     storage?: StorageInput;
     /**
@@ -2896,10 +2900,6 @@ declare class GraphCheckpointNotSupportedError extends WolbargError {
  */
 declare function wrapOperationError(operation: string, error: unknown): WolbargError;
 
-/**
- * Public factory helpers for storage, telemetry, checkpoints, and graph providers (v0.5.5).
- */
-
 /**
  * Create a SQLite {@link StorageProvider} from a filesystem path or `:memory:`.
  *
@@ -2911,7 +2911,9 @@ declare function wrapOperationError(operation: string, error: unknown): WolbargE
  * wolbarg({ organization: "acme", storage: sqlite("./memory.db"), embedding: ... })
  * ```
  */
-declare function sqlite(connectionString: string): StorageProvider;
+declare function sqlite(connectionString: string, options?: {
+    concurrency?: ConcurrencyConfig$1;
+}): StorageProvider;
 /**
  * Create a SQLite storage **config object** (for `database` / `init` options).
  *
@@ -3046,6 +3048,16 @@ interface ConcurrencyConfig {
     maxBackoffMs?: number;
     /** SQLite busy_timeout pragma in ms. Default: 5000 */
     lockTimeoutMs?: number;
+    /**
+     * Hard ceiling for total lock-wait + retry budget in ms.
+     * Default: lockTimeoutMs * (maxRetries + 1).
+     */
+    lockDeadlineMs?: number;
+    /**
+     * When true, use multi-process-oriented defaults (higher busy_timeout / retries)
+     * unless the caller overrides individual fields.
+     */
+    multiProcess?: boolean;
 }
 
 /**
@@ -3082,6 +3094,20 @@ declare class SqliteStorageProvider implements StorageProvider {
     private transactionDepth;
     /** Incrementing counter for deterministic savepoint names. */
     private savepointCounter;
+    /**
+     * Serializes top-level write transactions on the single SQLite connection.
+     * SQLite is single-writer; serializing in-process avoids SQLITE_BUSY churn
+     * AND prevents interleaved BEGIN/SAVEPOINT state corruption when many async
+     * callers share one connection (see "no such savepoint" class of bugs).
+     */
+    private readonly writeMutex;
+    /**
+     * Async-context flag: true while executing inside a top-level write
+     * transaction held by this provider. Used so writes issued from within an
+     * ambient transaction (e.g. compress()) join that ACID unit, WITHOUT
+     * mistaking the coalescer's own flush window for an ambient transaction.
+     */
+    private readonly txContext;
     /** Hot in-process ANN for blob backend (sqlite-vec unavailable platforms). */
     private memoryIndex;
     private memoryIndexDirty;
@@ -3115,6 +3141,8 @@ declare class SqliteStorageProvider implements StorageProvider {
     setRetryLogger(fn: ((msg: string) => void) | null): void;
     /** Open the database, run migrations, and prepare statements. */
     open(): Promise<void>;
+    /** Single open attempt — connect, apply pragmas, migrate, prepare. */
+    private openOnce;
     /** Drain pending inserts, optimize, and close the SQLite connection. */
     close(): Promise<void>;
     /**
@@ -3320,6 +3348,8 @@ declare class PostgresStorageProvider implements StorageProvider {
     private insertFlushScheduled;
     private insertFlushTimer;
     private insertFlushInFlight;
+    /** Per-provider TX context — never share across PostgresStorageProvider instances. */
+    private readonly txStore;
     /**
      * @param options - Connection string, pool size, and durability flags.
      */