docs(plan): revise .trodesconf importer around ntrode_id-immutability invariant

Second-review revision. Central invariant: imported Trodes ntrode_ids are
immutable; a new import-aware completion path (fillImportedNtrodeMaps) fills map
values into existing rows instead of the renumbering device-type path. Also:
expected channel counts stored off-export (trodesImport sibling, never on
NtrodeMap — reorder is lossless); first-config seeds v1 from the import (not a
post-create v2); changed-layout re-import is review, not blocking; re-import
preserves existing multi-shank grouping; DIO direction/id rules handle
ECU_/MCU_/Controller_ + input=0; Phase 6 resolves the inventory in DioTab and
passes it down. 5 -> 6 phases (new phase-3 completion).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: edeno

.claude/docs/plans/trodesconf-import/PLAN.md

@@ -3,34 +3,35 @@
 **Status:** Not started.
 
 Let users establish an animal's hardware configuration by importing the `.trodesconf` (the SpikeGadgets
-workspace XML embedded in every `.rec`) instead of hand-building electrode groups and counting
-channels. The import is a **hardware-structure scaffold**: from the config it creates the exact
-electrode-group/ntrode structure with per-ntrode channel counts (guaranteeing the YAML matches the
-`.rec` so trodes_to_nwb's `len(map)` cross-check can't fail) and records the board's DIO channel
-inventory; it deliberately leaves the experiment semantics it cannot know — `device_type`, brain
-`location`, stereotax coordinates — blank for the existing validation to drive. It targets the
-**animal configuration version** (seed v1 at create-animal; a changed layout makes a new version via
-the existing reconfiguration path), feeding the diff/apply machinery the app already has. **Exported
-YAML is unchanged** — the importer fills the same fields the user would, and the channel `map` values
-still come from `device_type` as today.
+workspace XML embedded in every `.rec`) instead of hand-building electrode groups and counting channels.
+The import is a **hardware-structure scaffold**: it creates ntrode rows with the exact channel counts
+**and immutable `ntrode_id`s from the config** (so the YAML matches the `.rec` and trodes_to_nwb's
+`ntrode_id`/`len(map)` cross-check cannot fail), groups them (default 1 ntrode → 1 group; the user merges
+shanks for a multi-shank probe), and records the board's DIO channel inventory. It deliberately leaves
+the experiment semantics it cannot know — `device_type`, brain `location`, coordinates — for the user;
+when `device_type` is set, a **new import-aware completion path fills the map values into the existing
+rows without renumbering** (the central invariant). It targets the **animal configuration version**
+(seed v1 at create-animal; a changed layout makes a new version via the existing reconfiguration path).
+**Exported YAML is unchanged** — the importer produces the same fields a hand-built config would.
 
 ## Reading order
 
 For agent invocation, **load only the slice you need**:
 
 1. **Working a specific phase?** Open the matching phase file — each is self-contained.
-2. **Need the channel-map contract or the parsed-config type?** [shared-contracts.md](shared-contracts.md).
+2. **Need the invariant, the parsed type, the plan shape, or the DIO mapping?** [shared-contracts.md](shared-contracts.md).
 3. **Need upstream `.trodesconf` XML / trodes_to_nwb line refs?** [appendix.md](appendix.md).
-4. **Need scope / risks / rollout / the persistence-migration call?** [overview.md](overview.md).
+4. **Need scope / risks / rollout / the persistence + renumbering integration calls?** [overview.md](overview.md).
 
 ## Files
 
-- [overview.md](overview.md) — scope, integration points, the byte-identity + persistence invariants, risks, rollout.
-- [shared-contracts.md](shared-contracts.md) — the `ParsedTrodesConfig` type, the trodes_to_nwb channel-map contract, and the import-plan shape; referenced by ≥2 phases.
-- [appendix.md](appendix.md) — `.trodesconf` XML structure + trodes_to_nwb consumer file:line refs (the authoritative behavior the plan is built against).
+- [overview.md](overview.md) — scope, integration points, the byte-identity + persistence + renumbering invariants, risks, rollout.
+- [shared-contracts.md](shared-contracts.md) — `ParsedTrodesConfig`, the channel-map contract, **the ntrode_id-immutability + import-aware-completion invariant**, the import-plan shape, and the DIO id-reconciliation contract.
+- [appendix.md](appendix.md) — `.trodesconf` XML structure + trodes_to_nwb consumer file:line refs.
 - Phases (each ships as a separable PR, in dependency order):
-  - [phase-1-parser.md](phase-1-parser.md) — pure `.trodesconf` XML → `ParsedTrodesConfig`.
-  - [phase-2-plan.md](phase-2-plan.md) — candidate `ProbeConfiguration` + diff/plan (reuses `diffProbeConfigs`) + count/device_type conflict flags.
-  - [phase-3-apply.md](phase-3-apply.md) — apply via the existing reconfig action; add the optional `dioInventory` field.
-  - [phase-4-ui.md](phase-4-ui.md) — entry points (create-animal + new-configuration), file upload, diff preview, post-import validation punch-list.
-  - [phase-5-dio-day.md](phase-5-dio-day.md) — surface the config DIO inventory as a channel picker in the day DIO editor.
+  - [phase-1-parser.md](phase-1-parser.md) — pure XML → `ParsedTrodesConfig` (+ stricter DIO direction, informational `numChannels`).
+  - [phase-2-plan.md](phase-2-plan.md) — candidate config + diff/plan with **id-preserving** ntrode shells + the grouping model.
+  - [phase-3-completion.md](phase-3-completion.md) — **the invariant:** `fillImportedNtrodeMaps` (preserve ids) + branch `ElectrodeGroupsContainer` away from the renumbering path.
+  - [phase-4-apply.md](phase-4-apply.md) — apply via the existing reconfig action; add the optional `dioInventory` field (+ extend `ConfigSnapshotInput` + the transition).
+  - [phase-5-ui.md](phase-5-ui.md) — real file-input + `file.text()`, a **new** diff/preview component, the grouping + device_type step, entry points.
+  - [phase-6-dio.md](phase-6-dio.md) — reconcile board ids → editor index + limit the day DIO picker to present channels.

.claude/docs/plans/trodesconf-import/appendix.md

@@ -11,9 +11,12 @@ if the executor's checkout differs.
 
 ## 1. `.trodesconf` XML structure (trodes)
 
-Sample files: `trodes/Resources/SampleWorkspaces/*.trodesconf` (e.g.
-`128_Tetrodes_ECU_Sensors.trodesconf`, `128_Tetrodes_NoECU_Sensors_PTPcamera.trodesconf`) — copy 2–3 as
-Phase 1 fixtures.
+Sample files (Phase 1 fixtures): `trodes/Resources/SampleWorkspaces/*.trodesconf`
+(`128_Tetrodes_ECU_Sensors.trodesconf`, `128_Tetrodes_NoECU_Sensors_PTPcamera.trodesconf`,
+`BlankWorkspace.trodesconf` — the last has `Controller_Din*` with **no `input` attr**) **and**
+`trodes_to_nwb/src/trodes_to_nwb/tests/test_data/reconfig_probeDevice.trodesconf` (`ECU_Din*`/`ECU_Dout*`
++ a real probe layout). Together they cover the `Din*`/`ECU_*`/`MCU_*`/`Controller_*` id + direction
+variants the parser and `reconcileDioId` must handle.
 
 Relevant elements (verified against `128_Tetrodes_ECU_Sensors.trodesconf`):