quadkit-testing 0.0.44__tar.gz → 0.0.46__tar.gz

{quadkit_testing-0.0.44 → quadkit_testing-0.0.46}/PKG-INFO

@@ -1,14 +1,14 @@
 Metadata-Version: 2.5
 Name: quadkit-testing
-Version: 0.0.44
+Version: 0.0.46
 Summary: Centralized testing infrastructure for Quadkit Framework - Fixtures, factories, and utilities
-Project-URL: Homepage, https://dbtinoy-.github.io/quadkit/
+Project-URL: Homepage, https://oridecon.dev
 Project-URL: Repository, https://github.com/dbtinoy-/quadkit
-Project-URL: Documentation, https://dbtinoy-.github.io/quadkit/
+Project-URL: Documentation, https://oridecon.dev/quadkit/
 Project-URL: Issues, https://github.com/dbtinoy-/quadkit/issues
 Project-URL: Changelog, https://github.com/dbtinoy-/quadkit/blob/main/CHANGELOG.md
-Author-email: Quadkit Framework Team <team@quadkit.dev>
-Maintainer-email: Quadkit Framework Team <team@quadkit.dev>
+Author-email: Quadkit Framework Team <hello@oridecon.dev>
+Maintainer-email: Quadkit Framework Team <hello@oridecon.dev>
 License: Apache-2.0
 License-File: LICENSE
 License-File: NOTICE
@@ -234,16 +234,16 @@ vulnerabilities privately per [SECURITY.md](https://github.com/dbtinoy-/quadkit/
 
 ## Stability
 
-Version `0.0.44` in the `0.x` series, released in lockstep with the
-other four distributions; APIs may change between minor versions until
-1.0 — pin an exact version (`quadkit-testing==0.0.44`) or a tight range
-(`>=0.0.44,<0.1.0`). Full policy:
-[stability and compatibility](https://dbtinoy-.github.io/quadkit/reference/stability/).
+Version `0.0.46` in the `0.x` series, released in lockstep with the
+other twelve distributions; APIs may change between minor versions until
+1.0 — pin an exact version (`quadkit-testing==0.0.46`) or a tight range
+(`>=0.0.46,<0.1.0`). Full policy:
+[stability and compatibility](https://oridecon.dev/quadkit/ecosystem/compatibility/).
 
 ## Links
 
-- **Documentation** — <https://dbtinoy-.github.io/quadkit/>
-- **Getting started** — <https://dbtinoy-.github.io/quadkit/getting-started/installation/>
+- **Documentation** — <https://oridecon.dev/quadkit/>
+- **Getting started** — <https://oridecon.dev/quadkit/getting-started/installation/>
 - **Changelog** — <https://github.com/dbtinoy-/quadkit/blob/main/CHANGELOG.md>
 - **Issues** — <https://github.com/dbtinoy-/quadkit/issues>
 - **Security** — report privately per [SECURITY.md](https://github.com/dbtinoy-/quadkit/blob/main/SECURITY.md)

{quadkit_testing-0.0.44 → quadkit_testing-0.0.46}/README.md

@@ -178,16 +178,16 @@ vulnerabilities privately per [SECURITY.md](https://github.com/dbtinoy-/quadkit/
 
 ## Stability
 
-Version `0.0.44` in the `0.x` series, released in lockstep with the
-other four distributions; APIs may change between minor versions until
-1.0 — pin an exact version (`quadkit-testing==0.0.44`) or a tight range
-(`>=0.0.44,<0.1.0`). Full policy:
-[stability and compatibility](https://dbtinoy-.github.io/quadkit/reference/stability/).
+Version `0.0.46` in the `0.x` series, released in lockstep with the
+other twelve distributions; APIs may change between minor versions until
+1.0 — pin an exact version (`quadkit-testing==0.0.46`) or a tight range
+(`>=0.0.46,<0.1.0`). Full policy:
+[stability and compatibility](https://oridecon.dev/quadkit/ecosystem/compatibility/).
 
 ## Links
 
-- **Documentation** — <https://dbtinoy-.github.io/quadkit/>
-- **Getting started** — <https://dbtinoy-.github.io/quadkit/getting-started/installation/>
+- **Documentation** — <https://oridecon.dev/quadkit/>
+- **Getting started** — <https://oridecon.dev/quadkit/getting-started/installation/>
 - **Changelog** — <https://github.com/dbtinoy-/quadkit/blob/main/CHANGELOG.md>
 - **Issues** — <https://github.com/dbtinoy-/quadkit/issues>
 - **Security** — report privately per [SECURITY.md](https://github.com/dbtinoy-/quadkit/blob/main/SECURITY.md)

{quadkit_testing-0.0.44 → quadkit_testing-0.0.46}/pyproject.toml

@@ -6,7 +6,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "quadkit-testing"
-version = "0.0.44"
+version = "0.0.46"
 description = "Centralized testing infrastructure for Quadkit Framework - Fixtures, factories, and utilities"
 readme = "README.md"
 requires-python = ">=3.11"
@@ -42,10 +42,10 @@ dependencies = [
     "pytest-mock>=3.10.0,<4",
 ]
 authors = [
-    { name = "Quadkit Framework Team", email = "team@quadkit.dev" },
+    { name = "Quadkit Framework Team", email = "hello@oridecon.dev" },
 ]
 maintainers = [
-    { name = "Quadkit Framework Team", email = "team@quadkit.dev" },
+    { name = "Quadkit Framework Team", email = "hello@oridecon.dev" },
 ]
 
 [project.license]
@@ -78,9 +78,9 @@ integration = [
 ]
 
 [project.urls]
-Homepage = "https://dbtinoy-.github.io/quadkit/"
+Homepage = "https://oridecon.dev"
 Repository = "https://github.com/dbtinoy-/quadkit"
-Documentation = "https://dbtinoy-.github.io/quadkit/"
+Documentation = "https://oridecon.dev/quadkit/"
 Issues = "https://github.com/dbtinoy-/quadkit/issues"
 Changelog = "https://github.com/dbtinoy-/quadkit/blob/main/CHANGELOG.md"
 

{quadkit_testing-0.0.44 → quadkit_testing-0.0.46}/src/quadkit/testing/clients/web/client.py

@@ -61,6 +61,19 @@ class TestResponse:
         """Get the response headers."""
         return dict(self._response.headers)
 
+    @property
+    def cookies(self) -> dict[str, str]:
+        """Get the cookies the response set.
+
+        Without this an application whose behaviour *is* a cookie cannot be
+        tested through this client at all — a session that issues an
+        identity, a per-visitor scope, anything that proves two callers are
+        kept apart. ``headers`` carries only the raw ``set-cookie`` line,
+        which a test then has to parse, and the underlying response is
+        private on purpose.
+        """
+        return dict(self._response.cookies)
+
     def assert_status(self, expected: int) -> TestResponse:
         """Assert the response status code.
 

{quadkit_testing-0.0.44 → quadkit_testing-0.0.46}/src/quadkit/testing/compliance/__init__.py

@@ -29,6 +29,7 @@ from quadkit.testing.compliance.event_bus import EventBusCompliance
 from quadkit.testing.compliance.flags import FlagProviderCompliance
 from quadkit.testing.compliance.middleware import MiddlewareCompliance
 from quadkit.testing.compliance.notification import NotificationChannelCompliance
+from quadkit.testing.compliance.pool import ConnectionPoolCompliance
 from quadkit.testing.compliance.queue_backend import QueueBackendCompliance
 from quadkit.testing.compliance.repository import RepositoryCompliance
 from quadkit.testing.compliance.search import SearchEngineCompliance
@@ -77,6 +78,7 @@ __all__ = [
     "AuditStoreCompliance",
     "BlobStoreCompliance",
     "CacheBackendCompliance",
+    "ConnectionPoolCompliance",
     "DatabaseProviderCompliance",
     "DistributedLockCompliance",
     "EventBusCompliance",

{quadkit_testing-0.0.44 → quadkit_testing-0.0.46}/src/quadkit/testing/compliance/cache.py

@@ -22,6 +22,19 @@ import pytest
 __all__ = ["CacheBackendCompliance"]
 
 
+def _value(result: Any) -> Any:
+    """Unwrap an ``Ok`` result, failing the test when it is ``Err``.
+
+    ``CacheBackendProtocol`` answers every operation with a
+    ``Result[T, CacheError]``: a cache that cannot reach its store reports that
+    rather than raising. Unwrapping in one place keeps each test about the
+    behaviour it names, and a failure message carries the error instead of a
+    bare assertion.
+    """
+    assert result.is_ok(), f"expected Ok, got {result!r}"
+    return result.unwrap()
+
+
 class CacheBackendCompliance:
     """Reusable test suite for any ``CacheBackendProtocol`` implementation.
 
@@ -47,39 +60,28 @@ class CacheBackendCompliance:
     async def test_set_and_get(self) -> None:
         """set then get returns the stored value."""
         backend = await self.create_backend()
-        await backend.set("key", "value")
-        result = await backend.get("key")
-        assert result == "value"
+        _value(await backend.set("key", "value"))
+        assert _value(await backend.get("key")) == "value"
 
     @pytest.mark.asyncio
-    async def test_get_missing_returns_default(self) -> None:
-        """get on a missing key returns the default."""
+    async def test_get_missing_returns_none(self) -> None:
+        """get on a missing key returns Ok(None)."""
         backend = await self.create_backend()
-        result = await backend.get("nonexistent", "fallback")
-        assert result == "fallback"
-
-    @pytest.mark.asyncio
-    async def test_get_missing_returns_none_without_default(self) -> None:
-        """get on a missing key returns None when no default is given."""
-        backend = await self.create_backend()
-        result = await backend.get("nonexistent")
-        assert result is None
+        assert _value(await backend.get("nonexistent")) is None
 
     @pytest.mark.asyncio
     async def test_delete_existing_key(self) -> None:
-        """delete returns True and removes the key."""
+        """delete returns Ok(True) and removes the key."""
         backend = await self.create_backend()
         await backend.set("key", "value")
-        deleted = await backend.delete("key")
-        assert deleted is True
-        assert await backend.get("key") is None
+        assert _value(await backend.delete("key")) is True
+        assert _value(await backend.get("key")) is None
 
     @pytest.mark.asyncio
     async def test_delete_missing_key(self) -> None:
-        """delete on a missing key returns False."""
+        """delete on a missing key returns Ok(False)."""
         backend = await self.create_backend()
-        deleted = await backend.delete("nonexistent")
-        assert deleted is False
+        assert _value(await backend.delete("nonexistent")) is False
 
     @pytest.mark.asyncio
     async def test_clear(self) -> None:
@@ -87,9 +89,9 @@ class CacheBackendCompliance:
         backend = await self.create_backend()
         await backend.set("a", 1)
         await backend.set("b", 2)
-        await backend.clear()
-        assert await backend.get("a") is None
-        assert await backend.get("b") is None
+        _value(await backend.clear())
+        assert _value(await backend.get("a")) is None
+        assert _value(await backend.get("b")) is None
 
     @pytest.mark.asyncio
     async def test_overwrite_existing_key(self) -> None:
@@ -97,7 +99,7 @@ class CacheBackendCompliance:
         backend = await self.create_backend()
         await backend.set("key", "first")
         await backend.set("key", "second")
-        assert await backend.get("key") == "second"
+        assert _value(await backend.get("key")) == "second"
 
     @pytest.mark.asyncio
     async def test_ttl_expiry(self) -> None:
@@ -105,8 +107,7 @@ class CacheBackendCompliance:
         backend = await self.create_backend()
         await backend.set("key", "value", ttl=0.05)
         await asyncio.sleep(0.1)
-        result = await backend.get("key")
-        assert result is None
+        assert _value(await backend.get("key")) is None
 
     @pytest.mark.asyncio
     async def test_no_ttl_does_not_expire(self) -> None:
@@ -114,8 +115,7 @@ class CacheBackendCompliance:
         backend = await self.create_backend()
         await backend.set("key", "value")
         await asyncio.sleep(0.1)  # small delay
-        result = await backend.get("key")
-        assert result == "value"
+        assert _value(await backend.get("key")) == "value"
 
     @pytest.mark.asyncio
     async def test_stores_various_value_types(self) -> None:
@@ -128,4 +128,25 @@ class CacheBackendCompliance:
             ("list", [1, 2, 3]),
         ]:
             await backend.set(key, value)
-            assert await backend.get(key) == value
+            assert _value(await backend.get(key)) == value
+
+    @pytest.mark.asyncio
+    async def test_errors_are_returned_not_raised(self) -> None:
+        """A backend that fails reports Err(CacheError) rather than raising.
+
+        The protocol's whole point is that a cache miss or an unreachable
+        cache is a value the caller handles; a suite that only ever sees a
+        happy backend would certify a backend that raises on failure.
+        """
+        backend = await self.create_backend()
+        for result in (
+            await backend.get("key"),
+            await backend.set("key", "value"),
+            await backend.delete("key"),
+            await backend.exists("key"),
+            await backend.clear(),
+        ):
+            assert hasattr(result, "is_ok"), (
+                f"{type(backend).__name__} returned {type(result).__name__} "
+                "where CacheBackendProtocol promises Result"
+            )

{quadkit_testing-0.0.44 → quadkit_testing-0.0.46}/src/quadkit/testing/compliance/database.py

@@ -87,7 +87,7 @@ class DatabaseProviderCompliance:
 
     @pytest.mark.asyncio
     async def test_execute_and_fetch(self) -> None:
-        """Data inserted via execute is retrievable via fetch_one."""
+        """Data inserted via execute is retrievable via the contract's fetchrow."""
         provider = await self.create_provider()
         async with provider.scoped_context():
             conn = await provider.get_scoped_connection()
@@ -96,11 +96,95 @@ class DatabaseProviderCompliance:
                 "(id INTEGER PRIMARY KEY, val TEXT)"
             )
             await conn.execute("INSERT INTO _compliance_rw(id, val) VALUES(1, 'hello')")
-            row = await conn.fetch_one("SELECT val FROM _compliance_rw WHERE id = 1")
+            row = await conn.fetchrow("SELECT val FROM _compliance_rw WHERE id = 1")
             assert row is not None
             val = row["val"] if hasattr(row, "__getitem__") else row.val
             assert val == "hello"
 
+    # ------------------------------------------------------------------
+    # Provider-level CRUD surface
+    #
+    # The connection-level tests above cover the ``ConnectionProtocol`` path.
+    # The framework's own stores (inbox, delivery state, audit) do not use it:
+    # they provision a table and write rows through the provider-level
+    # ``execute_query``/``execute_insert`` surface. Two contract rules live
+    # only there, and both have been violated in practice by a provider that
+    # passed the connection-level suite:
+    #
+    # 1. a statement that returns no rows (DDL) is a success with no rows, and
+    # 2. JSON-shaped bind values (``dict``/``list``) are encoded before binding.
+    # ------------------------------------------------------------------
+
+    @pytest.mark.asyncio
+    async def test_execute_query_ddl_is_not_a_failure(self) -> None:
+        """A row-less statement through execute_query succeeds with no rows.
+
+        Stores provision their tables this way (``CREATE TABLE IF NOT
+        EXISTS``); an implementation that reports "no result set" as failure
+        makes provisioning look broken even though the table was created.
+        """
+        provider = await self.create_provider()
+        result = await provider.execute_query(
+            "CREATE TABLE IF NOT EXISTS _compliance_ddl (id INTEGER PRIMARY KEY)"
+        )
+        assert result.success is True
+        assert result.rows == []
+
+    @pytest.mark.asyncio
+    async def test_execute_insert_binds_json_shaped_values(self) -> None:
+        """A ``dict``/``list`` column value round-trips as JSON text.
+
+        Relational drivers cannot bind a Python container. Stores that declare
+        JSON columns — an inbox message's ``metadata``, a delivery record's
+        ``message`` — pass containers, so the provider encodes them and the
+        value comes back as the JSON text the schema stores.
+        """
+        provider = await self.create_provider()
+        created = await provider.execute_query(
+            "CREATE TABLE IF NOT EXISTS _compliance_json "
+            "(id TEXT PRIMARY KEY, metadata TEXT NOT NULL DEFAULT '{}')"
+        )
+        assert created.success is True
+
+        inserted = await provider.execute_insert(
+            "_compliance_json",
+            {"id": "row-1", "metadata": {"order_id": "7", "tags": ["a", "b"]}},
+        )
+        assert inserted.success is True, inserted.error_message
+
+        fetched = await provider.execute_query(
+            "SELECT metadata FROM _compliance_json WHERE id = ?", ["row-1"]
+        )
+        assert fetched.success is True, fetched.error_message
+        assert fetched.rows, "the inserted row was not readable"
+        stored = fetched.rows[0]["metadata"]
+        assert stored == '{"order_id":"7","tags":["a","b"]}'
+
+    @pytest.mark.asyncio
+    async def test_execute_update_binds_json_shaped_values(self) -> None:
+        """``execute_update`` encodes JSON-shaped values in its data mapping."""
+        provider = await self.create_provider()
+        await provider.execute_query(
+            "CREATE TABLE IF NOT EXISTS _compliance_json_update "
+            "(id TEXT PRIMARY KEY, metadata TEXT NOT NULL DEFAULT '{}')"
+        )
+        await provider.execute_insert(
+            "_compliance_json_update", {"id": "row-1", "metadata": "{}"}
+        )
+
+        updated = await provider.execute_update(
+            "_compliance_json_update",
+            {"metadata": {"patched": True}},
+            "id = ?",
+            ["row-1"],
+        )
+        assert updated.success is True, updated.error_message
+
+        fetched = await provider.execute_query(
+            "SELECT metadata FROM _compliance_json_update WHERE id = ?", ["row-1"]
+        )
+        assert fetched.rows[0]["metadata"] == '{"patched":true}'
+
     # ------------------------------------------------------------------
     # Transaction rollback
     # ------------------------------------------------------------------
@@ -122,5 +206,5 @@ class DatabaseProviderCompliance:
             )
             await conn.execute("ROLLBACK")
 
-            row = await conn.fetch_one("SELECT val FROM _compliance_tx WHERE id = 42")
+            row = await conn.fetchrow("SELECT val FROM _compliance_tx WHERE id = 42")
             assert row is None

quadkit_testing-0.0.46/src/quadkit/testing/compliance/pool.py

@@ -0,0 +1,165 @@
+"""Contract compliance suite for ``ConnectionPoolProtocol`` implementations.
+
+Subclass :class:`ConnectionPoolCompliance` and implement
+:meth:`create_pool` to verify any connection pool satisfies the
+``ConnectionPoolProtocol`` contract::
+
+    from quadkit.testing.compliance import ConnectionPoolCompliance
+
+    class TestMyPool(ConnectionPoolCompliance):
+        async def create_pool(self):
+            return await MyProvider().get_primary_pool()
+
+The suite owns shutdown: a pool that is never disposed keeps its engine's
+threads alive past the event loop, so the final test in the class closes the
+pool it built and the earlier ones close theirs as they go.
+"""
+
+from __future__ import annotations
+
+from abc import abstractmethod
+from typing import Any
+
+import pytest
+
+__all__ = ["ConnectionPoolCompliance"]
+
+
+class ConnectionPoolCompliance:
+    """Reusable test suite for any ``ConnectionPoolProtocol`` implementation."""
+
+    @abstractmethod
+    async def create_pool(self) -> Any:
+        """Return a ready-to-use pool instance under test."""
+        ...
+
+    # ------------------------------------------------------------------
+    # Lifecycle
+    # ------------------------------------------------------------------
+
+    @pytest.mark.asyncio
+    async def test_initialize_is_idempotent(self) -> None:
+        """initialize() can be called twice without raising."""
+        pool = await self.create_pool()
+        try:
+            await pool.initialize()
+            await pool.initialize()
+        finally:
+            await pool.shutdown()
+
+    @pytest.mark.asyncio
+    async def test_shutdown_is_idempotent(self) -> None:
+        """shutdown() can be called twice — a restart must not crash on it."""
+        pool = await self.create_pool()
+        await pool.initialize()
+        await pool.shutdown()
+        await pool.shutdown()
+
+    @pytest.mark.asyncio
+    async def test_pool_is_usable_after_shutdown(self) -> None:
+        """The pool re-opens connections after shutdown().
+
+        ``shutdown()`` closes holders, not the engine: a process that restarts
+        its pool (a worker recycling between jobs, a graceful reload) must be
+        able to use it again. A pool that only works once would turn a routine
+        restart into an outage.
+        """
+        pool = await self.create_pool()
+        await pool.initialize()
+        await pool.shutdown()
+        await pool.initialize()
+        async with pool.get_connection() as connection:
+            assert connection is not None
+        await pool.shutdown()
+
+    # ------------------------------------------------------------------
+    # Properties and statistics
+    # ------------------------------------------------------------------
+
+    @pytest.mark.asyncio
+    async def test_capacity_properties_are_sane(self) -> None:
+        """Capacity properties are non-negative.
+
+        ``max_connections`` reports ``0`` for a pool with no ceiling — the
+        framework's own ``AsyncEnginePool`` defines it that way, and the
+        SQLite-backed default has exactly that shape. The suite therefore
+        checks the type and sign, not that a bound exists: a bounded-pool
+        assertion here would fail every unbounded deployment, which is a
+        configuration, not a defect.
+        """
+        pool = await self.create_pool()
+        try:
+            assert isinstance(pool.max_connections, int)
+            assert pool.max_connections >= 0
+            assert pool.connection_timeout >= 0
+        finally:
+            await pool.shutdown()
+
+    @pytest.mark.asyncio
+    async def test_pool_stats_returns_dict(self) -> None:
+        """get_pool_stats() returns a mapping of counters."""
+        pool = await self.create_pool()
+        try:
+            await pool.initialize()
+            stats = await pool.get_pool_stats()
+            assert isinstance(stats, dict)
+        finally:
+            await pool.shutdown()
+
+    @pytest.mark.asyncio
+    async def test_query_stats_returns_dict(self) -> None:
+        """get_query_stats() returns a mapping for the requested window."""
+        pool = await self.create_pool()
+        try:
+            await pool.initialize()
+            stats = await pool.get_query_stats(time_range_seconds=60)
+            assert isinstance(stats, dict)
+        finally:
+            await pool.shutdown()
+
+    # ------------------------------------------------------------------
+    # Connections
+    # ------------------------------------------------------------------
+
+    @pytest.mark.asyncio
+    async def test_get_connection_yields_usable_connection(self) -> None:
+        """get_connection() is an async context manager yielding a connection."""
+        pool = await self.create_pool()
+        try:
+            await pool.initialize()
+            async with pool.get_connection() as connection:
+                assert connection is not None
+                # The contract's pool hands out SQLAlchemy-style connections
+                # (``execute``), which is what framework pool consumers drive.
+                await connection.execute(__import__("sqlalchemy").text("SELECT 1"))
+        finally:
+            await pool.shutdown()
+
+    @pytest.mark.asyncio
+    async def test_warm_and_validate(self) -> None:
+        """warm() pre-creates connections and validate_connections() proves one works."""
+        pool = await self.create_pool()
+        try:
+            await pool.initialize()
+            await pool.warm(count=1)
+            assert await pool.validate_connections() == 1
+        finally:
+            await pool.shutdown()
+
+    # ------------------------------------------------------------------
+    # Health
+    # ------------------------------------------------------------------
+
+    @pytest.mark.asyncio
+    async def test_health_check_is_healthy_when_reachable(self) -> None:
+        """health_check() reports a result carrying a status and component."""
+        from quadkit.contracts.core.health import HealthStatus
+
+        pool = await self.create_pool()
+        try:
+            await pool.initialize()
+            result = await pool.health_check(timeout=5.0)
+            assert result.status is HealthStatus.HEALTHY
+            assert result.component
+        finally:
+            await pool.shutdown()

{quadkit_testing-0.0.44 → quadkit_testing-0.0.46}/src/quadkit/testing/fakes/clock.py

@@ -39,6 +39,16 @@ class SystemClock:
         """Return the current Unix timestamp."""
         return time.time()
 
+    def timestamp(self) -> float:
+        """Return the current Unix timestamp.
+
+        Present so :class:`SystemClock` satisfies
+        :class:`~quadkit.contracts.core.clock.ClockProtocol`, which requires
+        ``timestamp()`` alongside ``time()`` and so can back
+        :func:`quadkit.primitives.clock.use` and ``install()``.
+        """
+        return time.time()
+
 
 class FakeClock:
     """Controllable clock for deterministic time-based testing.
@@ -70,6 +80,23 @@ class FakeClock:
         """Return Unix timestamp of the current fake time."""
         return self.now().timestamp()
 
+    def timestamp(self) -> float:
+        """Return Unix timestamp of the current fake time.
+
+        Present so :class:`FakeClock` satisfies
+        :class:`~quadkit.contracts.core.clock.ClockProtocol`, which requires
+        ``timestamp()`` alongside ``time()``. Without it a ``FakeClock`` cannot
+        back the ambient seam: :func:`quadkit.primitives.clock.use` accepts it,
+        but any caller reaching ``clock.timestamp()`` then fails with
+        ``AttributeError``.
+
+        Like :meth:`time`, this derives from :meth:`now`, so constructing a
+        ``FakeClock`` from a *naive* datetime makes both interpret it as local
+        time rather than UTC. Pass an aware datetime — or lift a stored naive-UTC
+        value first — for deterministic results.
+        """
+        return self.now().timestamp()
+
     def advance(self, seconds: float) -> None:
         """Move time forward by *seconds*."""
         self._offset_seconds += seconds