Rulvar API reference / @rulvar/store-sqlite
@rulvar/store-sqlite
SQLite journal store implementing the Rulvar storage SPI with the lease capability and a fencing epoch, on the builtin node:sqlite driver; the reference implementation for community stores. Exports SqliteStore.
Part of Rulvar, an embeddable TypeScript engine for durable, budget-bounded multi-agent LLM workflows, where a completed LLM call is never paid for twice. Full documentation: docs.rulvar.com.
Install
bash
pnpm add @rulvar/core @rulvar/store-sqliteDocumentation
License
Classes
| Class | Description |
|---|---|
| SqliteAdmissionScheduler | - |
| SqliteQuotaLimiter | The cross-process reference implementation of the core QuotaLimiter SPI: engine processes pointing instances at ONE database file (this store's file or its own) enforce one global provider quota. Admission consumes the window counters inside a single BEGIN IMMEDIATE transaction, so two processes can never both take the last slot; reservations are rows, so reconcile settles a grant from any process; both tables are lazily pruned to the current and previous accounting window. The rule model, the fixed epoch-aligned one-minute windows, and the admission decision are the core's own exported functions, so this limiter and memoryQuotaLimiter agree on every verdict. The rules MUST be identical across coordinating processes (buckets key on rule content). Runtime contention queues briefly on the connection's busy_timeout (a hot limiter is EXPECTED to serialize); a call still busy past the bound throws, and the engine's onLimiterError policy decides what that means. Call close() when done. |
| SqliteStore | @rulvar/store-sqlite: SqliteStore implementing JournalStore and LeasableStore with fencing epochs over the builtin node:sqlite driver; the reference implementation for community stores (M5-T02). Requires a Node.js with node:sqlite available (unflagged in the 22.13+/23.4+ lines). |
Interfaces
| Interface | Description |
|---|---|
| SqliteAdmissionSchedulerOptions | - |
| SqliteQuotaLimiterOptions | - |
| SqliteStoreOptions | @rulvar/store-sqlite: SqliteStore implementing JournalStore and LeasableStore with fencing epochs over the builtin node:sqlite driver; the reference implementation for community stores (M5-T02). Requires a Node.js with node:sqlite available (unflagged in the 22.13+/23.4+ lines). |
| SqliteTranscriptStore | The fenced transcript twin over a SqliteStore database (the fenced run state RFC, F2): a TranscriptStore that declares fencedWrites because its blobs live in the SAME database as the lease rows, giving the fence check and the blob mutation one transactional domain. Obtain it from SqliteStore.transcripts; its lifetime is the owning store's (one shared connection, one close()). |
Variables
| Variable | Description |
|---|---|
| BOOT_BUSY_TIMEOUT_MS | Total time the constructor keeps retrying its schema bootstrap through SQLITE_BUSY before giving up, so concurrent multi-process construction over one fresh file serializes instead of dying raw. The bound applies ONLY to boot; every runtime contention path keeps the documented fail-fast semantics (busy surfaces immediately). A boot still busy past the bound throws the driver's error: something is wedged, not merely concurrent. |
| DEFAULT_LEASE_TTL_MS | Appendix A interim reference for the sqlite store. |
| QUOTA_BUSY_TIMEOUT_MS | How long a runtime reserve/reconcile transaction waits for a sibling process's transaction before the driver reports busy. Quota admissions are short single-writer transactions; queueing here IS the cross-process serialization working. |