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

# Invariants: the session file, the export and the source chooser

What a session persists and in what order, when a save is refused, and when an export is collected.

Part of [CLAUDE.md](../../CLAUDE.md). These are rules that cost a defect to learn; read the ones touching the area you are editing before you edit it.

- **The session is the layout.** `LayoutState` persists what makes a reopened scope look like the
  one that was closed: the window, the rows and their slot signals, the calibration, **the enabled
  signals**, **the chosen trace colours** (`[[color]]`, `name` + `rgb = "#RRGGBB"` — only the
  *overrides*, so a stream's new signals still take the positional palette and a saved session does
  not freeze a colour that is meant to follow the signal list), **the math channels with their
  graphs**, **the measurements pane**, and **`measure_stats`** — the measurements statistics
  toggle; written as a bare top-level boolean (`measure_stats = true/false`), defaults to `false`
  when absent. Signal identity
  is the *name* throughout (a CONFIG renumbers channels), 'enabled' is read off the channels the
  model built -- an enabled signal is exactly one that produced a channel -- and `apply_layout()`
  installs the graphs **before** assigning the rows, since a row may hold a math channel's name and
  that name is only a signal once its graph is in. Two format rules, both learned the hard way:
  write an op or a measure *type* as its index through `math_op_at()`/`measure_type_at()`, never as
  the raw enum value -- those accessors' orders are the dialog's, not the declaration order, so
  writing one and reading the other silently renames operations. And a top-level key written after
  a `[[table]]` belongs to *that table* in TOML: `enabled = [...]` emitted after `[[calibration]]`
  was parsed into the last calibration record and the enable state was lost without a word.
  `mkdirs()` used to create only components with a trailing slash, so `~/.config/udpscope` was never
  made and the *first* save failed silently -- worth knowing when a layout change "does not stick".
- **Measurement options persist under *named* keys -- `noise` and `hf` -- so a file written before them
  loads at the defaults**, which are exactly the behaviour it was written against: `noise = 10` is the
  hysteresis band the app has always counted with, and `hf = 0` is no filter.
- **The math node string is thirteen pipe fields, and the reader accepts twelve *or* thirteen.** `med_n` is
  the thirteenth, after `y`; a twelve-field node is a file written before the de-noise node existed, and its
  `med_n` stays at the struct's default -- which is what such a file meant. Field 0 is the op as a
  `math_op_at()` index, which is why `MathOp` may only be *appended* to.
- **The export is collected at click time, not in the file-dialog callback.** The live
  view keeps scrolling while the chooser is up, so a late collection would write a
  window the user never saw. The writer is picked by the chosen path's extension.
- **The chooser runs before `ScopeModel` exists, and `--server` is what decides.** `Config` carries
  `server_specified`, set only by the `--server` branch, and `main()` asks only when it is false —
  so declining costs no buffer and no socket, and `ScopeModel`, `Acquisition`, `RowSet` and
  `run_ui()` need no notion of "no source yet". It is `--server` alone and not "no arguments":
  `--multicast` still needs a server to fetch CONFIG from. **Every documented probe passes
  `--server`**, which is what makes the feature invisible to the regression net — a probe added
  without it would reach the chooser and hang. `gtk_init()` plus a nested `GMainLoop`, and then
  `run_ui()`'s `GtkApplication` afterwards in the same process, is a verified combination
  (`gtk_init()` is idempotent; running your own loop is the documented GTK4 replacement for the
  removed `gtk_dialog_run()`).
- **A session file's name cannot say how its source was reached, so the file says it.**
  `<host>_<port>.toml` carries neither the multicast group nor the interface, so a chooser row
  could not reconnect to a multicast source at all. `LayoutState::multicast`/`interface_addr` are
  written in the **top block, before the first `[[table]]`** — a bare key after a table header is
  that table's key in TOML, which is exactly how `enabled` was parsed into the last
  `[[calibration]]` record and lost without a word. A file from an older build has neither key and
  loads as unicast on the default route. The chooser's list filters to sessions that **name at
  least one signal**, because a probe run leaves a file per throwaway port and all of them hold
  `signals = ["", "", "", ""]`; `known_sources()` splits the filename at the **last** `_`, since
  `sanitize()` turns anything unsafe in a host into one.
- **`save_layout_now()` refuses to write while `signals()` is empty.** A run against a source
  whose streamer was down receives no CONFIG, so every slot name stays empty and the save would
  overwrite a configured session with `signals = ["", ...]`. The chooser then filters that file
  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.
- **It refuses again while `replaying` is set: a file view is not the source's session.** Same
  argument, different cause — this view configured nothing about the stream. A plain replay leaves
  the rows where the user put them, so its save would merely be pointless; a **group** rebinds every
  slot to its own renamed channels and the save wrote `signals = ["square (A)", …]` into the file.
  Nothing noticed until the way back: *Go live* re-applies the session, those names match no live
  signal, so nothing was enabled and **the live view came back with no channels at all** — on the
  window the poisoned file carried, which is also how it swallowed the window restore below it. The
  reading is `[events] live restored (after a group)`: the symptom was a stuck `pending=1` beside
  `channels=0`, because the restore waits for a channel list that was never going to arrive. The
  explicit *Save as* is deliberately **not** guarded: that one is a user's own answer to "save this
  view", and its dialog reports the outcome.

## 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.