Architecture remediation: P2 tier (completeness & polish) #122

2026-07-09T17:07:06-04:00

dohertj2 commented

2026-07-09 17:07:06 -04:00

Architecture remediation — P2 tier (completeness & polish). Third and final tier of the 2026-07-08 architecture review, stacked on the merged P0 (#120) and P1 (#121). Base main @ 69ea793.

Result: 35 of 38 P2 findings Done

Every change lands its fix and the affected docs in the same commit, with the archreview/remediation/00-tracking.md Status column kept in lockstep. Verified per toolchain: .NET / Go / Rust / Python / Java client suites green; gateway fake-worker + reconnect e2e tests green on macOS (TMPDIR=/tmp); worker hot-path windev-verified.

Session-resilience / client-parity epic (this closes Phase 3)

CLI-15 — all five clients surface the gateway's ReplayGap reconnect sentinel as a typed, non-terminal signal (.NET MxEventStreamItem, Go EventResult.ReplayGap, Rust EventItem::ReplayGap, Python ReplayGap dataclass, Java MxEventStreamItem). Never synthesized, never swallowed.
CLI-04 — all five clients gained typed helpers for every parity-critical single-item command (AdviseSupervisory, WriteSecured/WriteSecured2, AuthenticateUser, ArchestrAUserToId, AddBufferedItem, SetBufferedUpdateInterval, Suspend, Activate). Same MXAccess-level reply validation as the bulk helpers; MXAccess parity preserved (WriteSecured-before-authenticate surfaces the native failure). Credentials route through each client's secret-redaction seam — tests assert they never reach logs/exceptions/ToString/Debug. New CLI subcommands take credentials via flag/env, never echoed.
CLI-30 — unregister typed helper for Rust + .NET.
TST-01 — server-side reconnect/replay end-to-end test (GatewayEndToEndReconnectReplayTests: no-gap tail replay + stale-cursor ReplayGap sentinel) plus the client consumers above.
TST-04 — epic governance: Phase 3 finished, Phase 4 scoped (Viewer default settled: admin-sees-all, Viewer strict), Phase 5 (orphan-worker reattach) deferred, not planned — the CLAUDE.md "gateway restart does not reattach orphan workers" invariant stands.

Gateway + worker hot-path

GWC-06/07/08/14/15, IPC-05/13/14 — trimmed event/command hot-path allocations (Stopwatch.GetTimestamp, dropped defensive event clones), pooled + coalesced worker pipe frame I/O, replay ring LinkedList → circular array, per-scrape queue-depth gauge.
WRK-06/11/12, IPC-15 — cached MXSTATUS_PROXY field reflection, removed enqueue clone (with value-cache snapshot), coalesced the worker frame flush across a drained batch. windev-verified (x86 Worker + Worker.Tests).

Security / dashboard

SEC-03 — restore the __Host- cookie prefix only when the cookie is Secure (else the plain name).
SEC-25 / SEC-30 — redact tag values from the dashboard SignalR mirror when ShowTagValues is off (default); value-log doc trimmed to "not yet implemented".

Docs currency + versioning

Doc-drift sweep (IPC-06/07/17/21, SEC-09/22, CLI-12/16, TST-13/23): proto-as-truth, Session-RPC future-work framing, package/naming, Java 17, RPC tables.
CLI-18/21/26/29, TST-11 — align client version constants to package manifests; single-source the .NET assembly version + git-SHA stamp via Directory.Build.props.
WRK-15 — worker STA thread-name / heartbeat doc fixes.

Deferred (tracked, not dropped)

TST-15 (dashboard EventsHub per-session ACL) — a Phase-4 feature needing a new session-tag mechanism + dashboard group→tag config; SEC-25 already prevents value leakage through the hub, so deferring carries no value-leak risk. The TODO(per-session-acl) stays.
TST-24 (per-client wire tests) — gated on TST-03 (CI), which is authored but not yet running on a Gitea runner.
TST-14 — deleting untracked, gitignored *-docs-*.md working files (owner action; zero repo impact).

Full Finding / Impact / Design / Verification for every ID lives in archreview/remediation/*.md.

https://claude.ai/code/session_01DMXXvNuPekkkrTEyPNxEkW

Architecture remediation — **P2 tier (completeness & polish)**. Third and final tier of the 2026-07-08 architecture review, stacked on the merged P0 (#120) and P1 (#121). Base `main` @ `69ea793`. ## Result: 35 of 38 P2 findings Done Every change lands its fix **and** the affected docs in the same commit, with the `archreview/remediation/00-tracking.md` Status column kept in lockstep. Verified per toolchain: .NET / Go / Rust / Python / Java client suites green; gateway fake-worker + reconnect e2e tests green on macOS (`TMPDIR=/tmp`); worker hot-path windev-verified. ### Session-resilience / client-parity epic (this closes Phase 3) - **CLI-15** — all five clients surface the gateway's `ReplayGap` reconnect sentinel as a typed, non-terminal signal (.NET `MxEventStreamItem`, Go `EventResult.ReplayGap`, Rust `EventItem::ReplayGap`, Python `ReplayGap` dataclass, Java `MxEventStreamItem`). Never synthesized, never swallowed. - **CLI-04** — all five clients gained typed helpers for every parity-critical single-item command (`AdviseSupervisory`, `WriteSecured`/`WriteSecured2`, `AuthenticateUser`, `ArchestrAUserToId`, `AddBufferedItem`, `SetBufferedUpdateInterval`, `Suspend`, `Activate`). Same MXAccess-level reply validation as the bulk helpers; MXAccess parity preserved (WriteSecured-before-authenticate surfaces the native failure). **Credentials route through each client's secret-redaction seam** — tests assert they never reach logs/exceptions/`ToString`/`Debug`. New CLI subcommands take credentials via flag/env, never echoed. - **CLI-30** — `unregister` typed helper for Rust + .NET. - **TST-01** — server-side reconnect/replay end-to-end test (`GatewayEndToEndReconnectReplayTests`: no-gap tail replay + stale-cursor `ReplayGap` sentinel) plus the client consumers above. - **TST-04** — epic governance: Phase 3 finished, Phase 4 scoped (Viewer default settled: admin-sees-all, Viewer strict), **Phase 5 (orphan-worker reattach) deferred, not planned** — the CLAUDE.md "gateway restart does not reattach orphan workers" invariant stands. ### Gateway + worker hot-path - **GWC-06/07/08/14/15, IPC-05/13/14** — trimmed event/command hot-path allocations (`Stopwatch.GetTimestamp`, dropped defensive event clones), pooled + coalesced worker pipe frame I/O, replay ring `LinkedList` → circular array, per-scrape queue-depth gauge. - **WRK-06/11/12, IPC-15** — cached `MXSTATUS_PROXY` field reflection, removed enqueue clone (with value-cache snapshot), coalesced the worker frame flush across a drained batch. **windev-verified** (x86 Worker + Worker.Tests). ### Security / dashboard - **SEC-03** — restore the `__Host-` cookie prefix only when the cookie is Secure (else the plain name). - **SEC-25 / SEC-30** — redact tag *values* from the dashboard SignalR mirror when `ShowTagValues` is off (default); value-log doc trimmed to "not yet implemented". ### Docs currency + versioning - **Doc-drift sweep** (IPC-06/07/17/21, SEC-09/22, CLI-12/16, TST-13/23): proto-as-truth, Session-RPC future-work framing, package/naming, Java 17, RPC tables. - **CLI-18/21/26/29, TST-11** — align client version constants to package manifests; single-source the .NET assembly version + git-SHA stamp via `Directory.Build.props`. - **WRK-15** — worker STA thread-name / heartbeat doc fixes. ## Deferred (tracked, not dropped) - **TST-15** (dashboard EventsHub per-session ACL) — a Phase-4 feature needing a new session-tag mechanism + dashboard group→tag config; **SEC-25 already prevents value leakage through the hub**, so deferring carries no value-leak risk. The `TODO(per-session-acl)` stays. - **TST-24** (per-client wire tests) — gated on **TST-03 (CI)**, which is authored but not yet running on a Gitea runner. - **TST-14** — deleting untracked, gitignored `*-docs-*.md` working files (owner action; zero repo impact). Full Finding / Impact / Design / Verification for every ID lives in `archreview/remediation/*.md`. https://claude.ai/code/session_01DMXXvNuPekkkrTEyPNxEkW

dohertj2 added 25 commits 2026-07-09 17:07:08 -04:00

fix(clients): align client version constants to package manifests (CLI-18/21/26/29) 4fe1917aa6

- .NET: add explicit <Version>0.1.2</Version> to client csproj (CLI-18)
- Go: ClientVersion 0.1.0-dev -> 0.1.2 (CLI-21)
- Python: __version__ 0.1.0 -> 0.1.2 to match pyproject.toml (CLI-26)
- Rust: CLIENT_VERSION now sourced from env!(CARGO_PKG_VERSION) so it
  cannot drift from Cargo.toml (CLI-29)

Verified: dotnet build clean; go build/test ok; cargo check/test/clippy
clean; pytest 127 passed. P2 client version-drift cluster.

Claude-Session: https://claude.ai/code/session_01DMXXvNuPekkkrTEyPNxEkW

docs(archreview): P2 doc-drift sweep (IPC-06/07/17/21, SEC-09/22, CLI-12/16, TST-13) 06e1046317

Reconcile load-bearing docs with shipped behavior:
- IPC-06: gateway.md Worker Envelope sketch -> points to mxaccess_worker.proto
  as source of truth (string correlation_id, real oneof arms incl.
  worker_shutdown_ack/worker_ready).
- IPC-07: docs/Grpc.md six RPCs -> seven; document QueryActiveAlarms handler
  + validation row.
- IPC-21: gateway.md Session RPC moved from live API into a 'Future work: not
  implemented' subsection.
- TST-13: drop stale design-era sketches from gateway.md; correct the
  single-subscriber-default (config-gated fan-out) note.
- SEC-09: dashboard GroupToRole sample GwAdmin:Admin -> Administrator so it
  passes GatewayOptionsValidator; clarify Administrator is the canonical role.
- SEC-22: rewrite docs/Authentication.md to the pipeline that actually ships
  (ZB.MOM.WW.Auth.ApiKeys package + gateway-owned CachingApiKeyVerifier,
  CoalescingMarkApiKeyStore, CanonicalForwardingApiKeyAuditStore, etc.);
  remove 18 stale type names (grep-verified absent).
- IPC-17: correct wrong Python generated dir (mxgateway -> zb_mom_ww_mxgateway)
  in CLAUDE.md + 3 docs.
- CLI-12: Java docs Java 21 -> Java 17 (JDK17 retarget for Ignition 8.3).
- CLI-16: docs/ClientPackaging.md reconciled with real .slnx, Python package
  name, and gradle project names; fix stale generateProto task name.

Docs-only; type/path/version claims verified against source.

Claude-Session: https://claude.ai/code/session_01DMXXvNuPekkkrTEyPNxEkW

docs(archreview): mark P2 Wave A findings Done (13: doc-drift + version alignment) 5a3951bcfd

Claude-Session: https://claude.ai/code/session_01DMXXvNuPekkkrTEyPNxEkW

fix(dashboard): conditionally restore __Host- cookie prefix (SEC-03) 7d42c85345

Restore the __Host- browser guarantees for the default secure deployment
without breaking plaintext/dev:
- DashboardServiceCollectionExtensions PostConfigure now resolves the cookie
  name as: explicit MxGateway:Dashboard:CookieName override wins; else
  __Host-MxGatewayDashboard when SecurePolicy==Always (RequireHttpsCookie
  true); else the plain MxGatewayDashboard default. Guard: never apply the
  __Host- prefix without Secure (browsers silently drop it).
- DashboardAuthenticationDefaults: add SecureCookieName const; keep the plain
  CookieName as the non-secure fallback.
- Docs corrected to the actual conditional contract (five stale claims):
  gateway.md, GatewayProcessDesign.md, ImplementationPlanGateway.md,
  GatewayDashboardDesign.md, CLAUDE.md; GatewayConfiguration.md phrasing
  tightened.
- Test: DashboardCookieOptionsTests asserts the name flips with
  RequireHttpsCookie and that an explicit override wins.

Server build clean (0 warnings); Dashboard tests 149/149.

Claude-Session: https://claude.ai/code/session_01DMXXvNuPekkkrTEyPNxEkW

docs(archreview): mark SEC-03 Done (P2 dashboard __Host- cookie prefix) 34aede6767

Claude-Session: https://claude.ai/code/session_01DMXXvNuPekkkrTEyPNxEkW

perf(gateway): pool+coalesce worker pipe frame I/O (GWC-08, IPC-13, IPC-14) baae59ce3b

Gateway server-side named-pipe frame path, wire format byte-identical:
- Writer (GWC-08/IPC-13): serialize once into a single ArrayPool-rented buffer
  holding the 4-byte LE length prefix + payload, then one WriteAsync. Removes
  the second serialization pass (ToByteArray re-ran CalculateSize), the
  separate prefix array + second stream write, and per-frame heap allocation.
- Reader (IPC-14): rent the payload buffer from ArrayPool instead of new byte[]
  per frame; read/parse bounded to the real length, return in finally. Matches
  the worker side which already pools.
- Correctness: length tracked separately from (larger) pool capacity; every
  rented buffer returned exactly once in finally incl. the malformed-protobuf
  path; ParseFrom copies into the message so the envelope never aliases the
  returned buffer.

Cross-checked LE-prefix framing agrees across gateway+worker writer/reader.
Server build clean (0 warnings); WorkerFrameProtocol tests 10/10 incl. a new
large-payload-near-cap round-trip (forces pool buffer > frame). The 2 failing
WorkerClient/FakeWorkerHarness tests are the known macOS UDS 104-char path
limit, not a regression.

Claude-Session: https://claude.ai/code/session_01DMXXvNuPekkkrTEyPNxEkW

perf(gateway): trim event/command hot-path allocations (GWC-06/07/15, IPC-05) 5e2e40a927

Behavior-preserving allocation cuts on the per-event/per-command path:
- GWC-06: StreamEvents send-timing uses Stopwatch.GetTimestamp() +
  GetElapsedTime() instead of a per-event Stopwatch allocation (same measured
  span).
- GWC-07/IPC-05 (event): MapEvent transfers ownership of the inner MxEvent
  instead of .Clone()-ing it. Safe: WorkerEvent is parsed fresh per pipe frame
  with the distributor pump as its single consumer (GWC-01), MapEvent runs once
  before fan-out, and every downstream consumer (subscribers, replay ring)
  only READS the event (WorkerSequence is stamped upstream; verified no
  post-mapping mutation). Comment documents the invariant + restore-clone
  caveat if a second consumer is added.
- IPC-05 (command): CreateCommandEnvelope no longer re-clones; MapCommand
  already isolated the graph from the caller-owned gRPC message.
- GWC-15: grpc_stream_queue.depth converts from a per-event push counter to an
  ObservableGauge summing registered channel sources at scrape time only
  (name/semantics unchanged); removes all per-event .Count/lock work.

Kept every load-bearing isolation clone (MapCommand, Invoke, bulk filters,
MapCommandReply). Server build clean (0 warnings); EventStream/Metrics/
Distributor/Mapper tests 62/62 (incl. formerly-flaky queue-depth tests, now
green under the lazy gauge, + 2 new MapEvent ownership tests). Docs: Metrics.md,
Grpc.md.

Claude-Session: https://claude.ai/code/session_01DMXXvNuPekkkrTEyPNxEkW

perf(gateway): replay ring LinkedList -> circular array (GWC-14) cf1b3d40a5

Replace the replay buffer's LinkedList<ReplayEntry> (a node allocation per
retained event on the fan-out hot path) with a preallocated ReplayEntry[] ring
sized to ReplayBufferCapacity, tracked by _replayHead (oldest) + _replayCount.
Appending a retained event now allocates nothing.

Behavior preserved exactly: ascending-WorkerSequence append order; capacity
eviction (overwrite head + advance when full); time trim via
_timeProvider.GetUtcNow() cutoff at the same three call sites; oldest-read for
ReplayGap math; both replay-from-sequence query paths + highest-seen tracking;
same _replayLock. Capacity-0 stays retain-nothing (guarded early return, no
modulo-by-zero).

Server build clean (0 warnings); Distributor/Replay tests 33/33 incl. two new
cases (multi-wrap ring keeps newest in order; capacity-1 overwrite + gap).

Claude-Session: https://claude.ai/code/session_01DMXXvNuPekkkrTEyPNxEkW

docs(archreview): mark gateway hot-path P2 findings Done (GWC-06/07/08/14/15, IPC-05/13/14) 96702321b1

Claude-Session: https://claude.ai/code/session_01DMXXvNuPekkkrTEyPNxEkW

fix(dashboard): redact mirror tag values when ShowTagValues off; trim value-log doc (SEC-25, SEC-30) e15c3cb052

SEC-25 (near-term hardening; full per-session EventsHub ACL stays deferred to
roadmap item 12): DashboardEventBroadcaster now redacts tag values from a deep
CLONE of the event before mirroring to SignalR when Dashboard:ShowTagValues is
false (the default). Clears MxEvent.value (covers OnDataChange/OnWriteComplete/
OperationComplete/OnBufferedDataChange — their bodies are empty discriminators,
values ride in the top-level field incl. buffered arrays) and the alarm body's
current_value/limit_value. Source event never mutated (shared with the gRPC
path + replay ring) - verified by a source-not-mutated test. Makes the formerly
dead ShowTagValues flag live for the mirror. EventsHub TODO(per-session-acl)
kept and tied to roadmap item 12. Tests: DashboardEventBroadcasterTests (3).

SEC-30: trim docs/Diagnostics.md to mark opt-in command-value logging as NOT
YET IMPLEMENTED (no LogCommandValues knob, RedactCommandValue has no call
sites, no values logged); wiring deferred pending secured-bulk redaction
coverage (SEC-13). No option/call sites added.

Server build clean (0 warnings); Dashboard tests 152/152.

Claude-Session: https://claude.ai/code/session_01DMXXvNuPekkkrTEyPNxEkW

docs(archreview): mark SEC-25/SEC-30 Done (P2 dashboard value redaction + value-log doc) 579282f015

Claude-Session: https://claude.ai/code/session_01DMXXvNuPekkkrTEyPNxEkW

fix(versioning,docs): stamp .NET assembly version + worker doc drift (TST-11, WRK-15) ec6f82b124

TST-11: single-source the .NET-side version in src/Directory.Build.props so
Server/Worker/Contracts/tests stamp 0.1.2 (was the SDK default 1.0.0) and
InformationalVersion carries the git short SHA (0.1.2+<sha>) for support
correlation; the git query is guarded (ContinueOnError) so a build outside a
git checkout still succeeds. Verified: Server assembly stamps 0.1.2+579282f,
build clean. Kept at 0.1.2 (matches Contracts + aligned Python/Rust/Go
clients); Java leads at 0.2.0 post JDK-17 retarget. Convergence to a single
0.2.0 cadence left as a release decision, not forced here.

WRK-15 (docs-only, no x86 worker build needed): correct the STA thread name in
docs/WorkerSta.md + docs/MxAccessWorkerInstanceDesign.md to the actual
MxGateway.Worker.STA (was the FQ ZB.MOM.WW.MxGateway.Worker.STA), and fix the
stale heartbeat-counter note - CaptureHeartbeat now populates event queue depth
(eventQueue.Count) and sequence (LastEventSequence) from the live queue.

Claude-Session: https://claude.ai/code/session_01DMXXvNuPekkkrTEyPNxEkW

docs(archreview): mark TST-11/WRK-15/TST-23 Done (P2 quick items) 73ce824f6c

Claude-Session: https://claude.ai/code/session_01DMXXvNuPekkkrTEyPNxEkW

perf(worker): event hot-path allocation + flush cuts (WRK-06/11/12, IPC-15) f61c816acf

WRK-06: MxStatusProxyConverter caches the four resolved FieldInfo per status
type in a static ConcurrentDictionary (the GetField metadata scan ran 4x per
status per event on the STA path). GetValue+Convert.ToInt32 still run per event
(late-bound RCW). Exceptions byte-identical: missing-field message unchanged
(ResolveField, not cached on throw via GetOrAdd); null-value message unchanged.

WRK-11: MxAccessEventQueue.Enqueue takes ownership of the passed MxEvent -
stamps WorkerSequence/WorkerTimestamp on it in place and enqueues it, no
Clone(). Audited all 3 callers (base/alarm event sinks, provider-mode handler):
each builds a fresh event per Enqueue, none reuse it. MxAccessValueCache.Set now
deep-copies its retained Value/SourceTimestamp/Statuses so the cache snapshot
never aliases the queue-owned (later serialized) event. Net: alarm/other events
clone nothing (was full clone); data-change clones payload-only.

WRK-12: WorkerFrameWriter coalesces the flush across a drained batch - each
frame is written but not flushed individually; one FlushAsync after the batch,
then all written frames complete. Preserves the written+flushed completion
contract; a burst of N events costs 1 flush, not N. On write failure the whole
in-flight batch + queue fail so no caller hangs.

IPC-15 (doc): the multi-event WorkerEnvelope body remains unimplemented (wire
still carries one event per worker_event frame); gateway.md Performance section
now distinguishes the shipped flush-coalescing from that deferred proto change.

net48-safe (no init/records; readonly struct cache entry). Worker builds x86
only - verification on windev. Tests added: converter cache-reuse, queue
ownership-transfer, value-cache snapshot independence, writer batch-flush-once.

Claude-Session: https://claude.ai/code/session_01DMXXvNuPekkkrTEyPNxEkW

docs(archreview): mark WRK-06/11/12 + IPC-15 Done (P2 worker hot-path, windev-verified) c823a7b60b

Claude-Session: https://claude.ai/code/session_01DMXXvNuPekkkrTEyPNxEkW

feat(clients): CLI-15 surface ReplayGap reconnect sentinel as typed signal (4/5 clients) 0c6e5b3ace

The gateway emits a ReplayGap sentinel MxEvent at the head of a StreamEvents
stream resumed via after_worker_sequence when the requested cursor predates the
oldest retained event. Clients previously ignored it, silently mis-treating a
lossy resume as continuous. Each client now surfaces the sentinel as a distinct,
typed, non-terminal signal (never synthesized, never swallowed) so a consumer can
detect the gap and re-snapshot; resume contract is
after_worker_sequence = oldest_available_sequence - 1.

- .NET: MxEventStreamItem (IsReplayGap/ReplayGap/Event) via new StreamEventItemsAsync
  + AsStreamItemsAsync extension. Build clean, 87 passed.
- Go: EventResult.ReplayGap field + IsReplayGap(); ReplayGap type alias. build/vet/test clean.
- Rust: EventItem enum (Event/ReplayGap); EventStream now yields Result<EventItem, Error>;
  CLI renders REPLAY_GAP line / replayGap JSON. fmt/check/test/clippy clean.
- Python: ReplayGap dataclass; stream_events yields pb.MxEvent | ReplayGap. 131 passed.
- Shared docs: ClientLibrariesDesign non-goals reframed (reconnect-replay protocol is
  consumable; auto-reconnect stays a non-goal); CrossLanguageSmokeMatrix resume-gap note.

Java client is deferred to the windev batch (no local JRE); CLI-15 stays open until it lands.

Claude-Session: https://claude.ai/code/session_01DMXXvNuPekkkrTEyPNxEkW

test(gateway): TST-01 end-to-end reconnect/replay integration test fed0685633

Proves the default-on reconnect protocol end to end through the real gRPC
StreamEvents path via the fake worker harness (no live COM). Two facts:

- ReconnectInsideRetainedWindow_ReplaysTailNoGap: capacity 16 retains all
  events; reconnect from a mid-batch after_worker_sequence cursor replays
  exactly the events with WorkerSequence > cursor (retained tail + events
  emitted while detached), strictly ascending, distinct, no ReplayGap.
- ReconnectWithStaleCursor_EmitsReplayGapSentinelFirst: capacity 3 with 6
  events forces eviction; reconnect with AfterWorkerSequence=1 yields the
  ReplayGap sentinel first (Family=Unspecified, no body, RequestedAfterSequence=1,
  OldestAvailableSequence=oldest retained), then the retained tail ascending.

Single-subscriber mode: the first stream is fully detached (cancel + await the
stream task runs EventStreamService's finally, dropping the subscriber count to
0) before reconnect; the distributor + replay ring are created once per session
and survive detach, so events emitted while detached are retained.

macOS note: fake-worker E2E tests need TMPDIR=/tmp (default macOS TMPDIR pushes
the CoreFxPipe Unix-socket path past the 104-byte sun_path limit). Windows CI
is unaffected. Server reconnect/replay behavior matched the contract exactly.

Claude-Session: https://claude.ai/code/session_01DMXXvNuPekkkrTEyPNxEkW

docs(archreview): E1 reconnect-replay — CLI-15 + TST-01 In progress ef498c80c2

CLI-15 (4/5 clients, commit 0c6e5b3) and TST-01 server e2e test (commit fed0685)
landed; both gated on the Java client (windev batch) before flipping to Done.

Claude-Session: https://claude.ai/code/session_01DMXXvNuPekkkrTEyPNxEkW

docs(archreview): TST-04 governance — Phase 3 done, Phase 4 scoped, Phase 5 deferred ed3c6c61c5

Resolve the session-resilience epic's shipped-vs-planned entanglement:

- Phase 3 (reconnect) finished: Task 13 = TST-02 (owner-scoped attach, P0),
  Task 15 = TST-01 (reconnect integration test), Task 14 = CLI-15 for 4/5
  clients (Java pending, windev batch).
- Phase 4 (per-session dashboard ACL) scoped as TST-15; the open Viewer-default
  decision is settled: admin-sees-all, Viewer strict per owned/granted session
  (matches TST-02's gRPC owner binding).
- Phase 5 (orphan-worker reattach) marked DEFERRED, not planned. The
  EnableOrphanReattach flag does not exist and must not be referenced as if it
  does. The CLAUDE.md "gateway restart does not reattach orphan workers"
  invariant stands.

Updates oldtasks.md, the tasks.json mirror (statuses + governance note), and the
CLAUDE.md reconnect paragraph (clients now consume ReplayGap; reattach deferred).

Claude-Session: https://claude.ai/code/session_01DMXXvNuPekkkrTEyPNxEkW

docs(archreview): TST-04 -> Done (epic governance decision landed) 4090a478c8

Claude-Session: https://claude.ai/code/session_01DMXXvNuPekkkrTEyPNxEkW

feat(clients): CLI-04 typed single-item command parity (+CLI-30 unregister) — 4/5 clients bde042b4d4

Every parity-critical single-item MXAccess command now has a typed session
helper instead of only a raw-Invoke escape hatch. Added per client:
- Phase 1: AdviseSupervisory, WriteSecured, WriteSecured2, AuthenticateUser,
  ArchestrAUserToId
- Phase 2: AddBufferedItem, SetBufferedUpdateInterval, Suspend, Activate
- CLI-30: Unregister (Rust + .NET; Go/Python already had it)

Each wraps the existing raw-command machinery (no new wire surface) and runs the
same MXAccess-level reply validation (hresult < 0 + MxStatusProxy). MXAccess
parity preserved: WriteSecured before AuthenticateUser+AdviseSupervisory surfaces
the native failure unchanged (not pre-validated/reordered). Credentials
(AuthenticateUser password, WriteSecured payloads) route through each client's
secret-redaction seam and never reach logs/exceptions/ToString/Debug/Display;
each suite asserts a distinctive credential is absent from surfaced errors. New
CLI subcommands source credentials via flag/env, never echoed.

- .NET: 21 helpers (validated + Raw), CLI subcommands, multi-secret CLI redactor.
  Build clean (0 warn), 102 passed.
- Go: 9 helpers + *Raw variants, redactSecrets seam, promoted CLI advise-supervisory
  to typed. gofmt/vet/build/test clean.
- Rust: 10 helpers incl. unregister; verified ensure_mxaccess_success runs on
  secured paths; error.rs credential scrub. fmt/check/test/clippy clean.
- Python: 9 async helpers, redact_secret seam + _invoke_redacted, CLI commands.
  145 passed.
- Shared doc: ClientLibrariesDesign "Typed Command Parity" section.

Java client typed parity is batched to windev (no local JRE); CLI-04 + CLI-30
stay open until it lands.

Claude-Session: https://claude.ai/code/session_01DMXXvNuPekkkrTEyPNxEkW

docs(archreview): E2 CLI-04 In progress (4/5) + CLI-30 Done; Java now local 908951be9d

Java client toolchain (homebrew openjdk@17) works on the Mac, so the remaining
Java halves of CLI-15/CLI-04 are done locally this session, not batched to windev.

Claude-Session: https://claude.ai/code/session_01DMXXvNuPekkkrTEyPNxEkW

feat(java-client): CLI-15 ReplayGap surface + CLI-04 typed-command parity (5/5 complete) 1cc0fa4007

Completes both findings across all five clients — done locally on the Mac now
that homebrew openjdk@17 is available (JAVA_HOME=/opt/homebrew/opt/openjdk@17).

CLI-15: new MxEventStreamItem record + MxEventStream.nextItem() surfaces the
gateway's ReplayGap sentinel as a typed, non-terminal signal (isReplayGap()/
replayGap()/event()); existing Iterator<MxEvent> path unchanged, sentinel never
swallowed/synthesized. Javadoc covers gap semantics + resume contract.

CLI-04: typed single-item helpers on MxGatewaySession — Phase 1
adviseSupervisory/writeSecured/writeSecured2/authenticateUser/archestrAUserToId,
Phase 2 addBufferedItem/setBufferedUpdateInterval/suspend/activate (unregister
already present). Each routes through invokeCommand -> ensureProtocolSuccess +
ensureMxAccessSuccess (same validation as bulk). MXAccess parity preserved.
Credentials flow only into the request proto; exceptions carry only the reply and
gRPC status text is scrubbed via MxGatewaySecrets.redactCredentials — tests
assert the password/secured value is absent from getMessage()/toString()/CLI
output. New CLI subcommands write-secured/authenticate-user (credential via
--password/--password-env, prints only the user id).

gradle test: 106 tests, 0 failures (58 client + 48 cli); no generated churn.
Shared docs: ClientLibrariesDesign + CLAUDE.md updated to "all five clients".

Claude-Session: https://claude.ai/code/session_01DMXXvNuPekkkrTEyPNxEkW

docs(archreview): CLI-15/CLI-04/CLI-30/TST-01 -> Done (Java completes 5/5) f1d9ad5ca2

Session-resilience epic Phase 3 fully closed (reconnect protocol + client
consumers across all five clients + server e2e test).

Claude-Session: https://claude.ai/code/session_01DMXXvNuPekkkrTEyPNxEkW

docs(archreview): wrap P2 epic — defer TST-15 + TST-24 (user decision)

ci / portable (push) Failing after 41s

Details

ci / java (push) Failing after 51s

Details

ci / portable (pull_request) Failing after 47s

Details

ci / java (pull_request) Failing after 50s

Details

ci / windows (push) Failing after 8s

Details

ci / windows (pull_request) Failing after 7s

Details

ci / live-mxaccess (push) Has been cancelled

Details

ci / live-mxaccess (pull_request) Has been cancelled

Details

2201fd8828

Epic bucket: 5/7 done (CLI-15, CLI-04, CLI-30, TST-01, TST-04). TST-15
(Phase-4 ACL feature; SEC-25 already prevents value leakage) and TST-24
(CI-gated on TST-03) deferred to a follow-up. Net P2: 35/38 Done.

Claude-Session: https://claude.ai/code/session_01DMXXvNuPekkkrTEyPNxEkW

dohertj2 closed this pull request

2026-09-03 10:53:57 -04:00

dohertj2 deleted branch fix/archreview-p2

2026-09-03 10:53:57 -04:00

ci / portable (push) Failing after 41s

Details

ci / java (push) Failing after 51s

Details

ci / portable (pull_request) Failing after 47s

Details

ci / java (pull_request) Failing after 50s

Details

ci / windows (push) Failing after 8s

Details

ci / windows (pull_request) Failing after 7s

Details

ci / live-mxaccess (push) Has been cancelled

Details

ci / live-mxaccess (pull_request) Has been cancelled

Details

Pull request closed

This pull request cannot be reopened because the branch was deleted.

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: dohertj2/mxaccessgw#122