salvus.flow.acta.memo.records
salvus.flow.acta.memo.records salvus flow acta memo records SQLite storage for cache records, provenance, leases, and run events.
Each instance serializes access to its connection with a lock. Databases use WAL mode and a busy timeout. Manifests and file observations are append-only; cache records, labels, leases, and invalidations are mutable. Explicit idle pruning may also remove disposable provenance.
Classes
FileObservation
FileObservationclass FileObservation(builtins.object):
def __init__(
self, digest: str, path: str, host: str, observed_at: str
) -> None: ...A recorded file digest, path, and hashing time.
digeststr — The content digest the file hashed to.pathstr — The absolute path it was read from.hoststr — Hostname that read the file.observed_atstr — ISO-8601 UTC timestamp of the hashing.
Manifest
Manifestclass Manifest(builtins.object):
def __init__(
self,
manifest_id: int,
key: str,
task: str,
envelope: dict[str, Any],
arg_values: dict[str, Any],
output_refs: dict[str, Any],
timings: dict[str, float],
hostname: str,
versions: dict[str, str],
created_at: str,
provenance: dict[str, Any],
fingerprint_parts: dict[str, str],
run_id: str | None = None,
input_snapshot: dict[str, Any] | None = None,
) -> None: ...Provenance for a computed or adopted result.
manifest_idint — Database row ID.keystr — Computation’s envelope key.taskstr — Task name.envelopedict[str, Any] — Complete cache-key envelope.arg_valuesdict[str, Any] — Normalized argument values with defaults omitted; artifact arguments use digests. Diagnostic only; empty for legacy manifests.output_refsdict[str, Any] — Output names mapped to digests or lists of digests.timingsdict[str, float] — Stage names mapped to elapsed seconds.hostnamestr — Host that committed the result.versionsdict[str, str] — Package names mapped to installed versions.created_atstr — ISO-8601 UTC insertion time.provenancedict[str, Any] — Execution or adoption metadata, excluded from cache keys.fingerprint_partsdict[str, str] — Qualified names and source digests for diagnostics. Empty for tasks with an explicitimpl.run_idstr | None — Producing run ID, orNonewithout a run context.input_snapshotdict[str, Any] | None — Dispatch inputs before normalization and default elision, orNoneif unavailable.
Record
Recordclass Record(builtins.object):
def __init__(
self,
key: str,
output_refs: dict[str, Any],
manifest_id: int,
retention: Retention = Retention.STANDARD,
last_used_at: str = "",
) -> None: ...A committed key -> outputs record.
keystr — The envelope key.output_refsdict[str, Any] — Mapping from output name to digest, or to a list of digests for multi-output tasks.manifest_idint — The manifest that produced this record.retentionRetention — Retention class recorded at commit.last_used_atstr — ISO-8601 UTC time of the last hit, stamped at commit and re-stamped (coalesced) byprotocol.lookup. Empty for a row written before the column existed, which means “fall back to the manifest’screated_at”.
RecordStore
RecordStoreclass RecordStore(builtins.object):
def __init__(self, db_path: pathlib.Path | str) -> None: ...SQLite-backed store for records and append-once manifests.
Call close() when finished. Abandoned stores also close their
connections when collected or at interpreter exit.
db_pathpathlib.Path | str — Path to the SQLite database file. Created on first use, along with its parent directory.
write_count int
write_count intReturn the number of transactions committed by this instance.
in_memory()
in_memory()def in_memory() -> RecordStore: ...Return a records store held entirely in memory (no file).
acquire_lock()
acquire_lock()def acquire_lock(self, key: str, holder: str, ttl_seconds: float) -> bool: ...Try to acquire the single-flight lock for key.
keystr — The envelope key to acquire.holderstr — This caller’s opaque identity. Must be passed again torelease_lock/renew_lock, and only that same holder can release or renew.ttl_secondsfloat — Lease duration from now; renew before expiry to avoid duplicate computation.
True if this call acquired the lock (fresh or stolen), False if a live holder already has it.active_ref_digests()
active_ref_digests()def active_ref_digests(self, now: float | None = None) -> set[str]: ...Return digests whose execution leases have not expired.
nowfloat | None — Unix timestamp to compare against; current time by default.
add_active_refs()
add_active_refs()def add_active_refs(
self, holder: str, digests: Sequence[str], ttl_seconds: float
) -> None: ...Lease content refs needed by an execution that is still running.
holderstr — Opaque execution identity.digestsSequence[str] — Content digests to keep reachable.ttl_secondsfloat — Lease duration from now.
append_events()
append_events()def append_events(self, rows: Sequence[EventRow]) -> list[Event]: ...Append a batch of events in one transaction, in order.
rowsSequence[EventRow] — Tuples of(run_id, attempt, task, key, parent_key, kind, at, detail).
seq the database assigned it.apply_prune()
apply_prune()def apply_prune(
self,
record_keys: Sequence[str],
manifest_ids: Sequence[int],
observation_digests: Sequence[str],
run_ids: Sequence[str],
) -> None: ...Apply a collector’s idle-maintenance database plan atomically.
Use through Session.prune, which computes reachability and verifies
exclusive idle maintenance before touching either store.
record_keysSequence[str] — Cache entries to remove.manifest_idsSequence[int] — Disposable provenance rows to remove.observation_digestsSequence[str] — File observations no longer needed.run_idsSequence[str] — Entire disposable runs, including their events.
close()
close()def close(self) -> None: ...Close the underlying SQLite connection.
commit_record()
commit_record()def commit_record(
self,
key: str,
output_refs: dict[str, Any],
manifest_id: int,
retention: Retention = Retention.STANDARD,
last_used_at: str | None = None,
from_binding: bool = False,
) -> None: ...Insert or replace the record for key.
keystr — The envelope key.output_refsdict[str, Any] — Mapping from output name to digest(s).manifest_idint — The manifest that produced this record.retentionRetention — Retention class to record.last_used_atstr | None — ISO-8601 UTC stamp to start the clock from; defaults to now, since committing is a use.from_bindingbool — Adopt a published result only if this database has not invalidated it. Only fresh computation clears an invalidation marker.
delete_label()
delete_label()def delete_label(self, name: str) -> bool: ...Remove the label called name.
namestr — The label name to remove.
True if a label was removed, otherwise False.delete_record()
delete_record()def delete_record(self, key: str) -> None: ...Delete the record for key, if any.
keystr — The envelope key whose record should be removed.
end_run()
end_run()def end_run(self, run_id: str, ended_at: str, outcome: str) -> None: ...Close a run with the time and outcome it ended on.
run_idstr — The run to close.ended_atstr — ISO-8601 UTC time it ended.outcomestr —"succeeded"or"failed".
events_for_run()
events_for_run()def events_for_run(self, run_id: str) -> list[Event]: ...Return one run’s events, in seq order.
run_idstr — Run ID; useget_runto resolve a name.
file_observations_for()
file_observations_for()def file_observations_for(self, digest: str) -> list[FileObservation]: ...Return every recorded sighting of digest, oldest first.
digeststr — The content digest to look up.
get_label()
get_label()def get_label(self, name: str) -> Label | None: ...Return the label called name, or None if there is none.
namestr — The label name to resolve.
get_manifest()
get_manifest()def get_manifest(self, manifest_id: int) -> Manifest | None: ...Return the manifest with manifest_id, or None if absent.
manifest_idint — Row id of the manifest to fetch.
get_record()
get_record()def get_record(self, key: str) -> Record | None: ...Return the record for key, or None if absent.
keystr — The envelope key to look up.
get_run()
get_run()def get_run(self, ref: str) -> Run | None: ...Return the run with this id or this name, or None.
refstr — A run id or a run name.
has_active_work()
has_active_work()def has_active_work(self) -> bool: ...Return whether live task locks or object leases forbid maintenance.
This check does not prevent new executions.
invalidate_record()
invalidate_record()def invalidate_record(self, key: str) -> None: ...Remove a record and prevent its adoption from a published binding.
keystr — Computation to invalidate in this database.
is_invalidated()
is_invalidated()def is_invalidated(self, key: str) -> bool: ...Return whether fresh computation is required for a key.
keystr — Computation to inspect.
iter_records()
iter_records()def iter_records(self) -> list[Record]: ...Return every current record.
latest_manifest_for_key()
latest_manifest_for_key()def latest_manifest_for_key(self, key: str) -> Manifest | None: ...Return the most recent manifest committed for key, or None.
keystr — The envelope key to look up.
None.latest_manifest_for_task()
latest_manifest_for_task()def latest_manifest_for_task(
self, task: str, before_manifest_id: int | None = None
) -> Manifest | None: ...Return the most recent manifest for task, or None.
taskstr — Task name to filter on.before_manifest_idint | None — If given, only consider manifests with a strictly smaller id (i.e. earlier than this run).
manifest_id matching the filters, or None if no manifest matches.list_labels()
list_labels()def list_labels(self, prefix: str = "") -> list[Label]: ...Return every label whose name starts with prefix, by name.
prefixstr — Literal name prefix; the empty default returns all labels and is not a special case.
list_manifests()
list_manifests()def list_manifests(self, limit: int | None = None) -> list[Manifest]: ...Return manifests in insertion order, most recent last.
limitint | None — If given, only the most recentlimitmanifests are returned (still in ascending id order); must be a positive integer.
list_runs()
list_runs()def list_runs(
self, limit: int | None = None, failed_only: bool = False
) -> list[Run]: ...Return runs, newest first.
limitint | None — Keep at most this many;Nonereturns all of them.failed_onlybool — Keep only runs whose outcome was a failure.
manifest_for_output_ref()
manifest_for_output_ref()def manifest_for_output_ref(self, digest: str) -> Manifest | None: ...Return the newest manifest that produced digest, if any.
digeststr — The content digest to find a producer for.
manifests_for_task()
manifests_for_task()def manifests_for_task(
self, task: str, limit: int | None = None
) -> list[Manifest]: ...Return task’s manifests, newest first.
taskstr — Task name to select.limitint | None — If given, at most this many, still newest first.
observation_counts()
observation_counts()def observation_counts(self) -> dict[str, int]: ...Return file observation counts by digest for maintenance previews.
prune_runs()
prune_runs()def prune_runs(self, before: datetime) -> tuple[int, int]: ...Delete runs started before before, and their events.
beforedatetime — Cutoff; a run started at or after it survives.
put_file_observation()
put_file_observation()def put_file_observation(
self, digest: str, path: str, host: str, observed_at: str
) -> int: ...Record a file digest observation.
Observations are appended without deduplication.
digeststr — The content digest the file hashed to.pathstr — The absolute path it was read from.hoststr — The hostname that read it.observed_atstr — ISO-8601 UTC timestamp.
put_label()
put_label()def put_label(
self,
name: str,
key: str | None = None,
ref: str | None = None,
force: bool = False,
created_at: str | None = None,
) -> Label: ...Point name at exactly one key or ref.
namestr — The label name; validated before anything is written.keystr | None — The envelope key to name, orNone.refstr | None — The content digest to name, orNone.forcebool — Allow replacing an existing label.created_atstr | None — ISO-8601 UTC timestamp; defaults to now.
put_manifest()
put_manifest()def put_manifest(
self,
key: str,
task: str,
envelope: dict[str, Any],
arg_values: dict[str, Any],
output_refs: dict[str, Any],
timings: dict[str, float],
hostname: str,
versions: dict[str, str],
created_at: str,
provenance: dict[str, Any],
fingerprint_parts: Mapping[str, str] | None = None,
run_id: str | None = None,
input_snapshot: dict[str, Any] | None = None,
) -> int: ...Append a new manifest row and return its id.
keystr — The envelope key this manifest was produced for.taskstr — Task name.envelopedict[str, Any] — The full envelope mapping.arg_valuesdict[str, Any] — The call’s raw argument values, diagnostic-only (seeManifest).output_refsdict[str, Any] — Mapping from output name to digest(s).timingsdict[str, float] — Mapping from stage name to elapsed seconds.hostnamestr — The hostname of the calling (not necessarily computing) process.versionsdict[str, str] — Mapping from package name to version string.created_atstr — ISO-8601 UTC timestamp.provenancedict[str, Any] — Execution or adoption metadata.fingerprint_partsMapping[str, str] | None — Source digests for diagnostics.Noneis stored as an empty mapping.run_idstr | None — The run that produced it, orNonefor a session with no run context.input_snapshotdict[str, Any] | None — Full dispatch inputs, orNoneif unavailable.
records_for_task()
records_for_task()def records_for_task(self, task: str) -> list[Record]: ...Return every current record whose manifest’s task is task.
taskstr — Task name to filter on.
release_active_refs()
release_active_refs()def release_active_refs(self, holder: str) -> None: ...Release every active-ref lease owned by holder.
holderstr — Opaque execution identity.
release_lock()
release_lock()def release_lock(self, key: str, holder: str) -> None: ...Release the lock on key, only if holder still owns it.
keystr — The envelope key whose lock should be released.holderstr — This caller’s opaque identity, as passed toacquire_lock.
renew_active_refs()
renew_active_refs()def renew_active_refs(self, holder: str, ttl_seconds: float) -> None: ...Extend every active-ref lease owned by holder.
holderstr — Opaque execution identity.ttl_secondsfloat — New lease duration from now.
renew_lock()
renew_lock()def renew_lock(self, key: str, holder: str, ttl_seconds: float) -> bool: ...Extend the lease on key, only if holder still owns it.
Sessions renew automatically; low-level callers must arrange renewal.
keystr — The envelope key whose lease should be extended.holderstr — This caller’s opaque identity, as passed toacquire_lock.ttl_secondsfloat — New lease duration from now.
True if renewed, False if holder no longer owns the lock (e.g. it was already stolen).schema_version()
schema_version()def schema_version(self) -> int: ...Return the schema version this database is at.
start_run()
start_run()def start_run(self, name: str | None = None) -> Run: ...Open a run and return it.
namestr | None — An explicit name; by default it is derived from the new id (seesalvus.flow.acta.observability.names.run_name).
touch_record()
touch_record()def touch_record(self, key: str, last_used_at: str) -> None: ...Set a record’s last-used stamp.
keystr — The envelope key to stamp.last_used_atstr — ISO-8601 UTC stamp to write.