dialcache 0.25.0__py3-none-any.whl

dialcache/clock.py

@@ -0,0 +1,53 @@
+"""Separate wall timestamps, monotonic elapsed time, and timer delivery."""
+
+from __future__ import annotations
+
+import asyncio
+import time
+from collections.abc import Callable
+from typing import Protocol
+
+
+class TimerHandle(Protocol):
+    def cancel(self) -> None: ...
+
+
+class Clock(Protocol):
+    """Injectable clocks and timers for deterministic application tests.
+
+    Wall time stamps Redis frames. Monotonic time governs local expiry and
+    deadlines. A controlled clock may advance elapsed time without delivering
+    timers, so callers also check elapsed time when operations settle.
+    """
+
+    def wall_ms(self) -> int | float: ...
+
+    def monotonic_ms(self) -> int | float: ...
+
+    def call_later(self, milliseconds: float, callback: Callable[[], None]) -> TimerHandle: ...
+
+
+class SystemClock:
+    """System wall time and the process-wide monotonic millisecond grid."""
+
+    def wall_ms(self) -> int:
+        return time.time_ns() // 1_000_000
+
+    def monotonic_ms(self) -> float:
+        return time.monotonic_ns() / 1_000_000
+
+    def call_later(self, milliseconds: float, callback: Callable[[], None]) -> TimerHandle:
+        return asyncio.get_running_loop().call_later(milliseconds / 1_000, callback)
+
+    async def sleep_ms(self, milliseconds: float) -> None:
+        future: asyncio.Future[None] = asyncio.get_running_loop().create_future()
+
+        def wake() -> None:
+            if not future.done():
+                future.set_result(None)
+
+        timer = self.call_later(milliseconds, wake)
+        try:
+            await future
+        finally:
+            timer.cancel()

dialcache/config.py

@@ -0,0 +1,296 @@
+"""Sparse runtime policy and the portable DialCache configuration domains."""
+
+from __future__ import annotations
+
+import math
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from enum import StrEnum
+from types import MappingProxyType
+from typing import Any
+
+from .errors import ConfigError
+
+MAX_SAFE_INTEGER = 9_007_199_254_740_991
+MAX_CACHE_TTL_SEC = 31_536_000
+MAX_SUPPORTED_DURATION_MS = MAX_CACHE_TTL_SEC * 1_000
+MAX_TRACKED_REDIS_VALUE_TTL_MS = 3_600_000
+MAX_TIMER_DELAY_MS = 2_147_483_647
+DEFAULT_REMOTE_READ_TIMEOUT_MS = 50
+DEFAULT_FALLBACK_TIMEOUT_MS = 60_000
+
+
+class _Unset:
+    __slots__ = ()
+
+    def __repr__(self) -> str:
+        return "UNSET"
+
+
+UNSET = _Unset()
+
+
+class CacheLayer(StrEnum):
+    LOCAL = "local"
+    REMOTE = "remote"
+
+
+def is_safe_integer(value: Any) -> bool:
+    return (
+        not isinstance(value, bool)
+        and isinstance(value, (int, float))
+        and abs(value) <= MAX_SAFE_INTEGER
+        and math.isfinite(value)
+        and value == int(value)
+    )
+
+
+def is_supported_cache_ttl_sec(value: Any) -> bool:
+    return is_safe_integer(value) and 0 < value <= MAX_CACHE_TTL_SEC
+
+
+def cache_ttl_sec_to_ms(value: Any) -> int:
+    if not is_supported_cache_ttl_sec(value):
+        raise ConfigError(f"cache TTL must be an integer from 1 through {MAX_CACHE_TTL_SEC} seconds")
+    return int(value) * 1_000
+
+
+def validate_deadline_ms(value: Any, name: str = "deadline") -> int:
+    if not is_safe_integer(value) or value <= 0 or value > MAX_TIMER_DELAY_MS:
+        raise ConfigError(f"{name} must be an integer from 1 through {MAX_TIMER_DELAY_MS} milliseconds")
+    return int(value)
+
+
+def _layer_map(value: Any, name: str) -> Mapping[str, Any]:
+    if value is UNSET:
+        return MappingProxyType({})
+    if not isinstance(value, Mapping):
+        raise ConfigError(f"{name} must be a layer map")
+    # Only the supported layers participate in the portable policy.
+    return MappingProxyType({layer: value[layer] for layer in ("local", "remote") if layer in value})
+
+
+def _shadow_map(value: Any) -> Any:
+    if value is UNSET:
+        return UNSET
+    if not isinstance(value, Mapping):
+        raise ConfigError("shadow must be an object")
+    result: dict[str, Any] = {}
+    if "ramp" in value:
+        result["ramp"] = value["ramp"]
+    if "log_mismatches" in value:
+        result["log_mismatches"] = value["log_mismatches"]
+    elif "logMismatches" in value:
+        result["log_mismatches"] = value["logMismatches"]
+    return MappingProxyType(result)
+
+
+@dataclass(frozen=True)
+class Policy:
+    """Per-use-case policy; omitted fields inherit in runtime overlays.
+
+    ``None`` is a supplied value, never an omitted leaf. Constructing a Policy
+    validates container shapes, boolean switches and read deadlines. TTL,
+    ramp and optional shadow/recovery leaves remain available for narrow
+    runtime fail-open resolution. Static operation setup uses
+    :func:`validate_static_policy` to reject invalid defaults before calls.
+    """
+
+    ttl_sec: Mapping[str, Any] = field(default_factory=dict)
+    ramp: Mapping[str, Any] = field(default_factory=dict)
+    request_local: Any = UNSET
+    coalesce: Any = UNSET
+    stale_on_error_max_age_sec: Any = UNSET
+    remote_read_timeout_ms: Any = UNSET
+    shadow: Any = UNSET
+
+    def __post_init__(self) -> None:
+        object.__setattr__(self, "ttl_sec", _layer_map(self.ttl_sec, "ttl_sec"))
+        object.__setattr__(self, "ramp", _layer_map(self.ramp, "ramp"))
+        object.__setattr__(self, "shadow", _shadow_map(self.shadow))
+        for name in ("request_local", "coalesce"):
+            value = getattr(self, name)
+            if value is not UNSET and not isinstance(value, bool):
+                raise ConfigError(f"{name} must be a boolean")
+        if self.remote_read_timeout_ms is not UNSET:
+            validate_deadline_ms(self.remote_read_timeout_ms, "remote_read_timeout_ms")
+
+    @classmethod
+    def enabled(cls, ttl_sec: int) -> Policy:
+        return cls(ttl_sec={"local": ttl_sec, "remote": ttl_sec}, ramp={"local": 100, "remote": 100})
+
+    @classmethod
+    def disabled(cls) -> Policy:
+        """Disable every inherited serving, recovery and shadow path."""
+        return cls(
+            request_local=False,
+            stale_on_error_max_age_sec=0,
+            shadow={"ramp": 0, "log_mismatches": False},
+            ramp={"local": 0, "remote": 0},
+        )
+
+    @classmethod
+    def from_mapping(cls, value: Mapping[str, Any]) -> Policy:
+        result = normalize_policy(value)
+        assert result is not None
+        return result
+
+
+KeyConfig = Policy
+DialCacheKeyConfig = Policy
+PolicyInput = Policy | Mapping[str, Any] | None
+
+_ALIASES = {
+    "ttl_sec": "ttlSec",
+    "ramp": "ramp",
+    "request_local": "requestLocal",
+    "coalesce": "coalesce",
+    "stale_on_error_max_age_sec": "staleOnErrorMaxAgeSec",
+    "remote_read_timeout_ms": "remoteReadTimeoutMs",
+    "shadow": "shadow",
+}
+
+
+def normalize_policy(value: PolicyInput) -> Policy | None:
+    if value is None:
+        return None
+    if isinstance(value, Policy):
+        return value
+    if not isinstance(value, Mapping):
+        raise ConfigError("DialCache policy must be an object")
+    if "shadowRamp" in value or "shadow_ramp" in value:
+        raise ConfigError('shadow_ramp was replaced by "shadow.ramp"')
+    supplied: dict[str, Any] = {}
+    for native, portable in _ALIASES.items():
+        if native in value:
+            supplied[native] = value[native]
+        elif portable in value:
+            supplied[native] = value[portable]
+    return Policy(**supplied)
+
+
+def merge_policy(defaults: PolicyInput, runtime: PolicyInput) -> Policy | None:
+    """Snapshot a sparse provider reply over the operation's static policy.
+
+    A whole-provider ``None`` inherits the static policy. Invalid explicitly
+    supplied leaves stay supplied, including ``None``, so runtime resolution
+    cannot accidentally enable an inherited layer.
+    """
+    base = normalize_policy(defaults)
+    overlay = normalize_policy(runtime)
+    if overlay is None:
+        return base
+    if base is None:
+        return overlay
+    values: dict[str, Any] = {
+        "ttl_sec": {**base.ttl_sec, **overlay.ttl_sec},
+        "ramp": {**base.ramp, **overlay.ramp},
+    }
+    for name in ("request_local", "coalesce", "stale_on_error_max_age_sec", "remote_read_timeout_ms"):
+        value = getattr(overlay, name)
+        values[name] = getattr(base, name) if value is UNSET else value
+    if base.shadow is UNSET and overlay.shadow is UNSET:
+        values["shadow"] = UNSET
+    else:
+        values["shadow"] = {
+            **({} if base.shadow is UNSET else base.shadow),
+            **({} if overlay.shadow is UNSET else overlay.shadow),
+        }
+    return Policy(**values)
+
+
+def _valid_ramp(value: Any) -> bool:
+    return (
+        not isinstance(value, bool)
+        and isinstance(value, (int, float))
+        and 0 <= value <= 100
+        and math.isfinite(value)
+    )
+
+
+def validate_static_policy(value: PolicyInput) -> Policy | None:
+    """Validate and capture operation defaults before registering the use case."""
+    policy = normalize_policy(value)
+    if policy is None:
+        return None
+    for layer in ("local", "remote"):
+        if layer in policy.ttl_sec and not is_supported_cache_ttl_sec(policy.ttl_sec[layer]):
+            raise ConfigError(f"ttl_sec.{layer} must be an integer from 1 through {MAX_CACHE_TTL_SEC}")
+        if layer in policy.ramp and not _valid_ramp(policy.ramp[layer]):
+            raise ConfigError(f"ramp.{layer} must be a finite number from 0 through 100")
+    age = policy.stale_on_error_max_age_sec
+    if age is not UNSET:
+        if not is_safe_integer(age) or age < 0 or age > MAX_CACHE_TTL_SEC:
+            raise ConfigError("stale_on_error_max_age_sec must be a supported nonnegative integer")
+        if age > 0 and ("remote" not in policy.ttl_sec or age <= policy.ttl_sec["remote"]):
+            raise ConfigError("stale_on_error_max_age_sec requires a smaller positive remote TTL")
+    if policy.shadow is not UNSET:
+        if "ramp" in policy.shadow and not _valid_ramp(policy.shadow["ramp"]):
+            raise ConfigError("shadow.ramp must be a finite number from 0 through 100")
+        if "log_mismatches" in policy.shadow and not isinstance(policy.shadow["log_mismatches"], bool):
+            raise ConfigError("shadow.log_mismatches must be a boolean")
+    return policy
+
+
+def deterministic_ramp_sample(urn: str, layer: str) -> float:
+    """Stable FNV-1a over UTF-16 code units, identical across DialCache ports."""
+    encoded = f"{urn}:{layer}".encode("utf-16-le", errors="surrogatepass")
+    value = 0x811C9DC5
+    for index in range(0, len(encoded), 2):
+        value ^= encoded[index] | (encoded[index + 1] << 8)
+        value = (value * 0x01000193) & 0xFFFFFFFF
+    return value / 0x1_0000_0000 * 100
+
+
+def deterministic_shadow_ramp_sample(urn: str) -> float:
+    return deterministic_ramp_sample(urn, "shadow")
+
+
+@dataclass(frozen=True)
+class LayerResolution:
+    status: str
+    reason: str | None = None
+    ttl_sec: int | None = None
+    ramp: float | None = None
+    stale_on_error_max_age_sec: int | None = None
+    stale_on_error_config_error: bool = False
+
+    @property
+    def enabled(self) -> bool:
+        return self.status == "enabled"
+
+
+def resolve_layer(policy: Policy | None, urn: str, layer: str | CacheLayer) -> LayerResolution:
+    """Resolve one serving layer; malformed leaves disable only that layer."""
+    if layer not in ("local", "remote"):
+        raise ConfigError(f"Unknown cache layer: {layer}")
+    age = UNSET if policy is None else policy.stale_on_error_max_age_sec
+    recovery_off = age is UNSET or (is_safe_integer(age) and age == 0)
+    if policy is None or layer not in policy.ttl_sec:
+        return LayerResolution(
+            "disabled",
+            "policy_disabled",
+            stale_on_error_config_error=layer == "remote" and not recovery_off,
+        )
+    ttl = policy.ttl_sec[layer]
+    if not is_supported_cache_ttl_sec(ttl):
+        return LayerResolution("disabled", "invalid_ttl")
+    ramp = policy.ramp.get(layer, 100)
+    if not _valid_ramp(ramp):
+        return LayerResolution("disabled", "invalid_ramp")
+    enabled = ramp >= 100 or (ramp > 0 and deterministic_ramp_sample(urn, str(layer)) < ramp)
+    recovery = None
+    recovery_error = False
+    if layer == "remote" and not recovery_off:
+        if is_supported_cache_ttl_sec(age) and age > ttl:
+            recovery = int(age)
+        else:
+            recovery_error = True
+    return LayerResolution(
+        status="enabled" if enabled else "disabled",
+        reason=None if enabled else "ramped_down",
+        ttl_sec=int(ttl),
+        ramp=float(ramp),
+        stale_on_error_max_age_sec=recovery,
+        stale_on_error_config_error=recovery_error,
+    )

dialcache/context.py

@@ -0,0 +1,133 @@
+"""Per-instance request scope with a shared, explicitly closed memo holder."""
+
+from __future__ import annotations
+
+from contextvars import ContextVar, Token
+from dataclasses import dataclass, field
+from types import TracebackType
+from typing import Any
+
+
+@dataclass
+class RequestLocalCache:
+    """Request values and flights; closing prevents all late publication."""
+
+    in_flight: dict[str, Any] = field(default_factory=dict)
+    _values: dict[str, Any] = field(default_factory=dict)
+    closed: bool = False
+
+    def read(self, key: str) -> tuple[bool, Any]:
+        if self.closed or key not in self._values:
+            return False, None
+        return True, self._values[key]
+
+    def set(self, key: str, value: Any) -> None:
+        if not self.closed:
+            self._values[key] = value
+
+    def close(self) -> None:
+        self.closed = True
+        self._values.clear()
+        self.in_flight.clear()
+
+
+@dataclass
+class _Holder:
+    closed: bool = False
+    memo: RequestLocalCache | None = None
+
+    def close(self) -> None:
+        self.closed = True
+        if self.memo is not None:
+            self.memo.close()
+            self.memo = None
+
+
+@dataclass(frozen=True)
+class _Store:
+    enabled: bool
+    holder: _Holder | None
+
+
+class _Scope:
+    def __init__(self, context: DialCacheContext, enabled: bool) -> None:
+        self._context = context
+        self._enabled = enabled
+        self._token: Token[_Store | None] | None = None
+        self._owned: _Holder | None = None
+        self._entered = False
+
+    def __enter__(self) -> _Scope:
+        if self._entered:
+            raise RuntimeError("A DialCache scope context manager can only be entered once")
+        self._entered = True
+        holder = self._context._live_holder()
+        if self._enabled and holder is None:
+            holder = self._owned = _Holder()
+        self._token = self._context._storage.set(_Store(self._enabled, holder))
+        return self
+
+    def __exit__(
+        self,
+        exception_type: type[BaseException] | None,
+        exception: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> None:
+        if self._token is None:
+            raise RuntimeError("DialCache scope was not entered or was already closed")
+        if self._owned is not None:
+            self._owned.close()
+        self._context._storage.reset(self._token)
+        self._token = None
+
+    async def __aenter__(self) -> _Scope:
+        return self.__enter__()
+
+    async def __aexit__(
+        self,
+        exception_type: type[BaseException] | None,
+        exception: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> None:
+        self.__exit__(exception_type, exception, traceback)
+
+
+class DialCacheContext:
+    """An independently enabled context for one cache instance.
+
+    Both ``with context.enable():`` and ``async with context.enable():`` are
+    supported. Async tasks inherit the live holder, but calls made after its
+    outer scope exits are disabled, even from a copied context.
+    """
+
+    def __init__(self) -> None:
+        self._storage: ContextVar[_Store | None] = ContextVar("dialcache_scope", default=None)
+
+    def _live_holder(self) -> _Holder | None:
+        store = self._storage.get()
+        if store is None or store.holder is None or store.holder.closed:
+            return None
+        return store.holder
+
+    def is_enabled(self) -> bool:
+        store = self._storage.get()
+        return store is not None and store.enabled and self._live_holder() is not None
+
+    def enable(self) -> _Scope:
+        return _Scope(self, True)
+
+    def disable(self) -> _Scope:
+        return _Scope(self, False)
+
+    def request_cache(self) -> RequestLocalCache | None:
+        if not self.is_enabled():
+            return None
+        holder = self._live_holder()
+        assert holder is not None
+        if holder.memo is None:
+            holder.memo = RequestLocalCache()
+        return holder.memo
+
+
+def get_or_create_request_local_cache(context: DialCacheContext) -> RequestLocalCache | None:
+    return context.request_cache()

dialcache/errors.py

@@ -0,0 +1,46 @@
+"""Public errors raised by DialCache operations and configuration."""
+
+
+class DialCacheError(Exception):
+    """Base class for errors owned by DialCache."""
+
+
+class ConfigError(DialCacheError, ValueError):
+    """Invalid static configuration or malformed runtime policy."""
+
+
+class FallbackTimeoutError(DialCacheError, TimeoutError):
+    """The enabled source invocation exceeded its DialCache deadline."""
+
+    def __init__(self, use_case: str, timeout_ms: int) -> None:
+        self.use_case = use_case
+        self.timeout_ms = timeout_ms
+        super().__init__(f'DialCache fallback for use case "{use_case}" timed out after {timeout_ms} ms')
+
+
+class RemoteReadTimeoutError(DialCacheError, TimeoutError):
+    """DialCache stopped waiting for a remote read."""
+
+    def __init__(self, use_case: str, timeout_ms: int) -> None:
+        self.use_case = use_case
+        self.timeout_ms = timeout_ms
+        super().__init__(f'DialCache Redis read for use case "{use_case}" timed out after {timeout_ms} ms')
+
+
+RedisReadTimeoutError = RemoteReadTimeoutError
+
+
+class UseCaseIsAlreadyRegisteredError(DialCacheError):
+    def __init__(self, use_case: str) -> None:
+        self.use_case = use_case
+        super().__init__(f"Use case already registered: {use_case}")
+
+
+class UseCaseNameIsReservedError(DialCacheError):
+    def __init__(self, use_case: str) -> None:
+        self.use_case = use_case
+        super().__init__(f"Use case name is reserved: {use_case}")
+
+
+class MissingRemoteError(DialCacheError):
+    """An explicit remote maintenance operation has no remote adapter."""

dialcache/key.py

@@ -0,0 +1,149 @@
+"""Portable DialCache identity, URI escaping, and deterministic cohorts."""
+
+from __future__ import annotations
+
+import math
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass, field
+from urllib.parse import quote
+
+from .serializer import UNDEFINED
+
+
+def _integer_string(value: int) -> str:
+    # Python's configurable decimal-digit guard must not truncate bigint identity.
+    negative = value < 0
+    value = abs(value)
+    parts: list[int] = []
+    while value >= 1_000_000_000:
+        value, remainder = divmod(value, 1_000_000_000)
+        parts.append(remainder)
+    result = str(value) + "".join(f"{part:09d}" for part in reversed(parts))
+    return "-" + result if negative else result
+
+
+def scalar_string(value: object) -> str:
+    """JavaScript-compatible scalar spelling; Python integers retain all digits.
+
+    Python's shortest-round-trip float digits use the same nearest-even rule;
+    ECMAScript differs in the decimal/exponent presentation thresholds.
+    """
+    if isinstance(value, str):
+        return value
+    if value is None:
+        return "null"
+    if value is True:
+        return "true"
+    if value is False:
+        return "false"
+    if isinstance(value, int):
+        return _integer_string(value)
+    if isinstance(value, float):
+        if math.isnan(value):
+            return "NaN"
+        if math.isinf(value):
+            return "-Infinity" if value < 0 else "Infinity"
+        if value == 0:
+            return "0"
+        sign = "-" if value < 0 else ""
+        raw = repr(abs(value)).lower()
+        coefficient, _, exponent = raw.partition("e")
+        whole, _dot, fraction = coefficient.partition(".")
+        digits = (whole + fraction).lstrip("0")
+        position = len(whole) + (int(exponent) if exponent else 0)
+        if whole == "0":
+            position -= len(whole + fraction) - len(digits)
+        digits = digits.rstrip("0")
+        if 0 < position <= 21:
+            return sign + (
+                digits[:position] + "." + digits[position:]
+                if position < len(digits)
+                else digits + "0" * (position - len(digits))
+            )
+        if -6 < position <= 0:
+            return sign + "0." + "0" * -position + digits
+        mantissa = digits[0] + ("." + digits[1:] if len(digits) > 1 else "")
+        power = position - 1
+        return sign + mantissa + "e" + ("+" if power >= 0 else "") + str(power)
+    raise TypeError("Cache key scalar must be str, int, float, bool, or None")
+
+
+def _scalar_text(value: str, *, replace: bool = False) -> str:
+    """Combine explicit UTF-16 pairs; reject (keys) or replace (payloads) lone units."""
+    if not isinstance(value, str):
+        raise TypeError("Cache key components must be strings")
+    return value.encode("utf-16-le", "surrogatepass").decode("utf-16-le", "replace" if replace else "strict")
+
+
+def encode_component(value: str) -> str:
+    return quote(_scalar_text(value), safe="~!*'()-._", encoding="utf-8", errors="strict")
+
+
+def normalize_args(args: Mapping[str, object]) -> tuple[tuple[str, str], ...]:
+    """Omit UNDEFINED and sort names by UTF-16 units; None remains literal null."""
+    pairs = [(name, scalar_string(value)) for name, value in args.items() if value is not UNDEFINED]
+    pairs.sort(key=lambda pair: pair[0].encode("utf-16-be", "surrogatepass"))
+    return tuple(pairs)
+
+
+def invalidation_prefix(namespace: str, key_type: str, id: object) -> str:
+    entity_id = scalar_string(id)
+    for name, value in [("namespace", namespace), ("key_type", key_type), ("id", entity_id)]:
+        if "{" in value or "}" in value:
+            raise ValueError(f"Tracked {name} must not contain braces")
+    return ":".join(encode_component(part) for part in (namespace, key_type, entity_id))
+
+
+@dataclass(frozen=True)
+class Key:
+    namespace: str
+    key_type: str
+    id: object
+    use_case: str
+    args: Sequence[tuple[str, str]] = ()
+    tracked: bool = False
+    prefix: str = field(init=False)
+    logical: str = field(init=False)
+    value_key: str = field(init=False)
+    watermark_key: str | None = field(init=False)
+
+    def __post_init__(self) -> None:
+        if "{" in self.namespace or "}" in self.namespace:
+            raise ValueError("DialCache namespace must not contain braces")
+        entity_id = scalar_string(self.id)
+        pairs = tuple((name, value) for name, value in self.args)
+        if self.tracked:
+            prefix = "{" + invalidation_prefix(self.namespace, self.key_type, entity_id) + "}"
+        else:
+            prefix = ":".join(encode_component(part) for part in (self.namespace, self.key_type, entity_id))
+        query = (
+            "?" + "&".join(f"{encode_component(name)}={encode_component(value)}" for name, value in pairs)
+            if pairs
+            else ""
+        )
+        logical = prefix + query + "#" + encode_component(self.use_case)
+        object.__setattr__(self, "id", entity_id)
+        object.__setattr__(self, "args", pairs)
+        object.__setattr__(self, "prefix", prefix)
+        object.__setattr__(self, "logical", logical)
+        object.__setattr__(self, "value_key", logical + ":dialcache-frame-v1")
+        object.__setattr__(self, "watermark_key", prefix + "#watermark" if self.tracked else None)
+
+    @property
+    def urn(self) -> str:
+        return self.logical
+
+    def __str__(self) -> str:
+        return self.logical
+
+
+def ramp_hash(key: Key | str, discriminator: str) -> int:
+    units = (str(key) + ":" + discriminator).encode("utf-16-le", "surrogatepass")
+    hashed = 0x811C9DC5
+    for offset in range(0, len(units), 2):
+        hashed = ((hashed ^ (units[offset] | units[offset + 1] << 8)) * 0x01000193) & 0xFFFFFFFF
+    return hashed
+
+
+def ramp_sample(key: Key | str, discriminator: str) -> float:
+    return ramp_hash(key, discriminator) / 0x1_0000_0000 * 100