feat(storage): cache filesystem paths by content

[pmrv]

Stacked on #793 (prepared-call) — merge that first; this PR shows only the path-caching commits on top of it.

What

First-class support for Path values in cached functions (#516, #33, #517): files and directories are stored by content and rematerialized under temporary paths on cache hits.

• Identity: a file is (basename, content); a directory is its tree alone (child names in, root name out); plain bytes is the content-only escape hatch. Nonexistent paths warn and run uncached (What's the digest of a non existing file? #517).
• Storage: PathValueMixin converts paths to FileBlob/DirectoryBlob records referencing content-addressed bytes blobs (identical bodies deduplicate across names, directories, and bytes values), wired into every default value storage. Digest salts mirror storage exactly, preserving digest(path) == save(path).
• Materialization: hits return TempPaths — Path subclasses whose backing temp tree lives while any derived path is referenced (3.12+ via with_segments; 3.11 via a weak registry of live roots).
• Destructuring: paths are found inside dicts / lists / tuples / dataclasses / attrs, as values or keys, at any depth. DigestedDict is generalized to a type-preserving DigestedMapping; the destructurer predicate is an exact-type allowlist (dict, OrderedDict, list, tuple) since subclasses may repurpose the type(value)(pairs) reconstruction contract (defaultdict, Counter).

Docs

• docs/usage/file_semantics.rst — the full user-facing contract (identity, materialization, lifetime, nesting, opaque containers, argument mutation, fidelity limits). Black-box validated: agents restricted to reading only this page wrote assertion scripts against it over three rounds; every failed or ambiguous expectation was folded back into the text.
• Recipes page, dev-internals page, and a runnable notebooks/PathsInContainers.ipynb exploring the container-nesting edge cases.

Interplay with #793

Path arguments make argument mutation easy (writing into a received directory), so this branch is where the two-phase save protocol pays off visibly: tests/integration/test_path_mutation.py pins that mutating consumers hit on honest repeats, the mutated tree is a distinct call, and a mutated argument passed back out is captured in its final state.

Full suite green on Python 3.13 and 3.11.

🤖 Generated with Claude Code

[claude]

🤖 CI failure summary for 6ed3580 on temppath

Summary
Type checking failed with three type errors in src/fleche/storage/. The code is calling object.__init__() and type() constructors with arguments where the type signature expects none.

Root cause
Two instances of calling type constructors with an iterable argument, and one unsupported class base:

error[too-many-positional-arguments]: Too many positional arguments to `object.__init__`: expected 1, got 2
   --> src/fleche/storage/destructuring.py:133:13 & 146:28

error[unsupported-base]: Unsupported class base
  --> src/fleche/storage/paths.py:12:16
  class TempPath(type(Path())):

Suggested fix

1. In destructuring.py:133 and 146: replace direct type construction with a dict constructor or explicit object initialization
2. In paths.py:12: change the base class from type(Path()) to pathlib.Path directly, or use a compatible mixin approach
3. Run ty check src/ locally to verify the fixes

---

Generated by Claude Haiku 4.5.

[github-actions]

Benchmark Results

Baseline: efeeebc (recomputed) · HEAD~: 2da4b10

Delta

Significant changes (|Δ| > 10%): 7 — 233 other rows hidden

Integration

configuration	workload	function	time @ efeeebc	time @ head	Δ vs base	Δ vs 2da4b10
SizeLimitedCache(Memory,max=10)	data_heavy	hit	190 µs	190 µs	+0.0%	🟢 -64.8%
H5+Sql	lightweight	miss	7.3 ms	6.1 ms	🟢 -16.4%	+1.7%
H5+Sql	data_heavy	miss	7.8 ms	6.8 ms	🟢 -12.8%	+0.0%
H5+Sql	compute_heavy	miss	7.9 ms	6.9 ms	🟢 -12.7%	+0.0%
SizeLimitedCache(Memory,max=10)	compute_heavy	hit	170 µs	190 µs	🔴 +11.8%	+5.6%

Value Storage

configuration	workload	function	time @ efeeebc	time @ head	Δ vs base	Δ vs 2da4b10
CloudpickleFile_Signed	nested_structures	save	360 µs	390 µs	+8.3%	🔴 +11.4%
DillFile	numpy_arrays	save	620 µs	660 µs	+6.5%	🔴 +10.0%

Full results

Call Storage

calls

configuration	contains_hit	contains_miss	evict	load	save
🔴 SqlFile	🟩 270 µs	🟩 250 µs	🟩 480 µs	🟩 750 µs	🟥 2.2 ms
🔴 SqlMemory	🟩 260 µs	🟩 250 µs	🟩 290 µs	🟩 730 µs	🟧 2 ms

Digest

workload	digest
Dict (small)	🟩 1.5 ms
Float	🟩 270 µs
Integer	🟩 140 µs
List (integers, len<100)	🟩 970 µs
List (integers, len>100)	🟥 28 ms
Nested (Random Hypothesis)	🟩 3.7 ms
None	🟩 120 µs
Numpy (integers, len<100)	🟩 940 µs
Numpy (integers, len>100)	🟩 2.7 ms
String (len<100)	🟩 140 µs
String (len>100)	🟩 230 µs

Integration

compute_heavy

configuration	contains_hit	contains_miss	hit	miss
🟠 H5+Sql	🟩 390 µs	🟩 390 µs	🟨 3 ms	🟥 6.9 ms
🟢 Pickle+Sql	🟩 390 µs	🟩 380 µs	🟩 1.4 ms	🟨 4 ms
🟣 Memory	🟩 81 µs	🟩 82 µs	🟩 160 µs	🟩 1.2 ms
🟣 Memory(Raw)	🟩 76 µs	🟩 76 µs	🟩 150 µs	🟩 1.1 ms
🟣 SizeLimitedCache(Memory,max=10)	🟩 84 µs	🟩 85 µs	🟩 190 µs	🟩 1.2 ms
🟣 SizeLimitedCache(Memory,max=100)	🟩 84 µs	🟩 84 µs	🟩 160 µs	🟩 1.2 ms
🟤 Memory+Sqlite(:memory:)	🟩 380 µs	🟩 370 µs	🟩 980 µs	🟨 2.7 ms

data_heavy

configuration	contains_hit	contains_miss	hit	miss
🟠 H5+Sql	🟩 400 µs	🟩 380 µs	🟨 3.1 ms	🟥 6.8 ms
🟢 Pickle+Sql	🟩 390 µs	🟩 380 µs	🟩 1.4 ms	🟨 3.5 ms
🟣 Memory	🟩 82 µs	🟩 82 µs	🟩 170 µs	🟩 490 µs
🟣 Memory(Raw)	🟩 75 µs	🟩 76 µs	🟩 160 µs	🟩 450 µs
🟣 SizeLimitedCache(Memory,max=10)	🟩 84 µs	🟩 84 µs	🟩 190 µs	🟩 500 µs
🟣 SizeLimitedCache(Memory,max=100)	🟩 84 µs	🟩 84 µs	🟩 180 µs	🟩 510 µs
🟤 Memory+Sqlite(:memory:)	🟩 370 µs	🟩 370 µs	🟩 1 ms	🟩 2 ms

lightweight

configuration	contains_hit	contains_miss	hit	miss
🟠 H5+Sql	🟩 390 µs	🟩 370 µs	🟨 2.9 ms	🟥 6.1 ms
🟢 Pickle+Sql	🟩 390 µs	🟩 380 µs	🟩 1.4 ms	🟨 3.3 ms
🟣 Memory	🟩 83 µs	🟩 83 µs	🟩 160 µs	🟩 350 µs
🟣 Memory(Raw)	🟩 74 µs	🟩 75 µs	🟩 150 µs	🟩 310 µs
🟣 SizeLimitedCache(Memory,max=10)	🟩 83 µs	🟩 84 µs	🟩 180 µs	🟩 380 µs
🟣 SizeLimitedCache(Memory,max=100)	🟩 84 µs	🟩 85 µs	🟩 170 µs	🟩 360 µs
🟤 Memory+Sqlite(:memory:)	🟩 380 µs	🟩 370 µs	🟩 1 ms	🟩 1.8 ms

Value Storage

nested_structures

configuration	contains_hit	contains_miss	evict	load	save
🔵 CloudpickleFile	🟩 33 µs	🟩 33 µs	🟩 57 µs	🟩 290 µs	🟩 380 µs
🔵 CloudpickleFile_Signed	🟩 33 µs	🟩 33 µs	🟩 57 µs	🟩 300 µs	🟩 390 µs
🟠 BagOfHoldingH5File	🟩 270 µs	🟩 33 µs	🟩 260 µs	🟧 1.1 ms	🟥 1.5 ms
🟡 DillFile	🟩 33 µs	🟩 33 µs	🟩 59 µs	🟩 290 µs	🟩 400 µs
🟡 DillFile_Signed	🟩 33 µs	🟩 34 µs	🟩 57 µs	🟩 300 µs	🟩 400 µs
🟢 PickleFile	🟩 33 µs	🟩 33 µs	🟩 57 µs	🟩 280 µs	🟩 350 µs
🟢 PickleFile_Signed	🟩 33 µs	🟩 33 µs	🟩 55 µs	🟩 290 µs	🟩 380 µs
🟣 Memory	🟩 7 µs	🟩 6.9 µs	🟩 7.3 µs	🟩 8.8 µs	🟩 9.8 µs
🟣 Memory(Raw)	🟩 1.9 µs	🟩 1.8 µs	🟩 2.1 µs	🟩 3.3 µs	🟩 3.7 µs

numpy_arrays

configuration	contains_hit	contains_miss	evict	load	save
🔵 CloudpickleFile	🟩 33 µs	🟩 34 µs	🟩 120 µs	🟩 310 µs	🟩 470 µs
🔵 CloudpickleFile_Signed	🟩 33 µs	🟩 34 µs	🟩 110 µs	🟩 380 µs	🟩 540 µs
🟠 BagOfHoldingH5File	🟩 270 µs	🟩 34 µs	🟩 690 µs	🟧 1.8 ms	🟥 2.3 ms
🟡 DillFile	🟩 33 µs	🟩 34 µs	🟩 120 µs	🟩 330 µs	🟩 660 µs
🟡 DillFile_Signed	🟩 33 µs	🟩 33 µs	🟩 120 µs	🟩 400 µs	🟩 720 µs
🟢 PickleFile	🟩 34 µs	🟩 34 µs	🟩 120 µs	🟩 320 µs	🟩 440 µs
🟢 PickleFile_Signed	🟩 33 µs	🟩 33 µs	🟩 120 µs	🟩 380 µs	🟩 510 µs
🟣 Memory	🟩 6.9 µs	🟩 6.9 µs	🟩 7.5 µs	🟩 14 µs	🟩 15 µs
🟣 Memory(Raw)	🟩 1.9 µs	🟩 1.8 µs	🟩 2.1 µs	🟩 7.8 µs	🟩 8.3 µs

small_strings

configuration	contains_hit	contains_miss	evict	load	save
🔵 CloudpickleFile	🟩 33 µs	🟩 32 µs	🟩 100 µs	🟩 280 µs	🟩 350 µs
🔵 CloudpickleFile_Signed	🟩 32 µs	🟩 33 µs	🟩 110 µs	🟩 290 µs	🟩 360 µs
🟠 BagOfHoldingH5File	🟩 280 µs	🟩 33 µs	🟨 600 µs	🟥 1.7 ms	🟥 1.7 ms
🟡 DillFile	🟩 33 µs	🟩 33 µs	🟩 110 µs	🟩 290 µs	🟩 370 µs
🟡 DillFile_Signed	🟩 32 µs	🟩 33 µs	🟩 110 µs	🟩 300 µs	🟩 380 µs
🟢 PickleFile	🟩 33 µs	🟩 33 µs	🟩 110 µs	🟩 280 µs	🟩 350 µs
🟢 PickleFile_Signed	🟩 33 µs	🟩 33 µs	🟩 110 µs	🟩 290 µs	🟩 350 µs
🟣 Memory	🟩 7 µs	🟩 6.9 µs	🟩 7 µs	🟩 8.7 µs	🟩 9.2 µs
🟣 Memory(Raw)	🟩 1.9 µs	🟩 1.8 µs	🟩 1.9 µs	🟩 3.2 µs	🟩 3.6 µs

[pmrv]

revise

[pmrv]

feels almost more like it should go into a more generic section rather than file specific.

[pmrv]

cross ref destructuring here, since that's the key

[pmrv]

save executed version

[pmrv]

move the completedprocess digester into fleche itself

[pmrv]

Interactions with ssh cache unclear

[pmrv]

Pushed 4e2083e here as you asked (from the #831 thread) — ty check src/ is green on main but was reporting three diagnostics on this branch, so the ty workflow was failing for every PR into it, and after #831 landed, for the branch itself.

Three suppression comments, no behaviour change:

-            (self.get(storage, k), self.get(storage, v))
+            (self.get(storage, k), self.get(storage, v))  # ty: ignore[too-many-positional-arguments]

-        return type(value)(zip(children[:n], children[n:]))
+        return type(value)(zip(children[:n], children[n:]))  # ty: ignore[too-many-positional-arguments]

-class TempPath(type(Path())):
+class TempPath(type(Path())):  # ty: ignore[unsupported-base]

Both are false positives on code that's correct at runtime. In DigestedMapping, ty narrows type(value) to type[Mapping] — an ABC with no __init__ — so the call resolves to object.__init__ and the argument reads as one positional too many; the runtime type is always a concrete dict/OrderedDict. For TempPath, ty can't resolve an MRO through a dynamic base, and that indirection has to stay while 3.11 is supported, since bare Path only became subclassable in 3.12.

I suppressed rather than reworked: a cast on the two constructors trades a checker complaint for an indirection that earns nothing, and the TempPath base can't change until the 3.11 floor moves. Say the word if you'd rather have the cast version in destructuring.py. Placement matters — ty binds a suppression to the line it reports, which for the first one is the generator expression, not the return type(self.items)( above it.

Verified with the pinned ty == 0.0.62 CI uses: All checks passed! Suite unchanged at 1763 passed / 11 skipped.

#828 is rebased on top of this and green locally (1788 passed / 11 skipped).

---

Generated by Claude Code

[pmrv]

Conflict resolved in fa5d2d2 — but it wasn't only textual, and your instinct about the path/destructuring interaction was right, just in a different place than depth. Two real bugs came out of it.

1. prepare is a fourth values-over-the-wire route

prepared-call adds SshCache.prepare, which ships the whole live call so the remote stashes argument values before the body runs. #828's guard covered save_value, save, and load_value — not this. So a path argument would have gone over as a bare string for the server to resolve against its own filesystem: the same silent digest(x) == save_value(x) break, via a new door. (The old comment there even said "paths over SSH are unsupported" — again, nothing enforced it.)

Resolved by keeping both sides and closing the route:

• save now handles PreparedCall as well as the live-Call and DigestedCall forms, and routes the result through save_value rather than _rpc so the guard applies to it.
• prepare falls back to the local BaseCache two-phase prepare when any argument carries a path. Each argument then goes through save_value, where a path degrades to a digest-only reference computed locally — seal intact, lookups still hit. Same degradation fix(remote): refuse Path values at the SshCache boundary #828 established elsewhere, no new concept. The fallback is narrow: ordinary calls keep the one-round-trip path, pinned by a test.

2. The guard was mirroring the wrong walk

Chasing your concern I checked remaining_depth first, and it's clean — 36/36 across remaining_depth ∈ {0,1,2,3,5,10} × nesting depth ∈ {0,1,2,3,5,8}, with the original file deleted before load, and with the setting verified to actually change storage layout (17 → 10 → 3 → 1 entries). A Path matches no destructurer, so its depth stays inf, it's never inlined, and PathValueMixin always gets it.

But the check turned up something worse. find_path mirrored destructuring — and the invariant at stake is digest(x) == save_value(x), while digest recurses further than destructuring does:

value	destructuring	digest reads the file	guard saw it (before)
[path]	descends	yes	yes
Bundle(path, 0.5) (namedtuple)	opaque	yes	no
{path} (set)	opaque	yes	no
frozenset({path})	opaque	yes	no

A path hidden in any of those still decides the key, so it crossed the wire and the server digested that name against its own disk. Locally this is harmless — same process, same filesystem — which is exactly why it wasn't visible before.

find_path now follows digest, stopping where digest stops (an arbitrary object is Indigestible, so no path inside it can decide a key) and declining to consume one-shot iterables rather than exhausting them as a side effect.

Verification

1807 passed / 11 skipped, ty check src/ clean. New tests pin: prepare not shipping a path-carrying call while still using the remote for ordinary ones, commit rejecting a path result, and namedtuple/set paths being refused at the boundary.

Two API changes on your branch that my #828 tests had to follow: PreparedCall.key → to_lookup_key(), and Cache.save_value is gone in favour of the two-phase protocol.

---

Generated by Claude Code

[pmrv]

Merged main in ad7b883, which means CI here will go red on FiveMinuteTour.ipynb — the ase problem from my last comment, still unfixed on main.

I held the merge back for a day to keep this PR green. What forced it: #856 rewrote the same agents/DEVELOPING.md notebook enumeration this branch edits, so GitHub flipped #797 to dirty. A conflicted PR can't be merged at all, a red one can be read — so I took the red rather than leave the conflict sitting.

Everything except that one notebook passes: 1909 passed, 11 skipped, FiveMinuteTour deselected. The three options are unchanged (add ase to the tests extra / skip notebooks whose imports are unavailable / drop the ASE cell) and I still haven't picked one — say the word and I'll do it here or in a separate PR against main.

The conflict itself resolved to the union: twelve notebooks, twelve symlinks, main's FiveMinuteTour beside this branch's Files and PathsInContainers, and this branch's purity / file_semantics / path_storage / recipes/files_and_paths pages. docs/index.rst auto-merged and I verified its entries survived.

One new thing worth your eyes, unrelated to the above. Sphinx now emits a warning that it didn't before:

docs/autoapi/fleche/index.rst:256: WARNING: duplicate object description of
fleche.D, other instance in digests/digests_as_args, use :no-index: for one of them

I checked this rather than guessing at it:

• origin/main builds clean — I built it in a separate worktree to be sure.
• This tree warns reproducibly, twice in a row, fresh output dir each time.
• docs/digests/digests_as_args.rst is byte-identical to main's and already carries :no-index:.

So it isn't a change to that page — it's that the extra pages here shift the order in which Sphinx reads documents relative to the autoapi-generated one, and the generated instance is the one without :no-index:. The build still succeeds (exit 0, one warning), so nothing is broken, but it would presumably show up on the next docs build on main once this lands. The fix belongs in the autoapi config rather than in path work, so I've left it alone — happy to take it if you'd like it fixed here.

Findings 1–5 and 7 remain done; still awaiting you on finding 6, the object-dtype ndarray digest issue, dropping child_slots, and the store-before-register gc window.

---

Generated by Claude Code

[claude]

🤖 CI failure summary for ad7b883 on temppath

Summary
Notebook test FiveMinuteTour.ipynb fails on both Python 3.13 and 3.14 due to a missing dependency. The notebook execution fails when trying to import the ase module.

Root cause
The ase package is not included in the test environment dependencies:

ModuleNotFoundError: No module named 'ase'

This occurs when executing the FiveMinuteTour.ipynb notebook, suggesting it was recently added or its imports changed without updating the test environment setup.

Suggested fix

1. Identify where ase is imported in the notebook and verify it's necessary
2. Add ase to the project's test dependencies (likely setup.py, requirements.txt, or pyproject.toml)
3. Re-run the tests to confirm the fix

---

Generated by Claude Haiku 4.5.

[claude]

🤖 CI failure summary for 4468aaf on temppath

Summary

The test notebook FiveMinuteTour.ipynb fails during execution because the ase (Atomic Simulation Environment) module is not installed. This affects both Python 3.11 and 3.12 test runs (1 failure out of 1920+ tests per run).

Root cause

ModuleNotFoundError: No module named 'ase'

The notebook attempts to import from ase.build and ase.calculators.emt, but the package is missing from the test environment.

Suggested fix

Add ase to the project's test dependencies in setup.py, pyproject.toml, or requirements-dev.txt. This dependency is needed for the FiveMinuteTour tutorial notebook to execute during CI validation.

---

Generated by Claude Haiku 4.5.

[pmrv]

Thanks for #857 — merged it here in f2ec078. It doesn't clear CI yet, though: the same notebook still fails, one cell later.

I ran it after merging rather than assuming the fix was complete:

ModuleNotFoundError: No module named 'executorlib'

Cell 30:

from executorlib import SingleNodeExecutor as Executor

Bare import, no guard — and executorlib is its own optional extra in pyproject.toml, not part of tests, which is all tests.yml installs. So it's the same shape as the ase case: the notebook reaches for an optional dep that CI never has.

The try/except ImportError you added for the ASE section applied to this import would do it:

try:
    from executorlib import SingleNodeExecutor as Executor
except ImportError:
    print("executorlib not installed, skipping this section")
else:
    ...

I haven't pushed that — it's your notebook and you're evidently mid-fix, so a duplicate patch from a path PR would just collide with whatever you land next. Say the word if you'd rather I did it here.

Worth noting the two filters that let this class of thing through, since it'll keep happening: the changes gate skips the suite for notebook-only PRs, and tests.yml doesn't run on pushes to main — so a notebook that reaches for an optional dep goes unnoticed until some unrelated PR touching src/ picks up the red. That's how #841 landed, and why #857's remaining half is only visible from here.

Everything else on this branch is unchanged and green: 1909 passed, 11 skipped with that notebook deselected.

Still open for you, unchanged: the Sphinx fleche.D duplicate-object warning (main builds clean, this tree warns reproducibly — fix belongs in the autoapi config), finding 6, the object-dtype ndarray digest issue, dropping the now-unused child_slots, and whether to close the store-before-register gc window with a readers-writer lock.

---

Generated by Claude Code

[claude]

🤖 CI failure summary for f2ec078 on temppath

Summary

Notebook integration tests are failing because executorlib is not installed. The FiveMinuteTour.ipynb notebook attempts to import SingleNodeExecutor from executorlib but the dependency is missing from the test environment.

Root cause

ModuleNotFoundError: No module named 'executorlib'
  File FiveMinuteTour.ipynb, Cell In[16], line 1
    from executorlib import SingleNodeExecutor as Executor

Both Python 3.12 and 3.14 environments are affected.

Suggested fix

Add executorlib to the project's test dependencies (requirements.txt, setup.py, or pyproject.toml). If this is a new dependency on the temppath branch, ensure it's properly declared before merging.

---

Generated by Claude Haiku 4.5.

[pmrv]

#862 does it — merged in d032f71, and this branch is green again, for the first time since #841 landed.

Verified after merging rather than assuming: the notebook that had been failing now passes on its own, and the full suite is 1910 passed, 11 skipped, zero failures. ty 0.0.65 clean.

The Sphinx fleche.D warning is also gone — and nothing on this branch changed to fix it. As I said when I reported it, it was an ordering effect between the autoapi-generated page and digests_as_args rather than a content problem; your docs churn since has evidently shifted the read order back. The build is now warning-free here. So that one is closed, no action needed from you.

Where #797 stands:

Finding	Status
1 — gc() destroys stored Path values	fixed, 28df4cd
2 — gc() evicts in-flight arguments	fixed, a9e1a13 + ff168a0 + 35c3aae
3 — SSH path fallback degrades all arguments	fixed, 4c10b92
4 — find_path misses re-iterable containers	fixed, 4d6ded1
5 — unreadable paths raise	fixed, 59f17e6
7 — test leaks the sticky cache	fixed, 58a0cfe
6 — three round trips per remote miss	your call, untouched

Still open for you, all small and all previously described:

1. Finding 6 — collapse the commit's two trips into one commit RPC. You called it take-or-leave; it also closes the partial-failure window your own comment on save flags, and it interacts with the finding-3 fix (a path-carrying prepare now costs a trip per argument), so both places want batching together if you want it at all.
2. child_slots — I added it in fix(remote): refuse Path values at the SshCache boundary #828 to back the old destructuring-shaped find_path; nothing calls or tests it now, but it is exported in fleche.storage.__all__. Drop it or keep it as a general helper?
3. Object-dtype ndarray digests are address-based — digest(np.array([mk()], dtype=object)) differs between two equal arrays, so such arguments never hit across processes. Pre-existing, unrelated to this PR, semver-breaking to fix. Want an issue?
4. The gc store-before-register window — the one race the ordering fix does not close, pinned by test_gc_may_evict_a_value_stored_but_not_yet_registered. Closing it needs a readers-writer lock shared by writers and the sweep; it is the same window one-shot save has always had, so it is arguably a separate change.

Nothing here blocks a merge — 1, 3 and 4 are questions, 2 is optional cleanup. Happy to take any of them on your word.

---

Generated by Claude Code

[pmrv]

test-minimum-deps went red on 30a9ccc — pre-existing digest collision on main, not this branch

30a9ccc is a merge of main that touches only agents/DEVELOPING.md, so I treated any red as new and mine. It isn't — but what it found is a real correctness bug in main, so I'd rather flag it than re-run past it silently.

What failed

Hypothesis found a falsifying example for tests/unit/storage/test_destructuring_storage.py::test_roundtrip:

value  = {None: [-512], '': -2.220446049250313e-16}
loaded = {None: [-2.220446049250313e-16], '': -2.220446049250313e-16}

The -512 came back as -2.220446049250313e-16 because the two share a digest:

>>> digest(-512) == digest(-2.220446049250313e-16)
True
>>> -512 == -2.220446049250313e-16
False

Why

The Number() arm of _digest_bytes ends with value = hash(value); return _digest_bytes(value) — a float's digest is the digest of the int hash(value). hash(-2**-52) == -512, so the float and the int -512 are indistinguishable to the cache.

That is the documented mechanism (docs/digests/digest_equivalence.rst: the type-name salt is deliberately not carried into number digests, which is what makes digest(1) == digest(1.0) == digest(1+0j)). What the docs assume, though, is that hash is injective. It isn't — it's a 61-bit fold — so the intended equal-values-collide becomes unequal-values-collide. Every non-integral float aliases some int:

value	hash(value)	equal?	same digest?
0.5	1152921504606846976	no	yes
0.1	230584300921369408	no	yes
1e308	156575653125701	no	yes
Fraction(1,3)	1537228672809129301	no	yes
Decimal("0.5")	1152921504606846976	no	yes

It reaches cache keys, not just digest():

>>> f.digest(0.5) == f.digest(1152921504606846976)
True

— i.e. f(0.5) can return the cached result of f(1152921504606846976).

Not from this branch

• The collision reproduces against origin/main's src/fleche/digest.py in a clean worktree (COLLIDES ON MAIN: True).
• This branch does not touch the Number arm; its digest.py changes are the Path / CompletedProcess arms and OPAQUE_ITERABLES.
• tests/strategies.py — which generates the example — is unchanged here, so main's own CI can draw this same example on an unlucky seed.

Seed-dependent: 3000 derandomized examples pass on both main and this branch, which is why it has stayed hidden.

What I'm not doing

Not fixing it here. Salting number digests by type (or by exact value) changes the digest of every float, complex, Fraction and Decimal, invalidating every persisted call that has one as an argument or result — a migration decision for a persistent cache, and squarely yours, not something to smuggle into a path-caching PR. Happy to take it in a follow-up if you want it, in whichever direction you prefer (full type+value salt, or keep cross-type equivalence but digest the exact value rather than hash).

I've re-run the failed job so the PR's CI state isn't left red on a seed accident. Flagging this alongside the four questions in this comment — still all awaiting your call, none started.

---

Generated by Claude Code

[pmrv]

Believe it or not the solution to the gc() vs Path problem is more abstract indirection! Behind both path and destructuring mixin we add another interface that recurses into selected items and route all item access through that. path and destructuring then implement that for their specific types.