cadrumo.application.storage.sync_runs.persist module

Persist one completed synchronisation run: record and event, one transaction.

Every surface calls record_sync_run() at the point its run finishes, on partial failure as well as on success. Nothing else writes this store.

The write is a co-write and not two writes. The record and the bucket event it carries the id of are handed to the SecureObjectRepository batch save in one call, with both repositories bound to the SAME instance so they share one session scope and roll back together. That is the shipped pattern rather than a per-repository wrapper method: the wrappers that exist are sugar over the same batch save, and a record type that owns no catalogue of its own has the shorter path.

Splitting the two would reintroduce exactly the failure the pairing prevents. A record written without its event is provenance no history mentions; an event written without its record is a history entry whose counts nobody can read, because a bucket-event payload value is capped and the counts live in the record. The namespace keys the record on the event’s own content-addressed id, so the two are joined by identity rather than by a field that could drift – and that identity only means anything if neither can land alone.

record_sync_run(*, bucket_id, surface, resolved_scope, succeeded, coverage, completed_at, repository, actor='system')[source]

Persist one completed run and its bucket event in a single transaction.

Call this on EVERY completion of a real run, including one that failed partway. A record written only on success makes every truncated sweep invisible, which is the state a reader would otherwise mistake for complete coverage.

Do NOT call it from a preview branch. A dry run reads the remote surface and persists nothing, so it has no last-sync provenance – nothing was synced – and a provenance record is itself a persist that would defeat the guard whose purpose is leaving no trace.

Parameters:

  • bucket_id (str) – Profile bucket the run belongs to.

  • surface (SyncSurface) – Which surface the run covered.

  • resolved_scope (str) – What the run actually resolved its scope to. Empty only when the run failed before any scope could be resolved.

  • succeeded (bool) – Whether the run completed without a refusal. Recorded independently of divergence_count, because a clean run can find divergences and a failed run can find none for want of getting far enough to look.

  • coverage (SyncRunCoverage) – What the run covered, derived from ONE source through coverage_of(). Taken as a derived pair rather than as two integers because two integer parameters let a caller pair counts drawn from different populations, which is exactly how a run once reported more divergences than units and refused its own record at the end of a real sweep.

  • completed_at (datetime) – UTC instant the run finished, successfully or not.

  • repository (SyncRunRecordRepositoryProtocol) – Persistence port that co-writes this record and its history event through one encrypted storage transaction.

  • actor (str) – Who invoked the run.

Return type:

SyncRunRecord

Returns:

The persisted SyncRunRecord, carrying the id of the event it was written with.