Skip to main content

Module write_group

Module write_group 

Expand description

The write-group port: a store’s log read back in the writes that made it.

§Why a store has to say this

EventStore::read yields one event at a time, and nothing on a SequencedEvent says which append, or which ingested group, wrote it. A runner pushing the local log, or a StoreSyncPeer answering a pull, therefore could not keep a multi-event write whole: it cut one at a page boundary, or merged independent writes into one atomic unit, and a relayed foreign group lost the guard it arrived with (SY-30, #420).

WriteGroupStore is the store saying it. Every row belongs to exactly one write group: one append call is one group, and one IngestGroup that lands at least one foreign event is one group, its compensation included (SY-2). A group is named by its first position, the lowest local position among the rows it wrote, and reads back with the guard it was ingested under.

§Why this trait lives here and not on EventStore

The argument ingest makes for IngestStore: coherence lets each adapter implement a trait this crate defines, so happenstance-core never hears about write groups and no published read type changes. A group id is store-local and never travels; the wire shape stays EventGroup.

§Why first is the cursor

A store that serialises its writers (SQLite, the Durable Object, the in-memory stores) writes a group’s rows contiguously, and either end of the group would do. Postgres and Neon do not serialise: two concurrent appends can interleave their positions, G = {5, 7} and H = {6, 8}. Resuming above the last position pushed after G would skip H’s row 6; resuming above G’s first position does not. Every row at a position at or below a group’s first belongs to a group whose own first is no higher, so it was read already, and a group commits in one transaction, so no group with first at or below an observed position can appear later (ES-10).

§Rows written before a store recorded groups

Read as one group each, named by their own position, with no guard. Which rows one earlier call wrote is not recorded anywhere, so it cannot be recovered; a pre-upgrade multi-event append still travels split, exactly as it did before.

Structs§

GroupOrderError
A GroupPageBuilder was offered a row out of group order: one naming the group first, after the group after had been offered and left, where first is not above after.
GroupPage
What one read_groups returned.
GroupPageBuilder
Folds rows, offered in group order, into a page of whole groups.
WriteGroup
One write as the store recorded it: the events one append, or one ingested group with its compensation, wrote together, and the origin’s guard.

Enums§

GuardCodecError
Why a guard could not be stored or read back.

Constants§

STORED_GUARD_FORMAT
The first byte of every stored guard.

Traits§

SendWriteGroupStore
A store that can read its log back in the write groups it wrote.
WriteGroupStore
A store that can read its log back in the write groups it wrote.

Functions§

decode_guard
The guard stored holds, as encode_guard wrote it.
encode_guard
The bytes a store keeps for guard.