Merge remote-tracking branch 'origin/main' into agent-1/issue-17-implement-dashboard-authentication

docs/gateway-process-design.md

@@ -206,13 +206,23 @@ accounting and a clear fan-out policy.
 Behavior:
 
 1. Validate session id and authorize event access.
-2. Attach a stream cursor to the session event channel.
-3. Send events in worker sequence order.
-4. Stop on client cancellation, session close, or session fault.
-5. Emit a terminal status when the session faults if gRPC status alone cannot
+2. Attach the single active subscriber lease for the session.
+3. Read worker events into a bounded public stream queue.
+4. Send events in worker sequence order.
+5. Stop on client cancellation, session close, or session fault.
+6. Emit a terminal status when the session faults if gRPC status alone cannot
    preserve the required details.
 
-The gateway must not reorder events from one worker.
+`EventStreamService` owns subscriber tracking and public stream backpressure.
+The default policy allows one active subscriber per session. A second subscriber
+is rejected with `EventSubscriberAlreadyActive`. Stream cancellation releases
+the subscriber lease so a later stream can attach to the session.
+
+The gateway must not reorder events from one worker. `EventStreamService` writes
+mapped events to a bounded first-in, first-out queue and faults the session with
+`EventQueueOverflow` if the queue fills. The gateway does not synthesize
+`OperationComplete`; it forwards that family only when the worker reports a
+native MXAccess `OperationComplete` event.
 
 ## Web Dashboard
 
@@ -584,7 +594,8 @@ worker MXAccess event
   -> worker outbound event queue
   -> worker pipe writer
   -> gateway read loop
-  -> session event channel
+  -> worker client event queue
+  -> EventStreamService bounded stream queue
   -> gRPC StreamEvents
 ```
 
@@ -598,13 +609,15 @@ The gateway should record:
 
 Default backpressure policy for parity testing should be fail-fast:
 
-1. If the session event channel fills, fault the session.
+1. If the worker client event queue fills, fault the worker client.
+2. If the public stream queue fills, fault the gateway session.
 2. Preserve the overflow details in logs and metrics.
 3. Do not silently drop data-change events.
 
-Do not set a production event-rate target before measurement. Emit event rate,
-queue depth, stream send latency, and overflow metrics. Later production modes
-may support explicit coalescing by item handle as an opt-in behavior.
+Do not set a production event-rate target before measurement. `GatewayMetrics`
+records received event counts by family, queue depth, stream disconnects, and
+overflow counts. Later production modes may support explicit coalescing by item
+handle as an opt-in behavior.
 
 The gateway should not synthesize `OperationComplete` from write completion,
 command replies, ASB completion queues, or completion-only status frames. Forward

docs/implementation-plan-mxaccess-worker.md

@@ -189,6 +189,8 @@ Tests:
 
 Labels: `area:worker`, `type:feature`, `priority:p0`
 
+Status: implemented.
+
 Deliverables:
 
 - `Register`,
@@ -447,4 +449,3 @@ Acceptance criteria:
 
 - each public method has planned parity fixture or documented gap,
 - gateway results preserve HRESULT/status/value/event shape.
-

docs/mxaccess-worker-instance-design.md

@@ -294,7 +294,10 @@ creates `LMXProxyServerClass` through `MxAccessComObjectFactory` on the STA,
 attaches `MxAccessBaseEventSink`, and returns `WorkerReady` only after those
 steps succeed. `MxAccessSession` keeps the raw COM object private, records the
 STA managed thread id that created it, detaches the base event sink during
-disposal, and releases the COM reference on the STA.
+disposal, and releases the COM reference on the STA. After creation,
+`MxAccessStaSession` owns a `StaCommandDispatcher` backed by
+`MxAccessCommandExecutor`; `DispatchAsync` queues contract commands back to the
+same STA instead of exposing the COM object to callers.
 
 Creation rules:
 
@@ -414,6 +417,21 @@ Diagnostics:
 Implement method-specific dispatch instead of a generic string method invoker.
 Parity tests need stable command-specific request and reply shapes.
 
+`MxAccessCommandExecutor` implements the first command pair:
+
+- `Register` calls `LMXProxyServerClass.Register` with the requested client
+  name and preserves the returned server handle in both `ReturnValue` and
+  `RegisterReply.ServerHandle`.
+- `Unregister` calls `LMXProxyServerClass.Unregister` with the requested server
+  handle. The reply has no method-specific payload because the public MXAccess
+  method returns `void`.
+
+Both commands set `Hresult` to `0` only after the COM call returns normally.
+COM exceptions flow through `StaCommandDispatcher`, which captures the thrown
+HRESULT and converts the reply to `ProtocolStatusCode.MxaccessFailure`.
+`MxAccessStaSession.GetRegisteredServerHandlesAsync` returns an STA-read
+snapshot of tracked server handles for diagnostics and future cleanup logic.
+
 ## Handle Registry
 
 The worker should track MXAccess state for diagnostics and cleanup, while still
@@ -434,6 +452,8 @@ Rules:
 
 - Do not invent handles.
 - Do not rewrite handles returned by MXAccess.
+- Record server handles only after `Register` succeeds.
+- Remove server handles only after `Unregister` succeeds.
 - Preserve invalid-handle behavior from MXAccess.
 - Preserve cross-server handle behavior from MXAccess.
 - Use registry state for cleanup and diagnostics, not semantic correction.