ADR-0014: Registry cache lifecycle: auto-start, never auto-stop, one shared instance

Status: accepted · Date: 2026-10-13 · Decision makers: James Hebden

Context and Problem Statement

A managed registry cache is a host process that outlives any single cluster. Three questions follow from that: who starts it, when it stops, and what happens when several projects on one machine each want it. The wrong answers cost either the warm cache (stopping too eagerly) or ports and disk (running one per project).

Decision Drivers

• The common loop is destroy then up, often within one session, and it should find a warm cache
• An idle cache costs almost nothing
• Several profiles on one host shouldn’t each claim a port and a data directory
• Coordination between separate xianyun processes needs to be simple enough to trust

Considered Options

1. up starts the cache if it isn’t running; destroy releases the project’s claim and leaves it running; only registry stop stops it; one instance serves every profile, tracked by marker files under a lock
2. Stop the cache when the last claim is released
3. Stop the cache after an idle timeout
4. One cache instance per profile
5. Inter-process messaging (a socket or named pipe) for the claim count

Decision Outcome

Chosen option: “auto-start, never auto-stop, one shared instance”. The original design tried option 2 first and it broke straight away for single-cluster users, who destroy and recreate in one session and found a cold cache each time. A timer (option 3) adds complexity for little benefit. Per-profile instances (option 4) multiply ports and disk with no sharing between profiles. Marker files, one empty file per participating profile under the registry’s refs/ directory, behind an exclusive flock, are the simplest coordination that works across processes: the directory listing is the count and the file names are the profiles.

Consequences

Good:

• A warm cache across destroy and recreate
• Claims are visible with ls, and xianyun registry status reports them

Bad:

• Stopping is manual. A forgotten cache keeps running and keeps listening (TM-REG-001).
• A PID file left behind by a crash can point at an unrelated process, and registry stop signals it without checking (TM-REG-002)

Neutral:

• The cache is started detached, with a PID file and a log file next to its data

Implementation Location

• crates/xianyun-deploy/src/registrycache/refs.rs
• crates/xianyun-deploy/src/registrycache/lock.rs
• crates/xianyun-deploy/src/registrycache/process.rs

More Information

• Recorded on 2026-10-13 from decisions 4 and 7 in the Go project’s registry-cache design.
• Related: ADR-0007, FR-011.