Relationships
#4918 A serve host registers the workspaces it runs in the workspace registry, where they are
Opened by zack · 11/19/2026· Shipped 11/19/2026
Second of six steps that merge a serve host's workspaces into the workspace registry. swamp-club#4865 lists the whole sequence. One PR. Depends on swamp-club#4848 (workspace services), which has landed.
Problem
A serve host knows its workspaces from the folders in <host folder>/workspaces/. The workspace registry (<config dir>/workspaces.json) is a second list that the host never touches. swamp-club#4919 and swamp-club#4865 make the registry the host's only list. Before that can happen, every workspace a host already runs has to be in the registry, or an upgrade would stop serving it.
Change
Every workspace a host runs is also a registry entry. The host writes the registry and does not read it to decide anything: the folder scan still decides what is served, so nothing a client sees changes.
The host registers what it runs
- At startup and with each rescan, the host registers every workspace folder in
workspaces/that the registry lacks. The entry's name is the folder's name and its folder is the folder's real path. Nothing is moved or copied. - The entry is recorded as
swamp workspace importwould record it, with no trust mark. workspace.createregisters the workspace it made, after the folder is renamed into place. A create stopped before that is registered by the host's next rescan.- A delete removes the entry: after the folder is removed and before the wanted file, which is still removed last. A host stopped halfway finishes at its next start, as it does today.
- A folder removed by hand loses its entry once its serve has stopped, when its status file is removed. The name is free again, as it is today.
- The host removes only an entry whose folder is inside its own
workspaces/and whose name is that folder's name.
Writes follow the registry's own rules
- Every write goes through the workspace store, under the registry's lock. A registry the host creates adopts the repos under the data dir first, as any command that writes does. Otherwise a later workspace command would find a registry and never adopt them.
- The host waits for the lock for a bounded time. A write that fails or times out is tried again at the next rescan and logged once per reason. It never delays or stops a serve.
- The file gains no field and no schema version. An older swamp reads and rewrites it without loss.
A folder that cannot be registered
- The name is registered to another folder, or the folder is registered under another name. The host does not change the registry.
- It logs an error once per reason. The error names both folders, says that a later release will stop serving this folder until the clash is resolved, and names
swamp workspace remove. - The workspace keeps running, as it does today.
A registry that cannot be read
- The file is corrupt, or was written by a newer swamp. The host logs it, registers nothing and goes on serving. The repository already refuses to rewrite such a file.
Compatibility
swamp serve host,host.yaml, the wanted and status files and every address are unchanged.- What is new is visible only on the host's machine: its workspaces appear in
swamp workspace listand on theswamp startpage. swamp workspace removeon one of these entries has no lasting effect while the folder is inworkspaces/: the next rescan registers it again. The design doc says so.
Decisions this issue makes
- Where the write runs. The expected answer is that the root registers on create, so
swamp workspace listis right at once, and the host's rescan is the safety net. - How long the host waits for the registry's lock. Long enough to pass a workspace command, short enough that a rescan is never held up.
Done when
- A host started on a host folder that already holds two workspaces lists both in
swamp workspace list, each at its own folder. Both still run and answer at their addresses. Their wanted and status files are unchanged. swamp serve workspace createadds an entry.swamp serve workspace rmremoves the folder and the entry.- A folder removed by hand loses its entry after its serve stops.
- A clash is logged once, the registry is unchanged and the workspace is still served.
- With a registry that cannot be read, the host serves as before and writes nothing.
- A registry the host created holds the repos under the data dir that a first read would adopt.
- The JSON the host writes has only the keys the registry has today.
- The tests use a fake process port and a registry in a temp config folder supplied with
withMockedEnv. They spawn no processes. - The fitness rule for
src/serve/host/still passes.
Where to look
src/serve/host/serve_host.ts,src/serve/host/workspace_folder.tsandsrc/serve/host/workspace_reconciler.tsfor the scan and the removal steps.src/libswamp/hosted_workspace/create.tsfor create.src/libswamp/workspace/workspace_store.ts(loadWorkspaceRegistry,importWorkspace) andsrc/infrastructure/persistence/workspace_registry_file_repository.tsfor the registry. A namesrc/serve/imports from libswamp must be exported fromsrc/libswamp/mod.ts.design/surfaces/workspace.mdfor the registry's own rules.
Out of scope
- Reading the registry to decide what the host serves. That is swamp-club#4919.
- Workspaces registered outside
workspaces/. The host still ignores them. - Moving any folder or file.
Shipped
Click a lifecycle step above to view its details.
Sign in to post a ripple.