Align docs with StyleGuide and add CLAUDE.md
- Rename 16 kebab-case docs to PascalCase per StyleGuide - Move per-language client design docs from docs/ to clients/<lang>/ alongside their READMEs - Add ## Related Documentation sections to 15 docs that lacked one - Fix sentence-case violations in H3 headings (StyleGuide rule) - Update cross-references in gateway.md, client READMEs, scripts, and generate-proto.ps1 helpers to follow the new paths - Add CLAUDE.md with build/test commands, the source-update verification matrix, the parity-first contract, and pointers to MXAccess and Galaxy Repository analysis sources Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
Joseph Doherty
@@ -0,0 +1,466 @@
|
||||
# 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/MxAccessWorkerInstanceDesign.md`
|
||||
- `docs/DesignDecisions.md`
|
||||
- `docs/ToolchainLinks.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/ToolchainLinks.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.
|
||||
|
||||
## Related Documentation
|
||||
|
||||
- [Implementation Plan Index](./ImplementationPlanIndex.md)
|
||||
- [MXAccess Worker Instance Detailed Design](./MxAccessWorkerInstanceDesign.md)
|
||||
- [Worker Bootstrap](./WorkerBootstrap.md)
|
||||
- [Worker STA](./WorkerSta.md)
|
||||
- [Worker Conversion](./WorkerConversion.md)
|
||||
- [Worker Frame Protocol](./WorkerFrameProtocol.md)
|
||||
- [Worker Process Launcher](./WorkerProcessLauncher.md)
|
||||
- [Parity Fixture Matrix](./ParityFixtureMatrix.md)
|
||||
Reference in New Issue
Block a user