Class: SqliteLedgerStore

Defined in: sqlite/src/stores/sqlite-ledger-store.ts:59

WAL-mode SQLite implementation of the @paraharness/core LedgerStore runtime port.

Persists flow runs, step continuation stacks, wire-frame chains, dynamic lane DAG mutations, and suspended fork records inside transactional SQLite tables serialized via p-queue.

Implements

• LedgerStore

Constructors

Constructor

new SqliteLedgerStore(uriOrDb): SqliteLedgerStore;

Defined in: sqlite/src/stores/sqlite-ledger-store.ts:72

Initializes a SqliteLedgerStore against a SQLite file path, :memory:, or existing Database instance.

Applies WAL-mode PRAGMAs and idempotent ledger DDL statements on initialization.

Parameters

Parameter	Type	Description
uriOrDb	string | Database	SQLite database URI or open better-sqlite3 handle.

Returns

SqliteLedgerStore

Methods

appendMessageFrame()

appendMessageFrame(runId, frame): Promise<void>;

Defined in: sqlite/src/stores/sqlite-ledger-store.ts:175

Appends a new WireFrameRecord to the conversation transcript for runId.

Persists both raw vendor wire bytes and canonical message projections.

Parameters

Parameter	Type	Description
runId	string	Enclosing flow run identifier.
frame	WireFrameRecord	Immutable wire frame record to append.

Returns

Promise<void>

Resolves once the frame is persisted.

Implementation of

LedgerStore.appendMessageFrame

---

close()

close(): void;

Defined in: sqlite/src/stores/sqlite-ledger-store.ts:381

Closes the underlying better-sqlite3 database connection.

Releases file descriptors and WAL shared-memory locks held by this store instance.

Returns

void

Returns nothing once the connection is closed.

---

compactRunFrames()

compactRunFrames(runId): Promise<void>;

Defined in: sqlite/src/stores/sqlite-ledger-store.ts:368

Prunes raw WireFrameRecord payloads for a terminal runId while retaining canonical audit headers.

Scoped strictly to runId so active runs sharing the same itemKey are never pruned.

Parameters

Parameter	Type	Description
runId	string	Terminal flow run identifier to compact.

Returns

Promise<void>

Resolves once wire frames for runId are compacted.

Implementation of

LedgerStore.compactRunFrames

---

createOrResumeRun()

createOrResumeRun(run): Promise<CreateOrResumeRunResult>;

Defined in: sqlite/src/stores/sqlite-ledger-store.ts:85

Creates a new flow run row (status: 'RUNNING') or resumes an existing run.

Pins compiledPrefixesJson on initial creation and returns completed step outputs for .inputFrom().

Parameters

Parameter	Type	Description
run	CreateOrResumeRunInput	Run initialization or resume request payload.

Returns

Promise<CreateOrResumeRunResult>

Current persisted state and completed step outputs.

Implementation of

LedgerStore.createOrResumeRun

---

getInterruptedStepsOnBoot()

getInterruptedStepsOnBoot(): Promise<readonly InterruptedStepBootRecord[]>;

Defined in: sqlite/src/stores/sqlite-ledger-store.ts:355

Queries all non-terminal runs ('QUEUED' | 'RUNNING' | 'WAITING' | 'SUSPENDED') on runtime startup.

Returns active step checkpoints and continuation stacks for reboot crash recovery.

Returns

Promise<readonly InterruptedStepBootRecord[]>

Non-terminal runs requiring recovery.

Implementation of

LedgerStore.getInterruptedStepsOnBoot

---

getMessageChain()

getMessageChain(leafMessageId): Promise<readonly WireFrameRecord[]>;

Defined in: sqlite/src/stores/sqlite-ledger-store.ts:236

Reconstructs the ordered WireFrameRecord[] ancestor chain from Turn 0 through leafMessageId.

Traverses parentMessageId links and returns frames in chronological root-to-leaf order.

Parameters

Parameter	Type	Description
leafMessageId	string	Identifier of the trailing message frame in the chain.

Returns

Promise<readonly WireFrameRecord[]>

Ordered root-to-leaf wire frame sequence.

Implementation of

LedgerStore.getMessageChain

---

getRunTerminalReceipts()

getRunTerminalReceipts(itemKeys): Promise<ReadonlyMap<string, RunTerminalReceiptRecord>>;

Defined in: sqlite/src/stores/sqlite-ledger-store.ts:342

Retrieves the latest terminal run receipts keyed by itemKey.

Used during prerequisite syncRoot wakeup and signal-correlated overlay commits.

Parameters

Parameter	Type	Description
itemKeys	readonly string[]	Work item keys to look up.

Returns

Promise<ReadonlyMap<string, RunTerminalReceiptRecord>>

Map of itemKey to terminal receipt record.

Implementation of

LedgerStore.getRunTerminalReceipts

---

getSuspendedForks()

getSuspendedForks(runId, opts?): Promise<readonly SuspendedForkRecord[]>;

Defined in: sqlite/src/stores/sqlite-ledger-store.ts:265

Queries unresolved suspended fork records for runId, optionally filtered by forkIds or parentStepExecId.

Excludes epochs already marked 'RESUMED' or 'ABORTED'.

Parameters

Parameter	Type	Description
runId	string	Enclosing flow run identifier.
opts?	GetSuspendedForksOptions	Optional filter criteria.

Returns

Promise<readonly SuspendedForkRecord[]>

Matching open suspended fork records.

Implementation of

LedgerStore.getSuspendedForks

---

markFrameTombstone()

markFrameTombstone(
   runId, 
   messageId, 
   callId, 
   compactedTombstone
): Promise<void>;

Defined in: sqlite/src/stores/sqlite-ledger-store.ts:209

Records a per-callId compacted skill tombstone on an earlier activateSkill message frame.

Updates compactedTombstones[callId] without mutating rawWireFrame.

Parameters

Parameter	Type	Description
runId	string	Enclosing flow run identifier.
messageId	string	Target WireFrameRecord.messageId.
callId	string	Tool call ID of the activateSkill invocation.
compactedTombstone	string	Tombstone replacement string for cross-model escalations.

Returns

Promise<void>

Resolves once the tombstone entry is recorded.

Implementation of

LedgerStore.markFrameTombstone

---

mutateLanePlan()

mutateLanePlan(req): Promise<void>;

Defined in: sqlite/src/stores/sqlite-ledger-store.ts:159

Atomically chains spawned prerequisite items and validates DAG acyclicity and maxPrerequisiteDepth.

Rejects cycles and depth limit breaches before committing any edge to SQLite.

Parameters

Parameter	Type	Description
req	MutateLanePlanRequest	Lane plan mutation request.

Returns

Promise<void>

Resolves once the lane DAG mutation is committed.

Implementation of

LedgerStore.mutateLanePlan

---

recordForkSuspension()

recordForkSuspension(record): Promise<void>;

Defined in: sqlite/src/stores/sqlite-ledger-store.ts:249

Persists a SuspendedForkRecord when a child fork suspends on an upward or sibling interrupt.

Stores the monotonic suspendedForkId (${forkId}#${suspensionEpoch}) and continuation stack.

Parameters

Parameter	Type	Description
record	SuspendedForkRecord	Suspended fork snapshot and continuation stack.

Returns

Promise<void>

Resolves once the suspension record is persisted.

Implementation of

LedgerStore.recordForkSuspension

---

recordRunTerminalReceipt()

recordRunTerminalReceipt(
   runId, 
   itemKey, 
   terminalState, 
   scopeReceiptJson?
): Promise<void>;

Defined in: sqlite/src/stores/sqlite-ledger-store.ts:315

Persists the terminal exit state and final scope receipt for runId and itemKey.

Updates both harness_terminal_receipts and harness_runs.

Parameters

Parameter	Type	Description
runId	string	Completed flow run identifier.
itemKey	string	Work item deduplication key.
terminalState	string	Terminal exit state string.
scopeReceiptJson?	string	Optional JSON-serialized final scope receipt.

Returns

Promise<void>

Resolves once the terminal receipt is committed.

Implementation of

LedgerStore.recordRunTerminalReceipt

---

recordStepStart()

recordStepStart(step): Promise<void>;

Defined in: sqlite/src/stores/sqlite-ledger-store.ts:100

Records the start of a flow step execution and initializes its ContinuationFrame[] stack.

Persists baseScopeCheckpoint and executableId for reboot recovery.

Parameters

Parameter	Type	Description
step	RecordStepStartInput	Step start metadata and initial continuation stack.

Returns

Promise<void>

Resolves once the step start is committed.

Implementation of

LedgerStore.recordStepStart

---

recordStepTransition()

recordStepTransition(transition): Promise<void>;

Defined in: sqlite/src/stores/sqlite-ledger-store.ts:297

Records a step lifecycle transition ('RUNNING' | 'COMPLETED' | 'INTERRUPTED' | 'FAILED' | 'SUSPENDED').

Commits serialized output, scope checkpoints, and universal step telemetry.

Parameters

Parameter	Type	Description
transition	RecordStepTransitionInput	Step transition payload and telemetry snapshot.

Returns

Promise<void>

Resolves once the step transition is persisted.

Implementation of

LedgerStore.recordStepTransition

---

replaceMessageFrame()

replaceMessageFrame(runId, frame): Promise<void>;

Defined in: sqlite/src/stores/sqlite-ledger-store.ts:191

Replaces an existing WireFrameRecord in-place (such as after appendToolResultNotes).

Updates rawWireFrame and canonical while preserving messageId and parentMessageId.

Parameters

Parameter	Type	Description
runId	string	Enclosing flow run identifier.
frame	WireFrameRecord	Updated wire frame record.

Returns

Promise<void>

Resolves once the frame replacement is committed.

Implementation of

LedgerStore.replaceMessageFrame

---

resolveSuspendedFork()

resolveSuspendedFork(suspendedForkId, status): Promise<void>;

Defined in: sqlite/src/stores/sqlite-ledger-store.ts:282

Marks suspendedForkId and any earlier unresolved epochs ${forkId}#1 .. ${forkId}#${epoch} as resolved.

Prevents resolved suspension epochs from remaining open in subsequent queries.

Parameters

Parameter	Type	Description
suspendedForkId	string	Monotonic ${forkId}#${suspensionEpoch} identifier.
status	"RESUMED" | "ABORTED"	Resolution status.

Returns

Promise<void>

Resolves once the status transition is committed.

Implementation of

LedgerStore.resolveSuspendedFork

---

updateContinuationStack()

updateContinuationStack(
   runId, 
   stepExecId, 
   continuationStack, 
   opts?
): Promise<void>;

Defined in: sqlite/src/stores/sqlite-ledger-store.ts:118

Atomically updates the serialized ContinuationFrame[] stack for stepExecId.

Optionally updates baseScopeCheckpoint after prerequisite syncRoot wakeup.

Parameters

Parameter	Type	Description
runId	string	Enclosing flow run identifier.
stepExecId	string	Target step execution identifier.
continuationStack	readonly ContinuationFrame[]	Updated outer-to-inner continuation stack.
opts?	UpdateContinuationStackOptions	Optional updated base scope checkpoint.

Returns

Promise<void>

Resolves once the continuation stack is persisted.

Implementation of

LedgerStore.updateContinuationStack

---

updateRunInput()

updateRunInput(runId, update): Promise<void>;

Defined in: sqlite/src/stores/sqlite-ledger-store.ts:144

Updates a run's serialized flow input payload and optional pending rewind target step ID.

Used during .replaceWith() step promotion and .onSignal().rewindTo() transitions.

Parameters

Parameter	Type	Description
runId	string	Target flow run identifier.
update	UpdateRunInputParams	Updated input JSON and rewind target.

Returns

Promise<void>

Resolves once the run input update is committed.

Implementation of

LedgerStore.updateRunInput