lmxopcua/docs/plans/2026-06-16-stillpending-phase-4b-driver-gaps-design.md

Phase 4b — Mac-verifiable driver gaps (design)

Status: approved 2026-06-16. Branch feat/stillpending-phase-4b-driver-gaps off master c081917a.

Goal: Close three independent, contract-free stillpending.md §2 driver gaps that are shippable on their own and (for the first two) live-verifiable from this Mac:

1. Modbus driver-type-string reconcile — "ModbusTcp" (AdminUI/probe) vs "Modbus" (runtime factory + seed) → rig Modbus drivers fall to the raw-JSON editor; AdminUI-created Modbus drivers store an unloadable type string.
2. Galaxy nested gobject hierarchy — GalaxyDiscoverer renders the gobject tree flat.
3. FOCAS cnc_getfigure auto-scale — axis positions need the decimal-place figure hand-configured; the CNC reports it via cnc_getfigure.

The three touch disjoint projects (AdminUI + Modbus driver / Galaxy driver / FOCAS driver), so implementers can run concurrently.

Hard constraints (every task): stage by explicit path, never git add .; never stage sql_login.txt / src/Server/ZB.MOM.WW.OtOpcUa.Host/pki/ / pending.md / current.md / docker-dev/docker-compose.yml / stillpending.md; no force-push / no --no-verify; NO EF migration; NO Commons wire/proto contract change; NO bUnit (Razor proven by live /run). The IFocasClient addition is a driver-internal interface, not a wire contract; the Galaxy proto is unchanged.

---

Component 1 — Modbus driver-type-string reconcile

Problem

The Modbus driver-type string is inconsistent:

• Runtime canonical = "Modbus" — ModbusDriver.DriverType (ModbusDriver.cs:185) and the factory registration key ModbusDriverFactoryExtensions.DriverTypeName (:16).
• AdminUI = "ModbusTcp" — DriverIdentitySection.razor, DriverTypePicker.razor, DriverEditRouter.razor, ModbusDriverPage.razor, Uns/TagEditors/TagConfigEditorMap.cs, Uns/TagEditors/TagConfigValidator.cs, + ~13 AdminUI.Tests rows.
• Probe = "ModbusTcp" — ModbusDriverProbe.cs:29 (a third spelling).

Effect: the rig's MAIN-modbus-eq is seeded DriverType="Modbus", so the /uns Tag modal's TagConfigEditorMap.Resolve (keyed on "ModbusTcp") misses → raw-JSON editor (and Phase 6's Build-address button is unreachable). An AdminUI-created Modbus driver stores "ModbusTcp", which the runtime factory ("Modbus") cannot instantiate.

Approach (chosen): canonicalize on "Modbus"

"Modbus" is the runtime factory registration key — the hard runtime dependency. Canonicalizing on it means never touching the factory key or ModbusDriver.DriverType and no data migration (the dev-rig seed is already "Modbus").

Changes — change the 7 outliers + tests to "Modbus":

• ModbusDriverProbe.cs:29 DriverType => "ModbusTcp" → "Modbus".
• The 6 AdminUI files above: every "ModbusTcp" stored/dispatched value → "Modbus".
• ~13 AdminUI.Tests rows seeding DriverType="ModbusTcp" → "Modbus".

A friendly display label ("Modbus TCP") stays in the picker UI; only the stored/dispatched value canonicalizes. Any legacy "ModbusTcp" DriverInstance.DriverType row (none on the rig) is a documented one-line SQL UPDATE — not a migration.

Rejected: canonicalize on "ModbusTcp" (forces a runtime-factory-key change + seed + DB migration — touches the load-bearing dependency); dual-alias registration (YAGNI machinery).

Tests

Unit: TagConfigEditorMap.Resolve("Modbus") returns the Modbus editor; TagConfigValidator validates "Modbus"; the picker/router dispatch on "Modbus". Update the ~13 AdminUI.Tests rows. Live /run: the rig's seeded MAIN-modbus-eq now opens the typed Modbus editor + Build-address button in the /uns Tag modal (the exact thing Phase 6 couldn't drive).

---

Component 2 — Galaxy nested gobject hierarchy

Problem

GalaxyDiscoverer.DiscoverAsync (Driver.Galaxy/Browse/GalaxyDiscoverer.cs) calls builder.Folder(...) at root level for every gobject, then adds the gobject's variables into it. Large Galaxy models browse as a flat list.

Approach (chosen): nest by parent_gobject_id (driver-internal, no gateway change)

The gateway proto GalaxyObject already carries the parentage we need: gobject_id (1), parent_gobject_id (5), is_area (6), hosted_by_gobject_id (8). IAddressSpaceBuilder.Folder(...) returns IAddressSpaceBuilder, so folders already nest (parentFolder.Folder(child, child)) — no contract change.

Rewrite DiscoverAsync as a two-pass build:

1. Pass 1 — folder map: create a gobject_id → folder-builder entry for every gobject (browse name = contained_name ?? tag_name, as today). Don't attach to a parent yet.
2. Pass 2 — link + populate: for each gobject, resolve its folder under its parent's folder when parent_gobject_id != 0 and that parent id is in the map; otherwise attach to the driver root (the current flat behaviour). Then add the gobject's variables into its own folder (unchanged per-attribute logic, incl. alarm-ref marking and the []-suffix strip).

Properties:

• Order-independent — children may appear before parents (build the map first, link second).
• Degrades to flat — gateways that don't populate parent_gobject_id (returns 0) or models with the parent outside the returned set fall back to root attachment. No regression for the current flat data.
• Nest by the model/area relationship (parent_gobject_id), not deployment hosting (hosted_by_gobject_id) — that is AVEVA's natural browse tree.
• Cycle/self-parent guard: if parent_gobject_id == gobject_id or a cycle is detected, attach to root (defensive; real Galaxy models are a DAG/tree).

Tests

Unit (Galaxy driver test project) — fake IGalaxyHierarchySource returns canned multi-level GalaxyObject sets through a capturing IAddressSpaceBuilder:

• two-level nest (child folder under parent folder, variables in the right folder);
• order-independence (child returned before parent → still nests);
• degrade-to-flat (parent_gobject_id=0, and parent-id-not-in-set → both attach to root);
• defensive self-parent/cycle → root. Live /run: Client.CLI browse the Galaxy driver tree vs the gateway on 10.100.0.48 → nested folders instead of flat.

---

Component 3 — FOCAS cnc_getfigure auto-scale

Problem

FocasDriver.PublishAxisSnapshot divides axis positions by 10^PositionDecimalPlaces (FocasDriver.cs:823-829), where PositionDecimalPlaces is a manual per-device config knob (default 0, added in Phase 4). The CNC reports the real figure via cnc_getfigure (IFocasClient.cs:219-221 notes the auto path "once that export lands").

Approach (chosen): add a cnc_getfigure binding; auto wins, manual is the fallback

• Add a binding to IFocasClient (e.g. Task<IReadOnlyList<int>> GetPositionFiguresAsync(CancellationToken) returning the per-axis decimal-place figure). The Wire client P/Invokes cnc_getfigure; the Fake and Unimplemented clients return an empty/unsupported result.
• At init (alongside the existing axis-name/sysinfo reads), fetch the per-axis figures and cache them on the driver state.
• Precedence (approved): auto wins; manual is the fallback. When cnc_getfigure returns a usable figure for an axis, that figure is authoritative for that axis's scale. When it returns nothing / is unavailable (older FWLIB, Fake/Unimplemented backend, per-axis gap), fall back to the configured PositionDecimalPlaces. This keeps existing manual-knob configs working when the CNC doesn't report and matches the "auto-scale" intent (the CNC's own scaling is the truth).
• Resolve the effective decimal places per axis (the figure can differ by axis), so PublishAxisSnapshot divides each axis by its own 10^figure.

Rejected: drop the manual knob entirely (loses the fallback for backends/sims that can't report); leave manual-only (that's the current gap).

Tests

Unit (FOCAS driver test project) with a fake IFocasClient:

• auto wins — fake returns figures → driver scales by the auto figure, ignoring a differing manual config;
• fallback — fake returns nothing/unsupported → driver uses the manual PositionDecimalPlaces;
• per-axis — different figures per axis scale independently;
• regression — the existing manual-only path (no getfigure) still divides correctly. Unit-proven only (no CNC on this Mac — honestly operator-gated for a live read).

---

Out of scope (deferred)

• S7 wide types / Timer-Counter, the cross-driver array slice (sink-contract change), AbCip/TwinCAT UDT member-paths, AbLegacy/TwinCAT bit-RMW writes, OpcUaClient ReadEventsAsync, Historian tie-cluster paging (#400). These remain the next slices of Phase 4b's theme.

Done criteria

• dotnet build ZB.MOM.WW.OtOpcUa.slnx clean.
• Affected suites green: AdminUI.Tests (Modbus reconcile), Galaxy driver tests (nesting), FOCAS driver tests (auto-scale).
• Live /run: Modbus typed editor + Build-address reachable on the rig's seeded driver; Galaxy tree browses nested vs the gateway. FOCAS unit-proven (operator-gated live).
• Subagent-driven, per-task review by classification, final integration review, then merge + push.