mxaccessgw/docs/implementation-plan-mxaccess-worker.md

# MXAccess Worker Implementation Plan

This plan implements the .NET Framework 4.8 x86 worker process after the
gateway foundation exists. The worker owns MXAccess COM, the dedicated STA
thread, message pumping, command dispatch, event sinks, conversion, heartbeat,
and shutdown.

Primary designs:

- `docs/mxaccess-worker-instance-design.md`
- `docs/design-decisions.md`
- `docs/toolchain-links.md`
- `C:\Users\dohertj2\Desktop\mxaccess\docs\MXAccess-Public-API.md`

## Milestone: mxaccess-worker-foundation

Goal: create the worker executable, connect to the gateway pipe, and report
ready from a functioning STA runtime.

### Issue: Scaffold Worker Project

Labels: `area:worker`, `type:infra`, `priority:p0`

Deliverables:

- create `src/MxGateway.Worker`,
- target `.NET Framework 4.8`,
- platform target `x86`,
- reference generated worker contracts,
- reference `ArchestrA.MXAccess.dll`,
- create `src/MxGateway.Worker.Tests`,
- document MSBuild command from `docs/toolchain-links.md`.

Acceptance criteria:

- worker builds as x86,
- worker tests run,
- MXAccess interop reference exists only inside worker boundary,
- gateway project does not reference MXAccess.

Tests:

- worker build,
- worker test project compile.

### Issue: Implement Worker Bootstrap And Options

Labels: `area:worker`, `type:feature`, `priority:p0`

Deliverables:

- parse `--session-id`,
- parse `--pipe-name`,
- parse `--protocol-version`,
- read `MXGATEWAY_WORKER_NONCE`,
- configure minimal structured logging,
- redact nonce and secrets.

Acceptance criteria:

- missing required arguments fail fast,
- invalid protocol version fails fast,
- nonce is never logged,
- bootstrap returns structured exit codes.

Tests:

- parser tests,
- missing/invalid values,
- redaction.

### Issue: Implement Pipe Client And Frame Protocol

Labels: `area:worker`, `area:contracts`, `type:feature`, `priority:p0`

Deliverables:

- connect to named pipe,
- frame reader/writer,
- envelope validation,
- `WorkerHello`,
- `GatewayHello` validation,
- `WorkerReady`,
- `WorkerFault`.

Acceptance criteria:

- session id, protocol, and nonce are validated before MXAccess creation,
- protocol mismatch fails session,
- malformed frames fault worker,
- all pipe writes go through one writer.

Tests:

- frame round-trip,
- wrong session/protocol/nonce,
- malformed frame,
- writer serialization.

### Issue: Implement STA Runtime And Message Pump

Labels: `area:worker`, `type:feature`, `priority:p0`

Deliverables:

- dedicated STA thread,
- COM initialization on STA,
- command queue wake event,
- `MsgWaitForMultipleObjectsEx` loop,
- `PeekMessage`/`TranslateMessage`/`DispatchMessage`,
- last STA activity timestamp,
- clean thread shutdown.

Acceptance criteria:

- commands execute on STA thread,
- pump continues while idle,
- shutdown exits thread,
- watchdog sees STA activity.

Tests:

- fake command executes on STA,
- queue wake,
- shutdown,
- watchdog timestamp.

### Issue: Create MXAccess COM Object On STA

Labels: `area:worker`, `type:feature`, `priority:p0`

Deliverables:

- instantiate `ArchestrA.MxAccess.LMXProxyServerClass`,
- record CLSID/ProgID/interoperability info,
- attach base event handlers,
- send `WorkerReady` only after COM creation succeeds,
- structured fault on COM creation failure.

Acceptance criteria:

- COM creation happens on STA only,
- gateway receives ready with worker info,
- failure includes HRESULT/exception where available,
- raw COM object never crosses threads.

Tests:

- fake COM factory tests,
- COM creation failure mapping,
- worker info mapping.

Live tests:

- opt-in live COM creation on installed MXAccess machine.

## Milestone: mxaccess-worker-parity-slice

Goal: implement first end-to-end command/event slice through real MXAccess.

### Issue: Implement STA Command Dispatcher

Labels: `area:worker`, `type:feature`, `priority:p0`

Deliverables:

- `StaCommand` model,
- command queue,
- one-at-a-time execution,
- command reply creation,
- cancellation before command starts,
- late-reply behavior after gateway timeout/cancel.

Acceptance criteria:

- command order is preserved,
- exceptions convert to command replies,
- current command correlation appears in heartbeat,
- shutdown rejects new commands.

Tests:

- order,
- exception mapping,
- cancellation-before-start,
- shutdown rejection.

### Issue: Implement Register And Unregister

Labels: `area:worker`, `type:feature`, `priority:p0`

Status: implemented.

Deliverables:

- `Register`,
- `Unregister`,
- server handle tracking,
- HRESULT/exception capture.

Acceptance criteria:

- returned MXAccess server handle is preserved,
- invalid unregister behavior is preserved,
- registry state is updated for diagnostics and cleanup only.

Tests:

- fake MXAccess register/unregister,
- invalid handle mapping,
- registry updates.

Live tests:

- real `Register`/`Unregister`.

### Issue: Implement AddItem, AddItem2, RemoveItem

Labels: `area:worker`, `type:feature`, `priority:p0`

Status: implemented.

Deliverables:

- `AddItem`,
- `AddItem2`,
- `RemoveItem`,
- item handle tracking,
- context string preservation,
- invalid/cross-server handle behavior preservation.

Acceptance criteria:

- returned item handles are not rewritten,
- context is passed exactly to MXAccess,
- invalid handles preserve HRESULT/status/exception shape.

Tests:

- fake item lifecycle,
- context mapping,
- invalid/cross-server cases.

Live tests:

- real `AddItem`,
- real `AddItem2("TestInt", "TestChildObject")`.

### Issue: Implement Advise, UnAdvise, AdviseSupervisory

Labels: `area:worker`, `type:feature`, `priority:p0`

Deliverables:

- advise command handlers,
- advise state tracking,
- plain and supervisory methods,
- unadvise cleanup.

Acceptance criteria:

- calls execute on STA,
- advise state is tracked for cleanup,
- plain and supervisory methods remain distinct commands.

Tests:

- fake advise/unadvise,
- cleanup state,
- invalid handle mapping.

Live tests:

- advise known tag and observe first event where provider state allows.

### Issue: Implement Event Sink And Event Queue

Labels: `area:worker`, `type:feature`, `priority:p0`

Status: implemented.

Deliverables:

- handlers for `OnDataChange`,
- handlers for `OnWriteComplete`,
- handlers for `OperationComplete`,
- handlers for `OnBufferedDataChange`,
- monotonic worker event sequence,
- bounded outbound event queue,
- fail-fast overflow.

Acceptance criteria:

- events are enqueued, not pipe-written on STA,
- order is preserved,
- `OperationComplete` is not synthesized,
- buffered events preserve raw metadata if conversion is incomplete,
- overflow faults session.

Tests:

- fake event conversion,
- ordering,
- overflow,
- no synthetic operation complete.

Live tests:

- real `OnDataChange` and `OnWriteComplete` where provider emits them.

### Issue: Implement Value Conversion

Labels: `area:worker`, `type:feature`, `priority:p0`

Deliverables:

- scalar `VARIANT` conversion,
- SAFEARRAY conversion,
- raw fallback metadata,
- timestamp conversion,
- array rank/dimension metadata where available.

Acceptance criteria:

- bool/int/float/double/string/time conversions work,
- arrays convert for supported types,
- unknown values keep raw metadata,
- credential-bearing values are not logged.

Tests:

- scalar conversion matrix,
- array conversion matrix,
- null/empty cases,
- raw fallback.

### Issue: Implement MXSTATUS_PROXY And HRESULT Conversion

Labels: `area:worker`, `type:feature`, `priority:p0`

Deliverables:

- `MXSTATUS_PROXY[]` conversion,
- category/source/detail preservation,
- success field preservation,
- HRESULT extraction from COM exceptions,
- safe diagnostic messages.

Acceptance criteria:

- status arrays are not collapsed,
- raw fields preserved,
- exception HRESULT is captured,
- completion-only status bytes are raw unless exact mapping is proven.

Tests:

- status struct conversion,
- exception/HRESULT mapping,
- raw fallback metadata.

### Issue: Implement Heartbeat And Watchdog

Labels: `area:worker`, `type:feature`, `priority:p1`

Deliverables:

- periodic heartbeat messages,
- last STA activity,
- pending command count,
- current command correlation id,
- event queue depth,
- watchdog warnings.

Acceptance criteria:

- gateway receives updates,
- stuck command is visible in heartbeat,
- high queue/stale activity warnings are observable.

Tests:

- heartbeat payload,
- stale activity,
- queue depth.

### Issue: Implement Graceful Shutdown

Labels: `area:worker`, `type:feature`, `priority:p0`

Deliverables:

- handle `WorkerShutdown`,
- reject new commands,
- let current command finish within timeout,
- best-effort `UnAdvise`, `RemoveItem`, `Unregister`,
- detach event handlers,
- release COM object,
- exit process.

Acceptance criteria:

- cleanup order follows design,
- cleanup failures are logged but do not hang shutdown,
- gateway can kill after timeout,
- worker exits with success on graceful shutdown.

Tests:

- fake cleanup order,
- cleanup failure,
- command in progress,
- shutdown timeout.

## Milestone: integration-and-parity

Goal: prove gateway plus worker behavior against installed MXAccess.

### Issue: Worker Live MXAccess Smoke Test

Labels: `area:worker`, `area:tests`, `type:test`, `priority:p0`

Deliverables:

- opt-in live test harness,
- open gateway session,
- spawn worker,
- create MXAccess COM,
- `Register`,
- `AddItem`,
- `Advise`,
- wait bounded time for data/status,
- `CloseSession`.

Acceptance criteria:

- test skips without explicit environment variable,
- test cleans up worker even on failure,
- logs include enough data for parity debugging.

### Issue: Parity Fixture Matrix

Labels: `area:worker`, `area:tests`, `type:test`, `priority:p1`

Deliverables:

- fixture list based on `C:\Users\dohertj2\Desktop\mxaccess\captures`,
- scenarios for invalid handles, write statuses, secured writes, add-item
  context, and buffered registration,
- comparison format for direct MXAccess vs gateway.

Acceptance criteria:

- each public method has planned parity fixture or documented gap,
- gateway results preserve HRESULT/status/value/event shape.