Class: PostgresLedgerStore

Defined in: postgres/src/stores/postgres-ledger-store.ts:64

PostgreSQL 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 PostgreSQL tables serialized via p-queue.

Implements

• LedgerStore

Constructors

Constructor

new PostgresLedgerStore(client): PostgresLedgerStore;

Defined in: postgres/src/stores/postgres-ledger-store.ts:79

Initializes a PostgresLedgerStore backed by a PostgresQueryClient, pg.Pool, or connection URI string.

Defers DDL execution until the first store operation so constructing the store performs zero I/O.

Parameters

Parameter	Type	Description
client	| string | PostgresQueryClient | Pool	PostgreSQL query client, pg.Pool, or connection URI.

Returns

PostgresLedgerStore

Methods

appendMessageFrame()

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

Defined in: postgres/src/stores/postgres-ledger-store.ts:197

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

---

compactRunFrames()

compactRunFrames(runId): Promise<void>;

Defined in: postgres/src/stores/postgres-ledger-store.ts:398

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: postgres/src/stores/postgres-ledger-store.ts:109

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: postgres/src/stores/postgres-ledger-store.ts:385

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: postgres/src/stores/postgres-ledger-store.ts:258

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: postgres/src/stores/postgres-ledger-store.ts:370

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: postgres/src/stores/postgres-ledger-store.ts:287

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?	GetPgSuspendedForksOptions	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: postgres/src/stores/postgres-ledger-store.ts:231

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: postgres/src/stores/postgres-ledger-store.ts:181

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

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

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: postgres/src/stores/postgres-ledger-store.ts:273

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: postgres/src/stores/postgres-ledger-store.ts:343

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: postgres/src/stores/postgres-ledger-store.ts:124

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: postgres/src/stores/postgres-ledger-store.ts:323

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: postgres/src/stores/postgres-ledger-store.ts:213

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: postgres/src/stores/postgres-ledger-store.ts:306

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: postgres/src/stores/postgres-ledger-store.ts:142

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?	UpdatePgContinuationStackOptions	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: postgres/src/stores/postgres-ledger-store.ts:168

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	UpdatePgRunInputParams	Updated input JSON and rewind target.

Returns

Promise<void>

Resolves once the run input update is committed.

Implementation of

LedgerStore.updateRunInput