staleflight 0.1.0__tar.gz

staleflight-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,27 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: pip install pytest ruff
+      - run: ruff check .
+      - run: ruff format --check .
+      - run: pip install -e .
+      - run: pytest

staleflight-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,33 @@
+name: Release to PyPI
+
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install build
+      - run: python -m build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write  # PyPI Trusted Publishing (OIDC) -- no API token stored
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

staleflight-0.1.0/.gitignore

@@ -0,0 +1,8 @@
+__pycache__/
+*.pyc
+dist/
+*.egg-info/
+.venv/
+.pytest_cache/
+.ruff_cache/
+.tools/

staleflight-0.1.0/CHANGELOG.md

@@ -0,0 +1,7 @@
+# Changelog
+
+## 0.1.0 (2026-09-02)
+
+- Initial release: `SWRCache`, `Snapshot`, `swr` — TTL + non-blocking
+  singleflight + stale-while-revalidate + stale-if-error for zero-argument
+  callables. Zero dependencies, typed, Python 3.11+.

staleflight-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Akarsh Sharma
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

staleflight-0.1.0/PKG-INFO

@@ -0,0 +1,90 @@
+Metadata-Version: 2.5
+Name: staleflight
+Version: 0.1.0
+Summary: Serve-stale singleflight caching: RFC 5861 stale-while-revalidate and stale-if-error for plain Python callables.
+Project-URL: Homepage, https://github.com/jaeger123/staleflight
+Project-URL: Repository, https://github.com/jaeger123/staleflight
+Project-URL: Changelog, https://github.com/jaeger123/staleflight/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/jaeger123/staleflight/issues
+Author: Akarsh Sharma
+License-Expression: MIT
+License-File: LICENSE
+Keywords: cache,dogpile,rfc5861,singleflight,stale-if-error,stale-while-revalidate,swr,ttl
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# staleflight
+
+**Serve-stale singleflight caching for Python — RFC 5861's `stale-while-revalidate` and `stale-if-error`, for plain callables instead of HTTP.**
+
+Zero dependencies. Fully typed (PEP 561). Python 3.11+.
+
+```python
+from staleflight import swr
+
+
+@swr(ttl=5.0)
+def mesh_health() -> dict:
+    return probe_all_the_things()  # expensive: network calls, big queries…
+
+
+snapshot = mesh_health.get()  # Snapshot(value=..., created_at=...) or None
+```
+
+## The semantics, precisely
+
+| State | What a caller gets |
+|---|---|
+| **fresh** (age < ttl) | the cached snapshot, ~0 cost |
+| **stale** | exactly **one** caller recomputes; every concurrent caller is served the **previous snapshot immediately** — nobody waits behind the refresh |
+| **refresh fails** | the previous snapshot keeps being served and keeps aging; the error lands on `cache.last_error` and your `on_error` callback |
+| **empty** (first ever call) | the first caller computes; concurrent callers get `None` and decide what "not yet" means for them |
+
+This is the **non-blocking** flavor of stampede protection. Most caching libraries offer the blocking flavor — losers park behind the winner's lock until the new value exists. That is the right choice when every reader must see the newest value, and the wrong one when bounded *latency* matters more than bounded *staleness*: readiness gates, dashboards, feature flags, config lookups. staleflight is for the second family.
+
+## Why not …
+
+*(Survey of 17 caching libraries, 2026. Corrections welcome.)*
+
+- **dogpile.cache** — the one mature library with this exact serve-stale semantic (`get_or_create`). Adopt it if you want regions, backends and invalidation strategies; staleflight is for when you want the 150-line version with no dependencies and stale-if-error built in (dogpile propagates creator failures to the winning caller).
+- **cachetools** — TTL only; its stampede options make concurrent callers *wait*. No stale-serving.
+- **PyPI `singleflight` ports** — deduplicate concurrent calls but block the losers, and cache nothing.
+- **cachier / diskcache / requests-cache** — respectively: immature memory backend; probabilistic *early* refresh that still blocks after full expiry; SWR for HTTP responses only.
+
+## API
+
+```python
+from staleflight import SWRCache, Snapshot, swr
+
+cache = SWRCache(source, ttl=5.0, on_error=log_it, clock=time.monotonic)
+
+cache.get()  # Snapshot | None — refreshes at most singleflight-once, never raises
+cache.peek()  # Snapshot | None — never triggers work
+cache.refresh()  # force recompute now; raises on failure (a command, not a read)
+cache.age()  # seconds since compute; float('inf') when empty
+cache.invalidate()  # drop the snapshot
+cache.last_error  # BaseException | None from the most recent failed get()-refresh
+```
+
+`Snapshot` is a frozen dataclass `(value, created_at)`; `created_at` is on the cache's (monotonic) clock. The `clock` parameter makes every behavior testable without sleeps — see the test suite.
+
+## Thread-safety
+
+Publication is a single reference assignment of an immutable `Snapshot`: readers observe the old snapshot or the new one, never a torn value. Safe under CPython's GIL (every currently supported default build). On free-threaded builds (PEP 703) reference-swap visibility is implementation behavior, not contract — wrap access in your own lock there.
+
+## Non-goals
+
+Keyed/memoizing caches, async, eviction policies, external backends, background refresh threads. One value, one callable, one file. If you need more, you want dogpile.cache.
+
+## License
+
+MIT

staleflight-0.1.0/README.md

@@ -0,0 +1,66 @@
+# staleflight
+
+**Serve-stale singleflight caching for Python — RFC 5861's `stale-while-revalidate` and `stale-if-error`, for plain callables instead of HTTP.**
+
+Zero dependencies. Fully typed (PEP 561). Python 3.11+.
+
+```python
+from staleflight import swr
+
+
+@swr(ttl=5.0)
+def mesh_health() -> dict:
+    return probe_all_the_things()  # expensive: network calls, big queries…
+
+
+snapshot = mesh_health.get()  # Snapshot(value=..., created_at=...) or None
+```
+
+## The semantics, precisely
+
+| State | What a caller gets |
+|---|---|
+| **fresh** (age < ttl) | the cached snapshot, ~0 cost |
+| **stale** | exactly **one** caller recomputes; every concurrent caller is served the **previous snapshot immediately** — nobody waits behind the refresh |
+| **refresh fails** | the previous snapshot keeps being served and keeps aging; the error lands on `cache.last_error` and your `on_error` callback |
+| **empty** (first ever call) | the first caller computes; concurrent callers get `None` and decide what "not yet" means for them |
+
+This is the **non-blocking** flavor of stampede protection. Most caching libraries offer the blocking flavor — losers park behind the winner's lock until the new value exists. That is the right choice when every reader must see the newest value, and the wrong one when bounded *latency* matters more than bounded *staleness*: readiness gates, dashboards, feature flags, config lookups. staleflight is for the second family.
+
+## Why not …
+
+*(Survey of 17 caching libraries, 2026. Corrections welcome.)*
+
+- **dogpile.cache** — the one mature library with this exact serve-stale semantic (`get_or_create`). Adopt it if you want regions, backends and invalidation strategies; staleflight is for when you want the 150-line version with no dependencies and stale-if-error built in (dogpile propagates creator failures to the winning caller).
+- **cachetools** — TTL only; its stampede options make concurrent callers *wait*. No stale-serving.
+- **PyPI `singleflight` ports** — deduplicate concurrent calls but block the losers, and cache nothing.
+- **cachier / diskcache / requests-cache** — respectively: immature memory backend; probabilistic *early* refresh that still blocks after full expiry; SWR for HTTP responses only.
+
+## API
+
+```python
+from staleflight import SWRCache, Snapshot, swr
+
+cache = SWRCache(source, ttl=5.0, on_error=log_it, clock=time.monotonic)
+
+cache.get()  # Snapshot | None — refreshes at most singleflight-once, never raises
+cache.peek()  # Snapshot | None — never triggers work
+cache.refresh()  # force recompute now; raises on failure (a command, not a read)
+cache.age()  # seconds since compute; float('inf') when empty
+cache.invalidate()  # drop the snapshot
+cache.last_error  # BaseException | None from the most recent failed get()-refresh
+```
+
+`Snapshot` is a frozen dataclass `(value, created_at)`; `created_at` is on the cache's (monotonic) clock. The `clock` parameter makes every behavior testable without sleeps — see the test suite.
+
+## Thread-safety
+
+Publication is a single reference assignment of an immutable `Snapshot`: readers observe the old snapshot or the new one, never a torn value. Safe under CPython's GIL (every currently supported default build). On free-threaded builds (PEP 703) reference-swap visibility is implementation behavior, not contract — wrap access in your own lock there.
+
+## Non-goals
+
+Keyed/memoizing caches, async, eviction policies, external backends, background refresh threads. One value, one callable, one file. If you need more, you want dogpile.cache.
+
+## License
+
+MIT

staleflight-0.1.0/pyproject.toml

@@ -0,0 +1,83 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "staleflight"
+version = "0.1.0"
+description = "Serve-stale singleflight caching: RFC 5861 stale-while-revalidate and stale-if-error for plain Python callables."
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.11"
+authors = [{ name = "Akarsh Sharma" }]
+keywords = [
+  "cache",
+  "singleflight",
+  "stale-while-revalidate",
+  "stale-if-error",
+  "swr",
+  "ttl",
+  "dogpile",
+  "rfc5861",
+]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Software Development :: Libraries :: Python Modules",
+  "Typing :: Typed",
+]
+
+[project.urls]
+Homepage = "https://github.com/jaeger123/staleflight"
+Repository = "https://github.com/jaeger123/staleflight"
+Changelog = "https://github.com/jaeger123/staleflight/blob/main/CHANGELOG.md"
+Issues = "https://github.com/jaeger123/staleflight/issues"
+
+[dependency-groups]
+dev = ["pytest>=8", "ruff>=0.6"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/staleflight"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-q"
+
+[tool.ruff]
+line-length = 88
+extend-exclude = [".tools"]
+target-version = "py311"
+
+[tool.ruff.lint]
+select = [
+  "E",    # pycodestyle errors
+  "W",    # pycodestyle warnings
+  "F",    # pyflakes
+  "I",    # isort
+  "N",    # pep8-naming
+  "D",    # pydocstyle
+  "UP",   # pyupgrade
+  "B",    # bugbear
+  "SIM",  # simplify
+  "RUF",  # ruff-specific
+]
+ignore = [
+  "D203",  # incompatible with D211
+  "D213",  # incompatible with D212
+]
+
+[tool.ruff.lint.isort]
+case-sensitive = true
+# Match the local formatter, which groups this package with third-party.
+known-third-party = ["staleflight"]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/*" = ["D"]  # tests document themselves through their names
+
+[tool.ruff.lint.pydocstyle]
+convention = "google"

staleflight-0.1.0/src/staleflight/__init__.py

@@ -0,0 +1,6 @@
+"""staleflight: serve-stale singleflight caching (RFC 5861 for callables)."""
+
+from staleflight.core import SWRCache, Snapshot, swr
+
+__all__ = ["SWRCache", "Snapshot", "swr"]
+__version__ = "0.1.0"

staleflight-0.1.0/src/staleflight/core.py

@@ -0,0 +1,187 @@
+"""Serve-stale singleflight caching for expensive zero-argument callables.
+
+This module implements the semantics of RFC 5861 (``stale-while-revalidate``
+and ``stale-if-error``) for plain Python callables:
+
+fresh
+    The cached snapshot is served; no work happens.
+stale
+    Exactly one caller recomputes. Every caller that arrives while the
+    recomputation is in flight is served the previous snapshot immediately
+    instead of waiting (``stale-while-revalidate``).
+refresh failure
+    The previous snapshot keeps being served and keeps aging
+    (``stale-if-error``). The error is recorded and optionally reported.
+empty
+    The very first caller computes; callers that arrive during that first
+    computation receive ``None`` and decide for themselves what "not yet"
+    means in their domain.
+
+The design is intentionally the opposite of a blocking dogpile lock: under
+load, no caller is ever parked behind another caller's slow recomputation.
+That trade -- bounded staleness in exchange for bounded latency -- is the
+right one for readiness gates, dashboards, and feature-flag style lookups,
+and the wrong one when every caller must observe the newest value.
+"""
+
+from __future__ import annotations
+
+import threading
+import time
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Generic, TypeVar
+
+__all__ = ["SWRCache", "Snapshot", "swr"]
+
+T = TypeVar("T")
+
+Clock = Callable[[], float]
+ErrorCallback = Callable[[BaseException], None]
+
+
+@dataclass(frozen=True, slots=True)
+class Snapshot(Generic[T]):
+    """An immutable value paired with the instant it was computed.
+
+    ``created_at`` is expressed on the cache's clock (monotonic by
+    default), so it is suitable for measuring age, not for display.
+    """
+
+    value: T
+    created_at: float
+
+
+class SWRCache(Generic[T]):
+    """A serve-stale singleflight cache around one zero-argument callable.
+
+    One instance guards one value. Publication is a single reference
+    assignment of an immutable :class:`Snapshot`, so readers in other
+    threads always observe either the previous snapshot or the new one,
+    never a partially built value.
+
+    Thread-safety: safe under CPython's GIL, which every current supported
+    runtime has. A free-threaded (PEP 703) deployment should wrap
+    ``get``/``peek`` in a lock of its own; reference-swap atomicity is
+    implementation behaviour there, not a documented guarantee.
+
+    Args:
+        source: The expensive callable producing the value.
+        ttl: Seconds a snapshot is considered fresh. Must be positive.
+        on_error: Called with the exception when a refresh triggered by
+            :meth:`get` fails. Failures never propagate out of ``get``;
+            they surface here and on :attr:`last_error`.
+        clock: Monotonic time source; injectable for tests.
+    """
+
+    def __init__(
+        self,
+        source: Callable[[], T],
+        *,
+        ttl: float,
+        on_error: ErrorCallback | None = None,
+        clock: Clock = time.monotonic,
+    ) -> None:
+        """See the class docstring for parameter semantics."""
+        if ttl <= 0:
+            raise ValueError(f"ttl must be positive, got {ttl!r}")
+        self._source = source
+        self._ttl = float(ttl)
+        self._on_error = on_error
+        self._clock = clock
+        self._snapshot: Snapshot[T] | None = None
+        self._refresh_lock = threading.Lock()
+        #: The exception from the most recent failed refresh, cleared by the
+        #: next successful one. Advisory: read it for diagnostics, not logic.
+        self.last_error: BaseException | None = None
+
+    @property
+    def ttl(self) -> float:
+        """Seconds a snapshot is served without triggering a refresh."""
+        return self._ttl
+
+    def get(self) -> Snapshot[T] | None:
+        """Return a snapshot, refreshing at most once per staleness.
+
+        Never blocks on another caller's refresh and never raises on a
+        failed refresh; see the module docstring for the full semantics.
+        Returns ``None`` only while the very first computation has not yet
+        completed.
+        """
+        snapshot = self._snapshot
+        if snapshot is not None and self._clock() - snapshot.created_at < self._ttl:
+            return snapshot
+        if self._refresh_lock.acquire(blocking=False):
+            try:
+                return self._refresh_locked()
+            # Broad on purpose: stale-if-error is the contract.
+            except Exception as error:
+                self.last_error = error
+                if self._on_error is not None:
+                    self._on_error(error)
+            finally:
+                self._refresh_lock.release()
+        # Lock was busy (another caller is refreshing) or the refresh
+        # failed: the previous snapshot -- possibly None -- is the answer.
+        return self._snapshot
+
+    def refresh(self) -> Snapshot[T]:
+        """Recompute synchronously and publish, regardless of freshness.
+
+        Unlike :meth:`get`, a failure here propagates: an explicit refresh
+        is a command, not a read. Explicit refreshes serialize on the
+        refresh lock, so a slow older computation can never overwrite a
+        newer snapshot.
+        """
+        with self._refresh_lock:
+            return self._refresh_locked()
+
+    def _refresh_locked(self) -> Snapshot[T]:
+        snapshot = Snapshot(value=self._source(), created_at=self._clock())
+        self._snapshot = snapshot
+        self.last_error = None
+        return snapshot
+
+    def peek(self) -> Snapshot[T] | None:
+        """Return the current snapshot, fresh or stale, without any work."""
+        return self._snapshot
+
+    def age(self) -> float:
+        """Seconds since the current snapshot was computed.
+
+        Returns ``float('inf')`` when nothing has been computed yet, so the
+        result is always comparable against a TTL or staleness budget.
+        """
+        snapshot = self._snapshot
+        if snapshot is None:
+            return float("inf")
+        return self._clock() - snapshot.created_at
+
+    def invalidate(self) -> None:
+        """Drop the snapshot; the next :meth:`get` recomputes from empty."""
+        self._snapshot = None
+
+
+def swr(
+    *,
+    ttl: float,
+    on_error: ErrorCallback | None = None,
+    clock: Clock = time.monotonic,
+) -> Callable[[Callable[[], T]], SWRCache[T]]:
+    """Build an :class:`SWRCache` in decorator position.
+
+    The decorated name is *replaced by the cache instance*, which makes the
+    call-site semantics explicit -- ``config.get()`` returns a
+    :class:`Snapshot`, not a bare value::
+
+        @swr(ttl=5.0)
+        def mesh_health() -> dict[str, bool]:
+            return probe_everything()
+
+        snapshot = mesh_health.get()
+    """
+
+    def wrap(source: Callable[[], T]) -> SWRCache[T]:
+        return SWRCache(source, ttl=ttl, on_error=on_error, clock=clock)
+
+    return wrap

staleflight-0.1.0/tests/test_staleflight.py

@@ -0,0 +1,239 @@
+import threading
+
+import pytest
+from staleflight import SWRCache, Snapshot, swr
+
+
+class FakeClock:
+    def __init__(self) -> None:
+        self.now = 100.0
+
+    def __call__(self) -> float:
+        return self.now
+
+    def advance(self, seconds: float) -> None:
+        self.now += seconds
+
+
+@pytest.fixture()
+def clock() -> FakeClock:
+    return FakeClock()
+
+
+def test_first_call_computes_and_returns_snapshot(clock):
+    cache = SWRCache(lambda: "v1", ttl=5.0, clock=clock)
+
+    snapshot = cache.get()
+
+    assert isinstance(snapshot, Snapshot)
+    assert snapshot.value == "v1"
+    assert snapshot.created_at == clock.now
+
+
+def test_fresh_snapshot_is_served_without_recompute(clock):
+    calls = []
+    cache = SWRCache(lambda: calls.append(1) or len(calls), ttl=5.0, clock=clock)
+
+    first = cache.get()
+    clock.advance(4.9)
+    second = cache.get()
+
+    assert calls == [1]
+    assert second is first
+
+
+def test_stale_snapshot_triggers_exactly_one_recompute(clock):
+    calls = []
+    cache = SWRCache(lambda: calls.append(1) or len(calls), ttl=5.0, clock=clock)
+
+    cache.get()
+    clock.advance(5.0)
+    refreshed = cache.get()
+
+    assert calls == [1, 1]
+    assert refreshed is not None and refreshed.value == 2
+
+
+def test_caller_during_refresh_gets_previous_snapshot_immediately(clock):
+    """The defining semantic: losers are served stale, never parked."""
+    in_refresh = threading.Event()
+    release = threading.Event()
+    values = iter(["old", "new"])
+
+    def slow_source():
+        value = next(values)
+        if value == "new":
+            in_refresh.set()
+            assert release.wait(timeout=5)
+        return value
+
+    cache = SWRCache(slow_source, ttl=5.0, clock=clock)
+    cache.get()  # publish "old"
+    clock.advance(5.0)
+
+    winner_result = {}
+    winner = threading.Thread(target=lambda: winner_result.update(snap=cache.get()))
+    winner.start()
+    assert in_refresh.wait(timeout=5)
+
+    loser_snapshot = cache.get()  # winner still inside slow_source
+    assert loser_snapshot is not None
+    assert loser_snapshot.value == "old"
+
+    release.set()
+    winner.join(timeout=5)
+    assert winner_result["snap"].value == "new"
+    assert cache.get().value == "new"
+
+
+def test_caller_during_first_ever_compute_gets_none(clock):
+    cache = SWRCache(lambda: "never", ttl=5.0, clock=clock)
+
+    with cache._refresh_lock:  # simulate the first computation in flight
+        assert cache.get() is None
+
+
+def test_failed_refresh_serves_stale_and_records_error(clock):
+    errors = []
+    state = {"fail": False}
+
+    def source():
+        if state["fail"]:
+            raise RuntimeError("boom")
+        return "good"
+
+    cache = SWRCache(source, ttl=5.0, on_error=errors.append, clock=clock)
+    cache.get()
+    state["fail"] = True
+    clock.advance(5.0)
+
+    snapshot = cache.get()
+
+    assert snapshot is not None and snapshot.value == "good"
+    assert cache.age() >= 5.0  # still aging: staleness stays observable
+    assert isinstance(cache.last_error, RuntimeError)
+    assert errors and errors[0] is cache.last_error
+
+
+def test_successful_refresh_clears_last_error(clock):
+    state = {"fail": True}
+
+    def source():
+        if state["fail"]:
+            raise RuntimeError("boom")
+        return "recovered"
+
+    cache = SWRCache(source, ttl=5.0, clock=clock)
+    assert cache.get() is None
+    assert cache.last_error is not None
+
+    state["fail"] = False
+    snapshot = cache.get()
+
+    assert snapshot is not None and snapshot.value == "recovered"
+    assert cache.last_error is None
+
+
+def test_explicit_refresh_raises_and_keeps_previous_snapshot(clock):
+    state = {"fail": False}
+
+    def source():
+        if state["fail"]:
+            raise RuntimeError("boom")
+        return "v1"
+
+    cache = SWRCache(source, ttl=5.0, clock=clock)
+    cache.get()
+    state["fail"] = True
+
+    with pytest.raises(RuntimeError):
+        cache.refresh()
+    assert cache.peek() is not None and cache.peek().value == "v1"
+
+
+def test_peek_never_computes(clock):
+    cache = SWRCache(lambda: pytest.fail("peek must not compute"), ttl=5.0, clock=clock)
+
+    assert cache.peek() is None
+
+
+def test_invalidate_forces_recompute_from_empty(clock):
+    calls = []
+    cache = SWRCache(lambda: calls.append(1) or len(calls), ttl=5.0, clock=clock)
+    cache.get()
+
+    cache.invalidate()
+
+    assert cache.peek() is None
+    assert cache.age() == float("inf")
+    assert cache.get().value == 2
+
+
+def test_age_uses_injected_clock(clock):
+    cache = SWRCache(lambda: "v", ttl=5.0, clock=clock)
+    cache.get()
+    clock.advance(2.5)
+
+    assert cache.age() == pytest.approx(2.5)
+
+
+def test_ttl_must_be_positive():
+    with pytest.raises(ValueError, match="ttl must be positive"):
+        SWRCache(lambda: 1, ttl=0)
+
+
+def test_swr_decorator_returns_a_cache(clock):
+    @swr(ttl=5.0, clock=clock)
+    def value() -> str:
+        return "decorated"
+
+    assert isinstance(value, SWRCache)
+    assert value.get().value == "decorated"
+
+
+def test_freshness_is_judged_on_the_returned_snapshot(clock):
+    """invalidate() between capture and age check must not corrupt get()."""
+    cache = SWRCache(lambda: "v", ttl=5.0, clock=clock)
+    first = cache.get()
+
+    # Regression guard for the capture race: age is computed from the same
+    # snapshot object that is returned, never re-read from the instance.
+    assert cache.get() is first
+
+
+def test_explicit_refreshes_serialize_on_the_lock(clock):
+    order = []
+
+    def source():
+        order.append("run")
+        return len(order)
+
+    cache = SWRCache(source, ttl=5.0, clock=clock)
+
+    slow_started = threading.Event()
+    release = threading.Event()
+
+    def slow_source():
+        slow_started.set()
+        assert release.wait(timeout=5)
+        order.append("slow")
+        return "slow"
+
+    cache._source = slow_source
+    slow = threading.Thread(target=cache.refresh)
+    slow.start()
+    assert slow_started.wait(timeout=5)
+
+    cache._source = source
+    fast = threading.Thread(target=cache.refresh)
+    fast.start()
+
+    release.set()
+    slow.join(timeout=5)
+    fast.join(timeout=5)
+
+    # The fast refresh could not start until the slow one finished, so the
+    # final publication is the later-started computation (which ran second
+    # and saw order == ["slow", "run"]), never a stale overwrite.
+    assert order == ["slow", "run"]
+    assert cache.peek().value == 2