lmxopcua/docs/v2/implementation/adr-001-equipment-node-walker.md

# ADR-001 — Equipment node walker: how driver tags bind to the UNS address space

**Status:** Accepted 2026-04-20 — Option A (Config-primary); Option D deferred to v2.1

**Related tasks:** [#195 IdentificationFolderBuilder wire-in](../../../) (blocked on this)

**Related decisions in `plan.md`:** #110 (Tag belongs to Equipment via FK in Equipment ns),
#116 / #117 / #121 (five identifiers as properties, `Equipment.Name` as path segment),
#120 (UNS hierarchy mandatory in Equipment ns; SystemPlatform ns exempt).

## Context

Today the `DriverNodeManager` builds its address space by calling
`ITagDiscovery.DiscoverAsync` on each registered driver. Every driver returns whatever
browse shape its wire protocol produces — Galaxy returns gobjects with attributes, Modbus
returns whatever tag configs the operator authored, AB CIP returns controller-walk output,
etc. The result is a per-driver subtree, rooted under the driver's own namespace, with no
UNS levels.

The Config DB meanwhile carries the authoritative UNS model for every Equipment-kind
namespace:

```
ConfigGeneration
 └─ ServerCluster
    └─ Namespace (Kind=Equipment)
       └─ UnsArea
          └─ UnsLine
             └─ Equipment (carries 9 OPC 40010 Identification fields + 5 identifiers)
                └─ Tag (EquipmentId FK when Kind=Equipment; DriverInstanceId + FolderPath when Kind=SystemPlatform)
```

Decision #110 already binds `Tag → Equipment` by foreign key. Decision #120 requires the
Equipment-namespace browse tree to conform to `Enterprise/Site/Area/Line/Equipment/TagName`.
The building blocks exist:

- `IdentificationFolderBuilder.Build(equipmentBuilder, row)` — pure function that hangs
  nine OPC 40010 properties under an Equipment node. Shipped, untested in integration.
- `Equipment` table rows with `UnsLineId` FK + the 9 identification columns + the 5
  identifier columns.
- `Tag` table rows with nullable `EquipmentId` + a `TagConfig` JSON column carrying the
  wire-level address.
- `NodeScopeResolver` — Phase-1 stub that returns a cluster-level scope only, with an
  explicit "future resolver will join against the Configuration DB" note.

What's missing is the **walker**: server-side code that reads the UNS + Equipment + Tag
rows for the current published generation, traverses them in UNS order, materializes each
level as an OPC UA folder, and wires `IdentificationFolderBuilder.Build` + the 5-identifier
properties under each Equipment node.

The walker isn't pure bookkeeping — it has to decide **how driver-discovered tags bind to
UNS Equipment nodes**. That's the decision this ADR resolves.

## Open question

> For an Equipment-kind driver, is the published OPC UA surface driven by (a) the Config
> DB's `Tag` rows, (b) the driver's `ITagDiscovery.DiscoverAsync` output, or (c) some
> combination?

SystemPlatform-kind drivers (Galaxy only, today) are unambiguous: decision #120 exempts
them from UNS + they keep their v1 native hierarchy. The walker does not touch
SystemPlatform namespaces beyond the existing driver-discovery path. This ADR only decides
Equipment-kind composition.

## Options

### Option A — Config-primary

The `Tag` table is the sole source of truth for what gets published. `ITagDiscovery`
becomes a validation + enrichment surface, not a discovery surface.

**Walker flow:**

1. Read `UnsArea` / `UnsLine` / `Equipment` / `Tag` for the published generation.
2. Walk Area → Line → Equipment, materializing each level as an OPC UA folder.
3. Under each Equipment node:
   - Add the 5 identifier properties (`EquipmentId`, `EquipmentUuid`, `MachineCode`,
     `ZTag`, `SAPID`) as OPC UA properties per decision #121.
   - Call `IdentificationFolderBuilder.Build` to add the `Identification` sub-folder with
     the 9 OPC 40010 fields.
   - For each `Tag` row bound to this Equipment: ask the driver's `IReadable` /
     `IWritable` surface whether it can address `Tag.TagConfig.address`; if yes, create a
     variable node. If no, create a `BadNotFound` placeholder with a diagnostic so
     operators see the mismatch instead of a silent drop.
4. `ITagDiscovery.DiscoverAsync` is re-purposed to **enrich** — driver may return schema
   hints (data type, bounds, description) that operators missed when authoring the Tag
   row. The Admin UI surfaces them as "driver suggests" hints for next-draft edits.

**Trade-offs:**

- ✅ Matches decision #110's framing cleanly. `Tag` rows carry the contract; nothing gets
  published that's not explicitly authored.
- ✅ Same model for every Equipment-kind driver. Modbus / S7 / AB CIP / AB Legacy /
  TwinCAT / FOCAS / OpcUaClient all compose identically.
- ✅ UNS hierarchy is always exactly as-authored. No race between "driver added a tag at
  runtime" and "operator hasn't approved it yet."
- ✅ Aligns with the Config-DB-first operator story the Admin UI already tells.
- ❌ Drivers with large native schemas (TwinCAT PLCs with thousands of symbols, AB CIP
  controllers with full @tags walkers) can't "just publish everything" — operators must
  author Tag rows. This is a pure workflow cost, not a correctness cost.
- ❌ A Tag row whose driver can't address it produces a placeholder node at runtime
  (BadNotFound), not a publish-time validation failure. Mitigation: `sp_ValidateDraft`
  already validates per-driver references at publish — extend it to call each driver's
  existence check, or keep it as runtime-visible with an Admin UI indicator.

### Option B — Discovery-primary

`ITagDiscovery.DiscoverAsync` is the source of truth for what gets published. The walker
joins discovered tags against Config-DB Equipment rows to assemble the UNS tree.

**Walker flow:**

1. Driver runs `ITagDiscovery.DiscoverAsync` — returns its native tag graph.
2. Walker reads `Equipment` + `Tag` rows; uses `Tag.TagConfig.address` to match against
   discovered references.
3. For each match: materialize the UNS path + attach the discovered variable under the
   bound Equipment node.
4. Discovered tags with no matching `Tag` row: silently dropped (or surfaced under a
   `Unmapped/` diagnostic folder).
5. `Tag` rows with no discovered match: hidden (or surfaced as `BadNotFound` placeholder
   same as Option A).

**Trade-offs:**

- ✅ Lets drivers with rich discovery (TwinCAT `SymbolLoaderFactory`, AB CIP `@tags`)
  publish live controller state without operator-authored Tag rows for every symbol.
- ✅ Driver-native metadata (real OPC UA data types, real bounds) is authoritative.
- ❌ Conflicts with the Config-DB-first publish workflow. Operators publish a generation
  + discover a different set at runtime + the two don't necessarily match. Diff tooling
  becomes harder.
- ❌ Galaxy's SystemPlatform-namespace path still uses Option-B-like discovery — so the
  codebase would host two compositions regardless. But adding a second
  discovery-primary composition for Equipment-kind would double the surface operators
  have to reason about.
- ❌ Requires each driver to emit tag identifiers that stably match `Tag.TagConfig.address`
  shape across re-discovery. Works for Galaxy (attribute full refs are stable); harder for
  AB CIP where the @tags walker may return tags operators haven't declared.
- ❌ Operator-visible symptom of "my tag didn't publish" splits between two places: the
  Tag row exists (Config DB) + the driver can't find it (runtime discovery). Option A
  surfaces the same gap as a single `BadNotFound` placeholder; B multiplies it.

### Option C — Parallel namespaces

Driver tags are always published under a driver-native folder hierarchy (discovery-driven,
same as today). A secondary UNS "view" namespace is overlaid, containing Equipment nodes
with Identification sub-folders + `Organizes` references pointing at the driver-native tag
nodes.

**Walker flow:**

1. Driver's native discovery publishes `ns=2;s={DriverInstanceId}/{...driver shape}` as
   today.
2. Walker reads UNS + Equipment + Tag rows.
3. For each Equipment, creates a node under the UNS namespace (`ns=3;s=UNS/Site/Area/Line/Equipment`)
   + adds Identification properties + creates `Organizes` references from the Equipment
   node to the matching driver-native variable nodes.

**Trade-offs:**

- ✅ Preserves the discovery-first driver shape — no change to what Modbus / S7 / AB CIP
  publish natively; those projects keep working identically.
- ✅ UNS tree becomes an overlay that operators can opt into or out of. External consumers
  that want UNS addressing browse via the UNS namespace; consumers that want driver-native
  addressing keep using the driver namespace.
- ❌ Doubles the OPC UA node count for every Equipment-kind tag (one node in driver ns,
  one reference in UNS ns). OPC UA clients handle it but it inflates browse-result sizes.
- ❌ Contradicts decision #120: "Equipment namespace browse paths must conform to the
  canonical 5-level Unified Namespace structure." Option C makes the driver namespace
  browse path NOT conform; the UNS namespace is a second view. An external client that
  reads the Equipment namespace in driver-native shape doesn't see UNS at all.
- ❌ Identification ACL semantics get complicated — the sub-folder lives in the UNS ns,
  but the tag data lives in the driver ns. Two different scope ids; two grants to author.

### Option D — Config-primary with driver-discovery-assist

Same as Option A, but `ITagDiscovery.DiscoverAsync` is called during *draft authoring*
(not at server runtime) to populate an Admin UI "discovered tags available" panel that
operators can one-click-add to the draft Tag table. At publish time the Tag rows drive
the server as in Option A — discovery runs only as an offline helper.

**Trade-offs:**

- ✅ Keeps Option A's runtime semantics — Config DB is the sole publish-time truth.
- ✅ Closes Option A's only real workflow weakness (authoring Tag rows for large
  controllers) by letting operators import discovered tags with a click.
- ✅ Draws a clean line between author-time discovery (optional, offline) and publish-time
  resolution (strict, Config-DB-driven).
- ❌ Adds work that isn't on the Phase 6.4 checklist — Admin UI needs a "pull discovered
  tags from this driver" flow, which means the Admin host needs to proxy a DiscoverAsync
  call through the Server process (or directly into the driver — more complex deployment
  topology). v2.1 work, not v2.

## Recommendation

**Pick Option A.** Ship the walker as Config-primary immediately; defer Option D's
Admin-UI discovery-assist to v2.1 once the walker is proven.

Reasons:

1. **Decision #110 already points here.** `Tag.EquipmentId` + `Tag.TagConfig` are the
   published contract. Option A is the straight-line implementation of that contract.
2. **Identical composition across seven drivers.** Every Equipment-kind driver uses the
   same walker code path. New drivers (e.g. a future OPC UA Client gateway mode) plug in
   without touching the walker.
3. **Phase 6.4 Admin UI already authors Tag rows.** CSV import, UnsTab drag/drop, draft
   diff — all operate on Tag rows. The walker being Tag-row-driven means the Admin UI
   and the server see the same surface.
4. **BadNotFound is a clean failure mode.** An operator publishes a Tag row whose
   address the driver can't reach → client sees a `BadNotFound` variable with a
   diagnostic, operator fixes the Tag row + republishes. This is legible + easy to
   debug. Options B and C smear the failure across multiple namespaces.
5. **Option D is additive, not alternative.** Nothing in A blocks adding D later; the
   walker contract stays the same, Admin UI just gets a discovery-assist panel.

The walker implementation lands under two tasks this ADR spawns (if accepted):

- **Task A** — Build `EquipmentNodeWalker` in `Core.OpcUa` that drives the
  `ClusterNode → Namespace → UnsArea → UnsLine → Equipment → Tag` traversal, calls
  `IdentificationFolderBuilder.Build` per Equipment, materializes the 5 identifier
  properties, and creates variable nodes for each bound Tag row. Writes integration
  tests covering the happy path + BadNotFound placeholder.
- **Task B** — Extend `NodeScopeResolver` to join against Config DB + populate the
  full `NodeScope` path (UnsAreaId / UnsLineId / EquipmentId / TagId). Unblocks the
  Phase 6.2 finer-grained ACL (per-Equipment, per-UnsLine grants). Add ACL integration
  test per task #195 — browse `Equipment/Identification` as unauthorized user,
  assert `BadUserAccessDenied`.

Task #195 closes on Task B's landing.

## Consequences if we don't decide

- Task #195 stays blocked. The `IdentificationFolderBuilder` exists but is dead code
  reachable only from its unit tests.
- `NodeScopeResolver` stays at cluster-level scope. Per-Equipment / per-UnsLine ACL
  grants work at the Admin UI authoring layer + the data-plane evaluator, but the
  runtime scope resolution never populates anything below `ClusterId + TagId` — so
  finer grants are effectively cluster-wide at dispatch. Phase 6.2's rollout plan calls
  this out as a rollout limitation; it's not a correctness bug but it's a feature gap.
- Equipment metadata (the 9 OPC 40010 fields, the 5 identifiers) ships in the Config DB
  + the Admin UI editor but never surfaces on the OPC UA endpoint. External consumers
  (ERP, SAP PM) can't resolve equipment via OPC UA properties as decision #121 promises.

## Next step

Accept this ADR + spawn Task A + Task B.

If the recommendation is rejected, the alternative options (B / C / D) are ranked by
implementation cost in the Trade-offs sections above. My strong preference is A + defer D.