Store

Event stores, URL parsing, and migration. For the conceptual model see concepts/graph (graph as projection of the event log) and concepts/replay.

Stores

Bases: Protocol

Append-only per-run event log. CONTRACT v0.5 #2.

Per-run view onto a SQLite-backed event log.

fork_run(path, *, parent_run_id, new_run_id, at_event_id, label, created_at) classmethod

Copy events from parent_run_id up to and including at_event_id into new_run_id (CONTRACT v0.5 #11: copy rows, no row-sharing).

Returns the number of events copied.

URL parsing + helpers

Open a store for run_id at url. Returns an EventStore.

This is the single entry point the runtime and CLI use to open a store from a URL. Drivers are imported lazily so the Postgres dependency stays optional.

Parse a store URL, or raise InvalidStoreURL with a helpful message.

Migration

Copy every run (or a subset) from source_url into dest_url.

Parameters:

Name	Type	Description	Default
source_url	str	e.g. sqlite:///dev.db	required
dest_url	str	e.g. postgres://localhost/prod	required
only_run_ids	Optional[list[str]]	if given, migrate only these runs.	None
on_progress	Optional[Callable[[MigrationRunReport], None]]	called after each run finishes (success or failure) with the MigrationRunReport for that run.	None
skip_corrupted	bool	if True, rows whose payload fails JSON decode are skipped (not migrated, not failing the run). The skipped event ids appear in the per-run report's skipped_events. The resulting destination run is partial — the operator is on notice.	False

Returns:

Type	Description
MigrationReport	A MigrationReport. The overall operation is considered
MigrationReport	successful iff every run's status is "ok" or "skipped".