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/go/cmd/mxgw-go/main.go

@@ -589,14 +589,19 @@ func runBenchReadBulk(ctx context.Context, args []string, stdout, stderr io.Writ
 	}()
 
 	// Warm-up: drive identical calls so any first-call JIT / connection-pool
-	// setup is amortised before the measurement window opens.
+	// setup is amortised before the measurement window opens. Honor ctx so
+	// Ctrl+C or a parent-cancel (e.g. the cross-language bench driver killing
+	// the child early) exits promptly rather than spinning failing calls until
+	// the wall-clock deadline.
 	warmupDeadline := time.Now().Add(time.Duration(*warmupSeconds) * time.Second)
 	timeout := time.Duration(*timeoutMs) * time.Millisecond
-	for time.Now().Before(warmupDeadline) {
+	for time.Now().Before(warmupDeadline) && ctx.Err() == nil {
 		_, _ = session.ReadBulk(ctx, serverHandle, tags, timeout)
 	}
 
-	// Steady state: per-call latency captured via time.Now() deltas.
+	// Steady state: per-call latency captured via time.Now() deltas. Same ctx
+	// guard as warm-up; on cancel we stop the loop and report the truncated
+	// window faithfully.
 	latenciesMs := make([]float64, 0, 65536)
 	var totalReadResults int64
 	var cachedReadResults int64
@@ -604,7 +609,7 @@ func runBenchReadBulk(ctx context.Context, args []string, stdout, stderr io.Writ
 	steadyStart := time.Now()
 	steadyDeadline := steadyStart.Add(time.Duration(*durationSeconds) * time.Second)
 
-	for time.Now().Before(steadyDeadline) {
+	for time.Now().Before(steadyDeadline) && ctx.Err() == nil {
 		callStart := time.Now()
 		results, err := session.ReadBulk(ctx, serverHandle, tags, timeout)
 		elapsed := time.Since(callStart)
@@ -772,8 +777,15 @@ func runStreamEvents(ctx context.Context, args []string, stdout, stderr io.Write
 	}
 	defer client.Close()
 
+	// Mirror runGalaxyWatch so Ctrl+C on a long-running stream-events command
+	// cancels the gRPC stream cleanly (the gateway sees codes.Canceled rather
+	// than a torn TCP connection) and the deferred subscription.Close() /
+	// client.Close() actually run.
+	signalCtx, stopSignals := signal.NotifyContext(ctx, os.Interrupt, syscall.SIGTERM)
+	defer stopSignals()
+
 	session := mxgateway.NewSessionForID(client, *sessionID)
-	streamCtx, cancelStream := context.WithCancel(ctx)
+	streamCtx, cancelStream := context.WithCancel(signalCtx)
 	defer cancelStream()
 	subscription, err := session.SubscribeEventsAfter(streamCtx, *after)
 	if err != nil {
@@ -956,31 +968,31 @@ func parseValue(valueType, valueText string) (*mxgateway.MxValue, error) {
 	case "bool":
 		value, err := strconv.ParseBool(valueText)
 		if err != nil {
-			return nil, err
+			return nil, fmt.Errorf("invalid -value for -type %s: %q: %w", valueType, valueText, err)
 		}
 		return mxgateway.BoolValue(value), nil
 	case "int32":
 		value, err := strconv.ParseInt(valueText, 10, 32)
 		if err != nil {
-			return nil, err
+			return nil, fmt.Errorf("invalid -value for -type %s: %q: %w", valueType, valueText, err)
 		}
 		return mxgateway.Int32Value(int32(value)), nil
 	case "int64":
 		value, err := strconv.ParseInt(valueText, 10, 64)
 		if err != nil {
-			return nil, err
+			return nil, fmt.Errorf("invalid -value for -type %s: %q: %w", valueType, valueText, err)
 		}
 		return mxgateway.Int64Value(value), nil
 	case "float":
 		value, err := strconv.ParseFloat(valueText, 32)
 		if err != nil {
-			return nil, err
+			return nil, fmt.Errorf("invalid -value for -type %s: %q: %w", valueType, valueText, err)
 		}
 		return mxgateway.FloatValue(float32(value)), nil
 	case "double":
 		value, err := strconv.ParseFloat(valueText, 64)
 		if err != nil {
-			return nil, err
+			return nil, fmt.Errorf("invalid -value for -type %s: %q: %w", valueType, valueText, err)
 		}
 		return mxgateway.DoubleValue(value), nil
 	case "string":
@@ -1201,7 +1213,7 @@ func runGalaxyWatch(ctx context.Context, args []string, stdout, stderr io.Writer
 	flags.SetOutput(stderr)
 	common := bindCommonFlags(flags)
 	jsonOutput := flags.Bool("json", false, "write JSON output")
-	lastSeen := flags.String("last-seen-deploy-time", "", "RFC3339 timestamp; when set, suppresses the bootstrap event")
+	lastSeen := flags.String("last-seen-deploy-time", "", "RFC 3339 timestamp (with optional fractional seconds); when set, suppresses the bootstrap event")
 	limit := flags.Int("limit", 0, "maximum events to read; 0 means unbounded (Ctrl+C to stop)")
 
 	if err := flags.Parse(args); err != nil {
@@ -1210,7 +1222,11 @@ func runGalaxyWatch(ctx context.Context, args []string, stdout, stderr io.Writer
 
 	var lastSeenPtr *time.Time
 	if *lastSeen != "" {
-		parsed, err := time.Parse(time.RFC3339, *lastSeen)
+		// Use RFC3339Nano so values copy-pasted from galaxy-watch -json output
+		// (which formatDeployEvent emits with fractional seconds) round-trip;
+		// RFC3339Nano also accepts whole-second values, so the layout switch is
+		// strictly broader than the previous time.RFC3339 parse.
+		parsed, err := time.Parse(time.RFC3339Nano, *lastSeen)
 		if err != nil {
 			return fmt.Errorf("invalid -last-seen-deploy-time: %w", err)
 		}

clients/go/cmd/mxgw-go/main_test.go

@@ -3,6 +3,7 @@ package main
 import (
 	"bytes"
 	"encoding/json"
+	"errors"
 	"strings"
 	"testing"
 )
@@ -85,3 +86,166 @@ func TestParseInt32ListReturnsErrorOnMalformedToken(t *testing.T) {
 		t.Fatalf("parseInt32List() error = %q, want it to name the bad token", err.Error())
 	}
 }
+
+// TestParseValueWrapsStrconvErrorWithFlagContext pins Client.Go-017: each
+// typed branch of parseValue wraps the bare strconv error with `%w` and names
+// the offending flag and value, so the CLI surface is consistent with
+// parseInt32List ("invalid item handle %q: %w") and parseRfc3339Timestamp
+// ("invalid RFC 3339 timestamp %q: %w").
+func TestParseValueWrapsStrconvErrorWithFlagContext(t *testing.T) {
+	cases := []struct {
+		valueType string
+		valueText string
+	}{
+		{"bool", "notabool"},
+		{"int32", "foo"},
+		{"int64", "foo"},
+		{"float", "notafloat"},
+		{"double", "notadouble"},
+	}
+	for _, tc := range cases {
+		t.Run(tc.valueType, func(t *testing.T) {
+			_, err := parseValue(tc.valueType, tc.valueText)
+			if err == nil {
+				t.Fatalf("parseValue(%q, %q) error = nil, want a parse error", tc.valueType, tc.valueText)
+			}
+			msg := err.Error()
+			if !strings.Contains(msg, "-value") {
+				t.Fatalf("parseValue() error = %q, want it to name the -value flag", msg)
+			}
+			if !strings.Contains(msg, tc.valueType) {
+				t.Fatalf("parseValue() error = %q, want it to name the type %q", msg, tc.valueType)
+			}
+			if !strings.Contains(msg, tc.valueText) {
+				t.Fatalf("parseValue() error = %q, want it to name the bad token %q", msg, tc.valueText)
+			}
+			// errors.Unwrap must reach the underlying strconv error so callers
+			// can still errors.Is/As against strconv.ErrSyntax if they care.
+			if errors.Unwrap(err) == nil {
+				t.Fatalf("parseValue() returned unwrapped error %q, want a %%w wrap", msg)
+			}
+		})
+	}
+}
+
+// TestRunWriteBulkVariantGatesSecuredFlags pins the Client.Go-015 fix at the
+// CLI surface: secured-only flags (-current-user-id, -verifier-user-id) must
+// not be registered on the non-secured variants, and -user-id must not be
+// registered on the secured variants. The flag package rejects an unknown
+// flag with "flag provided but not defined", which a future refactor that
+// re-broadens flag registration would silently undo without this test.
+func TestRunWriteBulkVariantGatesSecuredFlags(t *testing.T) {
+	cases := []struct {
+		name    string
+		command string
+		flag    string
+	}{
+		{"write-bulk rejects -current-user-id", "write-bulk", "-current-user-id"},
+		{"write-bulk rejects -verifier-user-id", "write-bulk", "-verifier-user-id"},
+		{"write2-bulk rejects -current-user-id", "write2-bulk", "-current-user-id"},
+		{"write-secured-bulk rejects -user-id", "write-secured-bulk", "-user-id"},
+		{"write-secured2-bulk rejects -user-id", "write-secured2-bulk", "-user-id"},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			var stdout, stderr bytes.Buffer
+			err := runWithIO(t.Context(), []string{
+				tc.command,
+				"-plaintext",
+				"-session-id", "sess",
+				"-server-handle", "1",
+				"-item-handles", "1",
+				"-values", "1",
+				tc.flag, "1",
+			}, &stdout, &stderr)
+			if err == nil {
+				t.Fatalf("runWithIO(%s %s) error = nil, want flag-not-defined", tc.command, tc.flag)
+			}
+			combined := err.Error() + stderr.String()
+			if !strings.Contains(combined, "flag provided but not defined") {
+				t.Fatalf("runWithIO(%s %s) error/stderr = %q, want 'flag provided but not defined'", tc.command, tc.flag, combined)
+			}
+		})
+	}
+}
+
+// TestRunReadBulkRejectsMissingArgs pins the "session-id and items are
+// required" validation in runReadBulk before any network dial happens.
+func TestRunReadBulkRejectsMissingArgs(t *testing.T) {
+	cases := []struct {
+		name string
+		args []string
+	}{
+		{"no flags", []string{"read-bulk"}},
+		{"missing items", []string{"read-bulk", "-plaintext", "-session-id", "sess"}},
+		{"missing session-id", []string{"read-bulk", "-plaintext", "-items", "Tag.Attr"}},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			var stdout, stderr bytes.Buffer
+			err := runWithIO(t.Context(), tc.args, &stdout, &stderr)
+			if err == nil {
+				t.Fatalf("runWithIO(%v) error = nil, want validation error", tc.args)
+			}
+			if !strings.Contains(err.Error(), "session-id and items are required") {
+				t.Fatalf("runWithIO(%v) error = %q, want 'session-id and items are required'", tc.args, err.Error())
+			}
+		})
+	}
+}
+
+// TestRunBenchReadBulkRejectsNonPositiveBulkSize pins the bulk-size>=1 check
+// at runBenchReadBulk's flag-parsing stage so a future refactor cannot drop
+// the positivity guard without breaking this test.
+func TestRunBenchReadBulkRejectsNonPositiveBulkSize(t *testing.T) {
+	var stdout, stderr bytes.Buffer
+	err := runWithIO(t.Context(), []string{
+		"bench-read-bulk",
+		"-plaintext",
+		"-bulk-size", "0",
+	}, &stdout, &stderr)
+	if err == nil {
+		t.Fatalf("runWithIO(bench-read-bulk -bulk-size 0) error = nil, want positivity error")
+	}
+	if !strings.Contains(err.Error(), "bulk-size must be positive") {
+		t.Fatalf("runWithIO error = %q, want 'bulk-size must be positive'", err.Error())
+	}
+}
+
+// TestRunBenchReadBulkRejectsNonPositiveDuration pins the duration-seconds>=1
+// check at runBenchReadBulk's flag-parsing stage.
+func TestRunBenchReadBulkRejectsNonPositiveDuration(t *testing.T) {
+	var stdout, stderr bytes.Buffer
+	err := runWithIO(t.Context(), []string{
+		"bench-read-bulk",
+		"-plaintext",
+		"-duration-seconds", "0",
+	}, &stdout, &stderr)
+	if err == nil {
+		t.Fatalf("runWithIO(bench-read-bulk -duration-seconds 0) error = nil, want positivity error")
+	}
+	if !strings.Contains(err.Error(), "duration-seconds must be positive") {
+		t.Fatalf("runWithIO error = %q, want 'duration-seconds must be positive'", err.Error())
+	}
+}
+
+// TestRunWriteBulkVariantRejectsMismatchedHandlesAndValues pins the explicit
+// "item-handles count ... does not match values count ..." check at the CLI
+// surface so the validation error surfaces before any dial happens.
+func TestRunWriteBulkVariantRejectsMismatchedHandlesAndValues(t *testing.T) {
+	var stdout, stderr bytes.Buffer
+	err := runWithIO(t.Context(), []string{
+		"write-bulk",
+		"-plaintext",
+		"-session-id", "sess",
+		"-server-handle", "1",
+		"-item-handles", "1,2,3",
+		"-values", "10,20",
+	}, &stdout, &stderr)
+	if err == nil {
+		t.Fatalf("runWithIO(write-bulk mismatched counts) error = nil, want mismatch error")
+	}
+	if !strings.Contains(err.Error(), "item-handles count") || !strings.Contains(err.Error(), "values count") {
+		t.Fatalf("runWithIO error = %q, want 'item-handles count ... values count ...'", err.Error())
+	}
+}