Code-review 2026-05-20 sweep #2: re-review at a020350, resolve 48 findings

Second re-review pass at commit a020350 caught 48 new findings — including
one High-severity regression I introduced in the prior sweep — and fixed
them all in one parallel wave.

High (1)
- Client.Python-018: prior sweep set `license = "Proprietary"` in
  pyproject.toml. setuptools >= 77 enforces PEP 639 and rejects the
  string (it must be a valid SPDX expression), so `pip wheel .` and
  `pip install -e .` both fail before any source compiles. Tests
  still pass because pytest bypasses the build backend via
  `pythonpath`. Dropped the invalid license string, kept the
  `License :: Other/Proprietary License` classifier, and added
  `tests/test_packaging.py` so a future regression of the same shape
  is caught in CI.

Mediums (6)
- Worker-023: `HeartbeatStuckCeiling` (default 75s = 5x HeartbeatGrace)
  on WorkerPipeSessionOptions bounds the in-flight-command watchdog
  suppression so a truly stuck COM call still triggers StaHung
  instead of permanently defeating the watchdog.
- Client.Rust-018: reverted Rust's `latencyMs` split so the
  cross-language bench comparison is apples-to-apples again;
  `failureLatencyMs` kept as Rust-only enrichment.
- Client.Java-021: applied Client.Java-002's terminal-state
  serialisation pattern to DeployEventStream so close() arriving
  after queue-overflow can't erase the overflow exception.
- IntegrationTests-017: teardown-parity test now uses a two-window
  stability check after UnAdvise instead of strict equality against
  the pre-UnAdvise count (which raced against in-flight events).
- IntegrationTests-019: new RecordingTestOutputHelper wraps every
  log sink the WriteSecured live test owns (worker stdout/stderr,
  gateway logs, direct WriteLine) so the credential is proven
  absent from the full output buffer, not just the diagnostic
  message.
- Tests-020: added MxAccessGatewayServiceConstraintTests coverage
  for the previously-uncovered Write2Bulk and WriteSecured2Bulk
  arms of WriteBulkConstraintPlan.SetPayload.

Lows (41 — highlights)
- Server: Galaxy glob cache eviction is race-free (Server-024);
  GalaxyRepositoryGrpcService takes IGalaxyRepository (Server-025);
  AlarmsOptions validated at startup (Server-026); Authorization.md
  Constraint Enforcement snippet/prose enumerate the bulk write/read
  family (Server-027); bulk-read-commands and bulk-write-commands
  capability tokens added to OpenSession (Server-029);
  NotWiredAlarmRpcDispatcher XML doc and missing scope-resolver and
  state-machine tests cleaned up (023, 028).
- Worker: AlarmCommandHandler now invokes the same STA-affinity
  guard the poll path uses, at every command entry (Worker-024);
  RunAsync null-checks the runtime-session factory result
  (Worker-025).
- Worker.Tests: shared LiveMxAccessOptInVariableName lives on
  GatewayContractInfo (Worker.Tests-025); MxAccessSession.CreateForTesting
  rejects production sinks (Worker.Tests-026); FakeRuntimeSession's
  CancelCommandReturnValue serialised under lock (Worker.Tests-027);
  Probes namespace lifted to MxGateway.Worker.Tests.Probes
  (Worker.Tests-029); cancel-envelope sequence numbers monotonised
  (Worker.Tests-030); docs/GatewayTesting.md gains a "Dev-rig Probes"
  section (Worker.Tests-028).
- Tests: ManualTimeProvider consolidated into one TestSupport/ copy
  (Tests-021); SessionManagerBulkTests adds a mid-flight cancellation
  test backed by a TaskCompletionSource fake (Tests-022); companion
  FakeWorkerProcess.WaitForExitAsync no longer fakes its exit signal
  (Tests-023); constraint plan reply-count divergence pinned
  (Tests-024).
- IntegrationTests: TryGetSession chain carries [MaybeNullWhen(false)]
  end-to-end (IntegrationTests-018); abnormal-exit keyword set
  tightened to pipe-disconnected/end-of-stream and the test now
  asserts streamTask.IsFaulted (020, 021).
- Client.Dotnet: bench commands added to isLongRunning so the
  default 30s wall-clock budget doesn't kill them (015);
  BenchStreamEventsAsync observes the inner stream task on every
  exit path (016).
- Client.Go: parseValue wraps strconv errors with flag context and
  %w (017); bench loops honour ctx.Done() (018); galaxy-watch parses
  RFC3339Nano with fractional seconds (019); runStreamEvents installs
  signal.NotifyContext like runGalaxyWatch (020); five new CLI-level
  table-driven tests cover the bulk/bench subcommands (021).
- Client.Java: toCompletable Javadoc rewritten to match the actual
  cancellation contract Client.Java-015 established (022); stream-events
  text path uses Long.toUnsignedString for worker_sequence (023);
  bench-read-bulk no longer pollutes success-latency histogram with
  failure durations (024); --shutdown-timeout CLI option propagates
  through to ClientOptions (025); seven new MxGatewayCliTests cover
  the bulk and bench commands (026).
- Client.Python: mxgateway_cli ships its own py.typed marker (019);
  wheel-build smoke test added under tests/test_packaging.py (020);
  README documents the Galaxy CLI parity gap explicitly (021).
- Client.Rust: RustClientDesign.md signatures match session.rs and
  document the AsRef<str> read_bulk genericism (019);
  next_correlation_id re-exported at the crate root, with a
  property-style doc contract and an explicit disclaimer that the
  literal textual format is not part of the contract (020).
- Contracts: BulkWriteResult comment names the actual
  IConstraintEnforcer mechanism instead of "tag-allowlist filter"
  (014); BulkReadResult gains explicit per-arm payload-population
  documentation for the success vs failure cases (015).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

clients/java/src/main/generated/main/java/mxaccess_gateway/v1/MxaccessGateway.java

@@ -59287,9 +59287,11 @@ public final class MxaccessGateway extends com.google.protobuf.GeneratedFile {
    * <pre>
    * Per-item result for the four bulk write families. `item_handle` mirrors the
    * request entry's item_handle so callers can correlate inputs to outputs even
-   * when the gateway's tag-allowlist filter dropped some entries before reaching
-   * the worker. Per-item failures populate `error_message` + `hresult` and never
-   * raise — callers iterate and inspect each entry.
+   * when the gateway's per-entry `IConstraintEnforcer.CheckWriteHandleAsync`
+   * filter (see `MxAccessGatewayService.ReplaceWriteBulkEntries` and
+   * `docs/Authorization.md`) dropped some entries before reaching the worker.
+   * Per-item failures populate `error_message` + `hresult` and never raise —
+   * callers iterate and inspect each entry.
    * </pre>
    *
    * Protobuf type {@code mxaccess_gateway.v1.BulkWriteResult}
@@ -59686,9 +59688,11 @@ public final class MxaccessGateway extends com.google.protobuf.GeneratedFile {
      * <pre>
      * Per-item result for the four bulk write families. `item_handle` mirrors the
      * request entry's item_handle so callers can correlate inputs to outputs even
-     * when the gateway's tag-allowlist filter dropped some entries before reaching
-     * the worker. Per-item failures populate `error_message` + `hresult` and never
-     * raise — callers iterate and inspect each entry.
+     * when the gateway's per-entry `IConstraintEnforcer.CheckWriteHandleAsync`
+     * filter (see `MxAccessGatewayService.ReplaceWriteBulkEntries` and
+     * `docs/Authorization.md`) dropped some entries before reaching the worker.
+     * Per-item failures populate `error_message` + `hresult` and never raise —
+     * callers iterate and inspect each entry.
      * </pre>
      *
      * Protobuf type {@code mxaccess_gateway.v1.BulkWriteResult}
@@ -61295,6 +61299,20 @@ public final class MxaccessGateway extends com.google.protobuf.GeneratedFile {
    * an existing live subscription's last OnDataChange (the worker did not touch
    * the subscription); false when the worker took the AddItem + Advise + wait +
    * UnAdvise + RemoveItem snapshot lifecycle itself.
+   *
+   * On `was_successful = true`, `value`, `quality`, `source_timestamp`, and
+   * `statuses` carry the read data (from the cached subscription or the snapshot
+   * lifecycle, depending on `was_cached`) and `error_message` is empty. On
+   * `was_successful = false`, only `server_handle`, `tag_address`, `item_handle`
+   * (when allocated), `was_cached`, and `error_message` are populated; `value`,
+   * `quality`, `source_timestamp`, and `statuses` are left at their proto3
+   * defaults (null / 0 / null / empty) and must not be read as data — they are
+   * wire-indistinguishable from "value is null with quality bad" data and serve
+   * only as absent markers. ReadBulk has no `hresult` field by design (its
+   * outcomes are timeout / cache / lifecycle states, not MXAccess COM return
+   * codes — see `docs/DesignDecisions.md` "Bulk Command Family"). Per-tag
+   * failures populate `error_message` and never raise — callers iterate and
+   * inspect each entry.
    * </pre>
    *
    * Protobuf type {@code mxaccess_gateway.v1.BulkReadResult}
@@ -61837,6 +61855,20 @@ public final class MxaccessGateway extends com.google.protobuf.GeneratedFile {
      * an existing live subscription's last OnDataChange (the worker did not touch
      * the subscription); false when the worker took the AddItem + Advise + wait +
      * UnAdvise + RemoveItem snapshot lifecycle itself.
+     *
+     * On `was_successful = true`, `value`, `quality`, `source_timestamp`, and
+     * `statuses` carry the read data (from the cached subscription or the snapshot
+     * lifecycle, depending on `was_cached`) and `error_message` is empty. On
+     * `was_successful = false`, only `server_handle`, `tag_address`, `item_handle`
+     * (when allocated), `was_cached`, and `error_message` are populated; `value`,
+     * `quality`, `source_timestamp`, and `statuses` are left at their proto3
+     * defaults (null / 0 / null / empty) and must not be read as data — they are
+     * wire-indistinguishable from "value is null with quality bad" data and serve
+     * only as absent markers. ReadBulk has no `hresult` field by design (its
+     * outcomes are timeout / cache / lifecycle states, not MXAccess COM return
+     * codes — see `docs/DesignDecisions.md` "Bulk Command Family"). Per-tag
+     * failures populate `error_message` and never raise — callers iterate and
+     * inspect each entry.
      * </pre>
      *
      * Protobuf type {@code mxaccess_gateway.v1.BulkReadResult}