test(live): capture OperationComplete trigger, subtag Clear and status rows on windev (#210, #211)
ci / nightly-windev (push) Has been skipped
ci / windows-x86 (push) Successful in 2m23s
ci / java (push) Failing after 7m49s
ci / portable (push) Failing after 16m36s

Live MXAccess captures against the windev DEV Galaxy, recorded in
docs/LiveCaptures-2026-11-13.md:

- OperationComplete follows a Suspend/Activate whose synchronous MxStatus is
  Pending (advised, resolved item); one Ok row from RespondingLmx. Pinned by
  the new OperationCompleteLiveProbeTests live fact, with an
  unresolved-reference negative control. (#211 §3.1)
- No public COM event carries completion-only status bytes. All 71
  completions were typed MXSTATUS_PROXY[], so they stay raw permanently.
  (#211 §3.3)
- Subtag-mode Clear is drivable: the TestAlarm UDAs are MxSecurityOperate,
  so AuthenticateUser + WriteSecured toggles them. The new self-driven
  LiveSubtag_SelfDrivenRaiseThenClear_SynthesizesClear fact asserts the
  UnackAlm -> UnackRtn Clear (mutation-checked). (#210 §3.7)
- The B8 buffered "NoData bootstrap" is a ConfigurationError resolution
  failure (detail 6 / 1002). The DEV Galaxy has no buffered attribute, so a
  multi-sample capture needs IDE work. provider_switches was not driven. (#210)
- Status-row catalogue for lmxopcua#872: no Warning row seen, and Pending
  only on the synchronous Suspend/Activate return.

Claude-Session: https://claude.ai/code/session_01GT67ACmpMR7b9LGRPLijMi
This commit is contained in:
Joseph Doherty
2026-11-12 23:34:46 -05:00
parent 4890a3d16e
commit 9e4be25807
7 changed files with 584 additions and 24 deletions
+21 -3
View File
@@ -576,9 +576,15 @@ Decision: model and forward `OperationComplete` only when native MXAccess fires
it. Do not synthesize `OperationComplete` from writes, command replies, ASB
completion queues, or other status frames.
Rationale: the event signature is known, but the MXAccess analysis has not yet
captured the runtime condition that triggers the public event. Synthesizing it
would risk breaking parity.
Rationale: synthesizing it would risk breaking parity.
Trigger (captured live 2026-11-13, `docs/LiveCaptures-2026-11-13.md` §1, pinned by
`OperationCompleteLiveProbeTests`): MXAccess raises `OperationComplete` after a
`Suspend` or `Activate` whose synchronous `MxStatus` is Pending (raw category 1,
detail 0). That happens only for an advised item whose reference resolved. The event
carries the same server/item handles and one Ok row detected by RespondingLmx. A
`Suspend`/`Activate` that returns Ok synchronously (already in that state, or an
unresolved reference) raises nothing, and writes never raise it.
## Buffered Data Change
@@ -589,6 +595,12 @@ The event signature and native path are known. A live buffered sample batch has
not yet been observed. Until then, preserve raw value, quality, timestamp, data
type, and status metadata whenever conversion is incomplete.
The empty `NoData` event that the rig delivers after `Advise` is a resolution
failure, not a bootstrap: its status row is ConfigurationError, detail 6 for the
`(item, context)` form and detail 1002 `InvalidPropertyId` for a full reference to an
attribute without a buffer (`docs/LiveCaptures-2026-11-13.md` §5). A multi-sample
capture needs a deployed field attribute or I/O extension with *Buffer* enabled.
## Completion-Only Status Mapping
Decision: preserve completion-only operation-status bytes as raw diagnostic
@@ -598,6 +610,12 @@ proves an exact `MXSTATUS_PROXY[]` mapping.
Do not guess status category/source/detail values for frames that MXAccess does
not expose through its public COM events.
Settled 2026-11-13 (`docs/LiveCaptures-2026-11-13.md` §2): every captured
`OnWriteComplete` and `OperationComplete` carried a typed `MXSTATUS_PROXY[]`, and no
public COM event delivers completion-only bytes. The mapping is not needed, and any
such bytes stay raw permanently. `PreserveCompletionOnlyStatusBytes` has no production
caller.
## API Key Administration
Decision: v1 API key management is a local administrative CLI/tool, not a
+157
View File
@@ -0,0 +1,157 @@
# Live MXAccess captures, 2026-11-13 (mxaccessgw#210, #211; lmxopcua#872)
Captured on windev (`DESKTOP-6JL3KKO`, TEST Galaxy `DEV`, Galaxy Repository DB `ZB`)
between 04:10 and 04:35 UTC on 2026-11-13 (the box clock runs about 9 minutes behind
UTC, so worker timestamps in raw logs read about 04:01 to 04:26).
Two capture paths were used:
- **Through the running gateway.** A throwaway .NET client (built on
`ZB.MOM.WW.MxGateway.Client`) talked to the `MxAccessGw` service on
`http://10.100.0.48:5120` (build `447070a5`) with a temporary API key, revoked
afterwards. It opened sessions, added/advised items, ran commands and recorded every
`StreamEvents` event and every command reply as JSON.
- **Worker.Tests live facts on windev** (direct COM, no gateway): the two facts added
with this document, `OperationCompleteLiveProbeTests` and
`AlarmSubtagLiveSmokeTests.LiveSubtag_SelfDrivenRaiseThenClear_SynthesizesClear`.
The service was never restarted or reconfigured. Writes went to `TestMachine_037`,
`_038` and `_039`; every value a probe changed was written back afterwards.
## 1. `OperationComplete` trigger (§3.1, #211): captured
`OperationComplete` follows a `Suspend` or `Activate` whose synchronous status is
**Pending**. That happens only for an item that is advised (plain or supervisory)
and whose reference resolved.
| Call | Synchronous `MxStatus` | `OperationComplete` |
|---|---|---|
| `Suspend`, advised resolved item | Pending (raw 1), success -1, detail 0, RequestingLmx | yes, 110-220 ms later: one row Ok, detail 0, **RespondingLmx (raw 1)**, same server/item handles |
| `Activate` of that suspended item | Pending (raw 1), as above | yes, as above |
| `Suspend` again on an already-suspended item | Ok | no |
| `Activate` on an already-active item | Ok | no |
| `Suspend`/`Activate`, advised but unresolved reference (`InvalidReference`) | Ok | no |
| `Suspend`/`Activate`, added but not advised | `E_INVALIDARG` (0x80070057) | no |
| `Suspend`/`Activate`, supervisory-advised resolved item | Pending | yes |
| Any `Write`/`WriteSecured`/`Write2`, success or failure | n/a | never (only `OnWriteComplete`) |
The item stops delivering `OnDataChange` between the Suspend's completion and the
Activate; the Activate's completion arrives together with a fresh `OnDataChange`.
The gateway already forwards the native event untouched (no synthesis), and the
mapping is unchanged. `OperationCompleteLiveProbeTests` pins it, including the
unresolved-reference negative control.
## 2. Completion-only status bytes (§3.3, #211): resolved, nothing to map
Of the 71 completion events captured (63 `OnWriteComplete`, 8 `OperationComplete`),
every one carried a typed `MXSTATUS_PROXY[]` that the converter unpacked. None set
`raw_status`. The public COM events have no completion-only byte payload.
`MxStatusProxyConverter.PreserveCompletionOnlyStatusBytes` has no production caller.
Any completion-only bytes exist only in the private ASB/NMX frames described by the
MXAccess analysis, which the worker never sees. So no `MXSTATUS_PROXY[]` mapping is
needed, and if such bytes ever reach the worker they stay raw.
## 3. Status rows observed (input for lmxopcua#872)
Every status-row shape these probes produced. **No `Warning` category (raw 2) was
observed anywhere, and `Pending` (raw 1) appeared only as the synchronous return of
`Suspend`/`Activate`.** It never appeared on an `OnDataChange`, `OnWriteComplete`,
`OperationComplete` or write-reply row. Every `Pending` had detail 0 and success -1.
| Category (raw) | Detail | Detected by (raw) | Produced by |
|---|---|---|---|
| Ok (0) | 0 | RequestingLmx (0) | every good `OnDataChange` |
| Ok (0) | 0 | RespondingAutomationObject (5) | every successful write completion |
| Ok (0) | 0 | RespondingLmx (1) | `OperationComplete` |
| **Pending (1)** | **0** | RequestingLmx (0) | `Suspend`/`Activate` synchronous return (success = -1) |
| ConfigurationError (4) | 6 `InvalidReference` | RequestingLmx (0) | advise/write of a nonexistent object or attribute; `AddBufferedItem(item, context)` form |
| ConfigurationError (4) | 8 `InvalidObjectId` | RespondingLmx (1) | advise of an attribute on an undeployed object (`BCD_T1`, `OtOpcUaParityTest_001`) |
| ConfigurationError (4) | 1002 `InvalidPropertyId` | RespondingAutomationObject (5) | `AddBufferedItem` on a UDA without a buffer |
| ConfigurationError (4) | 1003 `IndexOutOfRange` | RespondingAutomationObject (5) | advise/write `TestIntArray[99]` (dim 50) |
| ConfigurationError (4) | 8001 (AO-specific) | RespondingAutomationObject (5) | write rejected for type conversion: string to double/duration/datetime/bool, int to datetime, 1e300 to float, string[] to bool[] |
| OperationalError (5) | 1004 `DataOutOfRange` | RespondingAutomationObject (5) | alarm `Priority` 5000 or -3, `AlarmModeCmd` 99, scalar written to an array |
| OperationalError (5) | 1007 `NotWriteable` | RespondingAutomationObject (5) | write to `.Acked`, `ScanState`, `Tagname` |
| SecurityError (6) | 1008 `WriteAccessDenied` | RespondingAutomationObject (5) | plain `Write` to an Operate/Secured attribute through a plain advise; `WriteSecured` of a verified-write attribute with no verifier |
| SecurityError (6) | 8018 (AO-specific) | RespondingAutomationObject (5) | `WriteSecured` of a verified-write attribute (`ProtectedValue1`) with verifier = the writing user |
Writes accepted silently (Ok): NaN, +Inf, a numeric string into a double, int64
overflow / 3.7 / true into an int, float precision loss, a 3-element array into a
50-element int array, and 60 strings into a 50-element string array. The last two
**resize the array**. A plain `Write` through a *supervisory* advise succeeds where
the same write through a plain advise is refused with 1008. Off-scan objects
(`ScanStateCmd=false`) keep accepting writes, and their UDAs stay quality 192.
Unconnected DI items (`OI_MBTCP.PLC.40001`) report quality 32 and then 4, with an
Ok status row.
Conditions tried that produced no Warning: out-of-range, type mismatch, NaN/Inf,
array resize, off-scan object, undeployed object, unconnected I/O, read-only,
secured/verified writes, alarm-config writes, Suspend/Activate edge cases.
## 4. Subtag-mode Clear (§3.7, #210): captured
The rig's `TestAlarm00x` UDAs are `MxSecurityOperate`. A plain `Write` is refused
with 1008, and that refusal is why the 2026-06 runs concluded the alarms were
object-driven. `AuthenticateUser("Administrator", "")` followed by
`WriteSecured` drives them both ways. With the subtag pipeline
(`LmxSubtagAlarmSource` + `SubtagAlarmConsumer`, the production classes) watching
`TestMachine_037.TestAlarm001`:
```
Driving condition = true (RAISE) ...
raw ValueChanged: TestMachine_037.TestAlarm001.InAlarm = True
Transition emitted: Kind=Raise PreviousState=Unspecified State=UnackAlm ... Degraded=True Guid=9b60979f-826d-2842-e00b-2bf1234a7809
Driving condition = false (CLEAR) ...
raw ValueChanged: TestMachine_037.TestAlarm001.InAlarm = False
Transition emitted: Kind=Clear PreviousState=UnackAlm State=UnackRtn ... Degraded=True Guid=9b60979f-826d-2842-e00b-2bf1234a7809
CONFIRMED: subtag Clear synthesized (UnackAlm -> UnackRtn, Guid=9b60979f-826d-2842-e00b-2bf1234a7809).
```
Mutation check: with the clear write removed, the fact fails on `Assert.NotNull`
after its 30 s wait. The finally-block restore write then produces the Clear.
The same raise/clear through the running gateway's alarm feed (alarmmgr mode)
emitted `RAISE` and then `CLEAR` for `Galaxy!TestArea3.TestMachine_037.TestAlarm001`
(type `DSC`, severity 500, `sourceProvider` ALARMMGR).
## 5. Multi-sample `OnBufferedDataChange` (§3.2, #210): not capturable on this Galaxy
`AddBufferedItem` + `SetBufferedUpdateInterval` + `Advise` all return OK, but the
first and only `OnBufferedDataChange` carries a **ConfigurationError** status row:
- the `(item, context)` form (`"TestDouble"`, `"TestMachine_039"`) gives detail 6
`InvalidReference` (RequestingLmx);
- the full-reference form (`"TestMachine_039.TestFloat"`, context `""`) gives detail
1002 `InvalidPropertyId` from the automation object.
The empty `NoData` payload recorded as a "bootstrap" in B8 is therefore a
resolution failure, not a parity bootstrap. Buffering is a property of a field
attribute or I/O extension with *Buffer* enabled (the `_HasBuffer` property of the
`AnalogUtilities`/`BooleanUtilities` primitives). No deployed object in this Galaxy
has one. Rapid writes did not change this (36 secured writes at 150 ms to `TestDouble`
and `TestFloat`, 3 s interval).
**What a capture needs (IDE work, not done):** an object with an analog or discrete
field attribute (or I/O extension) that has *Buffer* enabled, bound to a source that
changes faster than the buffered update interval (for example an OI server item with
a reachable device or simulator), deployed. Then `AddBufferedItem("<Object>.<Attr>", "")`
should deliver arrays of length > 1.
## 6. `provider_switches{from,to,reason}` (§1.3, #210): not driven
A real alarmmgr to subtag failover needs the monitor worker's
`WnWrapAlarmConsumer.PollOnce` to throw `Threshold` times in a row. The only ways
to make that happen on this box are to kill or stop `alarmmgr.exe` (the rig's
Galaxy-wide alarm manager, which every engine's alarm provider registers with) or to
change the gateway's `Alarms:Fallback:Mode` and restart it. The first can disrupt the
rig's alarm registration for everyone using it, and its recovery is unproven. The
second was ruled out because it restarts the service. Neither was done. The probe
needs a maintenance window. Then either:
1. with the service running and `/metrics` scraped, stop `alarmmgr.exe` and wait for
`mxgateway_alarms_provider_mode` to go to subtag and a `provider_switches` sample
with `reason` set. Restart alarmmgr (or the platform) and watch the failback
switch; or
2. restart the gateway with `MxGateway__Alarms__Fallback__Mode=ForceSubtag`. This
proves only the forced-start path (`AlarmProviderReasons.ForcedSubtag`), not a
failover `reason`.