T-NNAG-fleet-root-overrides

State: closed/done · Impact: high · Complexity: medium

Goal

Let one environment variable move every state root an app uses into a scratch root. The e2e harness stands on this. Without it, a test can only move the few paths an app exposes as flags, and the rest still write under the real home.

Today

Location	Role today
packages/rust/fleet/src/lib.rs	BaseDirs::from_env() reads only dirs::* and temp_dir(). BaseDirs::rooted(root) already lays every home under one root (runtime at <root>/durable/run), used by tests, parity and SDF’s SDF_FLEET_ROOT
packages/ts/fleet/base-dirs.ts	systemBaseDirs() reads the per-OS table. Its overrides option replaces single roots, but an overridden durable does not move runtime. rootedBaseDirs(root) mirrors rooted
packages/fleet-parity/parity.json	Shared fixture both twins assert against
packages/rust/fleet-tauri/src/lib.rs	AppDirs::resolve takes the product dir from Tauri’s app_data_dir(), which ignores any override
solutions/determined/crates/determined-platform/src/bin/platform-server.rs	Default state dir is determined_core::workspace::suite_state_dir(), which is fleet. --state-dir / PLATFORM_STATE_DIR override it. No endpoint reports resolved paths
Rust call sites	About 49 Fleet::new() calls, all through BaseDirs::from_env()

Proposed

BaseDirs::from_env() and systemBaseDirs() resolve each home as FLEET_<HOME>_DIR, then FLEET_ROOT (the rooted layout), then the OS default, per “Overrides and scratch roots” in S-0011-application-state-locations. Runtime falls back to <durable>/run whenever durable is overridden. AppDirs::resolve returns <durable>/<bundle id> as the product dir under an override. platform-server reports its resolved paths on an introspection endpoint.

Approach

1. Rust: read the six FLEET_<HOME>_DIR vars (five homes and scratch) and FLEET_ROOT in from_env, through an injectable env seam so tests do not mutate the process env.
2. TS: same order in systemBaseDirs, read from the injected env. An overridden durable carries runtime to <durable>/run.
3. Add parity rows for each precedence case: home var only, FLEET_ROOT only, both, durable only.
4. fleet_tauri::AppDirs::resolve: when any override is set, derive the product dir from the fleet durable home and the bundle identifier.
5. platform-server: its default already derives from fleet, so it needs no change there. Add a read-only endpoint returning the resolved homes, suite durable dir, state dir, product dir and vault dir.
6. Update the fleet READMEs and doc comments for the new resolution order.

Areas

Area	Note
packages/rust/fleet/	from_env, tests
packages/ts/fleet/	systemBaseDirs, tests
packages/fleet-parity/parity.json	New precedence rows
packages/rust/fleet-tauri/	AppDirs::resolve
solutions/determined/crates/determined-platform/	Introspection endpoint (handler and generated transports)

Acceptance criteria

• AC-1: A unit test shows FLEET_ROOT alone moves the five homes and the scratch root, in Rust and in TS.
• AC-2: Parity rows for every precedence case pass on both twins with identical paths.
• AC-3: With only FLEET_DURABLE_DIR set, runtime resolves to <durable>/run on both twins.
• AC-4: AppDirs::resolve under FLEET_ROOT returns a product dir inside the root. Without overrides it returns Tauri’s app_data_dir() unchanged.
• AC-5: platform-server started with FLEET_ROOT=<tmp> reports every resolved path under <tmp> from the introspection endpoint.

Out of scope

• The lint guard against bypassing fleet (T-1KOY).
• The harness that sets these variables (T-4HBC).
• Removing --state-dir. It stays as a narrower override.
• App-level overrides that skip fleet (DETERMINED_MODELS_DIR, VAULT_BACKUP_STORE, CONNECTOR_STATE_DIR, PLATFORM_STATE_DIR): T-2YHP. SDF_FLEET_ROOT: T-JPFC.

Dependencies

• none. P-0017-scratch-root-isolation, S-0011-application-state-locations and S-0020-desktop-apps-tested-web-first-in-scratch-root land in the same PR as this task.

Discovery context

• Manual testing of Determined Backup showed --state-dir moves only workspace.json, last-active.json, settings/, tmp-heic and photo-match. The backup store, index, OCR, media and models stayed under the real home.

---

← Back to Tasks