Rulvar API reference / @rulvar/store-sqlite / SqliteStore
Class: SqliteStore
Defined in: packages/store-sqlite/src/store.ts:137
@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).
Implements
Constructors
Constructor
new SqliteStore(options): SqliteStore;Defined in: packages/store-sqlite/src/store.ts:161
Parameters
| Parameter | Type |
|---|---|
options | SqliteStoreOptions |
Returns
SqliteStore
Properties
| Property | Modifier | Type | Description | Defined in |
|---|---|---|---|---|
effectLane | readonly | true | Effect lane capability (plan 45, rfcs/effects.md section 4.5, item 3): the restoration generation lives OUTSIDE the journal bytes in the same database file. The restore runbook is one rule: after restoring the file from a backup, run bumpRestorationGeneration() BEFORE the restored file becomes reachable to any worker, so the effect lane comes up with dispatch disabled until an operator appends a fresh effect_epoch citing the bumped generation. | packages/store-sqlite/src/store.ts:155 |
fencedWrites | readonly | true | The fenced writes promise (fenced run state RFC, phase 2): every lease-carrying mutation of this store (append, putMeta, delete) verifies the lease is the current holder FOR THE MUTATED RUN, atomically with the mutation, and rejects stale or mismatched holders with the typed LeaseHeldError leaving nothing changed. | packages/store-sqlite/src/store.ts:145 |
Accessors
leaseTtlMs
Get Signature
get leaseTtlMs(): number;Defined in: packages/store-sqlite/src/store.ts:560
TTL introspection (the LeasableStore optional capability): lets createWorker verify at construction that its renew cadence matches this store's expiry instead of trusting two config sources to agree.
Returns
number
Optional TTL introspection (v1.35.0 review P2-4): the configured lease ttl in milliseconds. A store exposing it lets createWorker VERIFY at construction that the worker's renew cadence matches the store's expiry instead of trusting two config sources to agree; stores without it are accepted with the worker's own ttl.
Implementation of
Methods
acquire()
acquire(runId, owner): Promise<Lease>;Defined in: packages/store-sqlite/src/store.ts:565
Parameters
| Parameter | Type |
|---|---|
runId | string |
owner | string |
Returns
Promise<Lease>
Implementation of
append()
append(
runId,
e,
lease?): Promise<void>;Defined in: packages/store-sqlite/src/store.ts:352
Parameters
| Parameter | Type |
|---|---|
runId | string |
e | JournalEntry |
lease? | Lease |
Returns
Promise<void>
Implementation of
bumpRestorationGeneration()
bumpRestorationGeneration(): Promise<number>;Defined in: packages/store-sqlite/src/store.ts:259
The restore procedure's one mutation (see effectLane above): bumps the generation atomically and returns the new value. Idempotent in effect: every extra bump only widens the fence, never re-enables anything.
Returns
Promise<number>
close()
close(): void;Defined in: packages/store-sqlite/src/store.ts:242
Returns
void
delete()
delete(runId, lease?): Promise<void>;Defined in: packages/store-sqlite/src/store.ts:452
Parameters
| Parameter | Type |
|---|---|
runId | string |
lease? | Lease |
Returns
Promise<void>
Implementation of
getMeta()
getMeta(runId): Promise<RunMeta | undefined>;Defined in: packages/store-sqlite/src/store.ts:397
Parameters
| Parameter | Type |
|---|---|
runId | string |
Returns
Promise<RunMeta | undefined>
Implementation of
listRuns()
listRuns(f?): Promise<RunMeta[]>;Defined in: packages/store-sqlite/src/store.ts:406
Parameters
| Parameter | Type |
|---|---|
f? | RunFilter |
Returns
Promise<RunMeta[]>
Implementation of
load()
load(runId): Promise<JournalEntry[]>;Defined in: packages/store-sqlite/src/store.ts:364
Parameters
| Parameter | Type |
|---|---|
runId | string |
Returns
Promise<JournalEntry[]>
Implementation of
putMeta()
putMeta(m, lease?): Promise<void>;Defined in: packages/store-sqlite/src/store.ts:381
Parameters
| Parameter | Type |
|---|---|
m | RunMeta |
lease? | Lease |
Returns
Promise<void>
Implementation of
release()
release(l): Promise<void>;Defined in: packages/store-sqlite/src/store.ts:613
Parameters
| Parameter | Type |
|---|---|
l | Lease |
Returns
Promise<void>
Implementation of
renew()
renew(l): Promise<void>;Defined in: packages/store-sqlite/src/store.ts:602
Parameters
| Parameter | Type |
|---|---|
l | Lease |
Returns
Promise<void>
Implementation of
restorationGeneration()
restorationGeneration(): Promise<number>;Defined in: packages/store-sqlite/src/store.ts:247
The current restoration generation; 0 until a restore ever ran.
Returns
Promise<number>
Implementation of
EffectLaneStore.restorationGeneration
transcripts()
transcripts(): SqliteTranscriptStore;Defined in: packages/store-sqlite/src/store.ts:491
The fenced transcript twin (fenced run state RFC, F2): a TranscriptStore whose blobs live in THIS store's database, beside the lease rows, so a lease-carrying put or delete verifies the current holder of the run the ref's leading path segment names atomically with the blob mutation, in the same one-immediate- transaction shape as the journal side. Sharing the connection is what makes the capability implementable at all (a blob write and a lease check in different domains cannot commit as one unit; with ':memory:' a separate connection would not even see the leases) and keeps one close() lifecycle. Wire it as the engine's transcript store next to this store as the journal: over the pair every durable run mutation is fenced, which is what assertFencedWrites({ journal, transcripts }) verifies. The blob cascade of deleteRun/pruneRun stays ENGINE-side, exactly as the TranscriptStore contract says; the journal-side delete(runId) never touches blob rows.