@deftai/directive-content 0.55.1 → 0.56.0

package/scripts/_cache_quota.py

@@ -0,0 +1,529 @@
+#!/usr/bin/env python3
+"""_cache_quota.py -- size cap, entry cap, LRU eviction for the cache (#947).
+
+Extracted from :mod:`cache` to keep the parent module under the deft
+1000-line MUST limit (mirrors the existing ``_cache_fetch`` /
+``_cache_validate`` split). The module owns:
+
+- Cap resolution from env vars (``DEFT_CACHE_MAX_BYTES``,
+  ``DEFT_CACHE_MAX_ENTRIES``) with sensible defaults baked in
+  (100 MB / 10,000 entries; sized from the v0.26.0 smoke evidence
+  documented in ``docs/smoke-2026-05-07-v0.26.0-rerun.md`` --
+  320 entries = 3.03 MB, ~10 KB/entry average).
+- Usage scanning across the cache root: enumerate every entry's
+  ``meta.json``, sum ``size_bytes`` for the byte total, count entries,
+  and read ``meta.json`` ``mtime`` for the LRU timestamp.
+- LRU eviction: pick the oldest entry by ``(mtime, path)`` (path tie-break
+  for filesystems with 1s mtime granularity), remove the directory,
+  return the freed bytes + record so the caller can append a
+  ``cache:evict`` audit row.
+- :class:`CacheCapBreachedError`: raised when caps cannot be honored
+  even after eviction (e.g. the new entry alone exceeds the byte cap,
+  or every entry on disk is the just-written one). The cache CLI maps
+  this to exit-code 3 so callers can distinguish "schema invalid"
+  (exit 2) from "honoring the cap is impossible" (exit 3).
+
+LRU signal: the ``meta.json`` mtime is touched (single ``os.utime``
+syscall) on each ``cache:get`` hit. A v0.26.0 cache tree's existing
+entries already have a valid mtime (the original write timestamp),
+so this is backward-compatible without migration. The schema-bump
+alternative (add a ``last_accessed_at`` field) was rejected because
+it would (a) force a write-on-read of meta.json including schema
+re-validation, (b) require coordinated edits to the FROZEN
+``vbrief/schemas/cache-meta.schema.json`` plus the in-module
+validator, and (c) impose a migration burden on pre-existing
+cache trees. See the #947 vBRIEF ``DesignChoice`` narrative.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import json
+import os
+import shutil
+from collections.abc import Callable, Iterable
+from dataclasses import dataclass
+from pathlib import Path
+
+# ---------------------------------------------------------------------------
+# Defaults + env-var contract
+# ---------------------------------------------------------------------------
+
+#: 100 MB. Defensible at the smoke-evidenced ~10 KB/entry average;
+#: a 50,000-issue mono-repo would consume ~500 MB without a cap.
+DEFAULT_MAX_BYTES: int = 100 * 1024 * 1024
+
+#: 10,000 entries. Equivalent to the byte cap at the smoke-evidenced
+#: per-entry average, so either threshold should trip first depending
+#: on the actual mix of small vs large issues in the working set.
+DEFAULT_MAX_ENTRIES: int = 10_000
+
+#: A cap value of 0 (or a non-numeric env value) disables that cap.
+ENV_MAX_BYTES: str = "DEFT_CACHE_MAX_BYTES"
+ENV_MAX_ENTRIES: str = "DEFT_CACHE_MAX_ENTRIES"
+
+#: Sentinel meaning "the cap is disabled" -- evictor never trips for it.
+CAP_DISABLED: int = 0
+
+
+class CacheCapBreachedError(RuntimeError):
+    """Raised when the cache cap cannot be honored even after eviction.
+
+    Attributes mirror the structured exit shape that callers (and the
+    CLI exit-3 path) display so an operator can see *why* the put was
+    refused and what they could free up to make room.
+    """
+
+    def __init__(
+        self,
+        *,
+        reason: str,
+        max_bytes: int,
+        max_entries: int,
+        current_bytes: int,
+        current_entries: int,
+        incoming_bytes: int,
+    ) -> None:
+        self.reason = reason
+        self.max_bytes = max_bytes
+        self.max_entries = max_entries
+        self.current_bytes = current_bytes
+        self.current_entries = current_entries
+        self.incoming_bytes = incoming_bytes
+        super().__init__(
+            f"cache cap breached ({reason}): "
+            f"max_bytes={max_bytes} max_entries={max_entries} "
+            f"current_bytes={current_bytes} current_entries={current_entries} "
+            f"incoming_bytes={incoming_bytes}"
+        )
+
+
+# ---------------------------------------------------------------------------
+# Cap resolution
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class CacheCaps:
+    """Resolved cap thresholds in effect for one operation.
+
+    A value of :data:`CAP_DISABLED` (0) means the corresponding cap is
+    not enforced. Negative env values are clamped to 0 (disabled) rather
+    than raising -- the caps are an operator-friendly knob, not a
+    strict-mode setting.
+    """
+
+    max_bytes: int
+    max_entries: int
+
+    @property
+    def bytes_enforced(self) -> bool:
+        return self.max_bytes > 0
+
+    @property
+    def entries_enforced(self) -> bool:
+        return self.max_entries > 0
+
+    @property
+    def any_enforced(self) -> bool:
+        return self.bytes_enforced or self.entries_enforced
+
+
+def _parse_int_env(name: str, default: int) -> int:
+    """Parse an int from ``os.environ[name]``, falling back to ``default``.
+
+    Non-numeric or negative values resolve to ``CAP_DISABLED`` so a typo
+    in the env var doesn't masquerade as an enforced cap. ``""`` (empty
+    string) means "use the default" (consistent with how shell-set-but-
+    -unset env vars usually behave).
+    """
+    raw = os.environ.get(name)
+    if raw is None or raw == "":
+        return default
+    try:
+        value = int(raw)
+    except ValueError:
+        return CAP_DISABLED
+    return value if value >= 0 else CAP_DISABLED
+
+
+def resolve_caps(
+    *,
+    max_bytes: int | None = None,
+    max_entries: int | None = None,
+) -> CacheCaps:
+    """Resolve the active caps from explicit args, env vars, or defaults.
+
+    Resolution order (highest precedence first):
+
+    1. Explicit ``max_bytes`` / ``max_entries`` kwargs (used by tests
+       that need deterministic caps regardless of process env).
+    2. ``DEFT_CACHE_MAX_BYTES`` / ``DEFT_CACHE_MAX_ENTRIES`` env vars.
+    3. Module defaults (:data:`DEFAULT_MAX_BYTES`,
+       :data:`DEFAULT_MAX_ENTRIES`).
+    """
+    if max_bytes is None:
+        max_bytes = _parse_int_env(ENV_MAX_BYTES, DEFAULT_MAX_BYTES)
+    if max_entries is None:
+        max_entries = _parse_int_env(ENV_MAX_ENTRIES, DEFAULT_MAX_ENTRIES)
+    if max_bytes < 0:
+        max_bytes = CAP_DISABLED
+    if max_entries < 0:
+        max_entries = CAP_DISABLED
+    return CacheCaps(max_bytes=max_bytes, max_entries=max_entries)
+
+
+# ---------------------------------------------------------------------------
+# Usage scan
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class EntryUsage:
+    """One on-disk cache entry seen by the usage scan.
+
+    ``size_bytes`` is read from the entry's ``meta.json`` (authoritative
+    -- written at cache:put time and validated against the schema). If
+    the meta.json is missing or unparseable the entry is still listed
+    with ``size_bytes=0`` so eviction can drain corrupt entries first
+    (they cannot be served by ``cache_get`` anyway).
+    """
+
+    entry_dir: Path
+    source: str
+    key: str
+    size_bytes: int
+    last_accessed: float
+    meta_present: bool
+
+
+@dataclass(frozen=True)
+class UsageReport:
+    """Aggregate usage at the time of the scan."""
+
+    total_bytes: int
+    total_entries: int
+    entries: tuple[EntryUsage, ...]
+
+
+def _read_meta_size(meta_path: Path) -> tuple[int, str, str, bool]:
+    """Read ``size_bytes`` + (source, key) from a meta.json.
+
+    Returns ``(size_bytes, source, key, meta_present)``. On parse
+    failure, returns zeros so the corrupt entry sorts as evictable
+    without polluting the byte total.
+    """
+    try:
+        meta = json.loads(meta_path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return 0, "", "", False
+    if not isinstance(meta, dict):
+        return 0, "", "", False
+    size = meta.get("size_bytes")
+    src = meta.get("source")
+    key = meta.get("key")
+    if not isinstance(size, int) or size < 0:
+        size = 0
+    if not isinstance(src, str):
+        src = ""
+    if not isinstance(key, str):
+        key = ""
+    return size, src, key, True
+
+
+def scan_usage(
+    cache_root: Path,
+    *,
+    sources: Iterable[str],
+) -> UsageReport:
+    """Walk the cache root, returning one :class:`EntryUsage` per entry.
+
+    ``sources`` is the cache layer's ``ALLOWED_SOURCES`` tuple. The
+    scan only descends into those subtrees so audit-log / scratch files
+    at the cache root level don't pollute the count.
+    """
+    if not cache_root.exists():
+        return UsageReport(total_bytes=0, total_entries=0, entries=())
+    entries: list[EntryUsage] = []
+    total_bytes = 0
+    for src in sources:
+        src_root = cache_root / src
+        if not src_root.exists():
+            continue
+        # Snapshot before iteration: callers may evict mid-walk.
+        for meta_path in list(src_root.rglob("meta.json")):
+            size, meta_src, meta_key, present = _read_meta_size(meta_path)
+            try:
+                mtime = meta_path.stat().st_mtime
+            except OSError:
+                mtime = 0.0
+            entries.append(
+                EntryUsage(
+                    entry_dir=meta_path.parent,
+                    source=meta_src or src,
+                    key=meta_key
+                    or str(meta_path.parent.relative_to(src_root)).replace(
+                        os.sep, "/"
+                    ),
+                    size_bytes=size,
+                    last_accessed=mtime,
+                    meta_present=present,
+                )
+            )
+            total_bytes += size
+    return UsageReport(
+        total_bytes=total_bytes,
+        total_entries=len(entries),
+        entries=tuple(entries),
+    )
+
+
+# ---------------------------------------------------------------------------
+# LRU eviction primitives
+# ---------------------------------------------------------------------------
+
+
+def lru_order(usage: UsageReport) -> tuple[EntryUsage, ...]:
+    """Return entries oldest-first by (mtime, entry_dir-as-str).
+
+    The path tie-break is what makes eviction deterministic across
+    filesystems with 1s mtime granularity (most ext4 / NTFS configs).
+    Tests can rely on a stable order even for entries written within
+    the same second.
+    """
+    return tuple(sorted(usage.entries, key=lambda e: (e.last_accessed, str(e.entry_dir))))
+
+
+def cap_breached(
+    usage: UsageReport,
+    caps: CacheCaps,
+    *,
+    incoming_bytes: int = 0,
+    incoming_entries: int = 0,
+) -> bool:
+    """Return True iff ``usage`` plus a hypothetical add breaches caps.
+
+    ``incoming_bytes`` is the net byte delta the caller plans to add
+    (already accounting for any existing entry being replaced).
+    ``incoming_entries`` is the entry-count delta (0 for a re-put of an
+    existing key, 1 for a brand-new entry, 0 for prune-to-cap).
+    """
+    if caps.bytes_enforced and usage.total_bytes + incoming_bytes > caps.max_bytes:
+        return True
+    return bool(
+        caps.entries_enforced
+        and usage.total_entries + incoming_entries > caps.max_entries
+    )
+
+
+def evict_lru(
+    cache_root: Path,
+    *,
+    sources: Iterable[str],
+    caps: CacheCaps,
+    incoming_bytes: int = 0,
+    incoming_entries: int = 0,
+    protect_keys: Iterable[tuple[str, str]] = (),
+    on_evict: EvictCallback | None = None,
+) -> list[EntryUsage]:
+    """Evict LRU entries until the cap fits the incoming delta.
+
+    Single-pass O(n log n): one ``scan_usage`` call up-front, then iterate
+    the LRU-ordered candidate list maintaining running totals so each
+    eviction does not re-scan the cache root (the previous O(n^2)
+    re-scan pattern was a P2 finding from the iter-0 review).
+
+    Returns the list of evicted :class:`EntryUsage` records, oldest
+    first, in eviction order.
+
+    Args:
+        cache_root: Cache root path.
+        sources: Cache layer's ALLOWED_SOURCES tuple.
+        caps: Resolved cap thresholds.
+        incoming_bytes: Bytes the caller plans to add post-eviction.
+            May be negative for a shrinking re-put (caller subtracts
+            the existing entry's size).
+        incoming_entries: Entry-count delta (0 for re-put / prune-to-
+            cap, 1 for a brand-new entry).
+        protect_keys: Iterable of (source, key) pairs that MUST NOT be
+            evicted (typically the entry currently being written, so a
+            re-put cannot self-evict).
+        on_evict: Optional callback invoked once per evicted entry
+            BEFORE the directory is removed. Receives the victim, the
+            already-narrowed reason string (``"size_cap"`` /
+            ``"entry_cap"`` / ``"size_cap+entry_cap"``) reflecting which
+            cap was actually exceeded at the moment of eviction, and
+            the resolved caps for caller introspection.
+    """
+    if not caps.any_enforced:
+        return []
+    protect = {(s, k) for s, k in protect_keys}
+    usage = scan_usage(cache_root, sources=sources)
+    if not cap_breached(
+        usage,
+        caps,
+        incoming_bytes=incoming_bytes,
+        incoming_entries=incoming_entries,
+    ):
+        return []
+    ordered = [e for e in lru_order(usage) if (e.source, e.key) not in protect]
+    if not ordered:
+        # Every entry is protected -- caller decides what to do.
+        return []
+    evicted: list[EntryUsage] = []
+    running_bytes = usage.total_bytes
+    running_entries = usage.total_entries
+    for victim in ordered:
+        bytes_breach = (
+            caps.bytes_enforced
+            and running_bytes + incoming_bytes > caps.max_bytes
+        )
+        entries_breach = (
+            caps.entries_enforced
+            and running_entries + incoming_entries > caps.max_entries
+        )
+        if not (bytes_breach or entries_breach):
+            break
+        reasons: list[str] = []
+        if bytes_breach:
+            reasons.append("size_cap")
+        if entries_breach:
+            reasons.append("entry_cap")
+        reason = "+".join(reasons) or "unknown"
+        if on_evict is not None:
+            on_evict(victim, reason, caps)
+        # Concurrent removal -- treat as a no-op.
+        with contextlib.suppress(FileNotFoundError):
+            shutil.rmtree(victim.entry_dir)
+        evicted.append(victim)
+        running_bytes -= victim.size_bytes
+        running_entries -= 1
+    return evicted
+
+
+#: Type alias for the on_evict callback used by :func:`evict_lru` and
+#: :func:`enforce_caps`. Invoked once per evicted entry BEFORE the
+#: directory is removed. Signature is ``(victim, reason, caps)`` where
+#: ``reason`` is the already-narrowed breach descriptor reflecting which
+#: cap was actually exceeded at the moment of eviction (P1 fix from the
+#: iter-1 review: the previous ``(victim, caps, incoming_bytes)`` shape
+#: forced the audit callback to recompute reason without enough context
+#: and ended up tagging every record ``size_cap+entry_cap`` under the
+#: defaults).
+EvictCallback = Callable[[EntryUsage, str, CacheCaps], None]
+
+
+# ---------------------------------------------------------------------------
+# High-level enforce_caps entry point
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class EnforceResult:
+    """Outcome of an enforce_caps() call.
+
+    ``evicted`` is the list of entries removed during enforcement. Empty
+    when the cache was already under cap or no caps were enforced.
+    ``would_breach`` is True iff eviction could not free enough -- the
+    caller (cache:put) raises :class:`CacheCapBreachedError` in that
+    case; prune-to-cap surfaces a structured warning.
+    """
+
+    evicted: tuple[EntryUsage, ...]
+    final_usage: UsageReport
+    would_breach: bool
+
+
+def predict_eviction_set(
+    cache_root: Path,
+    *,
+    sources: Iterable[str],
+    caps: CacheCaps,
+) -> tuple[EntryUsage, ...]:
+    """Compute the LRU eviction set without removing anything (dry-run).
+
+    Walks entries in LRU order, accumulating evictions until the
+    projected running totals fit under the caps. Used by
+    ``cache:prune --to-cap --dry-run`` so operators can preview what
+    would be evicted before committing.
+    """
+    if not caps.any_enforced:
+        return ()
+    usage = scan_usage(cache_root, sources=sources)
+    if not cap_breached(usage, caps):
+        return ()
+    ordered = lru_order(usage)
+    evicted: list[EntryUsage] = []
+    running_bytes = usage.total_bytes
+    running_entries = usage.total_entries
+    for entry in ordered:
+        if not (
+            (caps.bytes_enforced and running_bytes > caps.max_bytes)
+            or (caps.entries_enforced and running_entries > caps.max_entries)
+        ):
+            break
+        evicted.append(entry)
+        running_bytes -= entry.size_bytes
+        running_entries -= 1
+    return tuple(evicted)
+
+
+def enforce_caps(
+    cache_root: Path,
+    *,
+    sources: Iterable[str],
+    caps: CacheCaps | None = None,
+    incoming_bytes: int = 0,
+    incoming_entries: int = 0,
+    protect_keys: Iterable[tuple[str, str]] = (),
+    on_evict: EvictCallback | None = None,
+) -> EnforceResult:
+    """Evict LRU entries until the cap fits the incoming delta.
+
+    Wrap :func:`evict_lru` with a final cap-breach check so callers can
+    differentiate "evicted cleanly" from "evicted but still breached".
+    """
+    resolved = caps if caps is not None else resolve_caps()
+    evicted = evict_lru(
+        cache_root,
+        sources=sources,
+        caps=resolved,
+        incoming_bytes=incoming_bytes,
+        incoming_entries=incoming_entries,
+        protect_keys=protect_keys,
+        on_evict=on_evict,
+    )
+    final_usage = scan_usage(cache_root, sources=sources)
+    breached = cap_breached(
+        final_usage,
+        resolved,
+        incoming_bytes=incoming_bytes,
+        incoming_entries=incoming_entries,
+    )
+    return EnforceResult(
+        evicted=tuple(evicted),
+        final_usage=final_usage,
+        would_breach=breached,
+    )
+
+
+__all__ = [
+    "CAP_DISABLED",
+    "CacheCapBreachedError",
+    "CacheCaps",
+    "DEFAULT_MAX_BYTES",
+    "DEFAULT_MAX_ENTRIES",
+    "ENV_MAX_BYTES",
+    "ENV_MAX_ENTRIES",
+    "EnforceResult",
+    "EntryUsage",
+    "EvictCallback",
+    "UsageReport",
+    "cap_breached",
+    "enforce_caps",
+    "evict_lru",
+    "lru_order",
+    "predict_eviction_set",
+    "resolve_caps",
+    "scan_usage",
+]

package/scripts/_cache_refresh.py

@@ -0,0 +1,163 @@
+#!/usr/bin/env python3
+"""_cache_refresh.py -- cache:refresh-closed reconciliation (#1476).
+
+Split out of :mod:`cache` so the parent stays under the deft 1000-line
+MUST limit (mirrors the existing ``_cache_fetch`` / ``_cache_quota`` /
+``_cache_validate`` split).
+
+Why this module exists
+----------------------
+The default ``cache:fetch-all`` enumeration is ``state=open``. Once an
+upstream GitHub issue closes it drops out of that enumeration, so its
+cached ``raw.json`` is never rewritten and keeps saying ``state=open``
+for the full 7-day cache TTL. ``triage:queue`` then keeps ranking the
+closed issue as actionable untriaged work -- the #1322 shape recorded
+in #1476.
+
+This module reconciles that gap. :func:`cache_refresh_closed`:
+
+1. Scans on-disk cache entries whose ``raw.json`` says ``state=open``.
+2. Enumerates the current open issue numbers (the authoritative set).
+3. For each cached-open entry NOT in the open enumeration, fetches its
+   live single-issue state and, when closed, rewrites the entry via
+   ``cache.cache_put`` so the next queue walk excludes it.
+
+The single-issue fetch + rewrite loop lives in
+:func:`_cache_fetch.run_state_refresh`; the open enumeration in
+:func:`_cache_fetch.list_open_issue_numbers`. This module owns the
+on-disk scan and the ``cache_put`` binding.
+
+Import-cycle note
+-----------------
+``cache`` imports ``cache_refresh_closed`` from here at module load, so
+this module MUST NOT import ``cache`` at the top level. The single
+``import cache`` lives inside :func:`cache_refresh_closed`, by which
+time ``cache`` is fully initialised.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import json
+import sys
+from pathlib import Path
+from typing import Any
+
+# Make sibling ``scripts`` modules importable when invoked via
+# ``python scripts/cache.py`` from a Taskfile dispatch.
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+
+from _cache_fetch import (  # noqa: E402  -- intentional sys.path tweak
+    StateRefreshReport,
+    list_open_issue_numbers,
+    run_state_refresh,
+)
+
+#: Default cache source. v1 ships ``github-issue`` only (mirrors
+#: ``cache.ALLOWED_SOURCES``).
+_DEFAULT_SOURCE = "github-issue"
+
+
+def scan_cached_open_entries(
+    repo: str,
+    *,
+    source: str,
+    cache_root: Path,
+) -> list[tuple[int, dict[str, Any]]]:
+    """Return ``(number, raw)`` for on-disk cache entries that say ``state=open``.
+
+    Walks ``<cache_root>/<source>/<owner>/<name>/<N>/raw.json`` and yields
+    the parsed payloads whose normalised ``state`` is ``open`` -- the
+    candidate set :func:`cache_refresh_closed` revisits against the live
+    open enumeration. The lowercase compare mirrors the #1236 reader-side
+    normalisation so a pre-#1239 cache carrying ``"state": "OPEN"`` is
+    still considered.
+    """
+    if "/" not in repo:
+        return []
+    owner, name = repo.split("/", 1)
+    base = cache_root / source / owner / name
+    if not base.is_dir():
+        return []
+    out: list[tuple[int, dict[str, Any]]] = []
+    for entry in sorted(base.iterdir()):
+        if not entry.is_dir() or not entry.name.isdigit():
+            continue
+        raw_path = entry / "raw.json"
+        if not raw_path.is_file():
+            continue
+        try:
+            raw = json.loads(raw_path.read_text(encoding="utf-8"))
+        except (OSError, json.JSONDecodeError):
+            continue
+        if not isinstance(raw, dict):
+            continue
+        number = raw.get("number")
+        if not isinstance(number, int):
+            with contextlib.suppress(ValueError, TypeError):
+                number = int(entry.name)
+        if not isinstance(number, int):
+            continue
+        state_raw = raw.get("state") or "open"
+        state = state_raw.lower() if isinstance(state_raw, str) else "open"
+        if state != "open":
+            continue
+        out.append((int(number), raw))
+    return out
+
+
+def cache_refresh_closed(
+    *,
+    source: str,
+    repo: str,
+    ttl_seconds: int | None = None,
+    delay_ms: int | None = None,
+    limit: int = 1000,
+    cache_root: Path | None = None,
+) -> StateRefreshReport:
+    """Rewrite cached-open entries that closed upstream to ``state=closed`` (#1476).
+
+    See the module docstring for the three-step reconciliation. Returns a
+    :class:`_cache_fetch.StateRefreshReport`. When no cached-open entries
+    exist the open enumeration is skipped entirely (an empty report is
+    returned without any network call).
+
+    Raises:
+        cache.CacheError: On an unsupported source, a malformed repo, or a
+            negative ``delay_ms`` -- so CLI / Taskfile callers exit non-zero
+            via the same error class as the rest of the cache surface.
+    """
+    # Deferred import breaks the cache <-> _cache_refresh cycle (see the
+    # module docstring). ``cache`` is fully initialised by call time.
+    import cache
+
+    if source != _DEFAULT_SOURCE:
+        raise cache.CacheError(
+            f"cache:refresh-closed source={source!r} not supported in v1 "
+            "(supports: github-issue only; other sources deferred to v2)"
+        )
+    if not cache._REPO_RE.match(repo):
+        raise cache.CacheError(
+            f"invalid --repo {repo!r}: expected 'owner/repo' "
+            "(alphanumerics, '.', '_', '-' only)"
+        )
+    effective_delay = delay_ms if delay_ms is not None else cache.DEFAULT_DELAY_MS
+    if effective_delay < 0:
+        raise cache.CacheError(f"--delay-ms must be >= 0 (got {effective_delay!r})")
+
+    root = cache_root if cache_root is not None else cache.DEFAULT_CACHE_ROOT
+    cached_open = scan_cached_open_entries(repo, source=source, cache_root=Path(root))
+    if not cached_open:
+        return StateRefreshReport()
+    open_numbers = list_open_issue_numbers(repo, state="open", limit=limit)
+
+    def _do_put(key: str, raw: dict[str, Any]) -> None:
+        cache.cache_put(source, key, raw, ttl_seconds=ttl_seconds, cache_root=cache_root)
+
+    return run_state_refresh(
+        repo=repo,
+        open_numbers=open_numbers,
+        cached_open=cached_open,
+        do_put=_do_put,
+        delay_ms=effective_delay,
+    )