Phase 25: improve LADSPA discovery, parameter editing and plugin lifecycle

docs/KNOWN_LIMITATIONS.md

@@ -47,3 +47,10 @@ PERFORMANCE.md, PLUGIN_HOSTING.md and RECOVERY.md for tested contracts/evidence.
   bus plugin inserts, per-track aux sends and sidechains remain deferred. Track
   meters are pre-bus; bus meters are pre-graph; master is post-graph. Sample peaks
   and sticky clipping do not provide loudness, true-peak analysis or limiting.
+
+- Plugin discovery is an explicit-file descriptor browser, not a directory scan.
+  Generic parameter dialogs own copied metadata; no native plugin editors or
+  custom MIDI instrument chooser. LADSPA units are unspecified. Replacement
+  requires the same mono audio layout and resets controls/automation. Missing
+  modules reject Open while retaining the current project; GUI module relink for
+  unopened documents is deferred. In-process plugin crashes/hangs are uncontained.

docs/PLUGIN_HOSTING.md

@@ -30,13 +30,17 @@ LADSPA 1.1 host. `xtc_plugin.h` is the C API; no C++ engine or FLTK type is need
 
 1. Choose **File → Load LADSPA plugin** and a trusted absolute `.so` path. Loading
    executes native code immediately, including constructors during discovery.
-2. The dialog lists compatible descriptor indices/labels. Select an index.
+2. The descriptor browser lists names, labels, makers and source/effect roles.
+   Select a row and Choose. Counts report compatible and skipped descriptors.
 3. In the Modular Graph, connect the new source/effect output to an output or
    other effect; effects have an optional mono input. Unconnected effect inputs
    receive external input, as other graph processors do.
-4. Select its node and use **Edit → Selected plugin control**. The dialog shows
-   actual port IDs, names, values and rate-adjusted ranges. Enter a port and value.
-   Toggled controls require 0/1 and integer controls require integral values.
+4. Select its node and use **Edit → Selected plugin control**. The editor shows
+   name, maker, copyright, module path, descriptor index and unique ID, then
+   actual port IDs, editable values, rate-adjusted bounds, defaults and discrete/
+   logarithmic hints. Apply validates all values and candidate initialization;
+   Cancel and window close preserve the document. Toggled controls require 0/1
+   and integer controls require integral values.
 5. Save normally, reopen, reconnect external JACK playback if needed, and Play.
    Plugin changes stop/rebuild playback and participate in ordinary undo/redo.
 
@@ -103,3 +107,89 @@ bundled or installed by the target):
 Tested packages: ladspa 1.17-7 and swh-plugins 0.4.17-7. These zero-latency
 processors define the initial compatible set; other plugins remain unqualified.
 Physical listening and plugin CPU/endurance qualification remain pending.
+
+## Phase 25: discovery, editing and graph lifecycle
+
+Discovery remains explicit-file only, bounded to 1024 descriptor indices; no
+recursive scan, plugin database or new dependency is introduced. Unsupported
+layouts are skipped with counts; source/effect roles describe audio ports, not
+MIDI instrument capabilities. Built-in MIDI synthesis remains the only GUI MIDI
+instrument. LADSPA sources can be identified, edited, replaced and removed in
+the graph but cannot receive MIDI events.
+
+**Edit → Insert LADSPA on selected wire** replaces one existing connection with
+`source -> effect -> destination`, as one undo step. Only one-input effects are
+accepted; stale wires, capacity failures and initialization failures retain the
+original graph. **Edit → Replace selected plugin** accepts the same audio input
+layout, keeps the node ID and all wires, and installs the new descriptor's default
+controls with no inherited automation. It can replace from another module.
+A source/effect layout mismatch is rejected. Undo restores the old identity,
+values and automation. Every candidate is compiled before adoption even when
+the backend is disconnected; no intermediate graph is published.
+
+Ordering is graph signal flow, not descriptor order, creation order or a flat
+rack. Use the graph's connection/disconnection tools to place effects in series
+or parallel. Insertion on a wire preserves its endpoints and changes only that
+stage. Select a plugin and Delete to remove it and incident wires, then reconnect
+as desired; deletion does not automatically bridge or sum routes. A now-unwired
+effect receives external audio, following existing graph semantics. Undo/redo
+restores removal and routing. Independent bus inserts are still outside the
+shared-source graph model.
+
+Reset defaults in the editor previews every control's declared/default-derived
+value. Apply also clears that plugin's automation; Cancel preserves it. The
+**Edit → Reset selected plugin** command does the same in one undo step. The
+public control-thread `xtc_plugin_reset` can reset one port (removing only its
+lane) or UINT32_MAX for all controls. Automation otherwise overrides static
+values, so editing a static control does not remove an existing lane.
+
+`xtc_plugin_describe` returns copied name/maker/copyright (bounded/truncated),
+parameter ranges/defaults and integer/toggle/logarithmic/sample-rate/boundedness
+flags. Missing maker/copyright receive explicit fallback labels. LADSPA has no
+standard unit metadata: unit stays empty and the editor says unspecified rather
+than guessing Hz/dB from names. Numeric inputs use linear parameter values;
+logarithmic is a descriptor hint, not an extra host conversion. Unbounded ends
+are labeled unbounded; finite float extrema remain the validation bounds.
+Sample-rate hints scale bounds and defaults once at the engine's actual rate;
+nonrepresentable scaled bounds are rejected. Discrete defaults are rounded and
+validated; impossible defaults fail discovery rather than reaching the engine.
+
+The generic modal editor owns copied metadata and temporary widget values only.
+It never owns or retains module handles, descriptors or audio instance pointers.
+Closing it cannot unload active DSP; Apply builds a new immutable plan before
+installation and existing retirement/quiescence rules release old instances.
+No embedded third-party editor UI is supported.
+
+### Compatibility and recovery
+
+LADSPA 1.1 descriptor identity is module path + index + label + unique ID, with
+exact supported port/control layout verified on restore. A unique ID is not a
+binary version/hash guarantee. Parameter values and bounded automation persist
+in existing project v9 records; this phase adds no file format change. Transient
+history/tails and opaque state remain unsupported. Native processor ABI 2 and
+its exact `struct_size` contract are unchanged; it remains parameter-only state.
+Consumers rebuild against public headers; the new copied details API adds no
+callbacks or GUI types to the C core.
+
+Missing/incompatible modules reject GUI Open with the offending label/path and
+leave the current project intact. Restore a compatible module at that path and
+retry; use metadata-only validation/save to preserve an unavailable module's
+records. No dummy replacement silently removes its controls. Failed discovery,
+replacement or instantiate reports an error and retains the current document.
+A LADSPA `run` callback has no error return; finite-sample sanitation does not
+contain crashes, hangs, memory corruption or prohibited work inside a plugin.
+Only trusted in-process plugins are supported. See RECOVERY.md.
+
+### Phase 25 verification
+
+Fixture tests cover copied identity/hints, integer and toggle defaults and range
+rejection, logarithmic/sample-rate hints, scaled-range overflow rejection, reset
+and unchanged-on-error behavior, parameter/automation save/reopen and exact
+rendering. Noncommutative gain/offset effects prove that graph order changes
+output as expected. GUI tests drive the actual chooser/editor, reset/Apply and
+Cancel, replacement layout/init/missing-module rollback, insertion/stale-wire
+failure, deletion and undo. Existing fixture tests exercise 100 live plan
+replacements with host allocation/free/dlopen/dlclose guards. Native ABI tests
+cover process-error silence/reset. The separately installed amp/inverter/sine
+modules remain the qualified LADSPA set. Human listening, arbitrary third-party
+editors/plugins and extended realtime endurance remain unverified.

docs/RECOVERY.md

@@ -57,3 +57,21 @@ float32 WAV from complete on-disk frames, ignoring a trailing partial frame.
 It never changes the source or overwrites an existing destination. This
 supersedes the earlier lack of a WAV recovery tool described above. See
 AUDIO_FILES.md for format/ownership/size limits and `make test-recording`.
+
+## Plugin load and replacement failures (Phase 25)
+
+GUI Open reports an unavailable/incompatible plugin's label and absolute module
+path and retains the current document. Preserve the saved file; restore a
+compatible module at its original path and retry Open. `xtc-check --validate`
+checks metadata without executing plugins, so success does not certify that a
+module exists or initializes. Metadata-only C load/save preserves unavailable
+plugin records. There is no automatic missing-plugin substitution or GUI relink
+for an unopened document.
+
+For an already loaded project, Replace selected plugin preserves wires and node
+ID only for the same audio layout. New defaults replace controls/automation;
+Undo restores the original configuration. Failed discovery/compile/instantiate
+retains the original graph, controls and history position. Cancel in the generic
+parameter editor discards its temporary values. Reset defaults clears automation
+only when applied. No host recovery can contain a crash or hang in trusted native
+plugin code; LADSPA has no runtime error-return channel.

docs/ROADMAP.md

@@ -625,10 +625,35 @@ Make instruments and effects practical to use, manage, and diagnose in real proj
 - Document plugin API versioning and compatibility expectations.
 
 ### Acceptance criteria
-- Users can identify and manage loaded instruments and effects without editing configuration files.
-- Missing or incompatible plugins produce actionable diagnostics and do not silently corrupt projects.
-- Plugin state restoration is tested for supported plugin types.
-- The engine remains safe if plugin initialization or processing fails, within the documented failure model.
+- [x] Users can identify and manage loaded instruments and effects without editing configuration files.
+- [x] Missing or incompatible plugins produce actionable diagnostics and do not silently corrupt projects.
+- [x] Plugin state restoration is tested for supported plugin types.
+- [x] The engine remains safe if plugin initialization or processing fails, within the documented failure model.
+
+Implemented for the supported LADSPA 1.1 mono effects/audio sources: explicit
+module descriptor browser, copied identity and control metadata, generic parameter
+editor with validated Apply/Cancel and defaults reset, compatible-layout
+replacement preserving node ID/wires, and atomic effect insertion on a selected
+wire. Graph connections define order and existing deletion removes incident
+wires. Edits integrate with undo/redo and compile before adoption. State uses
+existing v9 parameter/automation records; missing/incompatible plugins retain the
+current document and report recovery guidance. Native processor ABI 2 remains
+unchanged. See PLUGIN_HOSTING.md and RECOVERY.md.
+
+Validation: warning-enabled core/GUI builds; full unit/integration suite;
+fixture and installed amp/inverter/sine plugin tests; actual chooser/editor GUI
+tests; reset/cancel, insertion, replacement, removal and undo; layout/init/missing
+module rollback; exact persisted rendering and noncommutative processing order;
+callback allocation/module-lifetime guards, reliability and static analysis;
+software JACK GUI/audio/MIDI and workflow; dependency-free build; installation
+and package relocation; ASan/UBSan including generic-dialog lifetimes (existing
+fontconfig leak suppression for GUI/system font allocations).
+
+Qualification remains the documented in-process failure model: LADSPA cannot
+signal run failure or contain crashes/hangs. No external editor, opaque state,
+MIDI-capable plugin instrument, recursive scanner or new format was added.
+Physical listening and arbitrary third-party plugin/endurance qualification
+remain pending.
 
 ## Phase 26 — Automation and Control Mapping
 

docs/USER_MANUAL.md

@@ -130,3 +130,11 @@ Phase 24: Mixer also offers Add bus and a Route choice for ordinary tracks.
 Select Track/Bus strips to edit their controls and automation. Master and selected
 strip meters show dBFS with 20 dB/s release; Reset peaks clears latched clipping.
 See MIXER.md for solo rules, gain staging and meter taps.
+
+Phase 25: File → Load LADSPA plugin offers a descriptor browser. Select a graph
+plugin and Edit → Selected plugin control for identity, values, ranges and
+Reset defaults; Apply commits, Cancel discards. Edit also offers replacement,
+reset and insertion of an effect on a selected wire. Graph wires determine
+processing order; Delete removes a selected plugin and its wires. Changes are
+undoable. Replacement keeps compatible audio wiring but resets plugin controls
+and automation. See PLUGIN_HOSTING.md for supported formats and failure behavior.