Skip to content

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()

def active_ref_roots(
    records: RecordStore, now: datetime | None = None
) -> set[str]: ...

Return content refs leased by executions that have not committed.

Parameters
  • records RecordStore — Record store holding active execution leases.
  • now datetime | None = None — Moment at which a lease must still be live.
Returns set[str]

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.

Parameters
  • store ContentStoreBase — The store whose bindings are the roots.
  • expired_keys Collection[str] = () — Keys being evicted in this pass, whose bindings are excluded.
Returns set[str]

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.

Parameters
  • store ContentStoreBase — The content store to collect.
  • records RecordStore — The record store holding roots and provenance.
  • now datetime | None = None — The moment to judge expiry against; defaults to now.
  • grace timedelta = datetime.timedelta(seconds=3600) — How recently written a blob must be to be withheld.
  • delete bool = False — Whether to delete; False reports without changes.
  • assume_idle bool = False — 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.
  • durations Mapping[Retention, timedelta | None] | None = None — Per-class lifetime overrides; None means no expiry.
Returns EvictionReport — What was found, and whether it was acted on.

gc_dry_run()

def gc_dry_run(store: ContentStoreBase, records: RecordStore) -> list[str]: ...

Return object digests with no manifest, label, or binding reference.

Parameters
  • store ContentStoreBase — Content store to scan.
  • records RecordStore — Record store containing historical references.
Returns list[str] — Sorted unreferenced digests. Nothing is deleted.

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.

Parameters
  • records RecordStore — Record store to invalidate against.
  • task str — Task name whose records should be invalidated.
  • impl_version int | None = None — Restrict deletion to records with this implementation version.
Returns int — The number of records deleted.

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.

Parameters
  • records RecordStore — The record store whose labels are the roots.
Returns set[str]

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.

Parameters
  • records RecordStore — The record store whose run ledger is pruned.
  • retention timedelta = datetime.timedelta(days=30) — How much ledger to keep.
  • now datetime | None = None — The current time; defaults to datetime.now(UTC).
  • delete bool = False — Whether to remove stale runs and their events.
Returns RunLedgerReport — A report of what was found, and removed when delete was set.

render_eviction_report()

def render_eviction_report(report: EvictionReport) -> str: ...

Render an eviction report.

Parameters
  • report EvictionReport — The report to render.
Returns str — The lines to print, newline-joined.

Classes

EvictionReport

class 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.

Parameters
  • expired_records tuple[str, ...] — Keys whose retention class has lapsed.
  • deletable_blobs tuple[str, ...] — Digests reachable from no root and older than the grace period.
  • withheld_by_grace tuple[str, ...] — Unreachable digests newer than the grace period.
  • pinned_by_label tuple[str, ...] — Digests retained by labels.
  • deleted bool — Whether deletion was performed.

RunLedgerReport

class 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.

Parameters
  • stale_runs int — How many runs started before the cutoff.
  • pruned_runs int — Number of runs removed.
  • pruned_events int — How many of their events were removed with them.
  • deleted bool — Whether deletion was performed.

Exceptions

UnsafeCollectionError

Raised when collection lacks a complete view of shared-store roots.