state

Persistent State (conf)

State is stored via conf in packages/server/src/state.ts, which owns the on-disk shape (PersistedStateSchema, internal to that file) and the migration ladder. Domain modules (preferences.ts, hostPersistence.ts) read and write their own keys against the shared store.

When changing what is persisted (any of the per-domain schemas — PreferencesSchema in packages/common/src/surface.ts, PersistedHostsSchema in packages/common/src/hostKey.ts), you must add a migration in state.ts's migrations object and bump SCHEMA_VERSION. Without a migration, existing users' state files silently lose or misinterpret data on schema changes.

The disk shape is one schema, one migration ladder, one source of truth. PersistedStateSchema is intentionally not exported; consumers go through the domain accessors (getPreferences(), getPersistedHosts()).

Host-map membership rides this store too — it is not a special case. The fleet you add via the selector strip persists as the hosts field of PersistedStateSchema, owned by hostPersistence.ts (its getPersistedHosts() reader + savePoolMembership() persist-hook shaper) and carried by the SAME schema + migration ladder as every other domain. It IS real user data (unlike preferences, a silent reset would eat the fleet), so it must never be silently emptied — and conf already guarantees that: a corrupt/unparseable store THROWS on read (clearInvalidConfig is false, conf 15's default), it does NOT reset to defaults. That fail-fast is exactly why hosts belongs in this store rather than a hand-rolled file. An invalid-but-parseable value (a hand-edited local, a duplicate) additionally fails loud where it's read — getPersistedHosts re-validates through PersistedHostsSchema (in kolu-common/hostKey) and throws, never silently normalizing. Changing the hosts shape takes a migration + SCHEMA_VERSION bump like any other domain.