# Design Decisions

This document records current v1 choices for the MXAccess gateway design. These
decisions can change, but implementation should follow them until a later design
update says otherwise.

## Source References

Use these local analysis sources when answering MXAccess-specific design or
implementation questions:

```text
C:\Users\dohertj2\Desktop\mxaccess
C:\Users\dohertj2\Desktop\mxaccess\docs\MXAccess-Public-API.md
C:\Users\dohertj2\Desktop\mxaccess\docs\MXAccess-Reverse-Engineering.md
```

Use these local notes for Galaxy Repository SQL metadata:

```text
C:\Users\dohertj2\Desktop\lmxopcua\gr
```

## MXAccess COM Target

Decision: target the installed MXAccess COM interop surface directly from the
x86 worker.

Concrete COM details from the MXAccess analysis:

- Interop assembly:
  `C:\Program Files (x86)\ArchestrA\Framework\Bin\ArchestrA.MXAccess.dll`
- Assembly identity:
  `ArchestrA.MxAccess, Version=3.2.0.0, PublicKeyToken=23106a86e706d0ae`
- COM class:
  `ArchestrA.MxAccess.LMXProxyServerClass`
- CLSID:
  `{C30B52F5-2CB5-4760-AF0A-3A344A7EB5DC}`
- ProgID:
  `LMXProxy.LMXProxyServer.1`
- Version-independent ProgID:
  `LMXProxy.LMXProxyServer`
- Registered server:
  `C:\Program Files (x86)\ArchestrA\Framework\Bin\LmxProxy.dll`
- Registry view:
  `HKCR\Wow6432Node\CLSID\{C30B52F5-2CB5-4760-AF0A-3A344A7EB5DC}`
- Threading model:
  `Apartment`

Rationale: `LMXProxyServer` is a 32-bit in-process COM server, so a .NET 10 x64
gateway cannot instantiate it directly. The x86 sidecar worker is the reliable
parity path.

Implementation guidance:

- Worker should reference `ArchestrA.MXAccess.dll`.
- Worker should instantiate `new LMXProxyServerClass()` on the dedicated STA.
- Worker should expose the resolved class, ProgID, CLSID, interop assembly
  version, and `LmxProxy.dll` path through `GetWorkerInfo` / `WorkerReady`.
- Keep the ProgID/path configurable for diagnostics, but the default should be
  the installed MXAccess class above.

## Session Reconnect

Reconnectable sessions with event replay are shipped and config-gated. The
original "no reconnectable sessions" constraint is superseded.

One `OpenSession` creates one gateway session and one worker process. The
session ends on `CloseSession`, client disconnect policy, lease expiry, worker
fault, gateway shutdown, or — when `DetachGraceSeconds > 0` — detach-grace
expiry after the last external event subscriber drops.

`MxGateway:Sessions:DetachGraceSeconds` (default `30`) controls the retention
window. When positive, a session whose last external gRPC event-stream
subscriber drops stays `Ready` for that many seconds so a client can reconnect
to the same session instead of triggering a new `OpenSession` → worker spawn.
Setting it to `0` reverts to closing only on normal lease expiry.

A reconnecting client issues `StreamEvents` with `after_worker_sequence` set to
the last sequence it observed; the gateway replays retained events newer than
that watermark (capped by `MxGateway:Events:ReplayBufferCapacity` and
`MxGateway:Events:ReplayRetentionSeconds`) then transitions seamlessly to live
delivery. If the requested position precedes the oldest retained event, a
`ReplayGap` sentinel signals the client to re-snapshot. The replay→live handoff
is atomic (no gap, no duplicate). See [Sessions](./Sessions.md) for the full
reconnect and replay protocol.

Decision: event-stream attach is bound to the opening API key. Because the
detach-grace and replay-retention windows are on by default, the reconnect
surface is a trust boundary — a retained session outlives the stream that opened
it. The session records the opening key id (`GatewaySession.OwnerKeyId`) and
every `StreamEvents` attach/reattach is rejected with `PermissionDenied` unless
the caller's key id matches the owner. Gating on the `event` scope alone was
rejected: it would let any `event`-scoped key that learned a session id attach to
another key's retained session and receive its replayed and live data. The check
runs before any subscriber is attached, so a foreign key never touches the
replay ring. Admin-scope override is deferred.

## Event Subscribers

Multi-subscriber fan-out for data-side `StreamEvents` is shipped and
config-gated. The original "one active subscriber per session" constraint is
superseded for deployments that opt in.

`MxGateway:Sessions:AllowMultipleEventSubscribers` (default `false`) controls
the mode. When `false` the session still rejects a second `StreamEvents`
subscriber with `EventSubscriberAlreadyActive`, preserving the original
single-subscriber behavior. When `true`, up to
`MxGateway:Sessions:MaxEventSubscribersPerSession` (default `8`) concurrent
external subscribers may attach; a new attach that would exceed the cap is
rejected with `EventSubscriberLimitReached`. The count-check-and-increment is
atomic under the session lock.

Failure semantics differ by mode: in single-subscriber mode a slow consumer's
channel overflow faults the whole session (`FailFast` backpressure); in
multi-subscriber mode the same condition disconnects only that subscriber so one
slow consumer never faults a session shared by others. The mode is fixed at
session construction and is not changed by a live subscriber-count snapshot.

The gateway-owned internal dashboard mirror subscribes directly on the
distributor with `isInternal: true` and is not counted toward the cap or the
detach-grace subscriber-count in either mode.

See [Sessions](./Sessions.md) for the full event-distributor and backpressure
design.

### Alarms — separate fan-out architecture

The single-subscriber rule never applied to alarms. The gateway runs an
always-on central alarm monitor (`GatewayAlarmMonitor`) that owns one
gateway-managed worker session, caches the active-alarm set, and fans it out to
any number of clients through the session-less `StreamAlarms` RPC.
`AcknowledgeAlarm` is session-less and routes through the monitor. Rationale:
alarm state is gateway-wide, not session-scoped — every client wants the same
current set plus updates, and forcing each to own a worker would multiply AVEVA
polling load for no benefit.

## Authentication

Decision: API key authentication for the public gateway.

API keys are stored in a gateway-owned SQLite database. Store hashed API key
secrets only; never store raw key material.

Recommended client format:

```text
authorization: Bearer mxgw_<key-id>_<secret>
```

Recommended SQLite tables:

```sql
CREATE TABLE api_keys (
    key_id TEXT PRIMARY KEY,
    key_prefix TEXT NOT NULL,
    secret_hash BLOB NOT NULL,
    display_name TEXT NOT NULL,
    scopes TEXT NOT NULL,
    created_utc TEXT NOT NULL,
    last_used_utc TEXT NULL,
    revoked_utc TEXT NULL
);

CREATE TABLE api_key_audit (
    audit_id INTEGER PRIMARY KEY AUTOINCREMENT,
    key_id TEXT NULL,
    event_type TEXT NOT NULL,
    remote_address TEXT NULL,
    created_utc TEXT NOT NULL,
    details TEXT NULL
);
```

Recommended scopes:

- `session:open`
- `session:close`
- `invoke:read`
- `invoke:write`
- `invoke:secure`
- `events:read`
- `metadata:read`
- `admin`

Hashing recommendation:

- Use HMAC-SHA256 with a gateway-local secret/pepper stored outside SQLite, or
  use Argon2id if a suitable dependency is already accepted.
- Compare hashes using constant-time comparison.
- Log only the key id or prefix, not the raw key.

Storage recommendation:

- Default SQLite path should be under `ProgramData` or another configured
  gateway data directory.
- Apply restrictive filesystem ACLs for the gateway service identity and
  administrators.
- Require TLS when the gateway is reachable off-machine.

## Authorization

Decision: start with scope checks by command category.

Suggested mapping:

- `OpenSession`: `session:open`
- `CloseSession`: `session:close`
- `Register`, `Unregister`, `AddItem`, `AddItem2`, `RemoveItem`, `Advise`,
  `UnAdvise`, `AdviseSupervisory`, `AddBufferedItem`,
  `SetBufferedUpdateInterval`, `Suspend`, `Activate`: `invoke:read`
- `Write`, `Write2`: `invoke:write`
- `WriteSecured`, `WriteSecured2`, `AuthenticateUser`,
  `ArchestrAUserToId`: `invoke:secure`
- `StreamEvents`: `events:read`
- Galaxy SQL metadata endpoints if added: `metadata:read`
- worker shutdown diagnostics and key management: `admin`

## Worker Process Identity

Decision: run workers as the gateway service identity for v1.

Rationale: this avoids early COM/DCOM permission failures and keeps the first
implementation focused on MXAccess parity. The worker launcher should keep an
extension point for a restricted service account later.

## Event Backpressure

Decision: fail-fast bounded queues for v1 and parity testing.

If worker or gateway event queues fill, fault the session. Do not silently drop
or coalesce events in parity mode.

Rationale: event drops would hide parity defects. Production coalescing by item
handle can be added later as an explicit opt-in mode once event rates are
measured.

## Event-Rate Target

Decision: do not set a production event-rate target before measurement.

For v1, expose queue depth, event rate, stream send latency, and overflow
metrics. Keep bounded queues and fail-fast behavior. Use observed load from live
systems to set a later coalescing or scaling target.

## Command Batching

Decision: no public command batching for v1.

Use one command per request so replies, HRESULTs, status arrays, event ordering,
and failure behavior are easy to compare against direct MXAccess.

Batch tag registration can be added later if measured setup latency requires it.

## Bulk Command Family

Decision: the gateway exposes a fixed set of *bulk* command kinds —
`AddItemBulk`, `AdviseItemBulk`, `RemoveItemBulk`, `UnAdviseItemBulk`,
`SubscribeBulk`, `UnsubscribeBulk`, `WriteBulk`, `Write2Bulk`,
`WriteSecuredBulk`, `WriteSecured2Bulk`, `ReadBulk` — that carry a list of
entries in one round-trip and return one per-entry result. Each command kind
runs the corresponding single-item MXAccess COM call sequentially on the
worker STA; per-entry failures populate `was_successful = false` with the
underlying HRESULT and never throw. There is no transactional / fail-fast
semantic — bulk here means "one round-trip, per-entry results", not
"atomic".

Rationale: MXAccess COM itself has no native bulk API for any of these
operations. Surfacing the per-entry result list keeps parity transparent —
the caller sees the same per-item HRESULT they would see calling MXAccess
N times directly — while the bulk shape collapses the gateway/IPC overhead
to one round-trip per batch and lets the worker keep the STA hot.

`ReadBulk` is the only bulk command without a 1:1 MXAccess analogue. Two
choices were considered:

1. **Cache-then-snapshot** (chosen): when a requested tag is already in the
   session's item registry AND advised, the worker returns the last cached
   `OnDataChange` value without touching the subscription
   (`was_cached = true`). Otherwise it takes the full `AddItem + Advise +
   wait-for-first-OnDataChange + UnAdvise + RemoveItem` lifecycle itself
   (`was_cached = false`) and leaves the session exactly as it was before
   the call. The cache lives on a per-session `MxAccessValueCache`,
   populated by `MxAccessBaseEventSink` on every `OnDataChange` after the
   event clears the outbound queue.

2. **Always-snapshot**: take the AddItem-through-RemoveItem lifecycle for
   every requested tag. Cleaner conceptually but pays the full lifecycle
   cost on every call and would interfere with existing subscriptions if
   MXAccess reuses item handles.

The chosen behavior matches what callers actually want from "current
value" — a free read of an already-streaming tag, and a one-shot snapshot
otherwise — and never disturbs subscriptions the caller did not create.
The decision intentionally does NOT synthesize an `OnDataChange` event
from the snapshot path: the snapshot value reaches the caller through
`ReadBulk`'s reply payload only, not through the event stream. This
preserves the "Don't synthesize events" rule that scopes the rest of the
worker.

`ReadBulk`'s wait loop pumps Windows messages on the worker STA
(`StaRuntime.PumpPendingMessages`) on every poll iteration so the inbound
MXAccess COM event can dispatch while the bulk executor still holds the
thread — without the pump the OnDataChange would never deliver.

## Graceful Worker Shutdown

Decision: best-effort cleanup before COM release.

During graceful shutdown, the worker should attempt:

1. `UnAdvise` for advised items.
2. `RemoveItem` for active item handles.
3. `Unregister` for active server handles.
4. Event detach.
5. COM release.

Failures during cleanup should be logged and preserved diagnostically, but the
gateway may still kill the worker after shutdown timeout.

## OperationComplete

Decision: model and forward `OperationComplete` only when native MXAccess fires
it. Do not synthesize `OperationComplete` from writes, command replies, ASB
completion queues, or other status frames.

Rationale: the event signature is known, but the MXAccess analysis has not yet
captured the runtime condition that triggers the public event. Synthesizing it
would risk breaking parity.

## Buffered Data Change

Decision: include `OnBufferedDataChange` in the protocol and worker event
model, but treat multi-sample payload conversion as capture-validated work.

The event signature and native path are known. A live buffered sample batch has
not yet been observed. Until then, preserve raw value, quality, timestamp, data
type, and status metadata whenever conversion is incomplete.

## Completion-Only Status Mapping

Decision: preserve completion-only operation-status bytes as raw diagnostic
metadata unless native MXAccess raises a public event or the MXAccess analysis
proves an exact `MXSTATUS_PROXY[]` mapping.

Do not guess status category/source/detail values for frames that MXAccess does
not expose through its public COM events.

## API Key Administration

Decision: v1 API key management is a local administrative CLI/tool, not a
public admin API.

The tool should support:

- initialize auth database,
- create key,
- list keys without showing secrets,
- revoke key,
- rotate key,
- print the raw secret exactly once at creation.

Public gRPC key-management endpoints can be added later only behind `admin`
scope and TLS.

## SQLite Migrations

Decision: use simple startup migrations with a `schema_version` table.

Recommended table:

```sql
CREATE TABLE schema_version (
    id INTEGER PRIMARY KEY CHECK (id = 1),
    version INTEGER NOT NULL,
    applied_utc TEXT NOT NULL
);
```

Migrations should be idempotent, run inside transactions, and fail gateway
startup if the database is newer than the running binary understands.

## Web Dashboard

Decision: host a basic gateway dashboard with Blazor Server and Bootstrap
CSS/JS.

The dashboard should show gateway health, active sessions, worker instances,
basic metrics, queue depths, and recent faults. It should update in real time
through Blazor Server component updates.

Allowed UI stack:

- Blazor Server,
- Bootstrap CSS,
- Bootstrap JavaScript,
- small local CSS.

Do not use MudBlazor or other Blazor UI component libraries for v1.

Dashboard access should require API-key-backed dashboard authentication with
`admin` scope when enabled. For local development, anonymous localhost access
is enabled by default through `Dashboard:AllowAnonymousLocalhost`; the bypass is
limited to loopback requests.

## Lazy Browse Is Wire-Only

Decision: the gateway continues to pull the full Galaxy hierarchy on each
deploy. `BrowseChildren` and the lazy dashboard render only avoid sending and
DOM-materializing the full tree — they do not push laziness into SQL or cache
loading.

Rationale: snapshot persistence and the dashboard summary both depend on a
fully-materialized cache. Lazy SQL would increase per-click latency on a
deployment-heavy box, multiply per-session SQL connections, and complicate the
cold-start path. Wire-side laziness solves the actual pain (oversized gRPC
replies and a heavy DOM) without disturbing the materialization model.

## TLS Auto-Certificate and Lenient Client Trust

Decision: when a Kestrel `https://` endpoint is configured without a certificate
of its own (and no `Kestrel:Certificates:Default` is set), the gateway generates
and persists a self-signed certificate rather than failing to start. Clients
connecting over TLS without a pinned CA accept whatever certificate the server
presents by default; pinning a CA restores full verification.

Rationale: `mxaccessgw` is an internal tool with no PKI to issue or distribute
certificates. The prior behavior — an `https` endpoint with no certificate
fails at startup with Kestrel's opaque "no server certificate was specified"
error — pushed operators toward plaintext (`h2c`), exposing the API key and
request payloads on the wire. Auto-generating a long-lived, persisted, reused
certificate lets TLS "just work" with zero certificate management, while the
lenient client default means clients connect to that self-signed certificate
without a manual trust step. Both choices are deliberate, not oversights:
strict-by-default would force PKI work this tool does not warrant. Plaintext-only
deployments are untouched — no certificate or key material is written for them —
and an operator who supplies a real certificate transparently overrides the
generated one.

Two clients diverge from "accept any certificate" because their gRPC stacks lack
a per-channel skip-verify hook:

- Python uses trust-on-first-use: it fetches the server's presented certificate
  over a separate unverified probe and pins it for the channel, and defaults the
  SNI/target-name override to `localhost` (the generated certificate always
  carries a `localhost` SAN).
- Rust is pin-only: tonic exposes no public hook to inject a custom certificate
  verifier, so TLS over Rust requires either a pinned CA or an explicit opt-in to
  system-trust verification; otherwise connecting returns a clear, actionable
  error.

See [Gateway Configuration — Automatic self-signed certificate](./GatewayConfiguration.md#automatic-self-signed-certificate)
and the per-client READMEs for the as-built behavior.

## Alarm-Manager to Subtag Fallback

Decision: add a second alarm provider (subtag monitoring) that the worker
activates automatically when the native wnwrap alarm manager fails, and fails
back to automatically when the manager recovers.

### Worker-side synthesis

Synthesis of alarm transitions from subtag value changes happens entirely in
the worker (`SubtagAlarmConsumer` / `SubtagAlarmStateMachine`). The gateway
still forwards only events the worker emits and synthesizes nothing itself.
This satisfies the parity rule even though the subtag path is inherently
non-parity: the parity rule governs where synthesis lives, not whether
synthesis is permitted when the native source is unavailable.

### Degraded is explicit

Every subtag-mode transition carries `degraded = true` on the
`OnAlarmTransitionEvent` and `ActiveAlarmSnapshot` proto messages, and the
`AlarmFeedMessage` feed carries an `AlarmProviderStatus` payload on stream
open and on every switch. No client can mistake a subtag-mode alarm for an
authoritative alarmmgr record. Subtag mode has lower fidelity: synthetic
deterministic GUID (SHA-derived from the alarm reference), best-effort
original-raise timestamp, narrower field set. Clients that need full fidelity
must wait for failback.

### Failover trigger

The failover trigger is N consecutive wnwrap COM failures — a `COMException`
thrown by `Subscribe` or `PollOnce`, or a failure HRESULT from
`GetXmlCurrentAlarms2`. A single poll failure does not trigger a switch; the
threshold (default 3, floored at 1) guards against transient COM hiccups. The
counter resets on any clean poll so a flapping provider does not permanently
latch in subtag mode.

### Acknowledge via ack-comment write

In subtag mode, `AcknowledgeAlarm` writes the operator comment to the alarm
attribute's ack-comment subtag (`Fallback:Subtags:AckComment`). The write
performs the native ack in AVEVA. This differs from alarmmgr mode, where
`AlarmAckByName` on `wwAlarmConsumerClass` is called directly. The `AckComment`
subtag name is empty by default; configuring it is required for ack to work in
subtag mode. The exact AVEVA subtag names are not hard-coded — the `Subtags`
config block exists precisely so names are not guessed without validation
against the live MXAccess attribute set.

### Related documentation

- [Gateway Configuration — Alarm Fallback options](./GatewayConfiguration.md#alarm-fallback-options)
- [Alarm Client Discovery — Subtag provider](./AlarmClientDiscovery.md)
- [gRPC Contract — provider_status and degraded fields](./Grpc.md)

## Later Revisit Items

These are explicit post-v1 revisit items, not open blockers:

- restricted worker service account,
- production coalescing by item handle,
- command batching for high-volume tag setup.

The following items were previously listed here and have since shipped:

- **Reconnectable sessions with replay** — shipped, config-gated via
  `MxGateway:Sessions:DetachGraceSeconds` and
  `MxGateway:Events:ReplayBufferCapacity` / `ReplayRetentionSeconds`.
  See [Session Reconnect](#session-reconnect) above and [Sessions](./Sessions.md).
- **Multiple event subscribers per session** — shipped, config-gated via
  `MxGateway:Sessions:AllowMultipleEventSubscribers` and
  `MxGateway:Sessions:MaxEventSubscribersPerSession`.
  See [Event Subscribers](#event-subscribers) above and [Sessions](./Sessions.md).

## Related Documentation

- [Gateway Process Detailed Design](./GatewayProcessDesign.md)
- [MXAccess Worker Instance Detailed Design](./MxAccessWorkerInstanceDesign.md)
- [Authentication](./Authentication.md)
- [Authorization](./Authorization.md)
- [Galaxy Repository](./GalaxyRepository.md)
