diff --git a/docs/deploy/2026-11-12-pending-worker-time-fixes-226-228.md b/docs/deploy/2026-11-12-pending-worker-time-fixes-226-228.md new file mode 100644 index 00000000..b44601bc --- /dev/null +++ b/docs/deploy/2026-11-12-pending-worker-time-fixes-226-228.md @@ -0,0 +1,75 @@ +# Pending: Worker time-conversion fixes #226 + #228 (DEV first, then QA) + +**Status: NOT deployed.** This is the deploy note for the next gateway deploy. Ship both fixes in one +deploy: they are both in the x86 Worker, both change timestamps consumers see, and both are on `main`. + +| Fix | Commit | Behaviour change on the box | +|---|---|---| +| #226 wnwrap alarm DATE+TIME are already UTC; stop adding GMTOFFSET-DSTADJUST | `892bdc1a` | Every wnwrap alarm time (`QueryActiveAlarms`, alarm events) moves **4-5 h earlier**, to correct UTC. OtOpcUa/ScadaBridge dedup keyed on raise time sees each existing alarm once with the new time. | +| #228 `Write2`/`WriteSecured2` (+ bulk) time argument sent as box-local time | `9ef6fc84` | The stored source timestamp of a timestamped write equals the instant sent, instead of being shifted by the box's UTC offset (+5 h on a UTC-5 box in winter, +4 h in summer). No consumer calls `Write2` today (ScadaBridge and OtOpcUa have no call site). | + +Build **Server and Worker together from one `main` SHA at or after `9ef6fc84`** (the upgrade script refuses +staged builds from different SHAs; they share `WorkerProtocolVersion`). Procedure, traps and rollback: +`docs/runbooks/DeployUpgradeNssmService.md` and `scripts/deploy/Upgrade-MxGatewayService.ps1`. + +## What else rides along + +- **DEV vd03** runs `2b13564e`. `2b13564e..9ef6fc84` adds only #226, #227 (opt-in `emit_stream_attached`, + additive proto, Contracts/Client 0.4.0) and #228, plus docs/tests. Nothing else changes for current + consumers. +- **QA vq03/vq04** run `4f931e4`. A `main` build also carries the 2026-10-21 review remediation and the + operator-authenticated alarm ack (`488649c`). The QA deploy is therefore gated by **#170**: every QA + OtOpcUa node with a Galaxy driver must first run lmxopcua `dc0a24f2`+ and have an `AlarmAck` fallback + account (or per-key ack identities) configured, or every Galaxy ack is refused. Close that gate first or + in the same window. + +## DEV (wonder-app-vd03) first + +1. Build on windev in a scratch folder from the chosen SHA: Worker + `dotnet build src\ZB.MOM.WW.MxGateway.Worker\ZB.MOM.WW.MxGateway.Worker.csproj -c Release -p:Platform=x86` + and run `Worker.Tests` x86 (expect 0 failures; 783 passed / 12 skipped at `9ef6fc84`); publish the Server + self-contained as in runbook section 4. Do not touch windev's own `MxAccessGw` service. +2. Stage both to vd03 over SMB, run the upgrade script on the box (deploy activity, WinRM in scope): + `Upgrade-MxGatewayService.ps1 -ServerSource \Server -WorkerSource \Worker -ExpectedSha -Label issue226-228`. + Single box: stop, swap, start once (trap 1, `OrphanWorkerTerminator`). +3. Runbook section 7 checks (health 200, pre-upgrade `mxgw_` key authenticates, wrong key rejected, Worker + path proven by a read). +4. **#228 check, from the Mac, no remote exec:** with a scoped key for `MESReceiver_025.*` (Z28062, never + Z28061), run + `MXGATEWAY_LIVE_GATEWAY_ASSERT_WRITE2_TIMESTAMP=1 dotnet test clients/dotnet/ZB.MOM.WW.MxGateway.Client.Tests --filter FullyQualifiedName~LiveGatewayWrite2Tests` + with `MXGATEWAY_LIVE_GATEWAY_ENDPOINT`, `MXGATEWAY_LIVE_GATEWAY_API_KEY_FILE` and + `MXGATEWAY_LIVE_GATEWAY_WRITE_ITEM=MESReceiver_025.MoveInBatchID` (`docs/GatewayTesting.md`, "Live gateway + write"). Both tests must pass: `Write2_SupervisoryAdvise_KeepsSentTimestamp` failed on `2b13564e` with + sent `01:36:51Z` / stored `06:36:51Z`. Revoke and delete the key afterwards. +5. **#226 check:** `QueryActiveAlarms` for `Galaxy!CVDAisle_1.TableAlarms_008.RuntimeAlert` reads + `2026-07-28T20:02:46.830Z` (was `01:02:46.830Z` on 07-29), and a fresh alarm's time equals + `Runtime.dbo.Events.EventTimeUtc` on wonder-sql-vd03 (read over SQL, not WinRM). +6. Write the deploy record in `docs/deploy/` and update the scadaproj index row. + +## QA (wonder-app-vq03 / vq04) after DEV passes + +1. Confirm the #170 prerequisites above on both QA OtOpcUa nodes. +2. Same SHA and staged builds as DEV. The gateways are singletons per box: deploy vq03, run the section 7 + checks, then vq04 (rolling). The vq04 gateway depends on vq03 for Galaxy SQL and alarms. +3. #228 check as DEV step 4 against each QA gateway, with a Z28062 test attribute that exists on QA (pick + and record it; `MESReceiver_025.MoveInBatchID` is the DEV item). #226 check as DEV step 5 against the + QA Historian. +4. Deploy record, index row. + +## Rollback + +Runbook section 8: stop, confirm no Server/Worker process, rename the `Server.bak-*`/`Worker.bak-*` pair back, +start once. Both fixes are Worker-only behaviour; no store or schema changes, so rollback restores the old +(wrong) times and nothing else. + +## Evidence the fix works (windev, 2026-11-12, Eastern Standard Time, UTC-5) + +The live smoke `WorkerLiveMxAccessSmokeTests.GatewaySession_WithLiveWorker_Write2ValueWithTimestampToAdvisedItem` +(in-process gateway, its own worker; the `MxAccessGw` service was untouched) on `TestChildObject.TestInt`: + +| Worker | Sent | Stored | Result | +|---|---|---|---| +| `9ef6fc84` (fix) | `2026-11-13T01:46:31Z` | `2026-11-13T01:46:31Z` | Passed | +| `9ef6fc84` with the conversion removed (negative control) | `2026-11-13T01:47:32Z` | `2026-11-13T06:47:32Z` | Failed by exactly +5 h | + +Both runs got `OnWriteComplete` `Ok` and restored the original value.