# Code Review — Commons

<!-- Per-module findings for the Commons shared-utilities / message-contracts library.
     See ../../REVIEW-PROCESS.md for the full process. The base README.md is generated
     from these files by regen-readme.py — do not edit README.md by hand. -->

| Field | Value |
|---|---|
| Module | `src/Core/ZB.MOM.WW.OtOpcUa.Commons` |
| Reviewer | Claude Code |
| Review date | 2026-06-19 |
| Commit reviewed | `7286d320` |
| Status | Reviewed |
| Open findings | 0 |

## Checklist coverage

A comprehensive review completes every category, recording "No issues found" where
a category produced nothing rather than leaving it blank.

| # | Category | Result |
|---|---|---|
| 1 | Correctness & logic bugs | No issues found |
| 2 | OtOpcUa conventions | No issues found |
| 3 | Concurrency & thread safety | No issues found |
| 4 | Error handling & resilience | No issues found |
| 5 | Security | No issues found |
| 6 | Performance & resource management | No issues found |
| 7 | Design-document adherence | No issues found |
| 8 | Code organization & conventions | Commons-002 (deferred) |
| 9 | Testing coverage | Commons-003, Commons-004 |
| 10 | Documentation & comments | Commons-001 |

## Findings

### Commons-001

| Field | Value |
|---|---|
| Severity | Low |
| Category | Documentation & comments |
| Location | `src/Core/ZB.MOM.WW.OtOpcUa.Commons/Observability/OtOpcUaTelemetry.cs:79` |
| Status | Resolved |

**Description:** The XML doc comment on `StartAddressSpaceRebuildSpan` read "Phase7 plan →
apply", referencing the old `Phase7*` naming that was renamed to `AddressSpace*` in commit
`40e8a23e` (2026-06-18). The method name itself was correct; only the summary text was stale.

**Recommendation:** Replace "Phase7 plan → apply" with "AddressSpace plan → apply" in the summary.

**Resolution:** Fixed 2026-06-19 — updated stale "Phase7 plan → apply" to "AddressSpace plan → apply" in the XML doc comment (src edit, no commit SHA yet).

---

### Commons-002

| Field | Value |
|---|---|
| Severity | Low |
| Category | Code organization & conventions |
| Location | `src/Core/ZB.MOM.WW.OtOpcUa.Commons/Messages/Admin/RestartDriver.cs:27,36`, `ReconnectDriver.cs:16,25`, `TestDriverConnect.cs:16,27` |
| Status | Deferred |

**Description:** `RestartDriver`, `ReconnectDriver`, and `TestDriverConnect` (plus their result
records) carry `Guid CorrelationId` parameters using the raw `System.Guid` type, while every
other Commons message record uses the typed `CorrelationId` wrapper. This divergence requires
callers to manually extract `.Value` or wrap a raw `Guid` when correlating across these
boundaries. The inconsistency appears to be a historical accident — these three messages
predate the `CorrelationId` struct.

**Recommendation:** Migrate `Guid CorrelationId` → `CorrelationId CorrelationId` across
`RestartDriver`, `ReconnectDriver`, `TestDriverConnect` and their result records. This is a
cross-cutting public-API change that touches callers in at least AdminUI, Runtime, and Cluster
projects; defer to a coordinated cleanup pass.

**Resolution:** Deferred — cross-cutting public-API change requiring coordinated update across at least three other modules (AdminUI, Runtime, Cluster). Safe to defer.

---

### Commons-003

| Field | Value |
|---|---|
| Severity | Low |
| Category | Testing coverage |
| Location | `src/Core/ZB.MOM.WW.OtOpcUa.Commons/OpcUa/DeferredAddressSpaceSink.cs`, `DeferredServiceLevelPublisher.cs` |
| Status | Resolved |

**Description:** `DeferredAddressSpaceSink` and `DeferredServiceLevelPublisher` had no unit
tests. The deferred-sink pattern is a production-critical seam (a previously recorded MEMORY.md
gotcha: "a new optional capability interface MUST be forwarded through
`DeferredAddressSpaceSink` or it's inert on every driver-role host"). Key invariants now
covered: (1) before `SetSink`, all write operations are safe no-ops; (2) after `SetSink`,
operations are forwarded; (3) `UpdateTagAttributes` returns `false` for non-surgical inners and
`true` for surgical inners; (4) `SetSink(null)` / `SetInner(null)` reverts to the null sink.

**Recommendation:** Add `DeferredAddressSpaceSinkTests` and `DeferredServiceLevelPublisherTests`
under `tests/Core/ZB.MOM.WW.OtOpcUa.Commons.Tests/OpcUa/`.

**Resolution:** Fixed 2026-06-19 — added `DeferredAddressSpaceSinkTests.cs` (8 tests) and `DeferredServiceLevelPublisherTests.cs` (3 tests) covering the five invariants; all pass.

---

### Commons-004

| Field | Value |
|---|---|
| Severity | Low |
| Category | Testing coverage |
| Location | `tests/Core/ZB.MOM.WW.OtOpcUa.Commons.Tests/OpcUa/EquipmentNodeIdsTests.cs` |
| Status | Resolved |

**Description:** `EquipmentNodeIds.Variable` uses `IsNullOrWhiteSpace` to detect empty
`folderPath`, so a whitespace-only value (e.g. `"   "`) is treated identically to
null/empty — the parent falls back to `equipmentId` directly. This is the correct behaviour
but the whitespace-only branch had no test, leaving the intent implicit.

**Recommendation:** Add an `[InlineData]` case covering whitespace-only `folderPath`.

**Resolution:** Fixed 2026-06-19 — added `Variable_with_whitespace_folder_is_equipment_slash_name` test to `EquipmentNodeIdsTests.cs`; passes.