salvus.flow.acta.memo.gc
salvus.flow.acta.memo.gc salvus flow acta memo gc Record invalidation, blob eviction, and run-ledger pruning.
Eviction and ledger pruning default to reporting. Blob deletion requires
delete=True, assume_idle=True, and a local store. Invalidation deletes
matching records immediately. Manifests are retained.
Functions
active_ref_roots()
active_ref_roots()def active_ref_roots(
records: RecordStore, now: datetime | None = None
) -> set[str]: ...Return content refs leased by executions that have not committed.
recordsRecordStore — Record store holding active execution leases.nowdatetime | None — Moment at which a lease must still be live.
binding_roots()
binding_roots()def binding_roots(
store: ContentStoreBase, expired_keys: Collection[str] = ()
) -> set[str]: ...Return every store digest held alive by a binding.
Retain result blobs only, not their outputs. Skip unlistable bindings.
storeContentStoreBase — The store whose bindings are the roots.expired_keysCollection[str] — Keys being evicted in this pass, whose bindings are excluded.
evict()
evict()def evict(
store: ContentStoreBase,
records: RecordStore,
now: datetime | None = None,
grace: timedelta = datetime.timedelta(seconds=3600),
delete: bool = False,
assume_idle: bool = False,
durations: Mapping[Retention, timedelta | None] | None = None,
) -> EvictionReport: ...Report expired records and unreachable blobs, optionally deleting them.
Retain blobs referenced by labels, bindings, unexpired records, or active
leases. Preserve manifests, file observations, and blobs newer than
grace. Deletion requires exclusive idle maintenance.
storeContentStoreBase — The content store to collect.recordsRecordStore — The record store holding roots and provenance.nowdatetime | None — The moment to judge expiry against; defaults to now.gracetimedelta — How recently written a blob must be to be withheld.deletebool — Whether to delete;Falsereports without changes.assume_idlebool — Required for deletion. The caller must prevent all executions, writers, and other collectors until this call ends. Live locks or ref leases are additionally checked, but that check cannot prevent new work. Dry runs are only snapshots.durationsMapping[Retention, timedelta | None] | None — Per-class lifetime overrides;Nonemeans no expiry.
gc_dry_run()
gc_dry_run()def gc_dry_run(store: ContentStoreBase, records: RecordStore) -> list[str]: ...Return object digests with no manifest, label, or binding reference.
storeContentStoreBase — Content store to scan.recordsRecordStore — Record store containing historical references.
invalidate()
invalidate()def invalidate(
records: RecordStore, task: str, impl_version: int | None = None
) -> int: ...Delete every current record for task, forcing a recompute.
Local invalidation markers block adoption from published bindings until fresh computation succeeds. Other record databases are unaffected.
recordsRecordStore — Record store to invalidate against.taskstr — Task name whose records should be invalidated.impl_versionint | None — Restrict deletion to records with this implementation version.
label_roots()
label_roots()def label_roots(records: RecordStore) -> set[str]: ...Return every store digest held alive by a label.
Ref labels retain their artifacts; key labels retain their record’s outputs. A key label without a record retains no data.
recordsRecordStore — The record store whose labels are the roots.
prune_run_ledger()
prune_run_ledger()def prune_run_ledger(
records: RecordStore,
retention: timedelta = datetime.timedelta(days=30),
now: datetime | None = None,
delete: bool = False,
) -> RunLedgerReport: ...Report runs older than retention, optionally deleting them.
recordsRecordStore — The record store whose run ledger is pruned.retentiontimedelta — How much ledger to keep.nowdatetime | None — The current time; defaults todatetime.now(UTC).deletebool — Whether to remove stale runs and their events.
delete was set.render_eviction_report()
render_eviction_report()def render_eviction_report(report: EvictionReport) -> str: ...Render an eviction report.
reportEvictionReport — The report to render.
Classes
EvictionReport
EvictionReportclass EvictionReport(builtins.object):
def __init__(
self,
expired_records: tuple[str, ...],
deletable_blobs: tuple[str, ...],
withheld_by_grace: tuple[str, ...],
pinned_by_label: tuple[str, ...],
deleted: bool,
) -> None: ...Eviction candidates and deletion status.
expired_recordstuple[str, ...] — Keys whose retention class has lapsed.deletable_blobstuple[str, ...] — Digests reachable from no root and older than the grace period.withheld_by_gracetuple[str, ...] — Unreachable digests newer than the grace period.pinned_by_labeltuple[str, ...] — Digests retained by labels.deletedbool — Whether deletion was performed.
RunLedgerReport
RunLedgerReportclass RunLedgerReport(builtins.object):
def __init__(
self,
stale_runs: int,
pruned_runs: int,
pruned_events: int,
deleted: bool,
) -> None: ...Run-ledger pruning counts and deletion status.
stale_runsint — How many runs started before the cutoff.pruned_runsint — Number of runs removed.pruned_eventsint — How many of their events were removed with them.deletedbool — Whether deletion was performed.
Exceptions
UnsafeCollectionError
UnsafeCollectionErrorRaised when collection lacks a complete view of shared-store roots.