# OtOpcUa follow-ons design (2026-06-07)

Three independent hardening items surfaced during the Equipment-namespace live-values milestone
(`docs/plans/2026-06-07-equipment-namespace-live-values.md`). All live in OtOpcUa. They are
independent and ship as separate commits/tasks.

---

## 1. Fix the `DriverInstanceActor` subscribe race (Runtime — real bug)

**File:** `src/Server/ZB.MOM.WW.OtOpcUa.Runtime/Drivers/DriverInstanceActor.cs`

**Root cause.** `HandleSubscribeAsync` (dispatched via `ReceiveAsync<Subscribe>`) captures `Sender`/`Self`
on lines 362-363 — *after* the conditional `await UnsubscribeAsync().ConfigureAwait(false)` on line 359.
`ConfigureAwait(false)` opts out of Akka's `ActorTaskScheduler`, so in the re-subscribe path
(`_subscriptionHandle is not null`, which fires on every deploy re-apply and on bootstrap restore) the
post-await `Sender` read (`Sender` = `Context.Sender`) runs on a thread-pool thread with no active actor
context → `System.NotSupportedException: There is no active ActorContext`. It is provoked further when the
actor is stopping mid-await (a Subscribe lands during a deploy/restore reconcile while the driver is being
torn down) — observed live as `GalaxyDriver … shutting down` immediately followed by the error. Recovers on
a clean node restart, which is why a non-raced bootstrap subscribed cleanly.

**Fix (two parts).**
1. **Capture before await.** Move `var replyTo = Sender; var self = Self;` to the very top of
   `HandleSubscribeAsync`, before the `_subscriptionHandle is not null` check + its await. Use
   `replyTo`/`self` everywhere after; never read raw `Sender`/`Self`/`Context` past any await. This removes
   the failing line.
2. **Drop `.ConfigureAwait(false)` inside the `ReceiveAsync` handlers** (`HandleSubscribeAsync`,
   `UnsubscribeAsync`, `HandleApplyDeltaAsync`, `HandleWriteAsync`) so continuations resume on the actor's
   `ActorTaskScheduler` (idiomatic Akka — preserves actor context, handles the stopping actor gracefully).
   Audit each handler for any other post-await `Context`/`Sender`/`Self` access while doing so. (Note:
   `HandleApplyDeltaAsync` and `HandleWriteAsync` already capture `replyTo = Sender` before their awaits;
   only `HandleSubscribeAsync` has the after-await capture — confirm during implementation.)

**Out of scope.** The `ReceiveAsync` mailbox-blocking semantics (one message at a time during a long
SubscribeAsync) are unchanged — not part of this bug.

**Testing.** A TestKit test that subscribes, then subscribes again (drives the line-359
unsubscribe-then-resubscribe path) and asserts `SubscriptionEstablished` is replied with no exception
(today this throws). Use a fake `ISubscribable` driver. The stopping-mid-await race is hard to make
deterministic; the capture-before-await fix removes the failing access regardless.

---

## 2. Validate Tag↔VirtualTag name collisions at deploy (Configuration)

**Files:** `src/Core/ZB.MOM.WW.OtOpcUa.Configuration/Validation/DraftValidator.cs` + the `DraftSnapshot`
type + wherever `DraftSnapshot` is built (locate during planning).

**Problem.** `Phase7Applier` materialises both Equipment `Tag` variables and `VirtualTag` variables at the
folder-scoped NodeId `{EquipmentId}[/{FolderPath}]/{Name}`. `UX_Tag_EquipmentPath` and
`UX_VirtualTag_EquipmentPath` each enforce `(EquipmentId, Name)` uniqueness *within their own table*, but
there is **no cross-table constraint** — a `Tag` and a `VirtualTag` with the same `(EquipmentId, Name)` (and
same/empty FolderPath) would materialise to the same NodeId, and the sink (keyed on NodeId) would keep only
one. Not hit today (the company overlay is VirtualTag-only), but latent for mixed equipment.

**Change.**
- Extend `DraftSnapshot` to carry equipment-bound signal identities: the `(EquipmentId, FolderPath, Name)`
  of every `Tag` with a non-null `EquipmentId` and every `VirtualTag` (FolderPath = "" for VirtualTags).
  Populate them where `DraftSnapshot` is constructed.
- New rule `DraftValidator.ValidateNoEquipmentSignalNameCollision`: group those signals by the
  **folder-scoped key** `(EquipmentId, normalize(FolderPath), Name)` — exactly the materialiser's NodeId key
  — and emit a `ValidationError("EquipmentSignalNameCollision", …)` for any group with count > 1 (carry the
  EquipmentId + Name in the error). Wire it into `DraftValidator.Validate`.

**Why the folder-scoped key.** A Tag under a sub-folder (`{Eq}/sub/Name`) does not collide with a root
VirtualTag (`{Eq}/Name`) of the same Name. Keying on the full NodeId path avoids false positives. Galaxy /
SystemPlatform Tags (`EquipmentId` null) live in a different node space and are excluded.

**Testing.** Validator unit tests: a Tag + a VirtualTag with the same `(EquipmentId, Name)` (empty
FolderPath) → `EquipmentSignalNameCollision`; same Name but different FolderPath → OK; distinct names → OK;
a SystemPlatform Tag sharing a name with an equipment VirtualTag → OK (excluded).

---

## 3. docker-dev resource hardening (compose/config only — no app code)

**File:** `docker-dev/docker-compose.yml` (+ `docker-dev/README.md`).

**Problem.** The full single-mesh stack (central-1/2 + 4 site nodes) OOM-killed central-1 on a loaded host
(Docker Desktop VM memory cap; `OOMKilled=true`, host load ~12). Two contributors: (a) verbose EF Core
`Development` logging — every Deployment-poll `SELECT` + `Executed DbCommand` logged, flooding the dispatcher
and starving the cluster heartbeat thread (observed `heartbeat … delayed 4169ms … thread starvation`);
(b) no per-container memory limits, so total footprint is unbounded against the VM cap.

**Change.**
- **Quiet logging:** add `Logging__LogLevel__Microsoft.EntityFrameworkCore=Warning` (and
  `Logging__LogLevel__Microsoft.AspNetCore=Warning`) to the host services' `environment`. Keep application
  logs (`Default`/`ZB.MOM.WW`) at Info. This removes the SQL flood and the starvation cascade.
- **Per-service memory bounds:** add `mem_limit` (and `mem_reservation`) to each host service (central-1/2,
  site-a/b), sized by measuring a steady-state node (`docker stats`) and adding headroom. Document in
  `docker-dev/README.md` the approximate total Docker Desktop VM memory the full stack needs, so a
  constrained host knows to raise the VM or run fewer nodes.

**Coordinate with active docker-dev work.** `master` has recent in-flight docker-dev commits
(single-mesh topology, fresh-volume bootstrap). Rebase/merge carefully so these changes don't clobber that
work; keep the edits additive (env keys + `mem_limit` lines) where possible.

**Testing.** Operational only: bring the full stack up with the changes, confirm no OOM and all nodes serve
(`:9200` healthy, `:4840` listening on central-1, galaxy mirror Good). Not unit-testable.

---

## Sequencing & risk

| # | Area | Risk | Ships as |
|---|---|---|---|
| 1 | Runtime actor (`DriverInstanceActor`) | Medium (actor semantics) — small, well-understood | own commit + TestKit test |
| 2 | Configuration (`DraftSnapshot` + `DraftValidator`) | Low–medium (new snapshot field + rule) | own commit + validator tests |
| 3 | docker-dev compose/README | Low (config only) | own commit; coordinate with active docker-dev work |

All three are independent and can be reviewed/merged separately. No cross-dependencies.