lmxopcua/docs/plans/2026-07-15-v3-implementation-plan.md

v3 implementation plan — master orchestration

Date: 2026-07-15 Design: docs/plans/2026-07-15-raw-uns-two-subtree-v3-design.md (all open items resolved; required reading for every agent) Companion designs: 2026-07-15-calculation-driver-mini-design.md (Batch 2), 2026-07-15-universal-discovery-browser-design.md (pre-v3 dependency) Batch plans: 2026-07-15-v3-batch1-schema-identity-plan.md · 2026-07-15-v3-batch2-raw-ui-calculation-plan.md · 2026-07-15-v3-batch3-uns-rework-plan.md · 2026-07-15-v3-batch4-address-space-plan.md Executors: Opus agents. This document is the coordinator's contract: batch order, parallel lanes, merge discipline, and the non-negotiable verification gates.

1. Shape of the work

Four sequential batches (each = one feature branch + one PR to master, merged only after its live gate passes), plus one batch-independent track (Track 0) that can run in parallel with Batch 1 because it touches nothing Batch 1 touches.

Track 0 (parallel with Batch 1): ContextMenu component · RFC-4180 CSV parser ·
                                 DriverType constants · Calculation evaluator core
        │
Batch 1 (schema + RawPath identity)  ──►  Batch 2 (/raw UI + Calculation driver)
        ──►  Batch 3 (UNS reference-only + {{equip}})  ──►  Batch 4 (dual-namespace
        address space)  =  v3.0

Precondition: the universal DiscoveryDriverBrowser (2026-07-15-universal-discovery-browser-design.md) is a pre-v3 dependency that is NOT in the tree yet (verified 2026-07-15: no DiscoveryDriverBrowser exists; ITagDiscovery has no SupportsOnlineDiscovery member — the browser design adds it). Only Batch 2 work package B2-WP6 (browse re-target) is blocked on it. Everything else proceeds; if the browser slips, B2-WP6 detaches into a follow-up PR and the Batch 2 gate runs without the browse-commit leg.

Why the batches cannot overlap: each batch's live gate deploys the previous batch's schema/UI to docker-dev. Batch 2 authors against Batch 1's schema; Batch 3 references Batch 2's raw tags; Batch 4 lights up what 1–3 authored. Parallelism lives inside batches (see each batch plan's wave schedule), not between them.

2. Agent execution model

• One coordinator agent per batch. It reads the design + the batch plan, spawns implementation agents per work package, owns the batch feature branch, and is the only agent that merges.
• Implementation agents run in isolated git worktrees (isolation: worktree / EnterWorktree). Hard rule from project history: parallel implementers on a shared checkout race the git index and corrupt each other's staging — never share a tree.
• Contract-first fan-out. When a wave shares new types (e.g. the RawPaths helper, the reshaped entities), the coordinator lands a small contracts commit on the batch branch first; wave agents branch from it. No agent invents a shared type mid-wave.
• File-ownership discipline. The wave tables in each batch plan assign files to exactly one work package per wave. If an agent finds it must touch a file owned by another package, it stops and reports — the coordinator re-slices rather than letting two agents edit one file.
• Merge order is the wave order. After each wave merges, the coordinator runs dotnet build ZB.MOM.WW.OtOpcUa.slnx && dotnet test ZB.MOM.WW.OtOpcUa.slnx before starting the next wave. A red build blocks the next wave; the coordinator fixes or reverts, never "fixes forward" into a parallel wave.
• Review checkpoint per wave: a code-reviewer agent reviews the wave diff against the batch plan before merge. Findings are fixed in the worktree, not post-merge.
• Each batch ends with the live /run gate executed by an agent with browser tools (the docker-dev AdminUI has Security__Auth__DisableLogin: "true" — no sign-in needed; drive http://localhost:9200 directly). Live gates are non-negotiable: this project has repeatedly shipped prod-inert code that 250+ unit tests and three reviews missed (the DeferredAddressSpaceSink forwarding trap, the dormant GatewayTagProvisioner). A batch is not done until its live-gate checklist passes.

3. Track 0 — batch-independent work (start immediately, parallel with Batch 1)

Four packages with zero overlap with Batch 1's files. Each is a separate worktree + separate small PR (or merged onto the Batch 2 branch when it opens).

ID	Package	New files (nothing existing is touched)	Verification
T0-1	ContextMenu Blazor component — reusable oncontextmenu menu with keyboard/touch fallback (explicit "⋯" affordance). No right-click menu exists anywhere in the Blazor app today (the only ContextMenu is in the Avalonia desktop client — do not confuse them).	src/Server/ZB.MOM.WW.OtOpcUa.AdminUI/Components/Shared/ContextMenu.razor (+ .razor.css), ContextMenuItem.cs	Demo host page under a dev-only route; manual live check on docker-dev (AdminUI has no bUnit — Razor bugs must be live-verified)
T0-2	RFC-4180 CSV parser — quoted fields, embedded commas/quotes/newlines, CRLF/LF; plus a writer that quotes on demand. Pure, no I/O. No CSV code exists in the repo today (verified) — greenfield.	src/Core/ZB.MOM.WW.OtOpcUa.Commons/Csv/CsvParser.cs, CsvWriter.cs; tests in tests/Core/ZB.MOM.WW.OtOpcUa.Commons.Tests/Csv/	Unit suite incl. RFC 4180 edge corpus (quoted quote, trailing newline, empty field vs absent field)
T0-3	DriverTypeNames constants class — single source of truth for driver-type strings, authority = the factories' DriverTypeName (TwinCAT, FOCAS, GalaxyMxGateway). Consumed later by the four drifted maps (DriverEditRouter._componentMap currently keys TwinCat/Focas; TagConfigEditorMap; TagConfigValidator; EquipmentTagConfigInspector in ControlPlane, not AdminUI). T0-3 only adds the constants + a reflection test asserting they match every registered factory; the four consumers are rewired in Batch 2 (B2-WP8).	src/Core/ZB.MOM.WW.OtOpcUa.Core.Abstractions/DriverTypeNames.cs; test in tests/Core/ZB.MOM.WW.OtOpcUa.Core.Abstractions.Tests/ (or Commons.Tests if no such project)	Reflection test: every DriverTypeName exposed by DriverFactoryBootstrap.AddOtOpcUaDriverFactories registrations has a matching constant, and vice versa
T0-4	Calculation evaluator core — CalculationEvaluator built like RoslynVirtualTagEvaluator (src/Server/ZB.MOM.WW.OtOpcUa.Host/Engines/RoslynVirtualTagEvaluator.cs): CompiledScriptCache + TimedScriptEvaluator (2 s) + VirtualTagContext, single-tag mode (ctx.SetVirtualTag dropped + logged). Pure engine + unit tests only; the driver shell that hosts it is Batch 2 (B2-WP7). See mini-design §4.	New project src/Drivers/ZB.MOM.WW.OtOpcUa.Driver.Calculation/ (evaluator + tests only at this stage)	Parity unit tests vs the VT evaluator: passthrough fast-path, timeout, sandbox violation, SetVirtualTag drop

4. Batch summaries + gates (detail in the batch plans)

Batch	Branch	Content	Gate (summary — full recipe in the batch plan)
1	v3/batch1-schema-identity	Greenfield EF schema (RawFolder/Device-universal/TagGroup/Tag-raw-only/UnsTagReference; Namespace + EquipmentImportBatch retired); RawPaths identity helper; TagConfigIntent sheds FullName; all 8 drivers' resolvers keyed by RawPath (blob-fallback parsers retired); endpoint→DeviceConfig move; composer/artifact/DraftValidator/UnsTreeService rewired; seeds + golden corpus rewritten. Address space intentionally dark.	Full solution build + test green (incl. rewritten corpus); V3Initial migration applies to a fresh DB; docker-dev re-seeds and both nodes boot with drivers Connected (values not yet exposed — that's Batch 4)
2	v3/batch2-raw-ui	/raw project tree (lazy loading + T0-1 menus), driver config/device modals (typed pages refactored to embeddable bodies), tag manual entry + CSV import/export (T0-2 + decided column dictionaries), browse re-target (gated on universal browser), Calculation driver (T0-4 + mini-design), DriverTypeNames rewire	Live /run on :9200: author folder→driver→device→tags in-tree; Test-connect green vs a fixture; CSV round-trip; browse-commit raw tags (if browser landed); author + deploy a calc tag. Proves authoring + probe only — no live values until Batch 4
3	v3/batch3-uns-rework	Equipment Tags tab → reference list + cluster-scoped multi-select raw picker; effective-name uniqueness (authoring + DraftValidator); {{equip}} reference-relative resolution + unresolved-ref deploy error; rename-warning substring scan	Live /run: reference raw tags into an equipment; display-name override shows; deploy gate rejects a reference collision and an unresolved {{equip}} ref
4	v3/batch4-address-space	Dual namespaces, RawPath NodeIds, UNS fan-out registration, raw-only runtime binding, write routing via either NodeId, alarm multi-notifier (AddNotifier pattern + teardown symmetry), historian dual-registration, sink namespace discriminator + DeferredAddressSpaceSink forwarding + reflection-test extension	Live /run + Client.CLI: browse both namespaces; read/subscribe/write through both NodeIds; HistoryRead via both; native alarm visible at raw + equipment notifiers with exactly one Server-object copy; {{equip}} script computes; failed-write revert still works. = v3.0

5. Global conventions (binding for every agent)

• .NET 10, C#, xUnit + Shouldly, Serilog. Match surrounding code style; comments only for constraints the code can't show.
• JSON config keys are camelCase; enum values serialize as string names (JsonStringEnumConverter). Systemic past bug: AdminUI pages serialized enums numerically while DTOs were string-typed → authored configs faulted drivers. Every new serialization site gets the converter, and every new editor gets a round-trip test.
• Editors/models preserve unknown JSON keys (the established <Driver>TagConfigModel FromJson/ToJson contract). .NET 10 JsonNode.ToJsonString gotchas are documented in the existing models — copy the Modbus template.
• Do not enable CentralPackageTransitivePinningEnabled (breaks the Roslyn build via the 5.0.0/4.12.0 split). Transitive CVE fixes = surgical direct PackageReference at a common-ancestor project.
• EF migrations via dotnet ef with DesignTimeDbContextFactory (reads OTOPCUA_CONFIG_CONNECTION, defaults to 10.100.0.35,14330). All model config lives inline in OtOpcUaConfigDbContext.OnModelCreating — keep it there (no IEntityTypeConfiguration files exist; don't introduce the pattern mid-stream).
• Blazor: string component parameters need the @ prefix when passing C# expressions (the F15 gotcha that bit Global UNS); no bUnit exists — live-verify every Razor change on docker-dev.
• Name collision: Runtime already owns src/Server/ZB.MOM.WW.OtOpcUa.Runtime/Drivers/CapturingAddressSpaceBuilder.cs — any browser-side capturing builder must use a different name or namespace-qualify.

6. Global gotchas (project scar tissue — read before coding)

1. The forwarding trap (highest-severity recurring bug): any new or changed method on IOpcUaAddressSpaceSink / ISurgicalAddressSpaceSink (src/Core/ZB.MOM.WW.OtOpcUa.Commons/OpcUa/) must be forwarded through DeferredAddressSpaceSink and covered by tests/Core/ZB.MOM.WW.OtOpcUa.Commons.Tests/OpcUa/DeferredSinkForwardingReflectionTests.cs. A non-forwarded method compiles, passes unit tests, and is silently dead on driver hosts in production. Same family: registering a service in DI without passing it into its consumer (the dormant-GatewayTagProvisioner bug) — every "register X" step needs a "consume X" assertion.
2. OnWriteValue runs under the node-manager lock — treat driver write dispatch as fire-and-forget (Tell, never blocking ask) exactly as OnEquipmentTagWrite does today (OtOpcUaNodeManager.cs:1451).
3. Resolve DriverHostActor lazily from consumers wired at startup — the actor spawns after DI graph construction.
4. docker-dev :9200 round-robins central-1/central-2 behind Traefik — rebuild and restart both (docker compose build central-1 central-2 && docker compose up -d) before trusting any AdminUI verification; kind-changing config edits need deploy-THEN-recreate.
5. Historian provisioning: StorageRateMs must be > 0 (proto default 0 throws gateway-side and silently fails all provisioning — PR #439).
6. Client.CLI write reads first — you cannot write a node whose read is Bad. To force a protocol write failure on the rig, use the modbus fixture's exception_injector (FC06 reject rule on a seeded Good address).
7. Data-plane role tests need Security:Ldap:GroupToRole in appsettings; LDAP is the shared GLAuth 10.100.0.35:3893 (all test users password password).
8. Deploy API: POST http://localhost:9200/api/deployments with X-Api-Key from Security:DeployApiKey (self-disables 503 when unset). Direct SQL edits against the config DB need SET QUOTED_IDENTIFIER ON.
9. Driver fixtures live on the Docker host 10.100.0.35, controlled via lmxopcua-fix ls|up|down|sync from this VM (docker -H ssh:// does NOT work).
10. Native-alarm routing keys on ConditionId (the authored ref), never SourceNodeId — under v3 the ConditionId becomes the RawPath.

7. Deliverable checklist (coordinator ticks per batch)

• Batch branch opened from up-to-date master; contracts commit landed before fan-out.
• Every wave: worktree-isolated agents, file-ownership respected, reviewer pass, green build+test after merge.
• Batch-specific unit/integration suites listed in the batch plan all green, including the DB-backed suites (Configuration.Tests schema-compliance against 10.100.0.35,14330) and the 2-node harness (tests/Server/ZB.MOM.WW.OtOpcUa.Host.IntegrationTests/, default in-memory mode).
• Live /run gate checklist from the batch plan executed and evidence recorded in the PR description (what was clicked/deployed/observed).
• Docs touched by the batch updated in the same PR (docs/Configuration.md, docs/Uns.md, docs/ScriptEditor.md, docs/Historian.md, CLAUDE.md sections that describe replaced behavior).
• Cross-repo: after Batch 4 merges, update the ScadaBridge coordination note + the umbrella index ../scadaproj/CLAUDE.md OtOpcUa entry (the design's cutover plan step 4).