fix(remote): refuse Path values at the SshCache boundary

[pmrv]

Answers your comment on #797, "Interactions with ssh cache unclear". Targets temppath.

The four inline review threads on #797 moved to #831, which has since merged — temppath was merged back in here (f938975, no conflicts), so this PR is the SshCache × Path work only.

What the interaction actually was

Probed with a real python -m fleche remote --serve subprocess, client and server in different working directories so the same relative name denotes different files on each side. Three behaviours, all silent:

	before
server can see something at that name	stores its bytes, returns its digest — digest(x) == save_value(x) broken, so the record is filed under a key no client recomputes, and a load returns the wrong content
server can see nothing there	Indigestible surfaces from inside an RPC
loading a path stored remotely	server materializes into a temp dir on its disk and sends back only the name — dangling here, and unlinked there as soon as its own reference dies

The last one is not fixable by holding a reference: PurePath.__reduce__ rebuilds from parts alone, so TempPath's _temp_root is dropped in transit and _live_roots is per-process. The save_value comment already said "paths over SSH remain unsupported" — nothing enforced it.

What this does

Refuses, in both directions, via a new RemotePathUnsupported. It subclasses SaveError, so the two-phase-save degradations already in the codebase carry it and no caller special-cases anything:

• path argument → digest-only reference, digest computed locally. The seal stays intact, lookups hit and miss correctly; only the bytes aren't retrievable from the remote record.
• path result → Rejected. The call runs, returns the file, is logged as not cached.
• load → raises, lazily. A record whose result is a path still loads and queries; only touching the path value raises.

Detection is storage.paths.find_path, walking a value through a new storage.destructuring.child_slots — the read-only half of _intern_rec's dispatch — so nesting is covered exactly as far as a destructuring save reaches, and no further (a path inside an opaque object is still stored by location, same as locally).

Escape hatches, both documented: return bytes, or put a local layer in front of the remote one so saves never reach the wire.

Follow-up (second commit)

Per your review, the problem itself is tracked as #829 rather than left as a comment. The shape is already implied by PathValueMixin: it reduces a path to bytes plus a FileBlob/DirectoryBlob, all of which ship fine, and those blobs' __digest__ is defined to match the Path digest arm — so running the reduction client-side keeps the seal intact by construction, and needs no server change for saves (a FileBlob isn't a Path, so it falls straight through the server's path layer). The one genuinely new verb is an unmended load_value that returns the blob instead of materializing it on the server. Recorded in RemotePathUnsupported, dev/path_storage, and the DEVELOPING design-theme cheat sheet.

Docs

• usage/file_semantics.rst: new "Paths stop at a remote (SSH) cache" contract section + a quick-reference row.
• dev/path_storage.rst: the mechanism, and the Support Path values over SshCache (do the blob conversion client-side) #829 sketch.
• recipes/files_and_paths.rst: a recipe. SshCache's own docstring too.

Tests

tests/unit/test_remote.py — bare and nested (list/tuple/nested-dict/dataclass) rejection with nothing reaching the server; the bytes hatch still working; prepare() keeping prepared.key == call.to_lookup_key() for a path argument (the regression the guard buys); live-Call rejection; load-side rejection incl. nested; a LazyCall whose arguments still read fine and only .result raises.

tests/unit/storage/test_paths.py — find_path descent, opaque-leaf boundary, cycle termination.

tests/integration/test_remote.py — the divergent-cwd reproduction above, and a path-returning @fleche function running uncached against a remote instead of breaking.

Re-verified after merging temppath: 1788 passed / 11 skipped, docs build succeeds. ty check src/ reports 3 diagnostics — all already on temppath, none from this PR; see the #831 thread for the diagnosis and a verified fix, still pending your call on where it should land.

[pmrv]

CI is red on triage, but not because of this diff — GitHub Actions is failing to serve the action itself:

Prepare all required actions
Getting action download info
Failed to resolve action download info. Error: Service Unavailable
##[error]Service Unavailable

The job never reaches checkout, so no code in this PR is involved. Same failure on the original run and on a re-run ~7 min later, so the outage is ongoing. Collateral damage on the same commit: the ty workflow's changes gate sat queued for 15 min and was cancelled, which skipped ty itself.

Nothing to fix here. I'll re-run triage and ty once the service recovers, and report if either fails for a real reason.

For the record, locally on afb6851: full suite 1777 passed / 11 skipped, and ty check src/ at 4 diagnostics — the same 4 already present on temppath before this branch.

---

Generated by Claude Code

[pmrv]

Impl ok for now, but let's track the problem in an issue. I think this should be solvable.

[pmrv]

Tracked as #829 — agreed it's solvable, and the shape is fairly clear: PathValueMixin.save already reduces a path to bytes + FileBlob/DirectoryBlob, which ship fine, and those blobs' __digest__ is defined to match the Path digest arm. So running the reduction client-side keeps the seal intact by construction, and needs no server change for the save direction (a FileBlob isn't a Path, so it falls straight through the server's path layer). The one genuinely new verb is an unmended load_value that returns the blob instead of materializing it on the server, so the client materializes into its own temp dir and owns the TempPath lifetime. Round-trip count and a contains-batch to skip bytes the server already has are the perf questions; issue has the details. Referenced from remote.py, dev/path_storage, and the DEVELOPING theme list.

Also pushed e4a6f8e addressing the four inline threads on #797:

"feels almost more like it should go into a more generic section" — you were right that it isn't file-specific. Verified it generalizes (a mutated list argument behaves identically: cold call mutates, hit leaves the argument untouched, mutated-and-returned is stored post-mutation), so it's now usage/purity — keyed-as-passed, mutation not replayed, side effects cold-call-only — with file_semantics keeping only the path instance and linking out.

"cross ref destructuring here, since that's the key" — done, and reframed the section around it: only destructured children reach the path machinery, so _DESTRUCTURERS is the list of places a nested path gets content treatment. That one fact now explains the container list, the exact-types caveat, and the opaque-container section below it. Links to :ref:extending-destructurer``.

"move the completedprocess digester into fleche itself" — now a match arm in digest.py (args, returncode, stdout, stderr). Purely additive: those values raised Indigestible before, so no stored digest changes and no hash_version bump. Handles text-mode str and uncaptured None streams. The notebook's add_hook cell is gone and the pipeline section now just works.

"save executed version" — Files.ipynb committed executed. While there: PathsInContainers.ipynb had been added with no docs/notebooks/ symlink, no toctree entry, and no slot in test_notebooks.py — wired up all three and committed it executed too.

Verification: 1788 passed / 11 skipped. ty check src/ at the same 4 pre-existing diagnostics. Docs build succeeds — and a correction to my earlier note on this PR: the builds I called clean before had actually been dying at notebooks/CacheStack.ipynb for want of pandoc and never reached the pages I'd changed. With pandoc installed the full build succeeds and the only non-autoapi warning is the pre-existing fleche.D duplicate; I fixed a short title underline in usage/helpers that turned up once the build got that far.

---

Generated by Claude Code

[pmrv]

separate PRs for both commits

[pmrv]

Split — the four inline threads are now #831, this PR is the SshCache × Path work only.

The split isn't quite along the commit boundary, because the second commit carried three hunks that were about this PR: the #829 note in RemotePathUnsupported, the #829 rewrite of the dev/path_storage paragraph, and the "Distributed / remote caching" design-theme entry. Those stayed here as c047dd3 — they're the answer to your "let's track the problem in an issue", so they belong with the guard, not with the docs work.

Result: afb6851 (guard) + c047dd3 (record #829) here; everything else on #831. No shared hunks between the two branches — both are cut from temppath and either can land first.

Re-verified after the split: 1777 passed / 11 skipped here, 1763 on #831 (the two add 25 and 11 tests to temppath's baseline respectively, which reconciles with the 1788 the combined branch reported). ty unchanged at 4 pre-existing diagnostics on both; docs build succeeds on both.

---

Generated by Claude Code

[claude]

🤖 CI failure summary for afb6851c on claude/temppath-comment-r1zhhx

Summary
The workflow failed due to a runner acquisition issue. The changes job was cancelled because no hosted runner of the required type could be acquired after multiple attempts, causing the dependent ty job to be skipped.

Root cause
GitHub Actions runner unavailability:

The job was not acquired by Runner of type hosted even after multiple attempts

Suggested fix

1. Retry the run: gh run rerun 31120548574 --repo pmrv/fleche
2. If retries continue to fail, check GitHub's status page for runner capacity issues
3. If this is a custom runner requirement in the workflow, verify the runner is available and healthy

---

Generated by Claude Haiku 4.5.