Interface: TopologyStore

Defined in: ports/topology-store.ts:9

Runtime storage port for run-isolated Copy-on-Write partition contract overlays and 3-way commits.

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

Methods

commitRunOverlay()

commitRunOverlay(runId): Promise<CommitRunOverlayResult>;

Defined in: ports/topology-store.ts:90

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.

---

discardRunOverlay()

discardRunOverlay(runId): Promise<void>;

Defined in: ports/topology-store.ts:101

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.

---

getPartitions()

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

Defined in: ports/topology-store.ts:19

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.

---

resetRunOverlay()

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

Defined in: ports/topology-store.ts:64

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?	{ scope?: "step" | "run"; stepExecId?: string; }	Reset scope options.
opts.scope?	"step" | "run"	-
opts.stepExecId?	string	-

Returns

Promise<void>

Resolves once matching uncommitted overlay mutations are rolled back.

---

sealRunOverlay()

sealRunOverlay(runId): Promise<void>;

Defined in: ports/topology-store.ts:78

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.

---

syncRunOverlays()

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

Defined in: ports/topology-store.ts:52

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.

---

updateContract()

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

Defined in: ports/topology-store.ts:34

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.