Resolve Contracts-001/004/005/006/007/008 code-review findings

Contracts-001: docs/Grpc.md still described "four MxAccessGateway RPCs" —
updated to the actual six (adding AcknowledgeAlarm and QueryActiveAlarms to
the handler and validation-rule sections).

Contracts-003 (Won't Fix): the finding is factually wrong — the <Protobuf>
item for mxaccess_worker.proto already sets ProtoRoot="Protos"; all three
items are consistent (confirmed back to the reviewed commit).

Contracts-004: corrected the stale GatewayContractInfo XML summary
("before generated protobuf contracts are introduced").

Contracts-005: no proto field/enum value was ever removed, so no reserved
ranges were invented. Added a wire-compatibility policy comment to all three
.proto files instructing future editors to reserve removed numbers.

Contracts-006: documented MxStatusProxy.success — it mirrors the COM
MXSTATUS_PROXY numeric success member, is not a boolean, and clients should
branch on category.

Contracts-007: added 13 round-trip tests covering galaxy_repository.proto
messages, bulk-subscribe payloads, and raw-value/IPC worker bodies.

Contracts-008: WorkerAlarmRpcDispatcher never assigns AcknowledgeAlarmReply.
status, so the old "native status" proto comment was misleading. Corrected
the hresult/status proto comments and documented the worker native_status →
public reply mapping in AlarmClientDiscovery.md.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

docs/AlarmClientDiscovery.md

@@ -776,6 +776,28 @@ case, to distinguish the two acks. `WorkerAlarmRpcDispatcher` reads only
 the top-level `hresult`/`protocol_status`, so it handles both arms
 without unpacking the payload.
 
+**Worker `native_status` → public `AcknowledgeAlarmReply` mapping.** The
+worker carries the ack outcome as a single `int32`
+(`AcknowledgeAlarmReplyPayload.native_status`, the `AlarmAckByName` /
+`AlarmAckByGUID` return code; `0` = success), also mirrored into the
+worker `MxCommandReply.hresult`. The public `AcknowledgeAlarmReply` has
+two outcome-shaped fields, but only one is populated:
+
+- `AcknowledgeAlarmReply.hresult` — `WorkerAlarmRpcDispatcher` copies the
+  worker's `MxCommandReply.hresult` (the native return code) into this
+  field. **This is the authoritative ack-outcome field**; `0` means the
+  ack succeeded. It is absent only when the worker reply omitted the
+  value, which is a protocol violation surfaced in `protocol_status`.
+- `AcknowledgeAlarmReply.status` (`MxStatusProxy`) — the worker by-name /
+  by-GUID ack path produces only the `int32` return code, never a
+  populated `MXSTATUS_PROXY` struct, so `WorkerAlarmRpcDispatcher` leaves
+  this field **unset on every reply**. It is reserved for a future
+  structured view of the ack outcome. Clients must not depend on it.
+
+Client authors should therefore branch on `protocol_status` first (for
+transport/session-level failures) and then on `hresult` (`0` = ack
+accepted by MXAccess) — never on `status`.
+
 ### 5. STA / threading — production fix needed
 
 The wnwrap COM is `ThreadingModel=Apartment`. The consumer's

docs/Grpc.md

@@ -10,7 +10,7 @@ The layer is composed of four collaborators:
 
 | Type | Lifetime | Role |
 |------|----------|------|
-| `MxAccessGatewayService` | scoped (gRPC) | Implements the four `MxAccessGateway` RPCs, performs exception mapping. |
+| `MxAccessGatewayService` | scoped (gRPC) | Implements the six `MxAccessGateway` RPCs, performs exception mapping. |
 | `MxAccessGrpcRequestValidator` | singleton | Rejects malformed requests before any session work runs. |
 | `MxAccessGrpcMapper` | singleton | Converts public proto types to internal `WorkerCommand`/`WorkerEvent` types and back. |
 | `IEventStreamService` (`EventStreamService`) | singleton | Owns the event stream pipeline, including bounded queue and backpressure handling. |
@@ -29,7 +29,7 @@ A second gRPC service, `GalaxyRepositoryGrpcService`, is mapped alongside it. It
 
 ## RPC Handlers
 
-`MxAccessGatewayService` derives from the generated `MxAccessGateway.MxAccessGatewayBase` and implements every RPC declared in `mxaccess_gateway.proto`. The proto contract itself is documented in [Contracts](./Contracts.md); this section covers only what the server-side handler does on top of that contract.
+`MxAccessGatewayService` derives from the generated `MxAccessGateway.MxAccessGatewayBase` and implements every RPC declared in `mxaccess_gateway.proto` — six in total: `OpenSession`, `CloseSession`, `Invoke`, `StreamEvents`, `AcknowledgeAlarm`, and `QueryActiveAlarms`. The proto contract itself is documented in [Contracts](./Contracts.md); this section covers only what the server-side handler does on top of that contract.
 
 Public gRPC send and receive message sizes are configured from
 `MxGateway:Protocol:MaxGrpcMessageBytes` (default 16 MiB). Official clients use
@@ -86,6 +86,14 @@ Carrying the enqueue timestamp into the worker layer is what lets queue-wait tim
 
 `StreamEvents` is a server-streaming RPC. The handler delegates the full pipeline to `IEventStreamService` and just forwards each `MxEvent` onto the response stream. Keeping the channel and producer/consumer machinery out of the handler means cancellation, exception mapping, and metric bookkeeping live in one place.
 
+### `AcknowledgeAlarm`
+
+`AcknowledgeAlarm` is a unary RPC that acknowledges a single alarm. The handler validates `session_id` and `alarm_full_reference` inline (it does not run through `MxAccessGrpcRequestValidator`, because the alarm surface routes through `IAlarmRpcDispatcher` rather than the generic `Invoke` path), resolves the session, then delegates to the registered `IAlarmRpcDispatcher`. The production `WorkerAlarmRpcDispatcher` routes the ack over the worker IPC by GUID (`AcknowledgeAlarmCommand`) when the reference parses as a canonical GUID, or by `Provider!Group.Tag` reference (`AcknowledgeAlarmByNameCommand`) otherwise. The handler-level RPC behaviour and the alarm contract itself are documented in [Alarm Client Discovery](./AlarmClientDiscovery.md).
+
+### `QueryActiveAlarms`
+
+`QueryActiveAlarms` is a server-streaming RPC that returns an `ActiveAlarmSnapshot` per currently active alarm. The handler validates `session_id` inline, resolves the session, and delegates to `IAlarmRpcDispatcher`; `WorkerAlarmRpcDispatcher` issues a `QueryActiveAlarmsCommand` over the worker IPC and streams each snapshot from the worker reply.
+
 ## Validation Rules
 
 `MxAccessGrpcRequestValidator` rejects requests with `StatusCode.InvalidArgument` before any session work happens. The rules are intentionally narrow — anything that requires session state (for example, "session does not exist") is left for `ISessionManager` so the validator can stay synchronous and side-effect free.
@@ -96,6 +104,8 @@ Carrying the enqueue timestamp into the worker layer is what lets queue-wait tim
 | `CloseSession` | `session_id` must be non-empty. | `InvalidArgument` |
 | `StreamEvents` | `session_id` must be non-empty. | `InvalidArgument` |
 | `Invoke` | `session_id` non-empty, `command` present, `kind` not `Unspecified`, payload oneof must match `kind`. | `InvalidArgument` |
+| `AcknowledgeAlarm` | `session_id` and `alarm_full_reference` must be non-empty. Validated inline in the handler, not by `MxAccessGrpcRequestValidator`. | `InvalidArgument` |
+| `QueryActiveAlarms` | `session_id` must be non-empty. Validated inline in the handler, not by `MxAccessGrpcRequestValidator`. | `InvalidArgument` |
 
 The payload-vs-kind check matters because the `MxCommand.payload` oneof is non-discriminated on the wire — a misaligned client could send `kind = Write` with a `Register` payload and silently confuse the worker. The validator turns that into a clear client error: