working on todo.md features

docs/claude/invariants-session-and-export.md

@@ -52,3 +52,37 @@ Part of [CLAUDE.md](../../CLAUDE.md). These are rules that cost a defect to lear
   out — a source whose streamer was merely down during one run would silently vanish from the
   only list it can be picked from, for ever. Keeping the old file loses nothing: a run that
   configured nothing had nothing worth persisting.
+
+## A configuration is a named session, and a source may hold several
+
+One source, several arrangements: the same streamer serves different experiments, and retyping a
+layout to look at the second one is how a session gets lost. Storage is therefore a **directory
+per source** — `~/.config/udpscope/<host>_<port>/` — holding one `<name>.toml` per configuration
+plus an `active` file naming the one the source is on. `configuration_path()` is the only
+expression of the scheme, and the name is `sanitize()`d exactly as the host is, so a name typed
+with a slash cannot escape the directory.
+
+A configuration carries the whole session *and* the settings that can only be decided before the
+first socket: `buffer_mb`, `relative_time`, `capture_packets`. The startup chooser applies them
+(`apply_source()`), which works because `choose_source()` runs before `ScopeModel` is constructed
+— the one moment a buffer size can be applied at all. Switching configurations inside a running
+app applies what can change live and says in the status line that the rest takes effect on the
+next start; pretending otherwise would be a configuration that half-applies.
+
+A configuration's *startup* settings reach the model from two directions, and both are needed:
+`apply_source()` for a source picked in the chooser, and `apply_stored_settings()` for a source
+named with `--server`, which never reaches the chooser at all. Without the second, a saved host's
+buffer size, clock and capture ring were silently ignored — the layout still applied, because the
+app loads that separately once a CONFIG names the signals — so an edit to any of the three read as
+one that never took effect. **A flag the user typed wins over the file** (`--buffer-mb`,
+`--relative-time`, `--capture-packets`): the file fills in what the command line did not say, and
+`Config::buffer_mb_specified` is what tells "not asked" from "asked for the default".
+
+The `active` file is written on every save and by the chooser's pick, so "which configuration was
+I on" survives a restart. A session written before configurations existed is **imported once** as
+the configuration named `default`, and the old file is renamed to `<host>_<port>.toml.imported`
+rather than deleted: an import that cannot be undone by hand is a migration nobody can back out
+of.
+
+Nothing is lost by switching: the dialog saves the current session *before* loading the picked
+one, which is the only ordering in which a switch cannot lose what it switches from.