lmxopcua/docs/plans/2026-07-15-v3-batch1-schema-identity-plan.md

# v3 Batch 1 — greenfield schema + RawPath identity rewiring

**Branch:** `v3/batch1-schema-identity`
**Design authority:** `2026-07-15-raw-uns-two-subtree-v3-design.md` — §"v3 identity contract (RawPath)", §"Data model", §"Build plan" row 1.
**Master plan:** `2026-07-15-v3-implementation-plan.md` (conventions + gotchas are binding).
**End state:** the config schema and every identity seam speak RawPath; the solution builds and all tests pass; the address space composes hierarchy-only/empty (**deliberately dark until Batch 4**); docker-dev re-seeds and boots.

## Scope guard

- NO AdminUI feature work (Batch 2). AdminUI changes here are limited to *keeping it
  compiling* against the new entity shapes (pages that authored the old shapes may be
  temporarily stubbed with an "unavailable until Batch 2" banner — record each stub in the
  PR description; Batch 2 owns their replacement).
- NO OPC UA node materialization changes beyond making the composer emit an empty/
  hierarchy-only composition (Batch 4 owns the dual namespace).
- Greenfield means greenfield: no data-migration code, no back-compat shims for old
  `TagConfig` shapes, no blob-fallback retention "just in case."

## The RawPath contract (what every package codes against)

`RawPath = <Folder/…>/<DriverName>/<DeviceName>/<TagGroup/…>/<TagName>` — cluster-scoped,
slash-separated, built ONLY by the new `RawPaths` helper (never string-concatenated ad
hoc). Segments forbid `/` and leading/trailing whitespace (validated at authoring).
Case-sensitive ordinal comparison everywhere. It keys: driver wire-refs, the
`DriverHostActor` fan-out/write maps, historian default tagname + mux refs, native-alarm
`ConditionId`, `ctx.GetTag` paths, and (Batch 4) `ns=Raw` NodeIds.

## Work packages

### Wave A — foundations (2 agents, parallel, disjoint files)

**B1-WP1 — Greenfield EF model + `V3Initial` migration + seeds**

Files (all under `src/Core/ZB.MOM.WW.OtOpcUa.Configuration/` unless noted):
- `Entities/`: new `RawFolder.cs`, `TagGroup.cs`, `UnsTagReference.cs`; reshape
  `DriverInstance.cs` (add nullable `RawFolderId`; **drop `NamespaceId`**), `Device.cs`
  (add `DeviceConfig` JSON; now universal — every driver ≥1 device), `Tag.cs`
  (required `DeviceId` FK, nullable `TagGroupId`; **drop `EquipmentId` + `FolderPath`**;
  **keep `WriteIdempotent`** — dropping it regresses the R2 resilience fix),
  `Equipment.cs` (**drop the `DriverInstanceId`/`DeviceId` binding**). Delete
  `Namespace.cs`, `EquipmentImportBatch.cs` (both classes), and
  `Enums/NamespaceKind.cs`; delete `NamespaceKindCompatibility` + `AllowedNamespaceKinds`
  from `src/Core/ZB.MOM.WW.OtOpcUa.Core.Abstractions/DriverTypeRegistry.cs`.
- `OtOpcUaConfigDbContext.cs` — new DbSets; **all** uniqueness/integrity config inline in
  `OnModelCreating` per the design's rules: sibling-name unique indexes at every raw
  level (filtered indexes for nullable `ParentRawFolderId`/`RawFolderId`/`TagGroupId`),
  `OnDelete(Restrict)` so raw-tag delete is blocked while a `UnsTagReference` points at
  it and non-empty `RawFolder`/`TagGroup` deletes are blocked.
- **Migration strategy (decided): squash.** Delete the existing `Migrations/` folder and
  scaffold a single `V3Initial` migration. Port the hand-written stored-proc migrations'
  `Up` SQL (the `*_StoredProcedures.cs` / `*_ExtendComputeGenerationDiffWith*.cs` files)
  into `V3Initial` verbatim — audit them first: any proc referencing dropped
  columns/tables (`NamespaceId`, `Tag.EquipmentId`, `Tag.FolderPath`) must be rewritten
  to the new shape, and `ComputeGenerationDiff` must diff the new tables
  (`RawFolder`/`Device`/`TagGroup`/`UnsTagReference`). Greenfield = no production DB to
  upgrade, so squashing is safe; the fixture DBs are dropped/recreated.
- Seeds: rewrite `docker-dev/seed/seed-clusters.sql` (+ anything in
  `docker-dev/seed/entrypoint.sh` that names tables) and every `scripts/smoke/seed-*.sql`
  to the new schema — each driver gets a folder (optional), a device row with
  `DeviceConfig` (endpoint moved out of `DriverConfig` — coordinate the JSON shape with
  B1-WP5's contracts commit), and raw tags with RawPath-consistent names.
- Tests: `tests/Core/ZB.MOM.WW.OtOpcUa.Configuration.Tests/` —
  `SchemaComplianceFixture`/`SchemaComplianceTests` updated to the new schema; new unit
  tests for every integrity rule (delete-while-referenced blocked, non-empty folder/group
  delete blocked, default-device-with-tags delete blocked, sibling-name uniqueness per
  level, `/`-in-name rejected).

DoD: migration applies to a fresh DB (`dotnet ef database update` via
`DesignTimeDbContextFactory`); Configuration project + tests compile and pass (other
projects may be red until Wave B/C — that's expected mid-batch; the *batch branch* is
only merged green).

**B1-WP2 — `RawPaths` helper + `TagConfigIntent` successor + key normalization**

Files:
- New `src/Core/ZB.MOM.WW.OtOpcUa.Commons/Types/RawPaths.cs` — pure static: `Build(...)`
  from segment lists, `Validate(segment)` (no `/`, no lead/trail whitespace, non-empty),
  `Combine`, `TryParent`. This is the contracts-commit centerpiece — land it first.
- `src/Core/ZB.MOM.WW.OtOpcUa.Commons/Types/TagConfigIntent.cs` — sheds the
  FullName-derivation role: remove `FullName`/`ExplicitFullName` (the blob-as-identity
  convention dies here); **keep** the alarm/historize/array parsing
  (`TagAlarmIntent`, `ParseAlarm`/`ParseHistorize`/`ParseArray`) — those remain real
  `TagConfig` concerns. Callers to sweep (grounded list): `DraftValidator` (Galaxy
  ExplicitFullName rule → deleted; replaced by B1-WP6 rules),
  `Core/OpcUa/EquipmentNodeWalker.cs`, `OpcUaServer/AddressSpaceComposer.cs` +
  `AddressSpaceChangeClassifier.cs`, `AdminUI/ScriptAnalysis/IScriptTagCatalog.cs`,
  `AdminUI/Uns/TagEditors/OpcUaClientTagConfigModel.cs`,
  `Runtime/Drivers/DeploymentArtifact.cs`.
- Key normalization (greenfield, decided in the design): OpcUaClient's PascalCase
  `"FullName"` → `"nodeId"`; Galaxy's → `"attributeRef"`; the `deviceHostAddress` key
  (AbCip/AbLegacy/TwinCAT/FOCAS) is **dropped** (the tag's `DeviceId` FK owns placement).
  Update `OpcUaClientTagConfigModel.cs` (AdminUI) and the two browsers' commit paths
  (`Driver.OpcUaClient.Browser/OpcUaClientBrowseSession.cs`,
  `Driver.Galaxy.Browser/GalaxyBrowseSession.cs`) to emit the new keys.
- Tests: rewrite `tests/Core/ZB.MOM.WW.OtOpcUa.Commons.Tests/TagConfigIntentTests.cs`;
  new `RawPathsTests`; delete
  `Configuration.Tests/DraftValidatorGalaxyFullNameCorpusTests.cs` and
  `Core.Tests/OpcUa/EquipmentNodeWalkerFullNameCorpusTests.cs` (superseded — B1-WP6
  replaces them with RawPath-shaped corpus tests).

### Wave B — per-driver resolver rework (up to 9 agents, parallel, one per driver + exemplar-first)

**B1-WP3 — `EquipmentTagRefResolver` re-keying + blob-fallback retirement**

Shared seam first (the wave's contracts commit, done by the coordinator or the exemplar
agent): `src/Core/ZB.MOM.WW.OtOpcUa.Core.Abstractions/EquipmentTagRefResolver.cs` — the
`_byName` branch becomes the primary and only path: each deploy hands the driver its
authored raw tags keyed by RawPath (ref string) → `TagConfig`-derived definition. The
`_cache.GetOrAdd(fullReference, _parseRef)` blob-parse fallback is **deleted**; a miss is
a miss (`TryResolve` false → driver logs + Bad quality), never a parse attempt.

Then **exemplar: Modbus** (one agent, reviewed before fan-out so the pattern is fixed):
- `src/Drivers/ZB.MOM.WW.OtOpcUa.Driver.Modbus.Contracts/ModbusEquipmentTagParser.cs` —
  becomes a pure `TagConfig JSON → definition` mapper invoked at deploy-time table build
  (no more "is this ref a blob?" heuristics). Rename to `ModbusTagDefinitionFactory` (or
  similar) to make the retirement visible.
- Driver + tests updated to resolve by RawPath.

Then **fan-out, one agent per driver** (disjoint project directories — fully parallel):
S7 (`S7EquipmentTagParser.cs` — the leading-`{` blob convention dies), AbCip, AbLegacy,
TwinCAT, FOCAS (same shape as exemplar); **OpcUaClient** (no static parser — seam is
`Driver.OpcUaClient.Contracts/NamespaceMap.cs` + `OpcUaClientDriver.cs`; the definition's
address now reads `TagConfig.nodeId`); **Galaxy** (seam is
`Driver.Galaxy/Browse/GalaxyDiscoverer.cs` + `Browse/AlarmRefBuilder.cs`; address reads
`TagConfig.attributeRef`; note `AlarmRefBuilder` feeds `ConditionId` — under v3 that is
the RawPath, keep both directions consistent).

Each driver agent's DoD: driver project + its unit tests green with refs = RawPaths and
definitions sourced from the authored-tag table; zero references to
`TagConfigIntent.FullName` remain in the driver.

**B1-WP5 — endpoint → `DeviceConfig` move (runs parallel with WP3; owns different files)**

- Contracts: `src/Core/ZB.MOM.WW.OtOpcUa.Commons/Types/DeviceConfigIntent.cs` reworked —
  `DeviceConfig` JSON now carries host/endpoint + per-device settings for **all** drivers.
- The 4 multi-device drivers: remove the embedded `Devices[]` list from
  `ModbusDriverOptions.cs`(*), `S7DriverOptions.cs`(*), `AbCipDriverOptions.cs`,
  `AbLegacyDriverOptions` file, `TwinCATDriverOptions.cs`, `FocasDriverOptions` file —
  (*grounding note: Modbus and S7 options also carry `Devices` lists — treat all six
  options classes the same way: `DriverConfig` keeps protocol/channel-level settings only;
  per-device settings move to `DeviceConfig`). Single-endpoint drivers (OpcUaClient
  `EndpointUrl`, Galaxy gateway address, S7 host if single) move their endpoint into the
  auto-created default device's `DeviceConfig`.
- Runtime spawning: `Runtime/Drivers/DriverInstanceActor.cs` + the artifact device-host
  map in `Runtime/Drivers/DeploymentArtifact.cs` — driver instantiation now merges
  `DriverConfig` + per-device `DeviceConfig` rows (this merged shape is also what Batch
  2's browse modal passes as `configJson` — get the merge helper into Commons so both
  reuse it: `DriverDeviceConfigMerger`).
- Golden corpus: rewrite
  `tests/Server/ZB.MOM.WW.OtOpcUa.Runtime.Tests/Drivers/TagConfigGoldenCorpus.cs` +
  `TagConfigCorpusParityTests.cs` to the v3 shapes (no `deviceHostAddress`, no
  PascalCase `FullName`, per-device configs separate).

Coordination rule: WP5 and WP3 both touch driver projects. Split ownership per file:
WP3 owns `*EquipmentTagParser.cs`/resolver/driver read-path files; WP5 owns
`*DriverOptions.cs`/factory/spawn-path files. Where one file carries both (a driver
factory that parses options AND builds the tag table), WP5 waits for that driver's WP3
agent to merge first — the coordinator sequences per-driver.

### Wave C — pipeline integration (2 agents, then 1 integrator)

**B1-WP4 — composer / artifact / actors / validator / services rewiring**

- `OpcUaServer/AddressSpaceComposer.cs` (+ `AddressSpaceChangeClassifier.cs`) — composes
  from the new schema; emits a hierarchy-only/empty composition (folders exist as data;
  **no variable nodes materialize** — Batch 4). Keep the alarm-intent parse (it flows to
  the artifact) but drop equipment-tag NodeId composition.
- `Runtime/Drivers/DeploymentArtifact.cs` — flatten the new shape: per-driver authored
  raw tags keyed by RawPath (feeding the WP3 resolvers), device rows with merged config
  (WP5), historized set keyed by RawPath (effective historian tagname = override else
  RawPath).
- `ControlPlane/AdminOperations/ConfigComposer.cs` (`SnapshotAndFlattenAsync`) — snapshot
  the new tables into the sealed blob; `RevisionHash` inputs updated.
- `Runtime/Drivers/DriverHostActor.cs` — the map keys change meaning, not shape:
  `_nodeIdByDriverRef` / `_driverRefByNodeId` / `_alarmNodeIdByDriverRef` /
  `_driverRefByAlarmNodeId` now carry RawPath as the ref string. Rename the tuple member
  `FullName` → `RawPath` so no stale semantics survive. NodeId sets stay empty until
  Batch 4 (the maps still exist; mux forwarding still runs).
- `Configuration/Validation/DraftValidator.cs` + `DraftSnapshot(Factory)` — new rules:
  raw-name charset (no `/`, no lead/trail whitespace) at every level; **historized-tag
  effective tagname ≤ 255 chars** (live-verified AVEVA limit) → deploy error prompting a
  `historianTagname` override; retired rules deleted (Galaxy ExplicitFullName, equipment
  NodeId collision in its old form, namespace-binding checks).
- `AdminUI/Uns/UnsTreeService.cs` + `IUnsTreeService.cs`, `Components/Pages/Uns/*`,
  `Components/Shared/Uns/TagModal.razor` etc. — compile-only pass: the UNS tree keeps
  Area/Line/Equipment; the Tags tab and TagModal driver-binding paths are stubbed behind
  an "unavailable until v3 Batch 2/3" banner (list every stub in the PR).
- `ControlPlane/AdminOperations/AdminOperationsActor.cs` — per-tag TagConfig validation
  loop updated (no FullName checks; alarm/historize checks retained).

**B1-WP6 — test-suite + harness sweep**

- Rewrite/replace the corpus tests deleted in WP2 with RawPath equivalents (resolution
  per driver, artifact parity: `DeploymentArtifact*ParityTests.cs`).
- `tests/Server/ZB.MOM.WW.OtOpcUa.Runtime.Tests/Drivers/DriverHostActor*Tests.cs`,
  `DriverInstanceActor*Tests.cs`, `VirtualTags/*Tests.cs` — re-key refs to RawPaths.
- 2-node harness `tests/Server/ZB.MOM.WW.OtOpcUa.Host.IntegrationTests/` — seed shapes
  updated (`EquipmentNamespaceMaterializationTests.cs` will assert the *dark* address
  space this batch: hierarchy nodes only / no variables; mark the full assertion as
  Batch-4-pending with a skip-reason constant, don't delete it).
- `tests/Server/ZB.MOM.WW.OtOpcUa.ControlPlane.Tests/` — ConfigComposer/deploy-path
  shapes.

## Wave schedule + parallelization

| Wave | Packages | Agents | Parallel-safe because |
|---|---|---|---|
| A | WP1 ∥ WP2 | 2 | Disjoint: Configuration project vs Commons/driver-editor files. Coordinator lands `RawPaths.cs` + reshaped-entity contracts commit first |
| B | WP3 exemplar (Modbus) → review → WP3 fan-out (7 drivers) ∥ WP5 | up to 8 | Per-driver project directories are disjoint; WP3/WP5 per-file ownership rule above |
| C | WP4 → WP6 | 2 sequential (WP6 can start its mechanical re-keying while WP4 finishes, in a separate worktree, rebasing before merge) | WP4 is the single integration point — one agent only |

All agents in worktrees; merge order A → B → C; coordinator builds+tests the batch branch
after every merge.

## Batch verification gate

1. `dotnet build ZB.MOM.WW.OtOpcUa.slnx` and `dotnet test ZB.MOM.WW.OtOpcUa.slnx` green
   (macOS-safe suites), plus the DB-backed `Configuration.Tests` against
   `10.100.0.35,14330`.
2. Fresh-DB migration proof: point `OTOPCUA_CONFIG_CONNECTION` at a scratch DB,
   `dotnet ef database update`, then run `SchemaComplianceTests`.
3. docker-dev: rebuild the migrator image + **both** central nodes, re-seed
   (`docker-dev/seed/`), `docker compose up -d`; both nodes reach Running; seeded drivers
   show Connected against the `10.100.0.35` fixtures (`lmxopcua-fix up modbus standard`
   etc.); AdminUI loads (stubbed pages show their banners, nothing crashes).
4. Explicitly assert the dark address space: Client.CLI
   `browse -u opc.tcp://localhost:4840 -r -d 3` shows hierarchy/no tag variables — and
   the PR description says so, so nobody files it as a bug.