# Still-Pending §8 Completion — Design

> **Status:** Approved 2026-06-16. Next step: `superpowers-extended-cc:writing-plans`.

**Goal:** Close the actionable items in `stillpending.md` §8 ("Deferred test-coverage
follow-ups, never filed as findings") — the only Bucket-A work that is neither
vendor-gated nor live-rig-gated and is not already covered by the session-resilience
epic plan.

**Scope decision:** Bucket A only (actionable code/test work). The session-resilience
epic (Tasks 13–28) is already planned in `docs/plans/2026-06-15-session-resilience.md`
and is explicitly **out of scope** here — resume it separately. Vendor-gated
(§1.4/§3.4/§3.5) and live-rig/capture-gated (§1.3/§3.x/§5/§6.1) items cannot be
completed from this dev box and are out of scope.

**Approach:** "C" — the complete option, including new in-process gRPC test
infrastructure for the Java streaming/galaxy CLI commands and a full bounded
ready-wait in the gateway session hot path.

---

## Important correction (verified 2026-06-16)

The three §8 items cite findings marked **Resolved** in the review backlog, but those
resolutions did **not** survive into the current tree:

- The Java bulk-family CLI tests that `Client.Java-026` (resolved 2026-05-20) describes
  were written against the old `com.dohertylan.mxgateway` package. After the rename to
  `com.zb.mom.ww`, the current
  `clients/java/zb-mom-ww-mxgateway-cli/.../MxGatewayCliTests.java` has **zero** coverage
  for `read-bulk`, `write-bulk`, `write2-bulk`, `write-secured-bulk`,
  `write-secured2-bulk`, `bench-read-bulk`, `stream-events`, `close-session`,
  `galaxy-discover`, `galaxy-watch`. (`galaxy-test-connection`/`galaxy-last-deploy`/
  `galaxy-browse`/`stream-alarms` **do** have tests now.)
- `Server-030` (both states in the not-ready diagnostic) **is** done — confirmed at
  `src/ZB.MOM.WW.MxGateway.Server/Sessions/GatewaySession.cs:1676`. The *deferred
  follow-up* — should the gateway briefly wait for worker-Ready before failing fast? —
  is genuinely unbuilt.
- `Tests-023` extracted a canonical `TestSupport/FakeWorkerProcess(int)`, yet three test
  files still define private nested copies.

So §8's gap is real and current.

---

## Workstreams

Four independently landable workstreams.

| WS | Title | Files (language) | Classification | Depends on |
|----|-------|------------------|----------------|------------|
| A | Synchronous Java CLI tests (7 commands) | Java CLI test | small | — |
| B | In-process gRPC harness + streaming/galaxy CLI tests (3 commands) | Java CLI test + small CLI seam | standard | A (shares test file) |
| C | Worker-Ready bounded ready-wait | C# server session hot path | high-risk | — |
| D | `FakeWorkerProcess` consolidation | C# tests | small | — |

A, C, D are mutually independent (disjoint files/languages) and may be dispatched in
parallel. B follows A because both edit `MxGatewayCliTests.java`.

---

## WS-A — Synchronous Java CLI tests

**What:** Round-trip CLI tests for the 7 commands testable through the existing
`FakeSession`/`FakeClient` seam (the same seam `subscribe-bulk`/`write` already use):
`read-bulk`, `write-bulk`, `write2-bulk`, `write-secured-bulk`, `write-secured2-bulk`,
`bench-read-bulk`, `close-session`.

**How:** Upgrade `FakeSession` (currently returns empty lists) to per-call recorders
that capture the parsed entries (timeout, typed values via the shared `parseValue(type,
text)` switch, user-ids, timestamp) and synthesize one `BulkReadResult`/`BulkWriteResult`
per requested handle, so JSON-shape assertions exercise the
`bulkReadResultMap`/`bulkWriteResultMap` serializers. One `@Test` per command:

- `read-bulk`: `--timeout-ms` reaches session; JSON carries `tagAddress`/`itemHandle`/
  `wasCached`/`quality`.
- `write-bulk`: `--type int32 --values 111,222 --user-id 5` parses through `parseValue`;
  entries built with the expected typed `MxValue` + `userId`.
- `write2-bulk`: `--timestamp …Z` reaches the entry as `timestampValue`
  (`hasTimestampValue()` true).
- `write-secured-bulk`: `--current-user-id`/`--verifier-user-id` both propagate.
- `write-secured2-bulk`: timestamp + both user-ids.
- `bench-read-bulk`: 1s steady / 0s warmup; assert cross-language schema keys
  (`language=java`, `command=bench-read-bulk`, `totalCalls`, `successfulCalls`,
  `failedCalls`, `callsPerSecond`, `latencyMs.p50/p95/p99`).
- `close-session`: `CloseSessionReply` round-trips through `FakeClient`.

**Verify:** `gradle :zb-mom-ww-mxgateway-cli:test --tests *MxGatewayCliTests`.

---

## WS-B — In-process gRPC harness + streaming/galaxy CLI tests

**Why infra is required:** `MxEventStream` and `DeployEventStream` have package-private
constructors; `GalaxyRepositoryClient` is `final` with a static `connect()` and
`GalaxyCommand` has **no** injectable factory. None of `stream-events`/`galaxy-watch`/
`galaxy-discover` can be faked through the `FakeSession` seam.

**What:** A JUnit fixture that starts a gRPC **`InProcessServer`** hosting scripted
`MxAccessGateway` + `GalaxyRepository` service implementations and exposes an in-process
`Channel`. The **real** `MxGatewayClient`/`GalaxyRepositoryClient` connect to it, so the
real `MxEventStream`/`DeployEventStream` queue-draining and `GalaxyRepositoryClient`
paging are exercised end-to-end (highest fidelity; no reflection, no package hacks).

- **Production change (CLI module only, not the library):** add a `GalaxyClientFactory`
  seam to `GalaxyCommand` mirroring the existing `MxGatewayCliClientFactory`, so galaxy
  commands can target the in-process channel.
- `stream-events`: server streams a scripted `MxEvent` sequence → assert CLI render,
  including the unsigned-uint64 worker-sequence regression.
- `galaxy-watch`: server streams scripted deploy events → assert CLI feed output.
- `galaxy-discover`: server returns a paged `GalaxyObject` hierarchy → assert CLI JSON.

The 7 synchronous commands stay on the lightweight `FakeSession` seam (YAGNI — no reason
to route them through a server).

**Verify:** `gradle :zb-mom-ww-mxgateway-cli:test --tests *MxGatewayCliTests`.

---

## WS-C — Worker-Ready bounded ready-wait

**Problem:** `GetReadyWorkerClient` (`GatewaySession.cs:1665`) fails fast when the session
is `Ready` but the worker client's `WorkerClientState` has diverged (`Handshaking` after a
heartbeat blip, etc.). The both-states diagnostic exists; a brief wait does not.

**Constraint:** the check runs inside the `_syncRoot` lock — we cannot sleep/poll there.

**Design (pinned decisions):**

- New `GetReadyWorkerClientAsync`: read state under `_syncRoot`; **if** session is `Ready`
  but worker is **transient** (`Handshaking`/`Created`), release the lock, poll at a short
  interval (e.g. 25 ms) until the worker reaches `Ready` or a bounded timeout elapses, then
  re-check under the lock.
- **Terminal worker states (`Faulted`/`Closing`/`Closed`/null) fail fast immediately** —
  never wait; retrying a faulted worker is pointless and would mask the fault.
- New config `MxGateway:Sessions:WorkerReadyWaitTimeout` on `GatewaySessionOptions`,
  **default `0` = disabled** (preserves today's exact fail-fast behavior unless opted in),
  validated `>= 0` by the options validator. Document in `docs/GatewayConfiguration.md`.
- The both-states diagnostic is preserved for the final failure. Callers at
  `GatewaySession.cs:918` and `:1263` become `await`.

**Tests:**
- Handshaking→Ready within the timeout succeeds (worker invoked once).
- Faulted fails fast with both states in the message, zero waiting.
- Timeout elapses → fails with both states.
- Default `0` → unchanged fail-fast (no wait, no behavior change).

**Verify:** `dotnet test src/ZB.MOM.WW.MxGateway.Tests --filter "FullyQualifiedName~SessionManager"`
(plus the options-validator test class).

---

## WS-D — `FakeWorkerProcess` consolidation

**What:** Replace the private nested `FakeWorkerProcess` in
`SessionWorkerClientFactoryFakeWorkerTests`, `WorkerProcessLauncherTests`, and
`WorkerClientTests` with the canonical `TestSupport/FakeWorkerProcess(int)` (which already
has `MarkExited`/`Kill`/TCS-backed `WaitForExitAsync`). Where a nested copy carries extra
behavior the canonical lacks, fold that into the canonical first, then delete the copies.

**Verify:** `dotnet test src/ZB.MOM.WW.MxGateway.Tests --filter "FullyQualifiedName~WorkerClient | FullyQualifiedName~WorkerProcessLauncher | FullyQualifiedName~SessionWorkerClientFactory"`.

---

## Testing & sequencing

Per the targeted-test rule in `CLAUDE.md` (Source Update Workflow): each task runs only
its own filtered tests. Run the full gateway suite at most once, after WS-C + WS-D land.

Out-of-scope items remain recorded in `stillpending.md` (vendor/rig-gated) and the
session-resilience epic (`oldtasks.md`).