docs(audit): apply per-cluster judgment fixes across living docs

Resolve audit findings: correct WorkerEnvelope proto/route/metric/session
facts; rewrite auth (ZB.MOM.WW.Auth migration), dashboard (ZB.MOM.WW.Theme),
and StyleGuide (foreign-project copy-paste); document alarm subsystem, Ldap
options, and gateway alarm broker; fix client CLI flags and package paths.
This commit is contained in:
Joseph Doherty
2026-06-03 16:01:28 -04:00
parent f84e0c3474
commit e541339c07
29 changed files with 1102 additions and 432 deletions
+25 -1
View File
@@ -109,6 +109,30 @@ default:
The MXAccess engine returns values whose semantic type only fully resolves after consulting the engine's own attribute metadata. Clients that round-trip these values through the gateway (replay, parity fixtures, diagnostics) need the original `VT_*` tag, the engine-declared `MxDataType`, and any conversion diagnostic; otherwise edge cases such as decimal-to-double rounding, ulong overflow, or an unknown SAFEARRAY element type become invisible bugs. Storing both the typed projection and the raw fields in the same `MxValue`/`MxArray` lets cross-language clients recover the original observation byte-for-byte where possible and detect lossy cases where it is not.
### Inverse projection for COM writes
The conversions above run on the read path, turning COM values into `MxValue`.
The write path runs the same `VariantConverter` in reverse: `ConvertToComValue`
takes an `MxValue` from a `Write` command and returns a CLR object that the COM
marshaler boxes into the matching VARIANT, so it is the inverse of `Convert`.
- A null `MxValue` argument throws; an `MxValue` whose `IsNull` flag is set
returns `null` (the MXAccess null), keeping the read/write null semantics
symmetric.
- Each `KindCase` maps to its CLR scalar (`bool`, `int`, `long`, `float`,
`double`, `string`). A `TimestampValue` becomes a `DateTime`, which the
marshaler renders as `VT_DATE` — the form MXAccess accepts for the
timestamped-write argument.
- An array kind delegates to `ConvertToComArray`, which projects each
`MxArray.ValuesCase` to a typed CLR array (for example `int[]`, `string[]`, or
a `DateTime[]` for timestamp arrays) so the marshaler produces the
corresponding SAFEARRAY.
- `RawValue` payloads are intentionally rejected on both the scalar and array
paths. Raw bytes are preserved on the read path for diagnostics, but there is
no safe way to reconstruct the original VARIANT from them, so a write that
carries a raw value throws rather than guessing. An `MxValue` with no value
kind set throws for the same reason — there is nothing to write.
## HResultConverter and HResultConversion
`HResultConverter.Convert` wraps any `Exception` thrown across the COM boundary. It prefers `COMException.ErrorCode` over `Exception.HResult` because the runtime sometimes overwrites `Exception.HResult` while marshalling, and the `ErrorCode` field is the value the COM call actually returned.
@@ -223,7 +247,7 @@ public string PreserveCompletionOnlyStatusBytes(byte[] statusBytes)
`MxStatusDetailText` is an internal lookup that maps known `MXSTATUS_PROXY.detail` codes to short human-readable strings (for example `28 = "Index out of range"`, `42 = "Unable to convert string"`, `8017 = "Object must be offscan to modify attributes that have an MxSecurityConfigure security classification"`). `MxStatusProxyConverter.Convert` calls `Lookup` and writes the result to `DiagnosticText`. Unknown codes return `string.Empty`, leaving the numeric `Detail` field as the authoritative identifier.
The mapping covers the engine-error range documented for MXAccess (16-50, 56-61, 541-542, 8017). Adding entries here is the supported way to enrich wire-level diagnostics without changing the proto schema.
The mapping covers selected detail codes in the MXAccess engine-error ranges (16-50, 56-61, 541-542, 8017). The ranges are not contiguous: codes that the runtime does not assign a distinct meaning are omitted (for example 35, 45, and 46 in the 16-50 range and 58-59 in the 56-61 range), so only codes with a known text appear. Adding entries here is the supported way to enrich wire-level diagnostics without changing the proto schema.
## MxStatusConversionException