Relationships
#3159 Datastore sync: read one remote file without writing it to the local cache (fetchContent)
Opened by zack · 10/7/2026· Shipped 10/7/2026
Problem
On a synced datastore (S3, GCS) each process works from a cached copy of a run record, pulled at boot or at command start. Nothing in the sync contract lets core ask what the remote holds for one file without replacing the local copy:
- pullChanged and hydrateFile both write into the local cache, and overwrite a local file that differs from the remote, including one with a change not pushed yet.
- fetchForeignContent returns bytes without writing, but it always prefixes the key with a namespace, so it cannot address a datastore with no namespace, and its contract is for another namespace's data.
swamp serve needs this for swamp-club#3108. Before it resumes a suspended run by itself, it has to know that the run is still in the suspension its cached copy shows. A peer that cancelled, deleted or resumed the run leaves a copy that still says suspended, and resuming from it runs steps after a cancel and pushes over the peer's record. The run's lock serialises two processes but does not refresh the copy.
Proposal
An optional method on DatastoreSyncService:
fetchContent(relPath, options) returns the bytes of one file as the remote holds it, or null when the remote has no such file. It writes nothing locally. relPath is cache-relative and forward-slash-normalised, as for hydrateFile, and the namespace comes from options, as for hydrateFile, so a datastore with no namespace is addressed at its root.
Core treats the method's presence as the capability.
Scope
This issue covers the contract only. How swamp serve uses the method (refusing an automatic resume when the remote run record is missing or differs from the local copy, and running the periodic continuation sweep on a synced datastore only when fetchContent is available) is tracked in swamp-club#3108, where that code lives.
Acceptance
- DatastoreSyncService documents fetchContent, with a conformance test extension authors can run.
- The in-memory remote in the testing package implements it, so core code that calls it can be tested.
- The S3 and GCS datastore extensions implement it (filed separately).
Shipped
Click a lifecycle step above to view its details.