quadkit 0.0.42__tar.gz → 0.0.44__tar.gz

quadkit-0.0.44/.gitignore

@@ -0,0 +1,24 @@
+# Generated public-repository ignore rules.
+# Private monorepo paths are intentionally not referenced here.
+
+__pycache__/
+*.py[cod]
+*.so
+*.egg-info/
+.venv/
+venv/
+.env
+.env.*
+!.env.example
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.coverage
+coverage.xml
+htmlcov/
+build/
+dist/
+*.log
+.DS_Store
+.idea/
+.vscode/

{quadkit-0.0.42 → quadkit-0.0.44}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: quadkit
-Version: 0.0.42
+Version: 0.0.44
 Summary: Async-first DI/IoC framework for Python — core package
 Project-URL: Homepage, https://dbtinoy-.github.io/quadkit/
 Project-URL: Repository, https://github.com/dbtinoy-/quadkit
@@ -251,10 +251,10 @@ report vulnerabilities privately per
 
 ## Stability
 
-Version `0.0.42` in the `0.x` series, released in lockstep with the
+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==0.0.42`) or a tight range (`>=0.0.42,<0.1.0`). Full policy:
+(`quadkit==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/).
 
 ## Links

{quadkit-0.0.42 → quadkit-0.0.44}/README.md

@@ -199,10 +199,10 @@ report vulnerabilities privately per
 
 ## Stability
 
-Version `0.0.42` in the `0.x` series, released in lockstep with the
+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==0.0.42`) or a tight range (`>=0.0.42,<0.1.0`). Full policy:
+(`quadkit==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/).
 
 ## Links

{quadkit-0.0.42 → quadkit-0.0.44}/pyproject.toml

@@ -13,7 +13,6 @@
 #   - Database code          → quadkit-sql
 #   - Auth/JWT/crypto        → quadkit-auth
 #   - HTTP/ASGI/routing      → quadkit-web
-#   - Message queue / email  → quadkit-queue / quadkit-mailer / quadkit-notification
 #   - Any domain-specific feature
 #
 # Core should be lightweight. `pip install quadkit` should take seconds,
@@ -30,7 +29,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "quadkit"
-version = "0.0.42"
+version = "0.0.44"
 description = "Async-first DI/IoC framework for Python — core package"
 readme = "README.md"
 requires-python = ">=3.11"

{quadkit-0.0.42 → quadkit-0.0.44}/src/quadkit/di/container/validation.py

@@ -70,7 +70,7 @@ class ContainerValidator:
                         # not something the user can fix with annotations.
                         logger.warning(
                             "validate.scope_check_unhashable_hint",
-                            service=service_name,
+                            service_type=service_name,
                             error=str(e),
                         )
                     else:
@@ -85,13 +85,13 @@ class ContainerValidator:
                 except AttributeError as e:
                     logger.warning(
                         "validate.scope_check_attribute_error",
-                        service=service_name,
+                        service_type=service_name,
                         error=str(e),
                     )
                 except (KeyError, ValueError) as e:
                     logger.warning(
                         "validate.scope_check_resolution_error",
-                        service=service_name,
+                        service_type=service_name,
                         error=str(e),
                     )
 
@@ -123,7 +123,7 @@ class ContainerValidator:
             except (AttributeError, TypeError, KeyError, ValueError) as e:
                 logger.debug(
                     "validate_no_orphans.dep_resolution_error",
-                    service=getattr(service_type, "__name__", str(service_type)),
+                    service_type=getattr(service_type, "__name__", str(service_type)),
                     error=str(e),
                 )
                 continue

{quadkit-0.0.42 → quadkit-0.0.44}/src/quadkit/di/resolution/resolver.py

@@ -79,7 +79,7 @@ class ServiceResolver:
         if self._debug_resolution:
             logger.debug(
                 "di.resolution.resolved",
-                service=getattr(service_type, "__name__", repr(service_type)),
+                service_type=getattr(service_type, "__name__", repr(service_type)),
             )
         return instance
 

{quadkit-0.0.42 → quadkit-0.0.44}/src/quadkit/identity/ambient.py

@@ -7,7 +7,8 @@ Example:
     from quadkit import identity
 
     id = identity.generate_for("user")      # ULID/UUID based on config
-    uuid = identity.new_uuid()             # Random UUID4
+    opaque = identity.new_uuid()            # the configured strategy, not
+                                            # necessarily a UUID — see below
 
 For tests:
     from quadkit import identity
@@ -78,10 +79,26 @@ def generate_for(entity_type: str) -> str:
 
 
 def new_uuid() -> str:
-    """Generate a random UUID4.
+    """Generate an id with the ambient generator, whatever it is.
+
+    **The name is narrower than the behaviour.** This delegates to the
+    installed ``IdGeneratorProtocol``, so the result follows
+    ``IdentityConfig.strategy``: UUID4 by default, but a 36-char UUID7, a
+    26-char Crockford base32 ULID, or a prefixed ULID (``usr_01H…``) when
+    the application configures one — and whatever a test installs through
+    ``use()``.
+
+    Two consequences worth stating, because the name hides both:
+
+    - **Shape is not guaranteed.** Do not feed the result to a ``UUID``
+      column or ``uuid.UUID()`` unless the strategy is pinned to UUID4/7.
+    - **Randomness is not guaranteed.** UUID7 and ULID are time-ordered:
+      the leading bits are a millisecond timestamp. For a value that must
+      be unguessable — a reset token, a session id, a webhook secret — use
+      ``secrets.token_urlsafe()``, not this.
 
     Returns:
-        A random UUID4 string.
+        An id string from the ambient generator.
     """
     return _ambient.get().generate()
 

{quadkit-0.0.42 → quadkit-0.0.44}/src/quadkit/logging/README.md

@@ -43,15 +43,15 @@ Each log line is a single JSON object emitted by
 {
   "timestamp": "2026-08-19 10:15:30",
   "level": "INFO",
-  "logger": "quadkit.web.controller",
   "event": "user_created",
   "service": "my-app",
   "trace_id": "4bf92f3577b34da6a3ce929d0e0e4736",
   "span_id": "00f067aa0ba902b7",
-  "filename": "controller.py",
-  "lineno": 42,
-  "module": "controller",
-  "func_name": "create_user",
+  "_logger_name": "quadkit.web.controller",
+  "_filename": "controller.py",
+  "_lineno": 42,
+  "_module": "controller",
+  "_func_name": "create_user",
   "user_id": "usr_123"
 }
 ```
@@ -60,16 +60,44 @@ Each log line is a single JSON object emitted by
 |-------------|---------------------------------------------------------------|
 | `timestamp` | `TimeStamper(fmt="%Y-%m-%d %H:%M:%S")`                       |
 | `level`     | `structlog.stdlib.add_log_level`                             |
-| `logger`    | `_add_logger_name` — auto-prefixed with `quadkit.`          |
 | `event`     | Message passed to `logger.info("...")`                       |
 | `service`   | Injected by `configure_logging(service_name=...)` / `Application.name`; overridable via `bind(service=...)` |
 | `trace_id` / `span_id` | `_otel_processor` — only when an OTEL trace context is active |
-| `filename` / `lineno` / `module` / `func_name` | `CallsiteParameterAdder` |
+| `_logger_name` | `get_logger()` / `_add_logger_name` — auto-prefixed with `quadkit.` |
+| `_filename` / `_lineno` / `_module` / `_func_name` | `CallsiteParameterAdder`, wrapped by `_NamespacedCallsiteAdder` |
 | `exception` | Formatted traceback, present on `logger.exception(...)` / `exc_info=True` |
 
 Key-value arguments passed to a log call are appended verbatim as top-level
 fields (`logger.info("user_created", user_id=usr.id)` → `"user_id"`).
 
+## Field names: what the envelope owns, and what you own
+
+Two namespaces, so a caller's field and the pipeline's metadata can never
+be the same key:
+
+- **`_`-prefixed keys belong to the framework** — `_logger_name`,
+  `_filename`, `_lineno`, `_module`, `_func_name`. Do not pass them.
+- **Every other plain name belongs to the caller.** `module=`, `filename=`,
+  `name=`, `msg=` are ordinary fields; `logger.info("module_booted",
+  module=self.name)` renders the value you passed.
+- **Five envelope names are reserved**: `event`, `level`, `timestamp`,
+  `service` and `exception`. `service` is deliberately overridable via
+  `bind(service=...)`; the other four are not yours to set.
+  `dev/checks/reserved_log_fields.py` fails the build on a call site that
+  passes one.
+
+`event` is the sharp one: it is structlog's parameter for the *message*, so
+`logger.warning("emit_failed", event=type(evt).__name__)` raises
+`TypeError` — inside the `except` block that was reporting the failure.
+Because a diagnostic must never raise, `_NamedLogger` moves such a field to
+`event_field` rather than letting the call blow up; the gate is what makes
+you rename it properly (`event_type`, `webhook_event`).
+
+Callsite metadata reports *your* frame, not the framework's: the adder is
+configured with `additional_ignores=["quadkit.logging"]`, without which
+`_NamedLogger.info` in `logging/factory.py` is the nearest non-structlog
+frame and every line in the process is stamped with it.
+
 ## Behavior guarantees
 
 - **Levels**: `DEBUG < INFO < WARNING < ERROR < CRITICAL`. A global
@@ -94,5 +122,5 @@ fields (`logger.info("user_created", user_id=usr.id)` → `"user_id"`).
 - Never `print()`; never log secret material (redaction is a safety net,
   not a substitute for not logging secrets).
 - For error tracking, forward `level >= ERROR` events with `event`,
-  `exception`, `logger`, and `trace_id` fields — correlation IDs make
+  `exception`, `_logger_name`, and `trace_id` fields — correlation IDs make
   distributed debugging possible.

{quadkit-0.0.42 → quadkit-0.0.44}/src/quadkit/logging/configurator.py

@@ -21,6 +21,7 @@ from quadkit.logging.processors import (
     _add_logger_name,
     _context_processor,
     _level_filter_processor,
+    _NamespacedCallsiteAdder,
     _otel_processor,
     _redact_processor,
     _sampling_processor,
@@ -55,7 +56,7 @@ def configure_logging(
         service_name: Application name injected into log context.
         levels: Per-logger level overrides. Keys are logger name prefixes,
             values are level strings.  Example:
-            ``{"quadkit.di": "DEBUG", "quadkit.resilience": "WARNING"}``.
+            ``{"quadkit.di": "DEBUG", "the optional provider module": "WARNING"}``.
         sampling_enabled: Enable deterministic log sampling.
         sampling_default_rate: Default sample rate (1.0 = log everything,
             0.1 = log ~10%).
@@ -101,13 +102,16 @@ def configure_logging(
         _service_processor,
         _otel_processor,
         _redact_processor,
-        structlog.processors.CallsiteParameterAdder(
-            {
-                structlog.processors.CallsiteParameter.FILENAME,
-                structlog.processors.CallsiteParameter.LINENO,
-                structlog.processors.CallsiteParameter.MODULE,
-                structlog.processors.CallsiteParameter.FUNC_NAME,
-            },
+        _NamespacedCallsiteAdder(
+            structlog.processors.CallsiteParameterAdder(
+                {
+                    structlog.processors.CallsiteParameter.FILENAME,
+                    structlog.processors.CallsiteParameter.LINENO,
+                    structlog.processors.CallsiteParameter.MODULE,
+                    structlog.processors.CallsiteParameter.FUNC_NAME,
+                },
+                additional_ignores=["quadkit.logging"],
+            ),
         ),
         structlog.processors.StackInfoRenderer(),
     ]

{quadkit-0.0.42 → quadkit-0.0.44}/src/quadkit/logging/factory.py

@@ -3,6 +3,14 @@
 Provides ``get_logger()`` for obtaining structlog bound-loggers with a
 ``.name`` attribute, and ``LoggerFactoryImpl`` which implements the
 ``LoggerFactoryProtocol`` protocol.
+
+A logging call must never raise.  structlog names the message parameter
+``event``, so ``logger.info("task_finished", event=evt.name)`` is a
+``TypeError`` — raised from inside the ``except`` block that was trying to
+report a failure.  ``_deconflict()`` moves such a field to ``event_field``
+instead of letting the diagnostic take down the path it was diagnosing;
+``dev/checks/reserved_log_fields.py`` fails the build on the call site so
+the remap stays a safety net rather than an interface.
 """
 
 from __future__ import annotations
@@ -16,6 +24,25 @@ if TYPE_CHECKING:
     from quadkit.logging.config.models import LoggingConfig
 
 
+def _deconflict(kwargs: dict[str, Any]) -> dict[str, Any]:
+    """Move a caller field named ``event`` out of structlog's way.
+
+    ``event`` is structlog's parameter for the log message, so passing it as
+    a field raises ``TypeError``.  The field is preserved under
+    ``event_field`` (``event_field_``, ``event_field__``, … if the caller
+    already used that name) rather than dropped: a log call is a diagnostic
+    and must not raise.
+    """
+    if "event" not in kwargs:
+        return kwargs
+    safe = dict(kwargs)
+    key = "event_field"
+    while key in safe:
+        key += "_"
+    safe[key] = safe.pop("event")
+    return safe
+
+
 class _NamedLogger:
     """Thin wrapper that adds ``.name`` to a structlog bound logger.
 
@@ -34,26 +61,31 @@ class _NamedLogger:
     # These exist so ``hasattr(_NamedLogger, 'debug')`` etc. return True for
     # the DI validator.  At runtime the call is forwarded via __getattr__.
 
-    def debug(self, msg: str, *args: Any, **kwargs: Any) -> None:
-        self._inner.debug(msg, *args, **kwargs)
+    # ``msg`` is positional-only: without the ``/`` this wrapper would add a
+    # reserved word of its own making, and ``logger.info("x", msg=body)``
+    # would fail with "got multiple values for argument 'msg'" even though
+    # the underlying structlog logger has no such parameter.
+
+    def debug(self, msg: str, /, *args: Any, **kwargs: Any) -> None:
+        self._inner.debug(msg, *args, **_deconflict(kwargs))
 
-    def info(self, msg: str, *args: Any, **kwargs: Any) -> None:
-        self._inner.info(msg, *args, **kwargs)
+    def info(self, msg: str, /, *args: Any, **kwargs: Any) -> None:
+        self._inner.info(msg, *args, **_deconflict(kwargs))
 
-    def warning(self, msg: str, *args: Any, **kwargs: Any) -> None:
-        self._inner.warning(msg, *args, **kwargs)
+    def warning(self, msg: str, /, *args: Any, **kwargs: Any) -> None:
+        self._inner.warning(msg, *args, **_deconflict(kwargs))
 
-    def error(self, msg: str, *args: Any, **kwargs: Any) -> None:
-        self._inner.error(msg, *args, **kwargs)
+    def error(self, msg: str, /, *args: Any, **kwargs: Any) -> None:
+        self._inner.error(msg, *args, **_deconflict(kwargs))
 
-    def critical(self, msg: str, *args: Any, **kwargs: Any) -> None:
-        self._inner.critical(msg, *args, **kwargs)
+    def critical(self, msg: str, /, *args: Any, **kwargs: Any) -> None:
+        self._inner.critical(msg, *args, **_deconflict(kwargs))
 
-    def exception(self, msg: str, *args: Any, **kwargs: Any) -> None:
-        self._inner.exception(msg, *args, **kwargs)
+    def exception(self, msg: str, /, *args: Any, **kwargs: Any) -> None:
+        self._inner.exception(msg, *args, **_deconflict(kwargs))
 
     def bind(self, **kwargs: Any) -> _NamedLogger:
-        result = self._inner.bind(**kwargs)
+        result = self._inner.bind(**_deconflict(kwargs))
         return self if result is self._inner else _NamedLogger(result, self.name)
 
     def unbind(self, *keys: str) -> _NamedLogger:
@@ -122,18 +154,21 @@ class LoggerFactoryImpl:
         self._config = config
 
     def get_logger(self, name: str | None = None) -> LoggerProtocol:
-        """Get or create a logger, optionally binding the service name."""
-        logger = get_logger(name)
-        if name:
-            try:
-                return cast("LoggerProtocol", logger.bind(service=name))
-            except (AttributeError, TypeError):
-                return cast("LoggerProtocol", logger)
-        return cast("LoggerProtocol", logger)
+        """Get or create a logger.
+
+        This used to ``bind(service=name)``.  ``service`` is the envelope
+        field identifying the *application* (set by ``configure_logging()``
+        and used for log routing), and ``_service_processor`` yields to a
+        bound value — so every DI-resolved logger relabelled the service as
+        whichever component had asked for it.  The logger name already
+        travels in ``_logger_name``.
+        """
+        return cast("LoggerProtocol", get_logger(name))
 
 
 __all__ = [
     "LoggerFactoryImpl",
     "_NamedLogger",
+    "_deconflict",
     "get_logger",
 ]

{quadkit-0.0.42 → quadkit-0.0.44}/src/quadkit/logging/processors.py

@@ -108,6 +108,52 @@ def _otel_processor(
     return event_dict
 
 
+class _NamespacedCallsiteAdder:
+    """Run structlog's ``CallsiteParameterAdder`` in the ``_`` namespace.
+
+    Two problems with using the adder directly:
+
+    1. It writes ``filename``, ``lineno``, ``module`` and ``func_name`` —
+       ordinary domain words.  ``logger.info("module_booted",
+       module=self.name)`` is a natural call (this repo had 111 of them) and
+       the adder silently overwrote every one with the emitting *source*
+       file's module.  Framework metadata therefore lives under ``_``-
+       prefixed keys, the convention ``_logger_name`` already follows, and
+       the plain names belong to the caller.
+    2. Left to itself the adder reports ``_NamedLogger.info`` in
+       ``logging/factory.py`` as the callsite of every log line in the
+       process, because that wrapper is the nearest non-structlog frame.
+       ``additional_ignores`` skips the framework's own logging package so
+       the real caller is reported.
+
+    The inner adder is run against a scratch dict so it cannot clobber a
+    caller field on its way past.
+    """
+
+    __slots__ = ("_inner",)
+
+    #: Keys structlog's adder may consult on the stdlib-bridge path.
+    _PASSTHROUGH = ("_record", "_from_structlog")
+
+    def __init__(self, inner: Any) -> None:
+        self._inner = inner
+
+    def __call__(
+        self,
+        logger: Any,
+        method_name: str,
+        event_dict: dict[str, Any],
+    ) -> dict[str, Any]:
+        scratch: dict[str, Any] = {
+            key: event_dict[key] for key in self._PASSTHROUGH if key in event_dict
+        }
+        for key, value in self._inner(logger, method_name, scratch).items():
+            if key in self._PASSTHROUGH:
+                continue
+            event_dict.setdefault(f"_{key}", value)
+        return event_dict
+
+
 def _add_logger_name(
     logger: Any,
     method_name: str,
@@ -116,12 +162,14 @@ def _add_logger_name(
     """Safe replacement for structlog.stdlib.add_logger_name.
 
     Handles loggers that don't have a ``.name`` attribute (like
-    ``PrintLogger``).
+    ``PrintLogger``).  Writes ``_logger_name`` — the key ``get_logger()``
+    already binds, and the framework namespace — not ``logger``, which a
+    caller may legitimately want as a field of their own.
     """
-    if "logger" not in event_dict:
+    if "_logger_name" not in event_dict:
         name = getattr(logger, "name", None)
         if name:
-            event_dict["logger"] = name
+            event_dict["_logger_name"] = name
     return event_dict
 
 
@@ -232,6 +280,7 @@ def _sampling_processor(
 __all__ = [
     "LEVEL_NAME_TO_INT",
     "_LoggingState",
+    "_NamespacedCallsiteAdder",
     "_add_logger_name",
     "_context_processor",
     "_level_filter_processor",

{quadkit-0.0.42 → quadkit-0.0.44}/src/quadkit/middleware/builtins/resilience.py

@@ -23,7 +23,7 @@ logger = get_logger(__name__)
 class RetryMiddleware:
     """Middleware that retries the downstream handler on transient failures.
 
-    Delegates to :func:`quadkit.resilience.retry` for backoff logic.
+    Delegates to :func:`the optional provider module` for backoff logic.
 
     Args:
         catch: Exception types considered retryable. Must be explicitly provided.

{quadkit-0.0.42 → quadkit-0.0.44}/src/quadkit/observability/di/sub_providers/observability.py

@@ -38,7 +38,7 @@ class ObservabilityProvider(Provider):
         on module composition order — and in nested module graphs this
         provider lands *after* ``MonitorProvider`` and suppresses the concrete
         collector. Guard each token, the same pattern the other fallback
-        sites use (``quadkit-auth``, ``quadkit-cache``, ``quadkit-ai-relay``),
+        sites use (``quadkit-auth``, ``quadkit-cache``, ``the optional provider``),
         so whichever real implementation registered first survives.
         """
         collector = NoOpMetricsCollector()

{quadkit-0.0.42 → quadkit-0.0.44}/src/quadkit/primitives/pipeline.py

@@ -2,7 +2,7 @@
 
 These primitives live in the core ``quadkit`` package so that any extension
 package can build pipeline-compatible steps without depending on
-``quadkit-workflow``.
+``the optional provider``.
 """
 
 from __future__ import annotations

{quadkit-0.0.42 → quadkit-0.0.44}/src/quadkit/security/hashing/ambient.py

@@ -65,13 +65,28 @@ def install(implementation: HasherProtocol) -> None:
 
 
 def hash_hex(data: str | bytes) -> str:
-    """Hash data and return hex digest.
+    """Hash data with the ambient hasher and return a hex digest.
+
+    **The algorithm is a process-wide config value, not a property of this
+    call.** ``HashingConfig.default_hasher`` selects sha256 (the default) or
+    blake2b, and ``use()`` swaps it again in tests — with no signal at the
+    call site and no algorithm marker in the returned string.
+
+    That makes this the right tool for an **ephemeral** digest (a cache key,
+    a content fingerprint compared within one process, a change detector)
+    and the wrong one for a **persisted** digest. A stored value is silently
+    coupled to the config that produced it: flip ``default_hasher`` and
+    every row written under the old algorithm stops matching, which for a
+    lookup key like a hashed API token means every credential fails to
+    resolve at once. Persist digests with an explicitly constructed hasher
+    (``Sha256Hasher().digest(...)``), or store the algorithm alongside the
+    digest so the value is self-describing.
 
     Args:
         data: String or bytes to hash.
 
     Returns:
-        Hex-encoded digest string.
+        Hex-encoded digest string from the ambient hasher.
     """
     return _ambient.get().digest(data)
 

{quadkit-0.0.42 → quadkit-0.0.44}/tests/unit/security/test_hashing.py

@@ -9,7 +9,8 @@ import pytest
 from quadkit.contracts.security import HasherProtocol, KeyDerivationProtocol
 from quadkit.di.container import Container
 from quadkit.security.config import HashingConfig, SecurityConfig
-from quadkit.security.hashing import Blake2bHasher, PBKDF2KDF, Sha256Hasher
+from quadkit.security.hashing import PBKDF2KDF, Blake2bHasher, Sha256Hasher
+from quadkit.security.hashing import ambient as hashing
 from quadkit.security.provider import SecurityProvider
 
 
@@ -95,3 +96,36 @@ class TestSecurityProviderHashingDefaults:
 
         assert isinstance(hasher, Sha256Hasher)
         assert isinstance(kdf, PBKDF2KDF)
+
+
+class TestAmbientHasherIsNotAPersistenceFormat:
+    """The ambient digest is a process-wide config value, not a stable format."""
+
+    def test_swapping_the_hasher_invalidates_every_stored_digest(self) -> None:
+        """A persisted `hash_hex` value is coupled to `default_hasher`.
+
+        Nothing at the call site says so, and the digest carries no
+        algorithm marker, so the coupling is invisible until someone flips
+        `HashingConfig.default_hasher` — at which point a stored lookup key
+        (a hashed API token, say) stops matching for every row at once. The
+        docstring now says this; the test keeps it true.
+        """
+        token = "sk-live-abc123"
+
+        stored = hashing.hash_hex(token)
+
+        with hashing.use(Blake2bHasher()):
+            assert hashing.hash_hex(token) != stored
+            assert hashing.verify_hex(token, stored) is False
+
+        assert hashing.verify_hex(token, stored) is True
+
+    def test_an_explicit_hasher_is_immune_to_the_ambient_swap(self) -> None:
+        """The documented escape hatch for values that outlive the process."""
+        pinned = Sha256Hasher()
+        token = "sk-live-abc123"
+
+        stored = pinned.digest(token)
+
+        with hashing.use(Blake2bHasher()):
+            assert pinned.digest(token) == stored

{quadkit-0.0.42 → quadkit-0.0.44}/tests/unit/test_identity_generators_and_ambient.py

@@ -6,6 +6,8 @@ from __future__ import annotations
 import time
 from uuid import UUID
 
+import pytest
+
 from quadkit.contracts.core.identity import IdStrategy
 from quadkit.identity import ambient
 from quadkit.identity.constants import DEFAULT_PREFIX_SEPARATOR, DEFAULT_ULID_LENGTH
@@ -135,3 +137,47 @@ def test_ambient_use_context_stacks() -> None:
 
     # Restored to the original after the outer block exits.
     assert not ambient.generate_for("X").startswith(("outer-", "inner-"))
+
+
+# ── What the name promises vs what the call returns ───────────────────────
+
+
+def test_new_uuid_is_whatever_the_ambient_generator_is() -> None:
+    """``new_uuid()`` is not a UUID unless the configured strategy is one.
+
+    The name says UUID4 and the docstring used to agree with it, but the
+    call delegates to the installed ``IdGeneratorProtocol``. An application
+    that configures ULID for database locality gets a 26-character Crockford
+    base32 string out of a function named ``new_uuid`` — so a ``UUID``
+    column or a ``uuid.UUID()`` parse on the far end fails at runtime, not
+    at boot.
+    """
+    with ambient.use(UlidGenerator()):
+        value = ambient.new_uuid()
+
+    assert len(value) == DEFAULT_ULID_LENGTH
+    with pytest.raises(ValueError, match=r"badly formed|invalid"):
+        UUID(value)
+
+
+def test_new_uuid_is_not_guaranteed_unpredictable() -> None:
+    """Time-ordered strategies leak their timestamp into the leading bits.
+
+    ``SECURITY.md`` used to describe this call as "uuid4() (random)" under
+    the heading *UUID predictability*, which is exactly the claim a reader
+    checks before using an id as a secret. Two ULIDs minted a moment apart
+    share their timestamp prefix and sort in creation order.
+    """
+    with ambient.use(UlidGenerator()):
+        first = ambient.new_uuid()
+        second = ambient.new_uuid()
+        time.sleep(0.002)
+        later = ambient.new_uuid()
+
+    # Same millisecond: identical timestamp prefix, only the random tail
+    # differs (the tail is not monotonic within a tick, so no ordering is
+    # asserted there).
+    assert first[:6] == second[:6]
+    # Across a tick: the value sorts by creation time, which is the property
+    # that makes it guessable.
+    assert later > first