Interface: LedgerStore

Defined in: ports/ledger-store.ts:18

Durable runtime storage port for flow runs, continuation call stacks, wire frames, suspended child forks, and lane DAG mutations.

Always resolves file or database paths against the immutable host process root (Invariant 5).

Methods

appendMessageFrame()

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

Defined in: ports/ledger-store.ts:88

Appends a new WireFrameRecord to the conversation transcript for runId.

Stores both the raw vendor wire bytes and canonical projection keyed by frame.messageId.

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.

---

compactRunFrames()

compactRunFrames(runId): Promise<void>;

Defined in: ports/ledger-store.ts:216

Prunes raw WireFrameRecord payloads for a terminal runId while retaining run receipts and telemetry.

Scoped strictly to runId so compaction never prunes frames of a newer run for the same itemKey.

Parameters

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

Returns

Promise<void>

Resolves once wire frames for runId are compacted.

---

createOrResumeRun()

createOrResumeRun(run): Promise<CreateOrResumeRunResult>;

Defined in: ports/ledger-store.ts:28

Creates a new flow run record or resumes an existing run for run.runId.

Pins compiledPrefixesJson on initial creation and returns the latest persisted status and step outputs.

Parameters

Parameter	Type	Description
run	CreateOrResumeRunInput	Run initialization and pinned wire prefix payload.

Returns

Promise<CreateOrResumeRunResult>

Current persisted state and completed step outputs for the run.

---

getInterruptedStepsOnBoot()

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

Defined in: ports/ledger-store.ts:205

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

Includes both mid-step runs and runs that crashed between steps where stepExecId is null.

Returns

Promise<readonly InterruptedStepBootRecord[]>

Non-terminal runs requiring crash recovery or scheduling.

---

getMessageChain()

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

Defined in: ports/ledger-store.ts:125

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

Traverses parentMessageId links to return the root-to-leaf conversation history.

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.

---

getRunTerminalReceipts()

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

Defined in: ports/ledger-store.ts:196

Retrieves the latest terminal run receipts keyed by itemKey.

Used by the scheduler and prerequisite barrier to verify prerequisite completion and gather receipts.

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.

---

getSuspendedForks()

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

Defined in: ports/ledger-store.ts:148

Queries open ('SUSPENDED') fork records for runId, optionally filtered by forkIds or parentStepExecId.

Returns only unresolved suspension epochs awaiting resumeFork resolution.

Parameters

Parameter	Type	Description
runId	string	Enclosing flow run identifier.
opts?	{ forkIds?: readonly string[]; parentStepExecId?: string; }	Optional filter criteria.
opts.forkIds?	readonly string[]	-
opts.parentStepExecId?	string	-

Returns

Promise<readonly SuspendedForkRecord[]>

Matching open suspended fork records.

---

markFrameTombstone()

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

Defined in: ports/ledger-store.ts:114

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

Substituted only when ModelDriver.prepareFork() escalates across distinct models (substituteTombstones: true).

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 used on cross-model escalations.

Returns

Promise<void>

Resolves once the tombstone entry is recorded.

---

mutateLanePlan()

mutateLanePlan(req): Promise<void>;

Defined in: ports/ledger-store.ts:76

Atomically validates DAG acyclicity and maxPrerequisiteDepth and enqueues spawned prerequisite items or dependencies.

Rejects cycles or depth violations before mutating the lane work queue.

Parameters

Parameter	Type	Description
req	MutateLanePlanRequest	Lane plan mutation request.

Returns

Promise<void>

Resolves once the lane DAG mutation is committed.

---

recordForkSuspension()

recordForkSuspension(record): Promise<void>;

Defined in: ports/ledger-store.ts:136

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

Captures the monotonic suspendedForkId epoch, child scope checkpoint, and nested continuation stack.

Parameters

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

Returns

Promise<void>

Resolves once the suspension record is persisted.

---

recordRunTerminalReceipt()

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

Defined in: ports/ledger-store.ts:185

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

Enables dependent runs to inspect prerequisite terminal receipts during syncRoot wakeup.

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.

---

recordStepStart()

recordStepStart(step): Promise<void>;

Defined in: ports/ledger-store.ts:39

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

Persists the initial baseScopeCheckpoint and executableId so crash recovery can rebind the step.

Parameters

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

Returns

Promise<void>

Resolves once the step start is durably committed.

---

recordStepTransition()

recordStepTransition(transition): Promise<void>;

Defined in: ports/ledger-store.ts:171

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

Commits the step's serialized output, scope checkpoints, and universal telemetry snapshot.

Parameters

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

Returns

Promise<void>

Resolves once the step transition is persisted.

---

replaceMessageFrame()

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

Defined in: ports/ledger-store.ts:100

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

Preserves messageId and parentMessageId chain links while updating rawWireFrame and canonical.

Parameters

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

Returns

Promise<void>

Resolves once the frame replacement is committed.

---

resolveSuspendedFork()

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

Defined in: ports/ledger-store.ts:160

Marks a previously suspended fork epoch as 'RESUMED' or 'ABORTED'.

Prevents a resolved suspendedForkId epoch from being replayed more than once.

Parameters

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

Returns

Promise<void>

Resolves once the status transition is committed.

---

updateContinuationStack()

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

Defined in: ports/ledger-store.ts:53

Atomically updates the serialized ContinuationFrame[] stack for stepExecId.

Serialized per stepExecId by the runtime to preserve active leases, skill state, and child fork frames.

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?	{ baseScopeCheckpoint?: string; }	Optional updated base scope checkpoint.
opts.baseScopeCheckpoint?	string	-

Returns

Promise<void>

Resolves once the continuation stack is persisted.

---

updateRunInput()

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

Defined in: ports/ledger-store.ts:65

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	{ inputJson: string; rewindPendingToStepId?: string | null; }	Updated input JSON and rewind target.
update.inputJson	string	-
update.rewindPendingToStepId?	string | null	-

Returns

Promise<void>

Resolves once the run input update is committed.