cachau 0.2.0__tar.gz

cachau-0.2.0/.gitignore

@@ -0,0 +1,26 @@
+# Internal design documents (source material, not part of the published repo)
+*.docx
+
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.venv/
+venv/
+
+# Tooling caches
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+
+# Cachau's own default cache dir (used in docs/examples)
+.cache/
+.cachau/
+
+# OS / editor noise
+.DS_Store
+Thumbs.db

cachau-0.2.0/GUIDELINES.md

@@ -0,0 +1,267 @@
+# Cachau — Design & Engineering Guidelines
+
+These guidelines define how Cachau must behave and how contributions should be designed. They exist so that every feature stays consistent with the project's core promise: **correct, bounded, observable, explainable caching for data workloads.**
+
+---
+
+## 1. API design
+
+- The common case must be minimal:
+
+  ```python
+  @cache
+  def expensive(x):
+      ...
+  ```
+
+- Configuration is declarative and progressive:
+
+  ```python
+  @cache(ttl="10m", max_memory="1GB", persist=True)
+  def expensive(x):
+      ...
+  ```
+
+- Complexity appears only as the user needs it. Backend objects, external configuration, serializers, and config files must **never** be required for basic usage.
+
+- Per-function secondary interface:
+
+  ```python
+  func.cache.stats()
+  func.cache.clear()
+  func.cache.invalidate(...)
+  func.cache.inspect()
+  func.cache.explain(...)
+  func.cache.profile(...)
+  ```
+
+- Global operations:
+
+  ```python
+  cache.clear()
+  cache.stats()
+  cache.configure(...)
+  ```
+
+## 2. Cache identity and keys
+
+A correct key conceptually represents:
+
+```
+function identity + implementation/version + normalized arguments + relevant external dependencies
+```
+
+- Semantically equivalent calls must share a key. Normalize arguments through signature binding (kwargs vs. positional must not fragment the cache).
+- Optimized, native hashing for: `numpy.ndarray`, `pandas.DataFrame`/`Series`, Polars, `pathlib.Path`, dataclasses, `dict`/`list`/`tuple`, and primitives.
+- **Never blindly serialize a huge object just to compute a key.**
+- Explicit keying must be supported:
+
+  ```python
+  @cache(key=lambda dataset, version: version)
+  def process(dataset, version):
+      ...
+  ```
+
+- Explicit exclusion of irrelevant arguments:
+
+  ```python
+  @cache(ignore=["logger", "progress_callback"])
+  def run(data, logger=None, progress_callback=None):
+      ...
+  ```
+
+- **Never silently ignore unhashable arguments.** Fail loudly or require explicit handling.
+
+## 3. Namespaces
+
+- Different functions must never collide, even with identical arguments. Conceptual identity: `package.module.function + function fingerprint + arguments`.
+- Stable namespaces allow refactors without unintended invalidation:
+
+  ```python
+  @cache(namespace="features.v2")
+  def build_features(...):
+      ...
+  ```
+
+## 4. TTL
+
+- Optional; accepts simple readable values: `ttl=60`, `"30s"`, `"10m"`, `"2h"`, `"7d"`.
+- TTL starts when the entry was **computed and committed**, not when execution began.
+- Expiration is **lazy** by default: check on access; if expired, treat as miss and remove/mark stale. No background workers unless a real need is demonstrated.
+
+## 5. Memory limits and eviction
+
+- Bounded resources are a core feature: `@cache(max_memory="1GB")` or `cache.configure(max_memory="4GB")`.
+- Document precisely what "size" means (serialized size, approximate in-memory size, deep size, or physical backend size).
+- **LRU** is the initial policy — understandable and predictable. Do not add more policies before demonstrated need.
+- If a single entry exceeds total capacity: compute the result, return it, **do not cache it**, and record `cache_skip_oversized`. Never flush the whole cache to fit one pathological entry.
+
+## 6. Persistence
+
+- Trivial to enable: `@cache(persist=True)` or `@cache(persist="./.cache")`.
+- Must survive interpreter, notebook, and process restarts.
+- Writes are **atomic**: serialize to temp file → sync where appropriate → atomic rename.
+- Per-entry metadata: key, `created_at`, `expires_at`, `last_access`, size, serializer, function identity, function fingerprint, format version.
+- The persistent format has **explicit versioning**. Incompatibility degrades to a miss or controlled invalidation — never mysterious errors.
+
+## 7. Invalidation
+
+Invalidation is a first-class concept:
+
+- Per function: `expensive.cache.clear()`
+- Per invocation: `expensive.cache.invalidate(x=1)`
+- Global: `cache.clear()`
+- **Changing a function's implementation invalidates previous results by default.** A result produced by `return x * 2` must not be reused after the code becomes `return x * 3`.
+- External dependency invalidation:
+
+  ```python
+  @cache(depends_on=["data.csv"])
+  def load_data():
+      ...
+  ```
+
+  Possible fingerprints: mtime, size, content hash, environment variable, package version, user-defined token.
+
+- Automatic detection is **conservative**. Explicitness is preferable to unreliable magic.
+
+## 8. Observability and metrics
+
+A cache that is hard to observe is hard to trust.
+
+- `func.cache.stats()` reports: hits, misses, hit rate, writes, skipped writes, expirations, invalidations, evictions, serialization/deserialization errors, entry count, current bytes, computation time, estimated time saved.
+- Misses must distinguish causes: `miss_not_found`, `miss_expired`, `miss_invalidated`, `miss_code_changed`, `miss_dependency_changed`, `miss_corrupt`.
+- `func.cache.explain(args)` answers: HIT or MISS? Why? Which dependency changed? Did the code change? How big is it? How much TTL remains? What was invalidated or evicted?
+- Metrics observe without changing behavior.
+
+## 9. Serialization
+
+- Extensible but invisible in normal cases. Priorities: Python types → NumPy → pandas → common objects.
+- Strategies: pickle/cloudpickle, native NumPy formats, Arrow/Parquet, custom serializers.
+- **Correctness beats micro-optimization.**
+- If the function computes correctly but serialization fails: return the result, record `cache_write_error`, optionally warn. The cache is an optimization, not a correctness dependency.
+
+## 10. Concurrency: single-flight
+
+- Multiple concurrent callers for the same absent key should not all compute:
+
+  ```
+  Caller A → MISS → computes
+  Caller B → same key → waits
+  Caller C → same key → waits
+  A commits the result
+  B/C reuse the result
+  ```
+
+- Synchronization is **per key**. Never a global lock that serializes independent work.
+
+## 11. Purity, exceptions, and mutability
+
+- Exceptions are **not cached** by default.
+- Correctness assumes the result is determined by the key and declared dependencies. Do not try to magically detect nondeterminism; random seeds should be explicit arguments.
+- Functions that mutate inputs in-place cannot be treated as conventional memoization. Default contract: functions are pure with respect to their key. Mutation: reject when detectable, require opt-in, or document as outside the standard guarantee.
+- Define what happens when a caller mutates a mutable result retrieved from the cache (especially for the in-memory backend).
+
+## 12. Notebook experience
+
+Notebooks are a primary target:
+
+- `func.cache.stats() / clear() / inspect() / explain(...)` must feel natural in a cell.
+- Re-running a cell must not unexpectedly destroy a useful persistent cache.
+- Changing the code **should** invalidate stale results, in an understandable way.
+
+## 13. Architecture
+
+Conceptual layers:
+
+```
+Decorator / Public API
+  → Invocation Normalization
+  → Key Builder
+  → Dependency Fingerprinting
+  → Cache Policy
+  → Storage Backend
+  → Serializer
+  → Metrics / Events
+```
+
+Separation of responsibilities:
+
+- The decorator does not implement storage.
+- The backend does not decide function semantics.
+- The serializer does not decide invalidation.
+- Metrics observe without changing behavior.
+
+Minimal backend interface:
+
+```python
+class CacheBackend:
+    def get(key): ...
+    def set(key, value, metadata): ...
+    def delete(key): ...
+    def clear(namespace=None): ...
+    def iter_entries(...): ...
+```
+
+V1 ships `MemoryBackend` + `DiskBackend`. Redis, S3, databases, and distributed caching stay out until the local model is consolidated.
+
+## 14. Numba support
+
+Numba is a **first-class workload**:
+
+```python
+@cache(ttl="1h", max_memory="4GB", persist=True)
+@njit
+def simulate(values, iterations):
+    ...
+```
+
+- Cachau operates at the **Python → Numba dispatcher boundary**. The initial goal is *not* making `@cache` callable from nopython mode — it is caching Numba workloads correctly, fast, and transparently.
+- **Dispatcher identity**: derived from the original Python function, semantically relevant compile options (`fastmath`, `parallel`, `boundscheck`, `error_model`), defaults, and namespace/version — never `repr()` or memory identity. Changing semantically relevant configuration invalidates stale persisted results.
+- **Compilation cache vs. result cache** are independent: Numba `cache=True` caches machine code; Cachau caches computed results. They coexist — a Cachau HIT skips execution; a MISS still benefits from Numba's compilation cache.
+- **Honest metrics**: distinguish cold JIT vs. warm JIT. Measure lookup, key generation, compile/dispatch, execution, serialization, and deserialization separately. Never repeatedly count one-time compilation cost as normal execution cost. Standard benchmark: compile → warm up → benchmark; report cold JIT separately.
+- **ndarray identity** includes at minimum dtype, shape, and content; strides/memory order only when semantically relevant. Equal bytes with different dtype or shape must not collide. C/F/non-contiguous layout must not fragment the cache unless it affects observable semantics — identity follows semantics, not compiler internals.
+- **Advanced types** (`numba.typed.List`, `typed.Dict`, jitclass, extension types): support is explicit and progressive. Do not declare support without deterministic hashing, serialization round-trip, stability tests, and benchmarks. For jitclass, prefer explicit keys or field-based adapters over compiler internals.
+- `parallel=True` works at the Python boundary without Cachau altering thread configuration. Do not needlessly bind persisted results to CPU/LLVM/machine code — prefer semantic identity over compilation-artifact identity.
+
+## 15. Cache economics
+
+The fundamental rule:
+
+```
+T_key + T_lookup + T_deserialize < T_recompute
+```
+
+Example: a Python function takes 10 s; with Numba it takes 50 ms; hashing a 2 GB array takes 800 ms — caching makes it *worse*. Cachau should measure (or make it easy to measure): keying cost, lookup, deserialize, warm recomputation, net time saved. `cache.profile()` embodies this philosophy: not just caching, but explaining when caching is a bad decision.
+
+## 16. Testing requirements
+
+Mandatory semantic tests:
+
+- HIT after first computation; MISS on different arguments
+- kwargs/positional normalization
+- TTL expiration; TTL starts after computation
+- Memory eviction; oversized-entry skip
+- Persistence across processes; corruption recovery
+- Invalidation: code change, dependency change, manual
+- Same-key concurrency (single-flight)
+- Serialization failure fallback
+- `stats()`, `clear()`, namespace isolation
+
+Numba-specific tests:
+
+- Warm/cold JIT distinction
+- dtype/shape/layout identity
+- `fastmath` and `parallel` variants
+- Large arrays
+- Typed containers (once supported)
+- Cross-process persistence
+- Keying cost vs. recomputation
+
+## 17. Feature acceptance bar
+
+Every new feature must justify its complexity through real use cases. When evaluating a proposal, ask:
+
+1. Does it preserve **correctness before hit rate**?
+2. Can the system still **explain** what happened?
+3. Is the behavior **predictable and bounded**?
+4. Is it needed for the narrow mission — *"a pleasant, robust function cache for expensive Python data workloads"* — or is it scope creep toward an anti-goal (distributed cache, workflow engine, artifact registry)?

cachau-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nicolás Seijas
+
+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.

cachau-0.2.0/PKG-INFO

@@ -0,0 +1,178 @@
+Metadata-Version: 2.4
+Name: cachau
+Version: 0.2.0
+Summary: Delightful, observable, bounded, and persistent function caching for Python data workloads.
+Project-URL: Repository, https://github.com/nicoseijas/Cachau
+Author-email: Nicolás Seijas <nicoseijas@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: cache,caching,data-science,memoization,numba,numpy,pandas
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.10
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Cachau
+
+**Delightful, observable, bounded, and persistent function caching for Python data workloads.**
+
+Cachau is a function cache designed around the real problems of data science: large arguments, expensive computations, notebooks that restart, voluminous results, invalidation when code or data changes, and explicit memory and disk limits.
+
+> Say ciao to recomputation.
+
+```python
+from cachau import cache
+
+@cache(ttl="1h", persist=True, max_memory="2GB")
+def expensive_analysis(df, config):
+    ...
+```
+
+> **Status: v0.2.0 — the core engine plus validated Numba Level A support** (236 tests): normalized keys with type-tagged hashing (incl. closure captures), native NumPy/pandas identity, `key=`/`ignore=` escape hatches, code-change invalidation, TTL, LRU memory bounds, atomic corruption-safe persistence, same-key single-flight, `stats()` with miss reasons and cold/warm JIT accounting, and `explain()`. Pre-1.0, so the API may still evolve. Next up: `depends_on=` dependency invalidation and `profile()` (see [ROADMAP](ROADMAP.md)).
+
+## Installation
+
+```
+pip install cachau
+```
+
+## Why not just `functools.lru_cache` / joblib / diskcache?
+
+Plenty of libraries offer TTL, persistence, or LRU. None of them combine what data workloads actually need:
+
+| Problem | Cachau's answer |
+|---|---|
+| Hashing a 2 GB DataFrame just to build a key | Native, optimized hashing for NumPy, pandas, and Polars — plus explicit `key=` / `ignore=` escape hatches |
+| Stale results after you edit the function | Code-fingerprint invalidation by default: change `x * 2` to `x * 3`, the old result dies |
+| Results that outlive the data they came from | `depends_on=["data.csv"]` — invalidate on file, env var, or package changes |
+| Caches that eat all your RAM or disk | First-class `max_memory` bounds with predictable LRU eviction |
+| Notebook restarts throwing work away | `persist=True` — atomic, versioned on-disk format that survives restarts |
+| "Why was that a miss?!" | `func.cache.explain(...)` tells you exactly what happened and why |
+| Caching that silently makes things *slower* | `func.cache.profile(...)` measures whether caching is even worth it |
+| Numba treated as an afterthought | First-class support at the dispatcher boundary — `fastmath`/`parallel`-aware identity, honest cold/warm JIT metrics |
+
+## A taste of the API
+
+The common case is one decorator, zero configuration:
+
+```python
+@cache
+def load_dataset(path):
+    return pd.read_parquet(path)
+```
+
+Configuration is declarative and progressive — no backend objects, no config files:
+
+```python
+@cache(ttl="1h")
+def build_features(df, config):
+    ...
+
+@cache(persist=True)
+def train_embedding(dataset_hash, params):
+    ...
+
+@cache(max_memory="2GB")
+def expensive_simulation(seed, params):
+    ...
+
+@cache(ignore=["logger", "progress_callback"])
+def run(data, logger=None, progress_callback=None):
+    ...
+
+@cache(key=lambda dataset, version: version)
+def process(dataset, version):
+    ...
+```
+
+Coming in V1.1: `@cache(depends_on=["data/train.parquet"])` — invalidation when files, environment variables, or package versions change.
+
+Every cached function carries its own control surface:
+
+```python
+build_features.cache.stats()        # hits, misses, hit rate, bytes, time saved...
+build_features.cache.clear()
+build_features.cache.invalidate(df, config)
+build_features.cache.explain(df, config)
+build_features.cache.profile(df, config)
+```
+
+### `explain()` — transparency on demand
+
+```
+MISS
+Reason:      expired
+Namespace:   features.build_features
+Created:     2026-07-19 14:03:11 UTC
+Expired:     3m 2s ago (at 2026-07-19 15:03:11 UTC)
+Size:        1.2 MB
+```
+
+(V1.1 adds dependency answers: *which file changed, previous vs. current fingerprint*.)
+
+### `profile()` — is caching even worth it? *(planned — V1.1)*
+
+```
+Cache suitability
+
+Computation (warm Numba):       182 ms
+Key generation:                 347 ms
+Cache lookup:                     2 ms
+Deserialization:                 41 ms
+--------------------------------------
+Cache hit total:                390 ms
+
+Caching is slower than recomputation by ~2.1x.
+Primary cause:   hashing ndarray[float64, 480 MB]
+Recommendation:  provide an explicit stable key or dataset version.
+```
+
+Cachau doesn't just cache — it tells you when caching is a bad decision.
+
+## First-class Numba support
+
+```python
+from numba import njit
+from cachau import cache
+
+@cache(ttl="1h", max_memory="4GB", persist=True)
+@njit
+def simulate(values, iterations):
+    ...
+```
+
+Cachau caches **results** at the Python → dispatcher boundary (`@cache` goes below `@njit`); Numba's `cache=True` caches **machine code**. They compose: a Cachau HIT skips execution entirely, and a MISS still benefits from Numba's compilation cache. Dispatcher identity covers the Python function, closure captures, and semantically relevant compile options (`fastmath`, `parallel`, `boundscheck`, `error_model`, `locals=` type forcing) — changing any of them invalidates stale results. Metrics are honest about JIT: each specialization's first compile is reported as `cold_compute_seconds` and never counted as normal execution cost. Validated by a 26-test matrix.
+
+## Design principles
+
+1. **Correctness before hit rate.** A false HIT is worse than a MISS. When in doubt, recompute.
+2. **Safe by default.** Exceptions aren't cached; serialization failure never loses your result; corruption degrades to a miss, never a mysterious error.
+3. **Observable before clever.** Every hit, miss, eviction, and skip has an inspectable reason code.
+4. **No hidden magic.** Automatic detection is conservative; explicitness beats unreliable cleverness.
+5. **Bounded by design.** Memory and disk limits are core features, not afterthoughts.
+
+## What Cachau is *not*
+
+Not Redis, not a distributed cache, not a workflow engine, not an artifact registry, not an experiment tracker, not a joblib/Dask replacement. The scope stays narrow on purpose:
+
+> *A pleasant, robust function cache for expensive Python data workloads.*
+
+## Documentation
+
+- **[VISION.md](VISION.md)** — why Cachau exists, positioning, and guiding maxims
+- **[ROADMAP.md](ROADMAP.md)** — phased plan from foundations to Numba Level B
+- **[GUIDELINES.md](GUIDELINES.md)** — the full design & engineering spec (API, cache identity, TTL, eviction, persistence, invalidation, observability, concurrency, Numba, testing)
+
+## Contributing
+
+The core engine is young and feedback is the most valuable contribution: try it on a real workload and open an issue with what surprised you. Bug reports with a failing test are gold. Before proposing features, read [GUIDELINES.md](GUIDELINES.md), especially the feature acceptance bar: every addition must preserve correctness, explainability, and the narrow mission.
+
+## License
+
+MIT

cachau-0.2.0/README.md

@@ -0,0 +1,158 @@
+# Cachau
+
+**Delightful, observable, bounded, and persistent function caching for Python data workloads.**
+
+Cachau is a function cache designed around the real problems of data science: large arguments, expensive computations, notebooks that restart, voluminous results, invalidation when code or data changes, and explicit memory and disk limits.
+
+> Say ciao to recomputation.
+
+```python
+from cachau import cache
+
+@cache(ttl="1h", persist=True, max_memory="2GB")
+def expensive_analysis(df, config):
+    ...
+```
+
+> **Status: v0.2.0 — the core engine plus validated Numba Level A support** (236 tests): normalized keys with type-tagged hashing (incl. closure captures), native NumPy/pandas identity, `key=`/`ignore=` escape hatches, code-change invalidation, TTL, LRU memory bounds, atomic corruption-safe persistence, same-key single-flight, `stats()` with miss reasons and cold/warm JIT accounting, and `explain()`. Pre-1.0, so the API may still evolve. Next up: `depends_on=` dependency invalidation and `profile()` (see [ROADMAP](ROADMAP.md)).
+
+## Installation
+
+```
+pip install cachau
+```
+
+## Why not just `functools.lru_cache` / joblib / diskcache?
+
+Plenty of libraries offer TTL, persistence, or LRU. None of them combine what data workloads actually need:
+
+| Problem | Cachau's answer |
+|---|---|
+| Hashing a 2 GB DataFrame just to build a key | Native, optimized hashing for NumPy, pandas, and Polars — plus explicit `key=` / `ignore=` escape hatches |
+| Stale results after you edit the function | Code-fingerprint invalidation by default: change `x * 2` to `x * 3`, the old result dies |
+| Results that outlive the data they came from | `depends_on=["data.csv"]` — invalidate on file, env var, or package changes |
+| Caches that eat all your RAM or disk | First-class `max_memory` bounds with predictable LRU eviction |
+| Notebook restarts throwing work away | `persist=True` — atomic, versioned on-disk format that survives restarts |
+| "Why was that a miss?!" | `func.cache.explain(...)` tells you exactly what happened and why |
+| Caching that silently makes things *slower* | `func.cache.profile(...)` measures whether caching is even worth it |
+| Numba treated as an afterthought | First-class support at the dispatcher boundary — `fastmath`/`parallel`-aware identity, honest cold/warm JIT metrics |
+
+## A taste of the API
+
+The common case is one decorator, zero configuration:
+
+```python
+@cache
+def load_dataset(path):
+    return pd.read_parquet(path)
+```
+
+Configuration is declarative and progressive — no backend objects, no config files:
+
+```python
+@cache(ttl="1h")
+def build_features(df, config):
+    ...
+
+@cache(persist=True)
+def train_embedding(dataset_hash, params):
+    ...
+
+@cache(max_memory="2GB")
+def expensive_simulation(seed, params):
+    ...
+
+@cache(ignore=["logger", "progress_callback"])
+def run(data, logger=None, progress_callback=None):
+    ...
+
+@cache(key=lambda dataset, version: version)
+def process(dataset, version):
+    ...
+```
+
+Coming in V1.1: `@cache(depends_on=["data/train.parquet"])` — invalidation when files, environment variables, or package versions change.
+
+Every cached function carries its own control surface:
+
+```python
+build_features.cache.stats()        # hits, misses, hit rate, bytes, time saved...
+build_features.cache.clear()
+build_features.cache.invalidate(df, config)
+build_features.cache.explain(df, config)
+build_features.cache.profile(df, config)
+```
+
+### `explain()` — transparency on demand
+
+```
+MISS
+Reason:      expired
+Namespace:   features.build_features
+Created:     2026-07-19 14:03:11 UTC
+Expired:     3m 2s ago (at 2026-07-19 15:03:11 UTC)
+Size:        1.2 MB
+```
+
+(V1.1 adds dependency answers: *which file changed, previous vs. current fingerprint*.)
+
+### `profile()` — is caching even worth it? *(planned — V1.1)*
+
+```
+Cache suitability
+
+Computation (warm Numba):       182 ms
+Key generation:                 347 ms
+Cache lookup:                     2 ms
+Deserialization:                 41 ms
+--------------------------------------
+Cache hit total:                390 ms
+
+Caching is slower than recomputation by ~2.1x.
+Primary cause:   hashing ndarray[float64, 480 MB]
+Recommendation:  provide an explicit stable key or dataset version.
+```
+
+Cachau doesn't just cache — it tells you when caching is a bad decision.
+
+## First-class Numba support
+
+```python
+from numba import njit
+from cachau import cache
+
+@cache(ttl="1h", max_memory="4GB", persist=True)
+@njit
+def simulate(values, iterations):
+    ...
+```
+
+Cachau caches **results** at the Python → dispatcher boundary (`@cache` goes below `@njit`); Numba's `cache=True` caches **machine code**. They compose: a Cachau HIT skips execution entirely, and a MISS still benefits from Numba's compilation cache. Dispatcher identity covers the Python function, closure captures, and semantically relevant compile options (`fastmath`, `parallel`, `boundscheck`, `error_model`, `locals=` type forcing) — changing any of them invalidates stale results. Metrics are honest about JIT: each specialization's first compile is reported as `cold_compute_seconds` and never counted as normal execution cost. Validated by a 26-test matrix.
+
+## Design principles
+
+1. **Correctness before hit rate.** A false HIT is worse than a MISS. When in doubt, recompute.
+2. **Safe by default.** Exceptions aren't cached; serialization failure never loses your result; corruption degrades to a miss, never a mysterious error.
+3. **Observable before clever.** Every hit, miss, eviction, and skip has an inspectable reason code.
+4. **No hidden magic.** Automatic detection is conservative; explicitness beats unreliable cleverness.
+5. **Bounded by design.** Memory and disk limits are core features, not afterthoughts.
+
+## What Cachau is *not*
+
+Not Redis, not a distributed cache, not a workflow engine, not an artifact registry, not an experiment tracker, not a joblib/Dask replacement. The scope stays narrow on purpose:
+
+> *A pleasant, robust function cache for expensive Python data workloads.*
+
+## Documentation
+
+- **[VISION.md](VISION.md)** — why Cachau exists, positioning, and guiding maxims
+- **[ROADMAP.md](ROADMAP.md)** — phased plan from foundations to Numba Level B
+- **[GUIDELINES.md](GUIDELINES.md)** — the full design & engineering spec (API, cache identity, TTL, eviction, persistence, invalidation, observability, concurrency, Numba, testing)
+
+## Contributing
+
+The core engine is young and feedback is the most valuable contribution: try it on a real workload and open an issue with what surprised you. Bug reports with a failing test are gold. Before proposing features, read [GUIDELINES.md](GUIDELINES.md), especially the feature acceptance bar: every addition must preserve correctness, explainability, and the narrow mission.
+
+## License
+
+MIT