Struct SerializableGraph 

pub struct SerializableGraph { /* private fields */ }

Common SSI algorithm for one database incarnation. Participants, both edge indexes, logical observations and owned predicate keys share a caller-selected retention budget. The owner serializes calls with snapshot admission, predicate registration and durable commit admission; this type does not acquire provider or SQL locks.

Only SERIALIZABLE transactions participate. Register a read/write edge when the reader cannot see the writer’s logical change, including absent keys and predicate ranges. Physical index-sharing conflicts are not such edges. Check existing writer intents when registering reads and existing reads when registering writes; observing only committed changes loses cycles.

A prepared transaction has passed the final serialization check and cannot be selected as a victim. Keep it prepared across an uncertain physical outcome, and call commit or rollback only after authoritative completion. Savepoint undo must not discard the transaction’s read dependencies.

Implementations

impl SerializableGraph

pub fn read_checkpoint_records( database: DatabaseId, coordinator: [u8; 16], control: &StorageReadControl, scan: impl FnMut(&mut dyn FnMut(&[u8], &mut dyn Read) -> VersionResult<()>) -> VersionResult<()>, ) -> VersionResult<Self>

Restore a complete ordered checkpoint record set for this database incarnation. The scanner supplies each key and one bounded value reader exactly once in byte-key order, stopping on a callback error. Admission retains the first decode error even if the scanner suppresses or replaces that stop signal; subsequent callbacks read nothing. Checksums, identities, keys, counts and graph references must all agree. The graph, owned predicates and retained comparison keys share the caller’s allowance; no partial restore escapes on error.

impl SerializableGraph

pub fn checkpoint_records_changed(&self) -> bool

Whether keyed checkpoint state needs publication. Graphs restored from a complete legacy checkpoint need initial record publication even without a logical change. Only a validated keyed-record restore establishes the comparison baseline.

pub fn write_checkpoint_changes<'a>( &'a self, control: &StorageReadControl, update: impl FnMut(SerializableCheckpointKey, Option<SerializableCheckpointRecord<'a>>) -> VersionResult<()>, ) -> VersionResult<()>

Stream the exact difference from the keyed checkpoint loaded under this admission. A missing value deletes the old key; a value inserts a new record or replaces the header. Providers apply the complete stream in one durable transaction, including changes preceding an operation error. This borrows existing graph data and allocates no deletion journal or second encoded graph. It does not acknowledge durability or change the baseline.

impl SerializableGraph

pub fn checkpoint_changed(&self) -> bool

Whether retained state needs a durable checkpoint. A new coordinator does; a fully restored checkpoint does not until an operation changes its contents, including changes preceding an error. Encoding alone cannot acknowledge provider durability, so it never clears this flag. Check only while holding the same exclusive admission that loaded this graph.

pub fn write_checkpoint( &self, output: &mut dyn Write, control: &StorageReadControl, ) -> VersionResult<()>

Stream one complete coordinator checkpoint, including predicates and prepared physical receipt bindings. The provider owns atomic replacement, encryption and shared admission. A checksum detects incomplete/corrupt state; it does not replace the provider’s authentication or durability. No complete encoded-state buffer is allocated.

pub fn checkpoint_length( &self, control: &StorageReadControl, ) -> VersionResult<u64>

Compute the exact serialized length for bounded physical BLOB allocation without creating an encoded-state copy.

pub fn read_checkpoint( database: DatabaseId, coordinator: [u8; 16], input: &mut dyn Read, control: &StorageReadControl, ) -> VersionResult<Self>

Restore a complete checkpoint for the expected database and coordinator incarnation. Decoded participants, both edge orientations and owned predicate keys share the supplied allowance. On any format, checksum, I/O, cancellation or resource failure, no partially restored graph is returned.

impl SerializableGraph

pub fn database(&self) -> DatabaseId

pub fn coordinator(&self) -> [u8; 16]

pub fn admit_with_lease( &mut self, read_only: bool, control: &StorageReadControl, retain: impl FnOnce(SerializableTransactionId) -> VersionResult<SerializableParticipant>, ) -> VersionResult<SerializableParticipant>

Bind admission to a retained provider lease before publishing the actor. Failed lease allocation aborts only the new actor and still consumes its allocation when the owner retains this state. Legacy manually owned actors have no lease binding and are never inferred dead by recovery.

pub fn recover_abandoned( &mut self, control: &StorageReadControl, is_alive: impl FnMut(SerializableTransactionId) -> VersionResult<bool>, finish: impl FnMut(StorageTransactionId) -> VersionResult<CommitStatus>, ) -> VersionResult<()>

Retire only participants whose liveness owner is authoritatively gone. Completed participants release their outcome-retention lease without changing their confirmed state. A live unbound participant can abort immediately. A prepared physical publication must be resolved or aborted through its exact durable receipt identity; a missing receipt stops recovery and never proves rollback. Earlier confirmed resolutions survive a later error. The caller retains the resulting state before releasing shared admission, including on failure.

impl SerializableGraph

pub fn observe_read( &mut self, transaction: SerializableTransactionId, predicate: SerializablePredicate<'_>, control: &StorageReadControl, ) -> VersionResult<()>

Register before a logical read can race with a write. This includes empty point/range results, index-only and cached reads. Check existing write intents as well as committed writers invisible to the reader’s fixed snapshot; later writers inspect the retained read. The caller coordinates this boundary with snapshot capture and publication.

pub fn observe_write( &mut self, transaction: SerializableTransactionId, predicate: SerializablePredicate<'_>, control: &StorageReadControl, ) -> VersionResult<()>

Register before staging a logical write. Supply the changed row and every affected old/new index key separately, or the entire object for an object-wide change. Physical posting clusters and counters are not logical keys. This checks existing readers and retains an intent for later reads. A failed observation publishes neither its intent nor any dependencies or peer victims.

pub fn write_mark( &self, transaction: SerializableTransactionId, ) -> VersionResult<SerializableWriteMark>

pub fn rollback_writes( &mut self, mark: SerializableWriteMark, ) -> VersionResult<()>

Cancel successful write intents after a statement/savepoint mark. This allocation-free cleanup remains usable for cancelled or peer-doomed transactions, but cannot erase their reads or serialization failure. Prepared or finished transactions cannot undo their publication inputs.

impl SerializableGraph

pub fn retains_transaction_receipt( &self, transaction: StorageTransactionId, ) -> bool

Whether the retained checkpoint still needs this exact physical receipt, including prepared outcomes, committed conflict history and live terminal completion leases. Receipt reclamation must check the durably published graph under the provider’s exclusive SSI admission.

pub fn validate_persisted_publications( &self, control: &StorageReadControl, lookup: impl FnMut(StorageTransactionId) -> VersionResult<CommitStatus>, ) -> VersionResult<()>

Validate terminal outcomes restored from a provider checkpoint before exposing its graph or invoking admission. Every retained committed or aborted publication must still have the same authoritative physical receipt; these receipts outlive record-history reclamation. A missing receipt rejects the persisted checkpoint rather than letting a stale backup branch borrow its confirmed outcome. Prepared publications keep their ordinary reconciliation path. This read-only check borrows retained entries, allocates no payload and leaves live-session terminal outcome precedence unchanged.

pub fn prepare_publication( &mut self, participant: SerializableTransactionId, transaction: StorageTransactionId, fingerprint: CommitFingerprint, control: &StorageReadControl, ) -> VersionResult<SerializablePublication>

Seal the participant against its caller’s already allocated durable transaction. Repeated preparation must preserve both identities and the original fingerprint, including during physical candidate re-preparation. A logically read-only participant can publish maintenance records outside logical predicate spaces; logical write observations remain forbidden. Participants without physical changes finish directly through the graph without allocating a durable transaction.

pub fn publication( &self, participant: SerializableTransactionId, ) -> VersionResult<Option<SerializablePublication>>

Retrieve the physical receipt identity needed for recovery of a retained prepared participant. The provider queries this exact durable transaction; the SSI participant allocation is never a receipt key.

pub fn reconcile_publications( &mut self, control: &StorageReadControl, lookup: impl FnMut(StorageTransactionId) -> VersionResult<CommitStatus>, ) -> VersionResult<()>

Reconcile unresolved physical publications under shared admission before capturing another data snapshot. A lost commit reply may leave committed data behind a prepared SSI participant; admitting a snapshot first would misclassify that visible writer. Confirmed pending allocations may remain prepared, but a missing authoritative receipt prevents admission and never proves abort. The provider retains confirmed resolutions even if a later lookup fails.

pub fn resolve_publication( &mut self, publication: SerializablePublication, status: CommitStatus, ) -> VersionResult<CommitStatus>

Apply an authoritative status obtained for this token’s physical transaction. Pending/unknown outcomes keep an unresolved participant prepared; a committed receipt must match the transaction and fingerprint. Known terminal outcomes cannot be downgraded by later pending/unknown status. Terminal completion neither allocates nor observes statement cancellation. The provider must retain the resolved state before releasing shared publication admission.

impl SerializableGraph

pub fn new( database: DatabaseId, coordinator: [u8; 16], memory: &MemoryBudget, ) -> VersionResult<Self>

Create the graph for a nonzero provider-coordinated incarnation. A provider must retain this incarnation and its admission state for every overlapping participant, including across process handoff.

pub fn admit( &mut self, read_only: bool, control: &StorageReadControl, ) -> VersionResult<SerializableTransactionId>

Allocate and admit a logical participant at the same boundary as its fixed data snapshot, without allocating a physical transaction or writing user data. The owner coordinates and retains admission across every provider process. Allocations survive graph reclamation and are never reused within the coordinator incarnation.

pub fn status( &self, transaction: SerializableTransactionId, ) -> VersionResult<SerializableStatus>

Read the original logical outcome while its participant lease is retained. Terminal outcomes take precedence over earlier victim selection; this never converts an uncertain physical publication into a completed transaction.

pub fn check_active( &self, transaction: SerializableTransactionId, ) -> VersionResult<()>

Fail a doomed transaction before another statement or commit. Prepared state is sealed, including while its durable outcome is unknown.

pub fn observe_rw( &mut self, observer: SerializableTransactionId, reader: SerializableTransactionId, writer: SerializableTransactionId, control: &StorageReadControl, ) -> VersionResult<()>

Register a dependency directed from reader to writer. The observing transaction must be one endpoint and still active. A peer may be marked doomed; its next active check or preparation then reports a serialization failure. A rejected local observation publishes no edge and does not doom its transaction: statement/savepoint recovery can undo that operation while retaining earlier reads. Nonoverlapping and duplicate edges are ignored.

pub fn prepare_commit( &mut self, transaction: SerializableTransactionId, control: &StorageReadControl, ) -> VersionResult<()>

Check incoming dangerous structures before durable publication, preferring an unprepared pivot as the victim. Preparation is idempotent and reserves ordering space for authoritative completion even if other transactions continue meanwhile.

pub fn commit( &mut self, transaction: SerializableTransactionId, ) -> VersionResult<()>

Publish a confirmed committed outcome without allocation or cancellation. Never call this on a merely attempted or uncertain provider commit. Repeating the same confirmed outcome is harmless.

pub fn rollback( &mut self, transaction: SerializableTransactionId, ) -> VersionResult<()>

Remove a confirmed aborted participant from dependency decisions. This cleanup does not allocate or observe statement cancellation. Uncertain prepared outcomes must remain retained.

pub fn safe_snapshot( &self, transaction: SerializableTransactionId, control: &StorageReadControl, ) -> VersionResult<SafeSnapshot>

A deferrable reader waits only for read/write transactions overlapping its snapshot admission. A committed overlap with a conflict to an earlier prepared transaction makes this snapshot unsafe; the owner must capture a new snapshot before executing it.

pub fn reclaim(&mut self)

Reclaim conflict history that cannot overlap any live snapshot, preserving earlier conflict-out order on every retained reader. Retained participant leases keep their terminal identity/outcome until owner recovery confirms release, without retaining obsolete predicates or edges. Dropping necessary summaries would allow a late read of a committed pivot to miss a serialization anomaly. No allocation or cancellation is needed for cleanup.