mxaccessgw/docs/plans/2026-08-25-cycle-3-p2-followups-design.md

Cycle 3 P2 And Follow-Up Design

Date: 2026-08-25

Source: archreview/2026-08-19/remediation/00-tracking.md

Scope: The 17 findings recorded as deferred P2 plus the three follow-ups recorded by the cycle-3 integration gate. SEC-37 and TST-32 remain external actions and are not part of this repository change.

Current-State Reconciliation

The 2026-08-25 audit refreshed origin/main and checked every finding against the current tree. Sixteen P2 findings remain open. WRK-34 is already complete in commit 3679e59 and needs a tracker correction rather than another code change. All three integration-gate follow-ups remain open:

• a live worker command and gateway path for refreshing an alarm subscription's subtag watch-list;
• the full WRK-32 recency limitation in the public reply-field comment;
• publication of the already-bumped client release train.

Design Principles

1. Preserve the existing worker STA and COM-affinity rules. Worker alarm-consumer construction, subscription changes, and disposal remain on the STA.
2. Preserve the primary alarm-manager subscription during watch-list repair. A refresh must never unsubscribe and recreate the whole alarm feed.
3. Make behavioral changes test-first and keep documentation in the same commit as the behavior it describes.
4. Perform one protobuf regeneration wave for the watch-list command, the WRK-32 reply-field clarification, and the IPC-36 operator-facing comment correction.
5. Publish clients only after every client-affecting change is integrated, all five client suites pass, the release commit is on main, and registry collision checks pass.
6. Keep the canonical archreview tracker current at every batch boundary, including commit IDs and verification counts.

Workstreams

1. Tracker And Low-Risk Currency

Correct WRK-34 to Done, repair the stale replay-watermark documentation (GWC-36), document the public DrainEvents command (IPC-38), reconcile stillpending.md (TST-33), wire the code-review README check into portable CI (TST-34), and replace the nonexistent event scope spelling with events:read (TST-36).

These edits form the first batch because they have a small conflict surface and establish an accurate tracker before code changes begin.

2. Gateway Correctness And Security

• GWC-33: stop faulted or closed worker clients from contributing frozen queue depth while retaining fault records for the configured grace period.
• GWC-35: make snapshot reconciliation emit a Raise when a cached acknowledged alarm is replaced by an active unacknowledged instance.
• SEC-38: consult and feed the cross-peer aggregate for every validly-shaped key ID, even when the per-peer key-partition cap routes the request through the fallback bucket. Aggregate cardinality remains bounded by the aggregate cache's existing eviction policy.
• SEC-39: never let a null effective key ID clear the shared fallback partition.

Each change gets a focused regression test that first reproduces the filed failure mode.

3. Secondary Contracts

• IPC-36: move all six worker-launch environment-variable names into one net48-safe Contracts class, consume those constants on both sides, enumerate the launch contract in the launcher and worker design documentation, and test that the launcher sets every declared variable.
• IPC-37: compare the retained gateway Galaxy descriptor with the descriptor served by the shared ZB.MOM.WW.GalaxyRepository package after normalizing source-only metadata.

This work makes the two non-protobuf peer contracts executable invariants rather than comments.

4. Client Alarm-Feed Parity

• CLI-47: explicitly render false-valued provider and snapshot status fields in .NET text output; document the deliberate protobuf-JSON omission behavior and Rust's explicit JSON shape.
• CLI-48: add provider-status and clearing snapshot-status coverage in .NET, Go, and Java, including Go's missing stream-alarms test scaffold.
• CLI-49: expose the two Go status payload aliases and update the alarm-feed alias documentation.
• CLI-50: change Python stream-alarms from a one-message buffered sample to incremental streaming with an unbounded-by-default limit, while retaining timeout and explicit finite-limit behavior.

The Python change uses the same arrival-order streaming model as the other four CLIs. Documentation examples will request a finite bound when a bounded demonstration is desirable.

5. Live Alarm Watch-List Refresh

The complete periodic hot-swap design is selected over failover-edge-only refresh and unsubscribe/resubscribe.

Contract

Add an explicit worker command for updating an active alarm subscription's watch-list. Add an explicit subscription flag that distinguishes these cases when the initial list is empty:

• alarm-manager-only deployment with no fallback requested;
• auto fallback configured, but discovery currently produced no targets.

The command is gateway-owned even though it travels through the shared MxCommand envelope. It returns a normal MxCommandReply; invalid mode/state or replacement-subscription failure returns a structured failure without destroying the existing subscription.

Worker

In auto mode, retain a failover composite even when fallback is enabled with an initially empty list. The composite retains its subscription expression and supports replacing its standby consumer on the STA:

1. construct the replacement standby;
2. subscribe and warm it before altering the current child;
3. attach transition forwarding;
4. atomically replace the standby reference;
5. dispose the previous standby;
6. if standby is currently active, keep the mode on subtag and expose the replacement snapshot immediately.

If any pre-swap step fails, dispose the replacement and keep the old standby untouched. Forced alarm-manager mode rejects refresh as inapplicable. Forced subtag mode may replace its sole consumer through the same build-first/swap-second rule.

Gateway

Reuse the existing alarm reconciliation cadence; do not add another timer or configuration option. Resolve only when fallback can use subtags. Compare a canonical target fingerprint with the list last acknowledged by the worker, and send an update only after material change or recovery from an empty/failed resolution.

The failover edge still performs an immediate refresh attempt before publishing its coverage verdict. A successful update changes the recorded sent fingerprint, clears stale-coverage status, and triggers reconciliation. A failed update retains the previous fingerprint and publishes/logs the degraded reason.

This design repairs the original startup-outage case before failover whenever Galaxy Repository recovers during normal monitor operation, while preserving the warm primary and current provider mode.

6. Windows Gateway Coverage

TST-35 extends windev live mode to run the net10 gateway suite after the serialized Worker tier and full solution build. The existing host lock remains the load-sensitivity control. Logs record the observed count rather than hard-coding the historical 879 or 1183 count as an invariant.

7. Protobuf Regeneration And Release

The watch-list command lands in the same regeneration wave as:

• WRK-32's explicit sequential stale-callback/recency limitation;
• IPC-36's replacement of the internal environment-variable name with the public configuration key.

Regenerate Contracts and all five client trees according to docs/Contracts.md and docs/ClientPackaging.md, then run the codegen cleanliness checks and every affected suite.

After integration to main, publish .NET/Contracts, Python, Rust, and Go as 0.2.1, and Java as 0.2.2. Query each exact coordinate before publishing, never overwrite, create and push the Go module tag at the exact release commit, then query every registry coordinate again and update the packaging record and tracker with immutable release evidence.

Verification Strategy

• macOS: clean NonWindows.slnx build and full gateway suite.
• Focused gateway tests after each behavioral batch.
• All five client build/test commands from docs/ClientPackaging.md.
• scripts/check-codegen.ps1, client-version guard, and code-review README check.
• windev: x86 Worker build plus Worker.Tests for worker/proto changes; live mode for TST-35 and the final integration gate.
• Release: exact registry-coordinate checks and Go module resolution from the pushed tag.

Completion Criteria

The continuation is complete only when all 16 open P2 findings and all three follow-ups are Done or explicitly blocked with evidence, WRK-34 is corrected in the tracker, every required verification is green, client releases are confirmed at their registries, and archreview/2026-08-19/remediation/00-tracking.md contains the commit and test evidence for every batch.