Reference

Event sourcing and disposable projections¶

Behavior¶

Event sequence	Projection behavior
Unique contiguous generations	Ordered replay and event-input build identity
Gap or duplicate generation	Reject the build
Failed dependency	Use the dependency planner to hold downstream work

Throughput and atomic pointer swaps belong to the selected backend. Mari defines replay semantics.

Example replay differences

Event generations	Result
`1, 2, 3`	Projection returned with stable build ID
`1, 3`	Rejected: generation gap
`1, 2, 2`	Rejected: duplicate generation/event

Canonical artifacts and append-only events remain authoritative. With a pure projector and stable initial state, replay_projection produces deterministic derived state. Its build ID fingerprints the ordered events. A backend can validate and swap that build using its own transaction boundary.

How it works¶

Events must have unique IDs and contiguous generations. The replay function folds them in order and hashes the complete event input. Generation gaps and duplicate events fail before a usable build is returned. Storage adapters own staging validation, pointer swaps, and rollback because those guarantees depend on the selected database.

The build ID covers event IDs, generations, kinds, and payloads. Initial state, projector implementation, and produced output are separate inputs to cache validity. Record those through a versioned derivation and completed receipt in the dependency planner. Keep the projector side-effect-free because a later invalid event can fail after earlier folds.

Papers and standards

Data pipeline reproducibility Invariant confluence W3C PROV

Canonical artifactsdocuments · events · reviews

deterministic fold

Staging projectionsvector · lexical · graph · Markdown

validate + swap

Current read versionrollback pointer retained

Deterministic replay with contiguous generations¶

from mari_kit.platform import KnowledgeEvent, replay_projection

events = [
    KnowledgeEvent(
        event_id="event-1",
        generation=1,
        kind="artifact.indexed",
        payload={"artifact_id": "policy-7"},
    )
]

def project(state: set[str], event: KnowledgeEvent) -> set[str]:
    return state | {str(event.payload["artifact_id"])}

build = replay_projection(set(), events, projector=project)
assert build.state == {"policy-7"}
assert build.generation == 1
print(build.build_id)  # stable SHA-256 identity of the replay input