Class: PostgresTopologyStore

Defined in: postgres/src/stores/postgres-topology-store.ts:34

PostgreSQL implementation of the @paraharness/core TopologyStore runtime port.

Provides run-isolated Copy-on-Write partition contract overlays, at-most-once per-run epoch increments, stacked-PR syncRunOverlays baseline advancement, step/run-scoped rollbacks, and atomic 3-way merge commits into harness_topology_base.

Implements

• TopologyStore

Constructors

Constructor

new PostgresTopologyStore(client): PostgresTopologyStore;

Defined in: postgres/src/stores/postgres-topology-store.ts:49

Initializes a PostgresTopologyStore 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

PostgresTopologyStore

Methods

commitRunOverlay()

commitRunOverlay(runId): Promise<CommitRunOverlayResult>;

Defined in: postgres/src/stores/postgres-topology-store.ts:180

Atomically commits runId's overlay (and any absorbed prerequisite SEALED_UNMERGED overlays) to the base store using a 3-way merge against baseContractTextAtAcquire.

Allocates monotonic base epoch numbers at commit time and returns { committedRunIds, updatedEpochs }.

Parameters

Parameter	Type	Description
runId	string	Flow run identifier whose changes landed.

Returns

Promise<CommitRunOverlayResult>

Committed run IDs and newly allocated base epoch numbers.

Implementation of

TopologyStore.commitRunOverlay

---

discardRunOverlay()

discardRunOverlay(runId): Promise<void>;

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

Discards runId's overlay when a run fails, a PR closes unmerged, or maxSealedAgeHours expires.

Removes all uncommitted or sealed overlay rows for runId without modifying the base store.

Parameters

Parameter	Type	Description
runId	string	Flow run identifier whose overlay should be discarded.

Returns

Promise<void>

Resolves once the overlay is removed.

Implementation of

TopologyStore.discardRunOverlay

---

getPartitions()

getPartitions(runId?): Promise<ReadonlyMap<string, TopologyPartitionState>>;

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

Loads the partition state map for runId, merging any uncommitted CoW overlay over harness_topology_base.

Pins baseContractTextAtAcquire when runId first inspects each base partition.

Parameters

Parameter	Type	Description
runId?	string	Optional active flow run identifier.

Returns

Promise<ReadonlyMap<string, TopologyPartitionState>>

Map of partitionId to partition state.

Implementation of

TopologyStore.getPartitions

---

resetRunOverlay()

resetRunOverlay(runId, opts?): Promise<void>;

Defined in: postgres/src/stores/postgres-topology-store.ts:149

Resets uncommitted overlay mutations for runId at either the 'step' or 'run' scope.

Preserves completed step mutations when scope === 'step' and rolls back the entire run overlay when scope === 'run'.

Parameters

Parameter	Type	Description
runId	string	Target flow run identifier.
opts?	ResetPgRunOverlayOptions	Reset scope options.

Returns

Promise<void>

Resolves once matching uncommitted overlay mutations are rolled back.

Implementation of

TopologyStore.resetRunOverlay

---

sealRunOverlay()

sealRunOverlay(runId): Promise<void>;

Defined in: postgres/src/stores/postgres-topology-store.ts:166

Transitions runId's overlay to SEALED_UNMERGED upon flow exit 'done' when awaiting an external merge signal.

Allows dependent stacked runs to absorb the sealed overlay via syncRunOverlays.

Parameters

Parameter	Type	Description
runId	string	Completed flow run identifier.

Returns

Promise<void>

Resolves once the overlay is sealed.

Implementation of

TopologyStore.sealRunOverlay

---

syncRunOverlays()

syncRunOverlays(targetRunId, prerequisiteRunIds): Promise<void>;

Defined in: postgres/src/stores/postgres-topology-store.ts:128

Merges prerequisite runs' ACTIVE or SEALED_UNMERGED overlays into targetRunId's overlay.

Advances targetRunId's 3-way merge-base text for each absorbed partition so stacked PRs never false-conflict.

Parameters

Parameter	Type	Description
targetRunId	string	Dependent run absorbing the prerequisite overlays.
prerequisiteRunIds	readonly string[]	Prerequisite run identifiers to merge from.

Returns

Promise<void>

Resolves once prerequisite overlays are merged.

Implementation of

TopologyStore.syncRunOverlays

---

updateContract()

updateContract(
   runId, 
   partitionId, 
   newContractText, 
   stepExecId?
): Promise<{
  newEpoch: number;
}>;

Defined in: postgres/src/stores/postgres-topology-store.ts:100

Writes a contract update to runId's isolated Copy-on-Write overlay.

Increments the partition's overlay epoch at most once per (runId, partitionId) unless reset, and tags the mutation with stepExecId for step-scoped rollback.

Parameters

Parameter	Type	Description
runId	string	Active flow run identifier.
partitionId	string	Target partition identifier.
newContractText	string	Updated contract text.
stepExecId?	string	Optional active step execution identifier.

Returns

Promise<{ newEpoch: number; }>

Updated overlay epoch for partitionId.

Implementation of

TopologyStore.updateContract