0007 — Persist routing and scenes by node/port name, never by numeric id
Status: Accepted (designed; the principle already shapes the built reconciler) Date: 2026-06-29
Context
PipeWire (and JACK) assign numeric object ids to nodes and ports. Those ids are not stable: they change across a restart, and they change when a device is unplugged and replugged. A stagebox that drops off the network and comes back, an X-Touch reconnected to a different USB port, the host rebooted between soundcheck and doors — all of these churn the ids. Any routing or scene that referenced a port by its numeric id would mis-route or silently fail after such an event. This is precisely when scene recall most needs to be correct.
Decision
Persist all routing and scene state by node-name + port-name (with glob/pattern matching), and re-resolve to live ids on every scan. Never store a numeric id.
The model (adopted from ZestBay's MIT AutoConnectRule): a rule carries a source pattern,
a target pattern, and explicit port mappings; on each scan, cached ids are re-resolved by
pattern, incompatible mappings (MIDI↔Audio) are dropped, and a fallback chain resolves a
port by channel name → identical name → physical index → first available. A scene's
routing is a rule-set; recall is "set the rules, then scan/reconcile". An explicit
per-scene merge-vs-exclusive flag controls whether recall leaves foreign links alone or
disconnects everything not in the rule-set.
Consequences
- "Restore my patch when the stagebox reappears" works, and scene recall does not mis-route after any replug.
- The built reconciler already leans on this: it diffs by name-keyed edges and only tears down destinations it manages, so it composes with name-based rules cleanly.
- It requires a settle-time debounce before re-applying rules after a graph change, so a burst of PipeWire events does not cause thrashing.
- Plugin instances in a scene carry a logical
stable_idso the chain reconciler can diff desired-vs-live by logical identity across id churn, independent of mod-host's instance numbers. - This is the explicit anti-pattern to avoid: do not persist by numeric PipeWire/JACK id.