Class: SqliteTopologyStore

Defined in: sqlite/src/stores/sqlite-topology-store.ts:28

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

Manages canonical base partition contracts alongside per-run Copy-on-Write overlays, stacked prerequisite synchronization, step/run-scoped resets, and 3-way overlay commits.

Implements

• TopologyStore

Constructors

Constructor

new SqliteTopologyStore(uriOrDb): SqliteTopologyStore;

Defined in: sqlite/src/stores/sqlite-topology-store.ts:41

Initializes a SqliteTopologyStore against a SQLite file path, :memory:, or existing Database handle.

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

Parameters

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

Returns

SqliteTopologyStore

Methods

close()

close(): void;

Defined in: sqlite/src/stores/sqlite-topology-store.ts:174

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.

---

commitRunOverlay()

commitRunOverlay(runId): Promise<CommitRunOverlayResult>;

Defined in: sqlite/src/stores/sqlite-topology-store.ts:146

Atomically commits runId's overlay (and any absorbed ancestor/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 the committed run IDs and updated epochs.

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: sqlite/src/stores/sqlite-topology-store.ts:161

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: sqlite/src/stores/sqlite-topology-store.ts:54

Loads the partition state map for runId (merging any uncommitted per-run CoW overlay over the base store).

Pins each partition's initial baseContractTextAtAcquire when runId first inspects the 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: sqlite/src/stores/sqlite-topology-store.ts:115

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?	ResetRunOverlayOptions	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: sqlite/src/stores/sqlite-topology-store.ts:130

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 without polluting the base store.

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: sqlite/src/stores/sqlite-topology-store.ts:97

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 when committed sequentially.

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: sqlite/src/stores/sqlite-topology-store.ts:73

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 by resetRunOverlay(), 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