Make your computer a home for your AI partner. Avibe is the local-first Agent OS: Vibey, its built-in AI partner, works out of the box, and Claude Code, Codex & OpenCode run unchanged beside it — reach them from your browser, phone, or any chat app.
Python agentagent-osaiai-agentsai-partnerchatopsclaudeclaude-codecodexdevtoolsdiscord-botlark-botllmlocal-firstlong-term-memoryopencodeslack-botvibe-codingvibeywechat
"""Bounded retention for internal agent trace events (avibe#1506 lane B).
This module owns automatic ``agent_events`` retention. Tool-trace retention
and Skill retention have independent allowlists and time windows. The tool
eligibility property, shared by planning, execution, and tests:
Only parseable rows with ``event_type='tool_call'`` AND
``visibility='trace'`` AND ``created_at`` strictly older than the retention
cutoff are ever removable. Unparseable timestamps are preserved.
``run_skill_retention`` separately removes only the two Skill trace types and
expired Skill daily buckets. User messages, deliveries, session/run records,
Vault audit data, non-trace events, and newer traces remain untouched.
Operational shape:
* Deletes run in small batches, each in its own transaction, so concurrent
writers (WAL mode) are never blocked for an unbounded interval.
* A ``state_meta`` marker records the last successful run and throttles the
automatic cadence to at most once per day; a lease row serializes
concurrent runners (controller task vs CLI) across processes.
* Physical compaction (``VACUUM``) only runs after a free-space and
writer-safety preflight, and only when reclaimable space justifies it.
When compaction is unsafe it is reported as deferred — never started on a
nearly-full volume.
"""
from __future__ import annotations
import json
import shutil
import threading
import time
import uuid
from dataclasses import dataclass
from datetime import datetime, timedelta, timezone
from pathlib import Path
from typing import Any, Callable, Optional
from sqlalchemy import Engine, LargeBinary, delete, func, select, cast
from sqlalchemy.exc import IntegrityError, OperationalError
from sqlalchemy.engine import Connection
from storage.models import agent_events, skill_usage_daily, state_meta
from vibe.trace_retention_policy import (
MAX_RETENTION_DAYS,
MIN_RETENTION_DAYS,
validate_retention_days,
)
DEFAULT_RETENTION_DAYS = 30
MIN_RUN_INTERVAL_SECONDS = 24 * 3600
DELETE_BATCH_ROWS = 1000
LEASE_TTL_SECONDS = 3600
# Compaction heartbeat interval: keeps the lease renewed well inside the TTL.
LEASE_HEARTBEAT_SECONDS = 60
# Compaction only when the free list alone would return at least this much,
# so a daily run does not rewrite a large database for pocket change.
VACUUM_MIN_RECLAIM_BYTES = 64 * 1024 * 1024
# VACUUM writes a full temp copy and the WAL rewrite can coexist with it, so
# the preflight must reserve room for both copies plus margin.
VACUUM_FREE_SPACE_MARGIN_BYTES = 256 * 1024 * 1024
RETENTION_MARKER_KEY = "agent_events_trace_retention.last_run"
RETENTION_LEASE_KEY = "agent_events_trace_retention.lease"
def run_skill_retention(engine: Engine, *, now=None, cancel_event=None, max_batches: int = 10) -> dict:
"""Independent fixed retention, on the existing maintenance worker.
Each pass is bounded; concurrent passes are harmless because selection and
deletion share one statement. No rebuild from raw events and no VACUUM.
"""
from storage.skill_observability import DAILY_RETENTION_DAYS, RAW_RETENTION_DAYS, SKILL_TRACE_FILTER
instant = now or _utc_now()
raw_cutoff = _iso(instant - timedelta(days=RAW_RETENTION_DAYS))
daily_cutoff = (instant.astimezone(timezone.utc).date() - timedelta(days=DAILY_RETENTION_DAYS - 1)).isoformat()
targets = (
(agent_events, SKILL_TRACE_FILTER
& func.datetime(agent_events.c.created_at).is_not(None)
& (agent_events.c.created_at < raw_cutoff)),
(skill_usage_daily, skill_usage_daily.c.day < daily_cutoff),
)
deleted = {"events": 0, "daily_rows": 0}
for key, (table, predicate) in zip(deleted, targets):
for _ in range(max_batches):
if cancel_event is not None and cancel_event.is_set():
return deleted
with engine.begin() as conn:
ids = select(table.c.id).where(predicate).limit(DELETE_BATCH_ROWS)
count = conn.execute(table.delete().where(table.c.id.in_(ids))).rowcount
deleted[key] += count
if count < DELETE_BATCH_ROWS:
break
return deleted
@dataclass(frozen=True)
class RetentionPolicy:
"""The validated policy used by every retention entry point.
``recovered`` means that the persisted policy could not be trusted. A
recovered policy is always disabled for automatic deletion; the CLI may
still run an explicitly supplied ``--days`` window.
"""
enabled: bool
days: int
recovered: bool = False
def _warning_replaces_retention_policy(warning: object) -> bool:
text = str(warning)
if "recovery defaults" in text or "could not be recovered" in text:
return True
# Field-scoped recovery warnings are rendered as
# ``runtime.agent_events_trace_retention_days``; both that form and the
# older whole-section form replace the policy we are about to use.
return "Recovered invalid config section 'runtime" in text
def resolve_policy(config: Any) -> RetentionPolicy:
"""Validate a loaded config without coercing destructive values.
This is deliberately independent of ``V2Config`` so controller, CLI, and
tests share one policy owner without introducing a config/storage import
cycle. Invalid values fail closed instead of being normalized to a
shorter retention window.
"""
warnings = getattr(config, "load_warnings", ()) if config is not None else ()
recovered = any(_warning_replaces_retention_policy(warning) for warning in (warnings or ()))
runtime = getattr(config, "runtime", None) if config is not None else None
if runtime is None:
return RetentionPolicy(False, DEFAULT_RETENTION_DAYS, True)
enabled = getattr(runtime, "agent_events_trace_retention_enabled", None)
days = getattr(runtime, "agent_events_trace_retention_days", None)
if not isinstance(enabled, bool):
return RetentionPolicy(False, DEFAULT_RETENTION_DAYS, True)
try:
validate_retention_days(days)
except ValueError:
return RetentionPolicy(False, DEFAULT_RETENTION_DAYS, True)
if recovered:
return RetentionPolicy(False, days, True)
return RetentionPolicy(enabled, days, False)
def _utc_now() -> datetime:
return datetime.now(timezone.utc)
def _iso(moment: datetime) -> str:
if moment.tzinfo is None:
moment = moment.replace(tzinfo=timezone.utc)
return moment.astimezone(timezone.utc).isoformat(timespec="microseconds").replace("+00:00", "Z")
def _parse_iso(value: str) -> Optional[datetime]:
if not isinstance(value, str):
return None
try:
normalized = value.strip()
if normalized.endswith("Z"):
normalized = normalized[:-1] + "+00:00"
parsed = datetime.fromisoformat(normalized)
if parsed.tzinfo is None:
parsed = parsed.replace(tzinfo=timezone.utc)
return parsed.astimezone(timezone.utc)
except (TypeError, ValueError):
return None
def normalize_retention_days(retention_days: Any) -> int:
"""Normalize legacy callers without allowing an oversized cutoff."""
try:
days = int(retention_days)
if days > MAX_RETENTION_DAYS:
raise ValueError
except (TypeError, ValueError):
return DEFAULT_RETENTION_DAYS
return max(MIN_RETENTION_DAYS, days)
def cutoff_iso(retention_days: int, *, now: Optional[datetime] = None) -> str:
"""Rows strictly older than this instant are eligible."""
moment = now or _utc_now()
days = validate_retention_days(retention_days)
try:
cutoff = moment - timedelta(days=days)
except OverflowError as exc:
raise ValueError("retention window produces an unrepresentable cutoff") from exc
return _iso(cutoff)
def eligible_filter(cutoff: str):
"""The single eligibility predicate shared by plan and delete.
Keep the scope and parseability clauses byte-for-byte compatible with the
partial index ``ix_agent_events_trace_retention`` (storage/models.py and
the alembic migration) so the scan stays bounded.
"""
return (
(agent_events.c.event_type == "tool_call")
& (agent_events.c.visibility == "trace")
& func.datetime(agent_events.c.created_at).is_not(None)
& (agent_events.c.created_at < cutoff)
)
def plan(conn: Connection, *, retention_days: int, now: Optional[datetime] = None) -> dict[str, Any]:
"""Dry-run report: how many eligible rows exist and their logical payload size.
Sizes are measured in UTF-8 bytes (``CAST(.. AS BLOB)``); SQLite's plain
``length(TEXT)`` counts Unicode characters and underreports CJK payloads
several-fold.
"""
cutoff = cutoff_iso(retention_days, now=now)
def _blob_bytes(column) -> Any:
return func.length(cast(func.coalesce(column, ""), LargeBinary))
logical_bytes = func.sum(
_blob_bytes(agent_events.c.content_text)
+ _blob_bytes(agent_events.c.content_json)
+ _blob_bytes(agent_events.c.metadata_json)
)
row = conn.execute(
select(func.count(), logical_bytes).where(eligible_filter(cutoff))
).one()
return {
"retention_days": normalize_retention_days(retention_days),
"cutoff": cutoff,
"eligible_count": int(row[0] or 0),
"eligible_logical_bytes": int(row[1] or 0),
}
def _delete_batch(conn: Connection, cutoff: str, batch_rows: int) -> int:
result = conn.execute(
delete(agent_events).where(
agent_events.c.id.in_(
select(agent_events.c.id)
.where(eligible_filter(cutoff))
.order_by(agent_events.c.created_at, agent_events.c.id)
.limit(batch_rows)
)
)
)
return int(result.rowcount or 0)
def renew_lease(conn: Connection, token: str, *, now: Optional[datetime] = None) -> bool:
"""Extend this runner's lease while work remains active.
Renewal is one token-conditional UPDATE (no read-then-write), so a
contender committing a replacement between operations can neither be
overwritten nor trip a busy-snapshot upgrade in the heartbeat thread.
"""
moment = now or _utc_now()
result = conn.execute(
state_meta.update()
.where(
state_meta.c.key == RETENTION_LEASE_KEY,
func.json_extract(state_meta.c.value_json, "$.token") == token,
)
.values(
value_json=json.dumps(
{"token": token, "expires_at": _iso(moment + timedelta(seconds=LEASE_TTL_SECONDS))},
sort_keys=True,
),
updated_at=_iso(moment),
)
)
return int(result.rowcount or 0) == 1
def run_retention(
engine: Engine,
*,
retention_days: int,
batch_rows: int = DELETE_BATCH_ROWS,
max_batches: Optional[int] = None,
between_batches: Optional[Callable[[], None]] = None,
now: Optional[datetime] = None,
lease_token: Optional[str] = None,
cancel_event: Optional[threading.Event] = None,
) -> dict[str, Any]:
"""Delete eligible rows in bounded batches, one transaction per batch.
``between_batches`` runs after each committed batch (test hook for
simulating concurrent writers between transactions). With ``lease_token``
the lease is renewed between batches so long runs stay owned.
"""
cutoff = cutoff_iso(retention_days, now=now)
deleted_rows = 0
batches = 0
lease_lost = False
cancelled = False
while max_batches is None or batches < max_batches:
if cancel_event is not None and cancel_event.is_set():
cancelled = True
break
ownership = True
with engine.begin() as conn:
removed = _delete_batch(conn, cutoff, batch_rows)
if lease_token is not None and not renew_lease(conn, lease_token):
ownership = False
batches += 1
if not ownership:
# The committed batch is counted, but ownership was lost mid-run:
# propagate the loss so run_once skips the marker write and
# compaction rather than racing the replacement runner.
lease_lost = True
deleted_rows += removed
break
if removed == 0:
break
deleted_rows += removed
if cancel_event is not None and cancel_event.is_set():
cancelled = True
break
if between_batches is not None:
between_batches()
return {
"cutoff": cutoff,
"deleted_rows": deleted_rows,
"batches": batches,
**({"lease_lost": True} if lease_lost else {}),
**({"cancelled": True} if cancelled and not lease_lost else {}),
}
@dataclass
class _MetaPayload:
payload: dict[str, Any]
def _read_meta(conn: Connection, key: str) -> Optional[dict[str, Any]]:
value = conn.execute(select(state_meta.c.value_json).where(state_meta.c.key == key)).scalar_one_or_none()
if not value:
return None
try:
parsed = json.loads(value)
except json.JSONDecodeError:
return None
return parsed if isinstance(parsed, dict) else None
def _write_meta(conn: Connection, key: str, payload: dict[str, Any], *, now: datetime) -> None:
stamp = _iso(now)
conn.execute(state_meta.delete().where(state_meta.c.key == key))
conn.execute(
state_meta.insert().values(key=key, value_json=json.dumps(payload, sort_keys=True), updated_at=stamp)
)
def get_last_run(conn: Connection) -> Optional[dict[str, Any]]:
return _read_meta(conn, RETENTION_MARKER_KEY)
def should_run(conn: Connection, *, now: Optional[datetime] = None) -> bool:
last = get_last_run(conn)
if not last:
return True
finished = _parse_iso(str(last.get("finished_at") or ""))
if finished is None:
return True
return (now or _utc_now()) - finished >= timedelta(seconds=MIN_RUN_INTERVAL_SECONDS)
def try_acquire_lease(conn: Connection, *, now: Optional[datetime] = None) -> Optional[str]:
"""Best-effort cross-process lease. Returns the lease token or ``None``.
Takes the database writer lock up front (``BEGIN IMMEDIATE`` via a
prelude statement) so the read-decide-write sequence below is atomic
against other contenders: a deferred transaction could let two processes
both see an absent lease, then serialize in an order where the loser's
unconditional delete removes the winner's still-valid lease.
"""
moment = now or _utc_now()
token = uuid.uuid4().hex
# BEGIN IMMEDIATE equivalent: force the write lock before reading.
conn.exec_driver_sql("UPDATE state_meta SET updated_at = updated_at WHERE key = ?", (RETENTION_LEASE_KEY,))
existing = _read_meta(conn, RETENTION_LEASE_KEY)
if existing:
expires = _parse_iso(str(existing.get("expires_at") or ""))
if expires is not None and expires > moment and existing.get("token") != token:
return None
conn.execute(state_meta.delete().where(state_meta.c.key == RETENTION_LEASE_KEY))
try:
conn.execute(
state_meta.insert().values(
key=RETENTION_LEASE_KEY,
value_json=json.dumps(
{"token": token, "expires_at": _iso(moment + timedelta(seconds=LEASE_TTL_SECONDS))},
sort_keys=True,
),
updated_at=_iso(moment),
)
)
except IntegrityError:
return None
return token
def release_lease(conn: Connection, token: Optional[str] = None) -> None:
"""Release the lease, deleting only the row this runner owns.
With ``token`` the delete is a single statement conditioned on the stored
token (JSON_EXTRACT), so a replacement lease committed after any prior
read cannot be removed by this stale owner.
"""
if token is None:
conn.execute(state_meta.delete().where(state_meta.c.key == RETENTION_LEASE_KEY))
return
conn.execute(
state_meta.delete().where(
state_meta.c.key == RETENTION_LEASE_KEY,
func.json_extract(state_meta.c.value_json, "$.token") == token,
)
)
def compaction_status(conn: Connection) -> dict[str, Any]:
page_size = int(conn.exec_driver_sql("PRAGMA page_size").scalar() or 0)
page_count = int(conn.exec_driver_sql("PRAGMA page_count").scalar() or 0)
freelist_count = int(conn.exec_driver_sql("PRAGMA freelist_count").scalar() or 0)
return {
"page_size": page_size,
"database_bytes": page_size * page_count,
"reclaimable_bytes": page_size * freelist_count,
}
def _wal_size(db_path: Path) -> int:
wal = db_path.parent / f"{db_path.name}-wal"
try:
return wal.stat().st_size
except OSError:
return 0
def maybe_compact(
engine: Engine,
*,
db_path: Optional[Path] = None,
min_reclaim_bytes: int = VACUUM_MIN_RECLAIM_BYTES,
free_space_margin_bytes: int = VACUUM_FREE_SPACE_MARGIN_BYTES,
wal_checkpoint: Optional[Callable[[Engine], tuple]] = None,
disk_usage: Optional[Callable[[str], Any]] = None,
lease_heartbeat: Optional[Callable[[], bool]] = None,
) -> dict[str, Any]:
"""Physically reclaim freed pages, only when it is safe to do so.
Order of gates: reclaimable-below-threshold (skip) -> checkpoint WAL
(defer if busy) -> free-space preflight (defer if the volume cannot hold
the rewrite) -> VACUUM. A deferred compaction is a reported state, never
an error, and never worsens a low-disk condition. ``wal_checkpoint`` and
``disk_usage`` are injectable for tests.
"""
if db_path is None:
db_path = Path(engine.url.database or "")
with engine.connect() as conn:
status = compaction_status(conn)
if status["reclaimable_bytes"] < min_reclaim_bytes:
return {"status": "skipped", "reason": "below_threshold", **status}
_checkpoint = wal_checkpoint or _default_wal_checkpoint
try:
checkpoint = _checkpoint(engine)
except OperationalError:
return {"status": "deferred", "reason": "checkpoint_busy", **status}
checkpoint_busy = bool(checkpoint and int(checkpoint[0]) != 0)
if checkpoint_busy:
return {"status": "deferred", "reason": "checkpoint_busy", **status}
database_bytes = max(status["database_bytes"], 1)
_disk_usage = disk_usage or shutil.disk_usage
try:
free_bytes = _disk_usage(str(db_path.parent)).free
except OSError:
return {"status": "deferred", "reason": "free_space_unknown", **status}
required = 2 * database_bytes + _wal_size(db_path) + free_space_margin_bytes
if free_bytes < required:
return {"status": "deferred", "reason": "insufficient_free_space", **status,
"free_bytes": free_bytes, "required_bytes": required}
before = db_path.stat().st_size if db_path.exists() else 0
try:
# VACUUM blocks for the whole rewrite and can outlast the lease TTL.
# A heartbeat thread keeps the lease renewed for as long as the
# compaction runs; if ownership is nonetheless lost, the heartbeat
# stops renewing and reports it so this runner never finishes into a
# state where a replacement runner was already admitted.
lease_state = {"owned": True, "lost": False}
heartbeat_stop: Optional[threading.Event] = None
heartbeat: Optional[threading.Thread] = None
if lease_heartbeat is not None:
heartbeat_stop = threading.Event()
def _beat() -> None:
while not heartbeat_stop.is_set():
try:
renewed = lease_heartbeat()
except OperationalError:
# VACUUM holds SQLite's sole writer lock, so a renewal
# attempt during the rewrite cannot take it. This is
# expected, not ownership loss: the lease was renewed
# just before VACUUM began (full TTL ahead) and is
# renewed again after it finishes. Definitive loss is
# detected by the token-conditional UPDATE returning
# 0 rows (replacement committed), which raises nothing.
heartbeat_stop.wait(LEASE_HEARTBEAT_SECONDS)
continue
if not renewed:
lease_state["lost"] = True
return
# Wait on the stop event (not time.sleep) so VACUUM's
# completion wakes the heartbeat immediately.
heartbeat_stop.wait(LEASE_HEARTBEAT_SECONDS)
heartbeat = threading.Thread(target=_beat, daemon=True)
heartbeat.start()
try:
with engine.connect() as conn:
conn.exec_driver_sql("VACUUM")
finally:
# Normal shutdown flips only "owned" so the thread exits; "lost"
# is reserved for an actual renewal failure observed mid-run.
lease_state["owned"] = False
if heartbeat_stop is not None:
heartbeat_stop.set()
if heartbeat is not None:
heartbeat.join(timeout=LEASE_HEARTBEAT_SECONDS * 2)
if lease_state["lost"]:
# The heartbeat observed an ownership loss during VACUUM: report
# the compaction as contested rather than a clean success.
return {"status": "deferred", "reason": "lease_lost_during_compaction", **status}
# In WAL mode the compacted database lands in the -wal file; a
# post-VACUUM checkpoint is what actually returns bytes to the OS.
# A busy checkpoint here means the space is still trapped in the WAL:
# report it as deferred rather than a completed compaction.
post_checkpoint = _checkpoint(engine)
except OperationalError as exc:
return {"status": "deferred", "reason": f"vacuum_failed: {exc.__class__.__name__}", **status}
if post_checkpoint and int(post_checkpoint[0]) != 0:
return {"status": "deferred", "reason": "post_checkpoint_busy", **status}
after = db_path.stat().st_size if db_path.exists() else 0
return {
"status": "vacuumed",
"database_bytes_before": before,
"database_bytes_after": after,
"reclaimed_bytes": max(before - after, 0),
**status,
}
def _default_wal_checkpoint(engine: Engine) -> tuple:
with engine.connect() as conn:
return conn.exec_driver_sql("PRAGMA wal_checkpoint(TRUNCATE)").fetchone()
def run_once(
engine: Engine,
*,
retention_days: int,
force: bool = False,
compact: bool = True,
db_path: Optional[Path] = None,
now: Optional[datetime] = None,
cancel_event: Optional[threading.Event] = None,
) -> dict[str, Any]:
"""One full maintenance pass: gate -> lease -> batched delete -> marker -> compact."""
moment = now or _utc_now()
with engine.connect() as conn:
last_run = get_last_run(conn)
if not force and not should_run(conn, now=moment):
return {"status": "not_due", "last_run": last_run}
token: Optional[str] = None
with engine.begin() as conn:
token = try_acquire_lease(conn, now=moment)
if token is None:
return {"status": "busy", "last_run": last_run}
# Recheck the cadence under the lease: a runner that finished between the
# gate above and this acquisition already did today's pass. Without this,
# overlapping controller startups would double-run deletion + compaction.
if not force:
with engine.connect() as conn:
if not should_run(conn, now=moment):
with engine.begin() as write_conn:
release_lease(write_conn, token)
return {"status": "not_due", "last_run": get_last_run(conn)}
started = time.monotonic()
try:
result = run_retention(
engine,
retention_days=retention_days,
now=moment,
lease_token=token,
cancel_event=cancel_event,
)
if result.get("lease_lost"):
# Ownership was lost mid-run: skip the marker write and compaction
# so this runner never reports success or VACUUMs beside the
# replacement runner.
return {
"status": "lease_lost",
"deleted_rows": result["deleted_rows"],
"cutoff": result["cutoff"],
}
if result.get("cancelled") or (cancel_event is not None and cancel_event.is_set()):
# Cancellation is cooperative: the last committed batch remains
# durable, but no marker or compaction claims a complete pass.
return {
"status": "cancelled",
"deleted_rows": result["deleted_rows"],
"batches": result["batches"],
"cutoff": result["cutoff"],
}
finished = moment + timedelta(seconds=round(time.monotonic() - started, 3))
with engine.begin() as conn:
_write_meta(
conn,
RETENTION_MARKER_KEY,
{
"finished_at": _iso(finished),
"deleted_rows": result["deleted_rows"],
"retention_days": normalize_retention_days(retention_days),
"duration_seconds": round(time.monotonic() - started, 3),
},
now=finished,
)
result_marker = get_last_run(conn)
compaction: dict[str, Any] = {"status": "not_attempted"}
if compact:
lease_replaced = {"flag": False}
def _lease_heartbeat() -> bool:
# Renewal is skipped while VACUUM holds the writer lock (the
# heartbeat treats that OperationalError as retry-later); do
# one renewal here so the TTL is fresh when VACUUM begins.
# A False return means the token-conditional UPDATE matched
# nothing — the lease was replaced. Record it in the flag so
# every caller (heartbeat, pre/post renewals) sees the same
# definitive-loss signal without an exception the heartbeat
# could mistake for a lock conflict.
with engine.begin() as conn:
renewed = renew_lease(conn, token)
if not renewed:
lease_replaced["flag"] = True
return renewed
# Refresh the lease, then compact; a final renewal after VACUUM
# closes the TTL window for the post-vacuum reporting path.
_lease_heartbeat()
if lease_replaced["flag"]:
return {
"status": "ok_with_contested_compaction",
"deleted_rows": result["deleted_rows"],
"batches": result["batches"],
"cutoff": result["cutoff"],
"duration_seconds": round(time.monotonic() - started, 3),
"last_run": result_marker,
"compaction": {"status": "deferred", "reason": "lease_lost_during_compaction"},
}
compaction = maybe_compact(engine, db_path=db_path, lease_heartbeat=_lease_heartbeat)
if lease_replaced["flag"]:
# A replacement committed during compaction (heartbeat saw a
# definitive token mismatch): report contested, not clean.
if str(compaction.get("reason")) != "lease_lost_during_compaction":
compaction = {**compaction, "status": "deferred", "reason": "lease_lost_during_compaction"}
return {
"status": "ok_with_contested_compaction",
"deleted_rows": result["deleted_rows"],
"batches": result["batches"],
"cutoff": result["cutoff"],
"duration_seconds": round(time.monotonic() - started, 3),
"last_run": result_marker,
"compaction": compaction,
}
with engine.begin() as conn:
renewed_after = renew_lease(conn, token)
if not renewed_after:
return {
"status": "ok_with_contested_compaction",
"deleted_rows": result["deleted_rows"],
"batches": result["batches"],
"cutoff": result["cutoff"],
"duration_seconds": round(time.monotonic() - started, 3),
"last_run": result_marker,
"compaction": {"status": "deferred", "reason": "lease_lost_during_compaction"},
}
if str(compaction.get("reason")) == "lease_lost_during_compaction":
# Deletion already completed and its marker is written; only
# the compaction was contested. Report that distinctly so the
# CLI does not claim deletion stopped partway.
return {
"status": "ok_with_contested_compaction",
"deleted_rows": result["deleted_rows"],
"batches": result["batches"],
"cutoff": result["cutoff"],
"duration_seconds": round(time.monotonic() - started, 3),
"last_run": result_marker,
"compaction": compaction,
}
return {
"status": "ok",
"deleted_rows": result["deleted_rows"],
"batches": result["batches"],
"cutoff": result["cutoff"],
"duration_seconds": round(time.monotonic() - started, 3),
"last_run": result_marker,
"compaction": compaction,
}
finally:
with engine.begin() as conn:
release_lease(conn, token)
def retention_status(engine: Engine, *, retention_days: int, now: Optional[datetime] = None) -> dict[str, Any]:
"""Read-only status: candidates, last successful run, compaction outlook."""
with engine.connect() as conn:
return {
"plan": plan(conn, retention_days=retention_days, now=now),
"last_run": get_last_run(conn),
"compaction": compaction_status(conn),
}