fleche 0.22.2__tar.gz → 0.22.4__tar.gz

{fleche-0.22.2 → fleche-0.22.4}/.github/workflows/test-minimum-deps.yml

@@ -35,7 +35,12 @@ jobs:
           fetch-depth: 0
       - uses: astral-sh/setup-uv@v5
         if: needs.changes.outputs.run == 'true'
-      - run: uv venv
+      # Pin the interpreter to the oldest Python allowed by requires-python
+      # (keep in sync with pyproject.toml). Without it, uv picks the runner's
+      # system Python, which drifts with the image (ubuntu-26.04 ships 3.14),
+      # and the floors may have no wheels there, so they get built from source.
+      # uv downloads a managed 3.11 if the image lacks one.
+      - run: uv venv --python 3.11
         if: needs.changes.outputs.run == 'true'
       # --resolution lowest-direct pins every direct dependency to the lowest
       # version its bound allows, exercising the floors declared in pyproject.

{fleche-0.22.2 → fleche-0.22.4}/.github/workflows/tests.yml

@@ -62,6 +62,29 @@ jobs:
         if-no-files-found: ignore
         retention-days: 90
 
+  executorlib:
+    needs: changes
+    if: needs.changes.outputs.run == 'true'
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v5
+    - name: Set up Python
+      uses: actions/setup-python@v6
+      with:
+        python-version: "3.12"
+        cache: pip
+    - name: Setup
+      shell: bash -l {0}
+      run: |
+        pip install -e .[tests,executorlib]
+    - name: Run executorlib tests
+      shell: bash -l {0}
+      env:
+        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+      run: |
+        # The main build job doesn't install executorlib, so it skips these.
+        pytest tests/integration/test_parallel_execution.py -k executorlib -v -rs
+
   sql-backends:
     needs: changes
     if: needs.changes.outputs.run == 'true'

{fleche-0.22.2 → fleche-0.22.4}/.gitignore

@@ -11,3 +11,7 @@ notebooks/*.db-shm
 notebooks/*.db-wal
 docs/_build
 src/fleche/_version.py
+.coverage
+.coverage.*
+coverage.xml
+htmlcov/

fleche-0.22.4/.release-please-manifest.json

@@ -0,0 +1,3 @@
+{
+  ".": "0.22.4"
+}

{fleche-0.22.2 → fleche-0.22.4}/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## [0.22.4](https://github.com/pmrv/fleche/compare/0.22.3...0.22.4) (2026-11-06)
+
+
+### Bug Fixes
+
+* **call:** keep an explicit __version__ when the module cannot be imported ([#1028](https://github.com/pmrv/fleche/issues/1028)) ([f47005c](https://github.com/pmrv/fleche/commit/f47005c572d6c5eed65f6a28fab96b58bebef815))
+
+## [0.22.3](https://github.com/pmrv/fleche/compare/0.22.2...0.22.3) (2026-11-06)
+
+
+### Bug Fixes
+
+* **digest:** digest numbers by exact value through a downcast tree ([#1020](https://github.com/pmrv/fleche/issues/1020)) ([4daccb3](https://github.com/pmrv/fleche/commit/4daccb3f34bf9f6b87620105a1f7e8bfde11155f))
+
 ## [0.22.2](https://github.com/pmrv/fleche/compare/0.22.1...0.22.2) (2026-10-23)
 
 

{fleche-0.22.2 → fleche-0.22.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fleche
-Version: 0.22.2
+Version: 0.22.4
 Summary: Hierachical, persistant caches in python
 Author-email: Marvin Poul <pmrv@posteo.de>
 License-Expression: BSD-3-Clause
@@ -43,7 +43,7 @@ Requires-Dist: attrs>=21.3; extra == "tests"
 Provides-Extra: executorlib
 Requires-Dist: executorlib; extra == "executorlib"
 Provides-Extra: ty
-Requires-Dist: ty==0.0.89; extra == "ty"
+Requires-Dist: ty==0.0.95; extra == "ty"
 Dynamic: license-file
 
 # fleche

{fleche-0.22.2 → fleche-0.22.4}/agents/DEVELOPING.md

@@ -130,11 +130,11 @@ Values and calls are stored separately so call records are queryable without des
   `Hook`, `add_hook`, `get_hooks`, `load_entry_points`;
   `Indigestible`;
   `DIGEST_LENGTH=64`.
-  Built-in types are inline `match` cases in `_digest_bytes`, ordered roughly hot-path first: `int` (`bool ⊂ int`) → `Digest` (returns `value.encode()` so `digest(Digest("abc")) == "abc"`) → `str` → `None` → `Number` (`float`, `complex`, `Decimal`, `Fraction`, plus `np.integer`/`np.floating` which satisfy `numbers.Number` automatically;
-  routed through `hash(value)` then recursed as int — a lossy encoding under which distinct numbers collide;
-  see the numeric-digest bullet under **Bugs** below) → `bytes` → `np.ndarray` (dtype + shape + `tobytes`;
-  structured dtypes instead digest each field name + field view recursively, because `dtype.str` is only `|V<itemsize>` and padding bytes are uninitialised;
-  other `dtype.hasobject` arrays digest every element of `ravel().tolist()` because their bytes are PyObject pointers) → `np.bool_` (delegates to `digest(bool(value))`, because `np.bool_ ∉ Number` since numpy 1.20) → pandas (`case _ if _pandas.is_pandas(value)`, which returns `_pandas.digest_pandas(value, _digest_bytes)`: `pd.DataFrame` / `pd.Series` / `pd.Index` / `pd.NA`;
+  Built-in types are inline `match` cases in `_digest_bytes`, ordered roughly hot-path first: `int` (`bool ⊂ int`) → `Digest` (returns `value.encode()` so `digest(Digest("abc")) == "abc"`) → `str` → `None` → `datetime.timedelta` / `np.timedelta64` (must precede `Number`, as numpy registers `timedelta64` `Integral`;
+  refused with `Indigestible` until a digest honours their cross-type, cross-unit `==` — the old `total_seconds()` float merged unequal `pd.Timedelta` nanoseconds;
+  `datetime.timezone` digests its offset as exact microseconds instead) → `Number` (`float`, `complex`, `Decimal`, `Fraction`, plus `np.integer`/`np.floating` which satisfy `numbers.Number` automatically;
+  handed to `_numbers.digest_number(value, _digest_bytes)`, see `_numbers.py` below, and `Indigestible` when it returns `None`;
+  This replaced `hash(value)`, a lossy encoding under which distinct numbers collided) → `bytes` → numpy (`case _ if _numpy.is_numpy(value)`, which returns `_numpy.digest_numpy(value, _digest_bytes)`: `np.ndarray` and `np.bool_`, see `_numpy.py` below) → pandas (`case _ if _pandas.is_pandas(value)`, which returns `_pandas.digest_pandas(value, _digest_bytes)`: `pd.DataFrame` / `pd.Series` / `pd.Index` / `pd.NA`;
   must precede `Iterable` — DataFrame iterates over column names only, so the `Iterable` arm collides any two DataFrames with the same columns regardless of values;
   DataFrame folds in columns + per-column dtype + index, Series folds in name + dtype + index, Index folds in name + dtype;
   values are mixed via `pd.util.hash_pandas_object(...).values.tobytes()` — `index=False` on the DataFrame/Series arms (the Index arm passes no kwarg since Index has no index) because `hash_pandas_object` only mixes per-element value bytes and ignores name/dtype/index metadata, so we hand-roll those.
@@ -161,13 +161,45 @@ Values and calls are stored separately so call records are queryable without des
   bound methods are their own arm (`types.MethodType`: receiver + underlying function, so `obj1.m` and `obj2.m` differ;
   a class receiver is named via `digest_class`), so there is no second entry point — `call._code_digest` reduces a bound method to `__func__` (the receiver already arrives as a call argument) and goes through `digest`;
   `digest_class(cls)` names a class `module.QualName` and is shared by the built-in-`type` arm and the `__class__` cell.
-  `_new_hash(salt)` is the one place a salted running hash is started, apart from `_pandas.digest_pandas`, which mirrors it.
-  NaN floats are packed via `struct.pack` (sign-preserving) instead of going through `hash()`;
-  complex NaNs use `<dd`.
+  `_new_hash(salt)` (imported from `_hashing.new_hash`) starts every salted running hash.
+- `_hashing.py` — the hash primitive, kept out of `digest.py` so the arm modules it imports (`_numbers`, `_numpy`, `_pandas`) can share it without importing it back.
+  `new_hash(salt)` starts a salted SHA256;
+  `running_hash(salt)` is a context manager over it whose `.result` is the finished digest in `_digest_bytes`'s wire format (hex as bytes) once the block exits, and raises `RuntimeError` if read earlier, so an arm module never spells out `hexdigest().encode()` itself.
+  The primitive lives only here and the encoding only here and in `digest.py`'s own `hexdigest()` returns, never in an arm module: the #440 raw-bytes switch touches those, and patching `_hashing.hashlib` swaps every digest's hash (`test_redigest`, `test_hashing`).
+  `running_hash` costs about 0.3 µs per use, so `digest.py`'s own hot path keeps the bare `_new_hash` + `hexdigest()`.
+- `_numbers.py` — the number digest arm, kept out of `digest.py`;
+  `digest_bytes` is passed in because `digest.py` imports it;
+  it hashes through `_hashing.running_hash` (`_salted`), never `hashlib` directly.
+  `digest_number` walks `NUMBER_TREE` (`int` → {`numbers.Integral`, `float` → {`complex` → `numbers.Complex`, `Fraction` → {`Decimal`, `numbers.Real`}}};
+  a complex with zero imaginary part first drops to its real part) from the root down to the value's own node and digests it as the first type whose converter holds it exactly, so equal values digest alike unless they sit on different branches below that type (none do in the current tree).
+  A value's node is the most derived tree type its type subclasses (`_path`, cached per type), registered ABCs included: a type in another's MRO is always its superclass, so one `issubclass` rule covers real subclasses and numpy scalars, which are only *registered* with the `numbers` ABCs — `np.int64` lands on `Integral`,
+  `np.float32`/`np.longdouble` on `Real` (below `float` and `Fraction`),
+  `np.complex64` on `Complex`, while `np.float64`/`np.complex128` subclass `float`/`complex`.
+  `_hold(value)` returns the node that holds a value and the converted value;
+  `test_branch_choice_follows_exact_value` checks its choice against exact arithmetic, since the converters go through numpy for numpy scalars.
+  `np.float32`/`np.longdouble` on `Real` (below `float` and `Fraction`), `np.complex64` on `Complex`, while `np.float64`/`np.complex128` subclass `float`/`complex`.
+  ABC nodes have no converter or encoder: they only place what sits under them, and `Decimal` never holds a value either (every finite `Decimal` is an exact `Fraction`).
+  A value nothing on its path holds gets `None`, which `digest.py` raises as `Indigestible`.
+  Converters must refuse inexact conversions themselves rather than rely on a trailing `==`: numpy compares `Fraction` to `np.longdouble` by rounding the `Fraction` to double, and an `np.longdouble` to an `int` through `str` (subject to `sys.int_max_str_digits`).
+  So `_as_int` decides on `as_integer_ratio` / `numerator`+`denominator` (also avoiding a quadratic `int()` round trip for `Decimal("1e1000000")`), falling back to `math.trunc` for a foreign `Real`, which promises `__trunc__` but neither `__int__` nor `as_integer_ratio`;
+  Encoders salt with the bare type name of the node (`_salted(float, …)`), like every generic arm;
+  a user type sharing the name and feeding the same bytes would collide, which is accepted as for all other types.
+  `_is_nan` skips `Rational`s and treats `OverflowError` as not-NaN, since `cmath.isnan` converts to float and `Fraction(10**400)` overflows it.
+  The promise, worded in `digest_equivalence.rst`: non-NaN numbers digest equal iff they hold the same exact value — numpy's `==` (NEP 50 down-casts, `Fraction` rounding) is not the reference.
+  `int` subclasses (`bool`, `IntEnum`) never reach the tree: the `int` arm catches them under their own type name, unlike `float` subclasses, which downcast.
+  The tree is drawn in the code comment and in `docs/digests/digest_equivalence.rst`;
+  no test checks the drawings, so update both by hand whenever `NUMBER_TREE` changes.
+  A NaN is digested by its bits exactly as the `float` (or, with an imaginary part, `complex`) node would encode them, whatever its type, so `np.float64("nan")` meets `float("nan")` and the sign survives;
+  `Decimal` NaNs (including `sNaN`, which `cmath.isnan` rejects) by `str()` under the `Decimal` salt.
+  Equal-value results of different numeric types share one value-storage entry, and whichever saved last wins the return type — intended, not a bug.
 - `_attrs.py` — Internal `is_attrs_instance` / `field_items` helpers gating optional `attrs` support;
   safe to import without `attrs` installed.
+- `_numpy.py` — the `np.ndarray` and `np.bool_` digest arm (`is_numpy` / `digest_numpy(value, digest_bytes)`), plus `is_timedelta64` for `digest.py`'s timedelta refusal, so `digest.py` no longer imports numpy;
+  arrays digest dtype + shape + `tobytes`, structured dtypes each field name + field view recursively (`dtype.str` is only `|V<itemsize>` and padding bytes are uninitialised), other `dtype.hasobject` arrays every element of `ravel().tolist()` (their bytes are PyObject pointers);
+  `np.bool_` delegates to the builtin `bool` (`np.bool_ ∉ Number` since numpy 1.20).
+  numpy *number* scalars are not handled here but by `_numbers`.
 - `_pandas.py` — Internal digest arms for pandas objects: `is_pandas` gates the one pandas case in `_digest_bytes`,
-  `digest_pandas` digests DataFrame / Series / Index / MultiIndex / `pd.NA` with the same salt and hex return as `_digest_bytes`, and `needs_element_digests` / `element_digests` handle object columns (#1004);
+  `digest_pandas` digests DataFrame / Series / Index / MultiIndex / `pd.NA` with the same bare-type-name salt as `_digest_bytes`, through `_hashing.running_hash`, and `needs_element_digests` / `element_digests` handle object columns (#1004);
   `digest_pandas` and `element_digests` take `digest._digest_bytes` as an argument, since `digest.py` imports the module.
 - `call.py` — `Call` dataclass (`from_call`, `to_lookup_key`, `.stash(values)→DigestedCall` writes args+result to value storage / `.digest()→DigestedCall` digests without saving);
   `DigestedCall` (storage representation: arguments and result are `Digest` keys;
@@ -404,7 +436,7 @@ Values and calls are stored separately so call records are queryable without des
   best-effort — non-Linux or an unreadable `/proc/mounts` reports "not network";
   network types are `nfs`/`nfs4`/`cifs`/`smb*`/`ceph*`/`glusterfs`/`9p`/`lustre`/`gpfs`/`panfs`/`afs`/`afpfs`;
   a warning is logged when WAL is skipped).
-  `:memory:` skips `journal_mode` entirely.
+  `:memory:` skips `journal_mode` entirely — the check is `engine.url.database in (None, ":memory:")`, because SQLAlchemy percent-encodes `:memory:` when rendering the URL, so a string match on the rendered URL never fires (a dead short-circuit until PR #980 fixed it).
   The schema is three tables: `calls`, `arguments` (one row per arg, `UNIQUE(call_key, name)`, ordered by `position`), `metadata` (one JSON blob per metadata namespace, `UNIQUE(call_key, name)`).
   `arguments.call_key`/`metadata.call_key` are FKs with `ondelete="CASCADE"`, so `_evict` is a single `session.execute(delete(CallModel).where(...))` (SQLAlchemy DSL, no raw SQL or ORM materialisation) and lets the DB clean up child rows (SQLite needs the `foreign_keys=ON` PRAGMA the dialect listener installs;
   Postgres/MySQL enforce FK cascades natively).
@@ -757,6 +789,18 @@ Git history is the changelog.
   Planned refactor moves built-in type handlers into an internal dispatch registry that mirrors the user `Hook` list;
   composes with #834.
 
+- **Enum digests** (#1022, survey filed 2026-10-24 — nothing decided;
+  probed on the #1020 branch).
+  Current behaviour: plain `Enum` members are `Indigestible`;
+  `IntEnum`/`StrEnum`/mixin members digest through their mixin's arm under the bare class `__name__` (two same-named classes sharing a value collide;
+  float/`Decimal` mixins go through the number logic).
+  Two bugs the survey found: `Flag` members — and `Flag` classes passed as values — raise `RecursionError` through the `Iterable` arm on 3.11+ (a Flag member iterates and yields itself;
+  `wrapper.py` only falls back on `Indigestible`, so a decorated `f(Perm.R)` *raises* instead of running uncached), and destructuring storage mishandles mixin enums (a `tuple`-mixin member fails `ValueMemory.save` with `ValueError`;
+  a dataclass-mixin member loads back as a bogus non-member).
+  Designs surveyed: digesting the full `{member_name: value}` mapping makes every member's digest depend on the whole class (drifts across Python versions — `http.HTTPStatus` has 62 members on 3.11, 66 on 3.13 — one indigestible sibling poisons all members, ~50× cost);
+  the leaner alternative digests class `__name__` + canonical member name (`None` for Flag pseudo-members) + `_value_` under one enum salt, placed before the whole `match` (float/tuple/date/dataclass mixins), trading away rename-relocatability.
+  Any enum arm changes `IntEnum`/`IntFlag`/`StrEnum`/mixin digests, and relocation only ever helps arguments — a stored result still unpickles through the old module path.
+
 **Open refactor proposals** (small, well-scoped, no PRs yet)
 
 *Source:*
@@ -876,24 +920,14 @@ Git history is the changelog.
   Composes with #883/#905 and #333.
 - #883 — `DestructuringMixin._raw_sub_digests` hardcodes a `match` over the three built-in `Digested` types, so a subclass registered via `register_destructurer` reports zero children: `Cache.gc()` can evict values reachable only through it (silent data loss) and `count_reuses()` under-counts.
   Fix in flight as PR #905 (below).
-- #1004 — digesting a DataFrame with an object column of numpy arrays raises at save time: `hash_pandas_object` calls `factorize`, which needs `hash()`-able elements.
-  Worse, every object column that does *not* raise is hashed through `str()`, so `["a", 1]` collides with `["a", "1"]`, equal-`__str__` objects collide, and `Series([object()])` keys on an address that changes per process;
-  `MultiIndex` levels have the same `str()` weakness, and level names and level dtypes are never folded in at all.
-  Fix in flight as PR #1006 (below);
-  maintainer direction on the issue: be strict (`Indigestible` beats a `str()` fallback), fix the MultiIndex in the same go, and "different tables hash differently" is the main priority.
-
-- Numeric digest collisions — no issue filed yet;
-  the full investigation (2026-10-06) lives in a comment on PR #990.
-  The `Number` arm digests via `hash(value)`, a lossy 61-bit residue, so distinct numbers share cache keys and produce wrong hits end to end: `digest(-1.0) == digest(-2.0)` (CPython reserves `-1` as an error sentinel),
-  `digest(0.5) == digest(2**60)` (rational hashing mod `2**61 - 1`),
-  `inf` vs `314159`,
-  `np.uint64(2**63)` vs `4`, complex via the `hash(a) + 1000003*hash(b)` formula;
-  digests are also platform-dependent (32-bit builds hash mod `2**31 - 1`).
-  The Hypothesis pair tests in `digest/test_digest.py` can't draw these coincidences, and the complex test's oracle restates the bug (`hash(x) == hash(y)` ⇒ equal digests) — regression tests need explicit `@example`s.
-  A second, separable finding: `digest(3) == digest(3.0)` by design, so equal-value different-type *results* share one value-storage entry and whichever saved last wins the return type.
-  The PR comment carries a validated `_digest_number` prototype (digest the exact rational via `as_integer_ratio`, dedicated salts for rational/complex/inf, NaN keeps `struct.pack`;
-  full suite green) pending maintainer decisions on unknown `Number` types (raise `Indigestible` vs keep `hash()`) and on result-type erasure.
-  The fix invalidates number-bearing keys — pre-1.0 that is a `fix:` per [Commit messages](#commit-messages), and it is worth coordinating with the blake2b switchover #615, which invalidates every key anyway.
+- `test-minimum-deps` is red on every run since 2026-10-23, also with no repo change: `ubuntu-latest` moved from ubuntu-24.04 (Python 3.12) to ubuntu-26.04 (Python 3.14, gcc 15), the job's bare `uv venv` uses that system Python, and `--resolution lowest-direct` selects pandas 2.2.0, which has no cp314 wheel and whose Cython 3.0.5 output does not compile under gcc 15.
+  The fix is in flight as PR #1026 (below): `uv venv --python 3.11`, the `requires-python` floor, so the job tests the dependency floors on the oldest supported Python and stops drifting with the runner image.
+  No issue filed yet.
+  Until it merges, a red `test-minimum-deps` on a `src/`-touching PR is likewise not that PR's failure.
+  Running the job on uv's managed 3.11 exposed a real cache-correctness bug, fixed in flight as PR #1028 (below): when `VersionInfo.of` raises `ModuleNotFoundError`,
+  `FunctionProfile.of`'s fallback set `version = None`, dropping the function's own `__version__` (the one `fleche(version=...)` sets) — so two versions of a function from an unimportable module shared one cache key and the second was served the first one's result.
+  Merge order: #1028 first, then rebase #1026 (its `test_fleche_with_version` failure under uv's Python — whose standalone builds ship no stdlib `test` package, so the test's `__module__ = "test"` import genuinely fails — needs the fix).
+
 
 **Feature requests**
 
@@ -906,6 +940,13 @@ Git history is the changelog.
 
 **Field reports**
 
+- #1019 — config lookup misses inside executorlib *file-backend* jobs (`SlurmClusterExecutor`, `TestClusterExecutor`) when `cache_directory` sits behind a symlink: the job chdirs into its task folder,
+  `getcwd()` returns the physical path, the upward `fleche.toml` walk never reaches the project directory, and fleche silently (INFO-level) falls back to a transient memory cache.
+  Inside an MPI/collective job the miss then recomputes on *every rank*.
+  Workarounds that hit: `wrap_executor` in the driver (the `BoundWrapper` carries the cache config into the payload), or resolving cached values in the driver and passing them in — the latter is the only option that also avoids per-rank recompute on a genuinely cold call.
+  Asks in the issue: document the collective-job pattern, make the fallback loud (WARN/raise when a parent had a persistent cache), and a `FLECHE_CONFIG`-style explicit config location (prototype on local branch `claude/fleche-config-env-var`, not pushed;
+  related to #868 and #568).
+
 - #942 — mine it before building anything in this area: migrating ~20k cached calls across a module rename under the default `hash_module=True`.
   The call index was rewritten via `dataclasses.replace(digested_call, module=new)` + `.to_lookup_key()` (reusing fleche's own key derivation), run add-only first against a backup copy, verified by a recompute-counter test (a `contains()` check would pass on a silent recompute), then `--replace` + `VACUUM` (SQLite does not shrink on delete).
   Value storage is untouched — a module rename changes call keys only.
@@ -915,20 +956,60 @@ Git history is the changelog.
 
 - #887 — `BoundWrapper.__reduce__` pre-serialises `func` into a standalone bytes payload (plain `pickle` by reference when importable, `cloudpickle` by value otherwise, a clear `TypeError` when cloudpickle is missing), so it survives `spawn`/`forkserver` pools;
   closes #840, regression pin `tests/regression/test_issue_840.py`.
-- #1006 — digests pandas object columns that pandas cannot hash faithfully with fleche's own per-element hash (anything `infer_dtype` doesn't label `"string"`/`"empty"`, including `bytes` columns and object categories), handing `hash_pandas_object` the column of hex digests;
-  elements fleche cannot digest raise `Indigestible` (strict), plus a new `pd.NA` arm;
-  closes #1004.
-  The 2026-10-19 review round reworked #1006 in place rather than replacing it with the once-superseding branch (`claude/issue-1004-20261013-1959`, never opened as a PR): the pandas arms moved to a new `fleche._pandas` module (`digest.py` no longer imports pandas), a `MultiIndex` arm was added (tuple of its levels, names included — every `MultiIndex` digest changes), and `hash_pandas_object` stays on the main path for faithful columns, so only object-column and `MultiIndex` keys change (migratable via `Cache.redigest()`).
-  The 2026-10-20 round dropped the `__fleche_own_hashed__` marker — no marker records the swap, so a column of arrays digests like the column of its elements' `Digest`s, the Merkle property lists already have — and renamed the helpers to `needs_element_digests`/`element_digests`.
-- #1014 (opened 2026-10-21) — fleche-hosted Postgres/MariaDB call storage with autostart: `calls.type = "postgres"` / `"mariadb"` plus `calls.datadir` (resolved relative to the declaring `fleche.toml`, like `root`) in config;
-  with `calls.autostart = true` the first process that finds nothing listening sets up `datadir` and launches `python -m fleche db …` detached (a `FileLock` on `<datadir>.lock` means racing processes wait for the winner, so exactly one server starts, and it outlives the process).
-  Setup creates database and user `fleche` with a random password and a free port;
-  the URL is written back as `url` into the declaring `fleche.toml` via tomlkit (comments survive), and a readable `DATADIR/fleche.url` takes precedence over it;
-  to support the write-back, the config loader now records which file each top-level table came from.
-  New CLI `python -m fleche db {postgres,mariadb} DATADIR` runs the server in the foreground (`--cache NAME` records the server into config, refusing in-memory values, stacks with several persistent layers, pools and SSH caches) and `python -m fleche db stop DATADIR` shuts it down;
-  `serve` writes host+pid to `DATADIR/fleche.server` before starting, and autostart refuses a datadir another host is serving (shared filesystems).
-  New extras `fleche[postgres]` / `fleche[mariadb]` (sqlalchemy + driver + tomlkit).
+- #1014 / #1017 / #1018 (opened 2026-10-21/22) — fleche-hosted Postgres/MariaDB call storage, a stack of three PRs, each based on the previous.
+  **#1014** (base): new CLI `python -m fleche db {postgres,mariadb} DATADIR` sets up `DATADIR` on first run (database and user `fleche`, random password kept in `DATADIR/fleche.url` mode 0600, a free port remembered across restarts) and runs the server in the foreground;
+  `python -m fleche db stop DATADIR` stops it via the host+pid that `serve` records in `DATADIR/fleche.server`.
+  Config side: `calls.type = "postgres"` / `"mariadb"` plus `calls.datadir` (resolved relative to the declaring `fleche.toml`, like `root`) builds a plain `Sql` on the URL from `DATADIR/fleche.url`, so the password is never copied;
+  nothing listening raises an error naming the start command.
+  New extras `fleche[postgres]` / `fleche[mariadb]`;
+  URLs name their driver explicitly because SQLAlchemy 2.1 changed what driver a bare `postgresql://` selects.
   Rides with two `Sql` concurrency fixes hit with 8 writers on a fresh server database — `create_all`'s check-then-create schema race retries, and `save` retries deadlock-aborted transactions (MariaDB error 1213, Postgres SQLSTATEs `40P01`/`40001`) — and a test-hygiene fix (`_test_missing_dep` now restores the storage registry it used to leave broken for later tests).
+  **#1017** (on #1014): `calls.autostart = true` — when nothing is listening, the first process launches `python -m fleche db …` detached (own session, logging to `<datadir>.log`) and waits until ready;
+  a `FileLock` on `<datadir>.lock` makes racing processes wait for the winner, so exactly one server starts, and it outlives the process.
+  Autostart never *creates* a database — a missing or uninitialized datadir is a `DbServerError` naming the setup command — and refuses a datadir another host is serving (shared filesystems).
+  **#1018** (on #1017): the URL is written back as `url` into the declaring `fleche.toml` via tomlkit (comments survive;
+  the config loader records which file each top-level table came from to support this), and `db --cache NAME` records the server into config (refusing in-memory values;
+  stacks with persistent layers, pools and SSH caches).
+- #1020 (opened 2026-10-23) — fixes the numeric digest collisions found on PR #990 (`hash()` made `digest(-1.0) == digest(-2.0)` and `digest(0.5) == digest(2**60)`): `_digest_bytes`'s `Number` arm stops routing through lossy `hash()` and instead digests each number as the first type on an explicit downcast tree (`int → float → {complex, Fraction → Decimal}`) that holds its exact value, so non-NaN numbers digest equal **iff** they are the same exact value (`1 == 1.0 == 1+0j` as `int`;
+  `0.5 == Fraction(1, 2) == Decimal("0.5")` as `float`), with converters deciding exactness themselves (`as_integer_ratio`, `math.trunc`) rather than trusting numpy's NEP-50 `==`;
+  a `Number` nothing on its path holds exactly raises `Indigestible`, never `hash()`.
+  NaNs digest by their bits, whatever their type;
+  timedeltas (`datetime.timedelta`, `pd.Timedelta`, `np.timedelta64`) now raise `Indigestible` until one digest can honour cross-type equality without unit loss (`total_seconds()` collided distinct `pd.Timedelta`s) — PR #1023 (below), stacked on this one, carries that digest;
+  `datetime.timezone` digests its offset as exact microseconds.
+  Also moves the number arm into a private `fleche._numbers` module and the numpy arms into `fleche._numpy` (the `_pandas` pattern), and extracts a shared `fleche._hashing` module (`new_hash(salt)` + a `running_hash` context manager) that all three use.
+  Persisted keys involving non-integral numbers, `±inf`, complex, huge ints, NaNs or timezones change (`Cache.redigest()` migrates;
+  plain `int` keys are unchanged).
+  Supersedes #990 (closed unmerged 2026-10-24;
+  the numeric-digest investigation referenced under **Bugs** stays readable in its review comments);
+  overlaps #1000's NaN-arm pins, so one of the two needs a rebase.
+- #1023 (opened 2026-10-24, stacked on #1020 — retargets to `main` once that merges) — digests each library's timedeltas by **exact length**, lifting #1020's `Indigestible` refusal: `datetime.timedelta` as exact microseconds (beside the other datetime arms in `digest.py`),
+  `pd.Timedelta` as exact nanoseconds via `to_timedelta64()` (`.value` would overflow;
+  the arm sits in `_pandas` ahead of the `datetime.timedelta` arm it subclasses),
+  `np.timedelta64` as exact attoseconds for every fixed unit,
+  `W` to `as` (in `_numpy`, ahead of `Number` — numpy registers it as `Integral`).
+  Libraries deliberately digest apart even where they compare equal (merging would force a unit-lossy common denominator), units within one library merge, and a timedelta never digests like a number;
+  `Y`/`M` digest as months, the unitless `np.timedelta64(5)` as its count, NaT alike in every unit — numpy's cross-unit `==` can wrap int64, so it is not the reference.
+  `datetime.timezone` digests its offset through the `datetime.timedelta` arm;
+  timedelta64 *arrays*/Series are unchanged (dtype + bytes).
+  `np.datetime64` stays `Indigestible`.
+- #1024 (opened 2026-10-24) — Python 3.15 support: `requires-python` → `>=3.11,<3.16`, 3.15 in the `tests.yml` matrix with `allow-prereleases: true`.
+  The one real breakage: on 3.15 `threading.RLock` is a plain function, so `_factory = threading.RLock` bound as a method and `_PicklableRLock()` raised `TypeError` — took down every `SerializingMixin` storage and `SizeLimitedCache` (~36 failures);
+  the lock factories are now real `@staticmethod`s.
+  The 3.15 job builds h5py from source (no cp315 wheels yet;
+  drop that step once wheels publish) and is **blocked**: `pyiron-snippets` and `bagofholding` both declare `Requires-Python <3.15` on every release, so pip refuses them on 3.15 (options in a PR comment).
+  Also carries the `ty` fix for the pandas-3.1 `pd.util` regression (fixed by #1020) as its own commit, and moves `test_fleche_with_version` off `__module__ = "test"` (only resolves when the stdlib `test` package is installed — uv's standalone builds leave it out).
+- #1026 (opened 2026-10-25) — pins `test-minimum-deps`'s venv to Python 3.11 via `uv venv --python 3.11` (see **Bugs**: the job is red since the runner image moved to ubuntu-26.04, whose system Python 3.14 has no pandas 2.2.0 wheel and fails its source build under gcc 15);
+  keep the pin in sync with the `requires-python` floor.
+  The rejected alternative was raising the numpy/pandas floors for every user just to get cp314 wheels;
+  the 3.12–3.14 interpreters stay covered with current deps by the `tests.yml` matrix.
+  Blocked on #1028 (below) — merge that first, then rebase.
+- #1028 (opened 2026-10-28) — `FunctionProfile.of` keeps an explicit `__version__` when the function's module cannot be imported: the `ModuleNotFoundError` fallback in `src/fleche/call.py` set `version = None` instead of `getattr(func, "__version__", None)`, so two versions of a function from an unimportable module shared one cache key (see **Bugs**).
+  Surfaced by #1026's uv-managed Python, where `test_fleche_with_version`'s mock module name `"test"` stops resolving (uv's standalone CPython ships no stdlib `test` package) and the fallback actually runs.
+  New regression test uses a module name that never exists, so it covers the fallback on every interpreter.
+  Its own `test-minimum-deps` check stays red until #1026's pin lands — the two merge in that order: #1028, then #1026 rebased.
+- #1032 (dependabot, opened 2026-11-04, replacing #1030, closed unmerged the same day) — bumps the pinned `ty` type-checker (the `ty` extra, which the CI job installs) 0.0.89 → 0.0.95.
+  Its `ty` run fails with the same three pandas-3.1 `call-non-callable` diagnostics as `main` before #1020, so the bump neither causes nor clears the known red;
+  `test-minimum-deps` is red as on every PR until #1026 lands, and the 3.11–3.14 test matrix is green.
 - #786 (draft) — a process-wide cache of read-only `h5py.File` handles for multi-bag files (bounded MRU of 32, `(inode, mtime_ns, size)` invalidation, `locking=False`, writers close the cached handle under the per-bag lock);
   multi-bag `contains` drops from ~240 µs to ~29 µs.
   `evict` deliberately untouched;
@@ -944,24 +1025,20 @@ Git history is the changelog.
     Needs a rebase onto `tldr.rst`/`helpers.rst` as they are on `main`.
   - #934 — SSH config + destructuring list.
     Needs a rebase onto `ssh_cache.rst` as #993 left it.
-  - #965 — usage: scope the lazy-return claim to `load()`/`query()`.
-  - #989 — parallel_execution: an MPI-decorated call runs once per rank cold and serves one rank's record warm.
-  - #990 — digests: the numeric-digest mechanism explanation;
-    superseded by its own review — the maintainer judged the rewrite the wrong level ("warrants deeper investigation") and the follow-up investigation on the PR found the digest *code* at fault (see the numeric-digest bullet under **Bugs**), so expect it to close in favour of a code fix rather than merge.
 
-  #932 and #989 both edit `parallel_execution.rst`;
-  whichever lands second needs a rebase.
+  #990 (digests: the numeric-digest mechanism explanation) closed unmerged 2026-10-24 as superseded — its review investigation found the digest *code* at fault, and PR #1020 (above) carries the code fix plus the docs promise.
+  #932 needs a rebase: #989 (merged 2026-10-22) changed `parallel_execution.rst` under it.
 - Test-only coverage sweeps: #939 (pins the `Intent.READ` no-op fast path in both lock mixins;
-  drops 11 tests strictly weaker than a sibling;
+  drops tests strictly weaker than a sibling — rebased 2026-10-23, where three of its eight digest-smoke removals turned out to have already landed via the merged #980 and are now no-ops;
   converts `test_local_function_digests_same_as_module_level` into `test_nesting_changes_a_function_digest` — `CO_NESTED` is in `co_flags`, so lifting a helper out of an enclosing function invalidates its cached calls under `hash_code=True`;
   pinned as observed, flip it there if ruled a bug), #955 (pins the deferred-future abandon arm in `wrapper.py`;
-  collapses five single-property tests in `test_dehydrate.py`), #980 (covers the `storage/sql.py` PRAGMA guards and fixes the dead in-memory journal-mode short-circuit — SQLAlchemy percent-encodes `:memory:`, so the check becomes `engine.url.database in (None, ":memory:")`;
-  drops 11 vacuous digest smokes), #1000 (pins the NaN `struct.pack` arm deterministically — two *simultaneously live* same-value NaNs must share a digest, which `hash()`-routing would break since CPython's NaN hash is address-derived;
+  collapses five single-property tests in `test_dehydrate.py`), #1000 (pins the NaN `struct.pack` arm deterministically — two *simultaneously live* same-value NaNs must share a digest, which `hash()`-routing would break since CPython's NaN hash is address-derived;
   covers the `<d` `Decimal`-NaN sub-arm and the `np.bool_` → builtin-`bool` delegation;
   narrows the Hypothesis float/complex pair tests to `allow_nan=False`, killing their self-fulfilling NaN oracle branches;
   drops four digest tests subsumed *in assertion* by siblings, after a per-test-arc ablation confirmed 89% of tests have zero unique arcs — reaffirming the collective-redundancy lesson below;
   also `.gitignore`s `pytest --cov`'s `.coverage` litter;
-  the PR body flags the next deterministic-coverage picks, led by `bagofholding_file.py`'s seed-dependent `SaveError` arm).
+  the PR body flags the next deterministic-coverage picks, led by `bagofholding_file.py`'s seed-dependent `SaveError` arm;
+  rebased 2026-10-23 and re-measured — note PR #1020 replaces the NaN arm it pins, so one of the two needs a rebase).
 
 **Lessons and standing decisions**
 
@@ -986,8 +1063,7 @@ Git history is the changelog.
   an addon package (`fleche-mpi` or similar) is the preferred home, and the close-out comment on #870 is its reference.
   Branch `claude/fleche-mpi-executor-caching-zxjazw` keeps the helper, 13 subprocess-isolated integration tests, and `docs/mpi_execution.rst`.
   Findings that stand regardless: lookup keys carry no rank, so all ranks contend for one record — warm runs flip the `[result, None]` return shape, and divergent per-rank hit/miss decisions make some ranks skip the body's collectives (silently wrong, or a hang).
-  What works today: decorate the *submission site*, not the MPI kernel.
-  `wrap_executor`'s cold/warm return-shape asymmetry is still undocumented in `docs/parallel_execution.rst` (#989 adds the per-rank warning).
+  User docs stay silent on MPI-native functions: fleche makes no promises either way, so #1037 removed the per-rank caveat #989 had added to `docs/parallel_execution.rst`, and the executorlib example uses task parallelism (`max_workers`) rather than `resource_dict={"cores": N}`.
 - Optional skip-saving of input arguments (#170), corruption-tolerant loads (#93), method-state restoration (#99), metadata-into-value-storage (#82) — parked for milestone 2.0.
 - Refactors flagged `backburner`: `_digest` dispatch registry (#333), `DigestedCall`/`LazyCall` consolidation (#404).
 - Terminology shift "cache" → "stash" and unifying "hash"/"digest" on "digest" (#350) — targeted for 1.0, not started.

{fleche-0.22.2 → fleche-0.22.4}/docs/dev/function_profile.rst

@@ -34,3 +34,8 @@ correctly without special-casing at call sites.
 ``FunctionProfile`` and populate it inside ``FunctionProfile.of``.  Downstream
 code then reads it from the profile instead of calling introspection APIs
 directly.
+
+See :doc:`/usage/helpers` ("Per-Function Static Caching") for the
+user-facing behavior and caveats — including the "mutating ``func`` after
+the first call isn't picked up" gotcha and how to clear the cache via
+``_profile.cache_clear()``.

{fleche-0.22.2 → fleche-0.22.4}/docs/dev/ssh_cache.rst

@@ -4,9 +4,9 @@
 ======================
 
 This page is a tour of :mod:`fleche.remote` for contributors hacking on the
-cross-machine cache.  End-user documentation lives in
-:doc:`/storage/configuration`; this page explains *how* the pieces fit
-together.
+cross-machine cache.  End-user configuration lives in
+:doc:`/storage/configuration` (see its ``type = "ssh"`` section); this page
+explains *how* the pieces fit together.
 
 Security model
 --------------

{fleche-0.22.2 → fleche-0.22.4}/docs/digests/digest_equivalence.rst

@@ -9,24 +9,77 @@ hold the same numeric value, and ``digest((1, 2)) != digest([1, 2])`` because th
 container type matters.  This page documents the deliberate equivalences ``fleche``
 guarantees, and the boundaries you should keep in mind.
 
-The digest function is content-based: it walks each value, typically salts the
-running hash with ``type(value).__name__`` for type discrimination, and folds in a
-representation that is stable across processes and Python versions (where the
+The digest function is content-based: it walks each value and folds in its type
+and a representation that is stable across processes and Python versions (where the
 underlying object's representation allows it).
 
-Number types (``int``, ``float``, ``complex``, and subclasses) are an explicit
-exception: their digest is computed via Python's numeric hash protocol
-(``hash(value)``), which itself guarantees ``hash(1) == hash(1.0) == hash(1+0j)``.
-The type name is therefore **not** carried into the final digest for numbers, which is
-precisely why ``digest(1) == digest(1.0) == digest(1+0j)``.
-
-``bool`` is the one numeric subclass excluded from this equivalence: it keeps
-its own type-name salt, so ``digest(True) != digest(1)`` even though
-``isinstance(True, int)``.
-
-For all other types the type-name salt is applied normally, so
-``digest((1, 2)) != digest([1, 2])`` because "tuple" and "list" diverge before
-the elements are processed.
+Numbers
+-------
+
+Numbers digest by their value, not their type: ``1``, ``1.0``, ``1+0j`` and
+``Fraction(1)`` all digest alike.  To find that value, ``fleche`` walks a fixed
+tree of number types:
+
+.. code-block:: text
+
+   int
+   ├── numbers.Integral
+   └── float
+       ├── complex
+       │   └── numbers.Complex
+       └── fractions.Fraction
+           ├── decimal.Decimal
+           └── numbers.Real
+
+A number's place in the tree is its class or, for a type the tree does not
+name, the :mod:`numbers` ABC the type belongs to; that is where numpy scalars
+such as ``np.int64`` or ``np.float32`` sit.  The digest walks from ``int`` down
+to that place and tries to convert the number to each type it passes.  The
+first type that holds the number exactly digests it: ``0.5`` is no ``int`` but
+an exact ``float``, and ``Fraction(1, 3)`` is neither, so it digests as a
+``Fraction``.  A complex number with no imaginary part digests as its real
+part.  A number that no type on its path holds exactly is
+:exc:`~fleche.digest.Indigestible` unless a hook handles it.
+
+Two numbers therefore digest equal exactly when they hold the same exact value.
+Three kinds of value are not digested as numbers:
+
+* ``bool`` and other ``int`` subclasses, such as ``IntEnum`` members, digest
+  as their own type, so ``digest(True) != digest(1)``.
+* NaNs equal nothing, so they digest by their bit pattern: NaNs with the same
+  bits digest alike whatever their type.
+* Timedeltas (``datetime.timedelta``, ``pd.Timedelta`` and ``np.timedelta64``)
+  are refused with :exc:`~fleche.digest.Indigestible` for now, although numpy
+  counts ``np.timedelta64`` as a ``numbers.Integral``.  A hook registered with
+  :func:`~fleche.digest.add_hook` can digest them meanwhile.
+
+For example:
+
+.. code-block:: python
+
+   digest(1) == digest(1.0) == digest(1 + 0j) == digest(Fraction(1))   # as int
+   digest(0.5) == digest(np.float32(0.5)) == digest(Decimal("0.5"))     # as float
+   digest(Fraction(1, 10)) == digest(Decimal("0.1"))                    # as Fraction
+   digest(-1.0) != digest(-2.0)
+   digest(0.1) != digest(Decimal("0.1"))   # the float is not exactly 1/10
+   digest(True) != digest(1)
+
+A number is converted to a lower type only when the conversion is lossless, so
+``digest(a) == digest(b)`` exactly when ``a`` and ``b`` are numerically equal.
+For standard library types this agrees with ``==``, but third party types do not
+always: numpy casts a Python float down to the precision of a numpy scalar
+before comparing (so ``np.float32(0.1) == 0.1``), rounds a ``Fraction`` to
+double, and compares a huge ``np.longdouble`` with an ``int`` through their
+string forms.  Following that ``==`` would let unequal values share a cache
+entry, so ``fleche`` goes by the exact value instead: ``np.float32(0.1)``
+stores 0.100000001490116…, and digests apart from ``0.1``.
+
+Other types
+-----------
+
+Every other value digests by its type as well as its content, so
+``digest((1, 2)) != digest([1, 2])``: a tuple and a list never digest alike,
+whatever their elements.
 
 Dataclasses and ``attrs`` classes
 ---------------------------------

{fleche-0.22.2 → fleche-0.22.4/docs}/notebooks/ConcurrentExecution.ipynb

@@ -454,11 +454,11 @@
     "\n",
     "```python\n",
     "with cache(shared_cache):\n",
-    "    with SingleNodeExecutor() as executor:\n",
+    "    with SingleNodeExecutor(max_workers=4) as executor:   # 4 tasks at once\n",
     "        wrap_executor(executor)\n",
     "        future = executor.submit(\n",
     "            expensive, 5,\n",
-    "            resource_dict={\"cores\": 4},   # goes to SingleNodeExecutor.submit\n",
+    "            resource_dict={\"threads_per_core\": 2},   # goes to SingleNodeExecutor.submit\n",
     "        )\n",
     "        future.result()                    # goes to expensive\n",
     "```\n",