lmxopcua/docs/plans/2026-07-16-v3-batch3-PR.md

v3 Batch 3 — UNS reference-only Equipment + {{equip}}/<RefName> reference-relative resolution

Implements docs/plans/2026-07-15-v3-batch3-uns-rework-plan.md (WP1–WP4), executed via the /v3-batch 3 coordinator: contracts-first fan-out, worktree-isolated Opus agents per wave, a code-reviewer pass + green build/test after each wave, then the non-negotiable 5-item live gate on docker-dev.

What landed

• Contracts — IEffectiveNameGuard (authoring-time effective-name uniqueness seam; WP2 implements, WP1 consumes).
• Wave A (3 parallel agents):
  • WP1 — equipment Tags tab → UnsTagReference list (effective name / RawPath / inherited DataType+AccessLevel / display-name override); new AddReferenceModal reusing RawTree in opt-in PickerMode (multi-select tag leaves + device/tag-group "Select all tags below"), cluster-scoped (structural + server-enforced tag.cluster == equipment.cluster); UnsTreeService reference CRUD; consumes IEffectiveNameGuard in all colliding mutations; ImportEquipmentModal/EquipmentInput dropped DriverInstanceId; deleted the retired equipment TagModal.
  • WP2 — EffectiveNameGuard (injectable, ordinal) + DI registration; verified the deploy-gate UnsEffectiveNameCollision rule (already computes ref effective name as override-else-current-raw-name, so it catches rename-induced collisions; ordinal; names both sources + equipment).
  • WP3 — RawTreeService.BuildRenameWarningsAsync: refined historized warning (only tags without a historianTagname override) + UNS-referenced + new substring scan of every Script.SourceCode for affected tags' OLD RawPaths (recomputed pre-save via RawPathResolver, ordinal).
• Wave B (1 integration agent):
  • WP4 — {{equip}}/<RefName> reference-relative resolution. EquipmentScriptPaths.DeriveEquipmentBase deleted; slash joint replaces the dot joint; new shared EquipmentReferenceMap (equipmentId → effectiveName → RawPath) built identically at both compose seams (AddressSpaceComposer + DeploymentArtifact, byte-parity). Unresolved-ref deploy error (EquipReferenceUnresolved) covering VT scripts, SA predicates, and SA message-template tokens; authoring guard (ValidateEquipTokenAsync, the Wave-A M1 fix); Monaco {{equip}}/ completion of reference effective names + unresolved diagnostic (OTSCRIPT_EQUIPREF), EquipmentId threaded request→model→JS.

Address space stays dark (values light up in Batch 4). Full solution builds 0 errors; Commons 309, Configuration 121, AdminUI 659, OpcUaServer 335/4-skip, Runtime 361/42-skip (the skips are the Batch-1 dark-address-space tests Batch 4 un-skips).

Reviewer findings fixed in-branch

• Wave A — no HIGH. Verified: the register-AND-consume guard seam (prod DI injects the real guard; the NoOp fallback only wins under new in tests; guard invoked in all 6 colliding mutations); cluster scoping structural + server-enforced; Razor default RawTree byte-unchanged; WP3 pre-save RawPath recomputation. L1 (misleading concurrency comment) fixed.
• Wave B — no HIGH; byte-parity + production wiring confirmed. M1 fixed: the editor⇔authoring⇔deploy invariant now holds on the ScriptedAlarm surface too (SA predicate + message-template {{equip}} refs validated at authoring, matching the deploy gate). L3 fixed: parity test hardened (unresolved-ref-intact
  • folder/tag-group RawPath ancestry). L1 already closed at the write path (empty override normalized→null).
• Deferred (documented follow-ups): absolute-path Monaco completion still projects the raw leaf name, not the RawPath (out of {{equip}} scope; {{equip}}/ completion works) — rework ScriptTagCatalog to RawPaths in Batch 4; a broken raw-topology-chain reference is deploy-accepted but compose-dropped (low reachability); message-template {{equip}}/X is gate-validated but rendered/substituted only in Batch 4.

Live /run gate (docker-dev :9200, both central nodes rebuilt on Batch-3 code)

Substrate: an Area→Line→Equipment seeded in MAIN, plus a SITE-A raw tag so cross-cluster exclusion is demonstrable. (Hand-seeded equipment surfaced the Batch-1 EquipmentIdNotDerived invariant — the canonical EQ-<hash> id was applied before the gate.)

1. Reference picker + list — "+ Add reference" header "The tree is scoped to the equipment's cluster"; only the Main cluster root shows (SITE-A/B absent — the seeded SiteAOnly tag unreachable); lazy expansion; a device "Select all tags below" pulled tags across a collapsed group → 4 references in one commit. Rows show effective name / RawPath (incl. deep opcua1/plc/OpcPlc/Telemetry/Basic/… ancestry) / DataType / Access / override. Set override "MainPressure" → effective name updated HR200 → MainPressure, RawPath unchanged.
2. Collision — authoring: setting a reference override to an existing VirtualTag's name → red banner "effective name 'GateVt' already used by VirtualTag 'VT-gatevt' in equipment '…'" (not persisted). rename-induced: renamed a raw tag so two references collide (allowed at rename) → deploy 422 [UnsEffectiveNameCollision] 2 UNS signals collide on effective name 'ImportedTag' … reference '…', reference '…'.
3. {{equip}} (editor ⇔ deploy) — resolving {{equip}}/MainPressure deploys 202; misspelled {{equip}}/MainPresure deploys 422 [EquipReferenceUnresolved] … has no reference named 'MainPresure'. Monaco: red squiggle + hover "'{{equip}}/MainPresure' does not resolve — … no reference named 'MainPresure' … (OTSCRIPT_EQUIPREF)"; typing {{equip}}/ completes the four reference effective names (AlternatingBoolean, ImportedTag, MainPressure, RandomSignedInt32).
4. Rename warning — renaming a driver whose beneath-it tag is historized-without-override + UNS-referenced
   • named in a script literal → "Renamed — with warnings" listing all three (historized fork, UNS-referenced by 'gateequip', "2 scripts ('cval','gatevt') reference tags … by their raw paths"); renaming an unrelated driver → no warning dialog. (Note: direct tag rename flows through UpdateTagAsync which has no warnings surface — warnings fire on container renames affecting descendants; documented follow-up if per-tag-rename warnings are wanted.)
5. Import without driver column — the Import equipment CSV modal columns are Name, MachineCode, UnsLineId (+ optional ZTag, SAPID, Manufacturer, Model); no DriverInstanceId.

Docs

docs/Uns.md Tags section rewritten to the reference-only model; docs/ScriptEditor.md updated (WP4) to the slash/reference {{equip}} semantics; CLAUDE.md gains a v3 Batch 3 paragraph.

https://claude.ai/code/session_01LVneM3eh1UtJxEisFXgmox