mxaccess/docs/ASB-Native-Integration-Decision.md

# ASB / Native Integration Decision

## Decision

Use `MxAsbClient` as the preferred implementation for the regular tag data
plane. Do not embed ASB inside the current `MxNativeSession` transport. Instead,
introduce a higher-level compatibility facade that can route each MXAccess-style
operation to either ASB or native NMX behind a common server/item-handle model.

The boundary should be operation-based, not inheritance-based:

- ASB owns direct `IASBIDataV2` connect, register, unregister, read, write,
  write-completion polling, publish subscriptions, cleanup, and explicit
  reconnect.
- Native NMX owns COM/DCOM activation, NMX service registration, callback export,
  Galaxy repository metadata resolution, native subscription callbacks, native
  recovery replay, and MXAccess behaviors whose ASB equivalent is not proven.
- The existing `MxNativeClient` should remain available as the native fallback
  and diagnostic path. ASB can replace its basic scalar/array read/write and
  simple data-change usage only after a shared facade makes routing explicit.

This avoids coupling the WCF ASB channel lifecycle to the DCE/RPC callback
lifecycle while still letting callers move to the simpler pure-managed x64 ASB
path where evidence is strongest.

## Evidence

Current ASB evidence is strong for the normal data path:

- The pure .NET 10 x64 ASB client connects to the live `IASBIDataV2` net.tcp
  endpoint, authenticates from local DPAPI-protected solution material, and
  performs register/read/write without AVEVA assembly references.
- ASB register/read/write is live-proven for deployed scalar and array tags, and
  `PublishWriteComplete` supplies write-handle completion records for basic
  writes.
- ASB subscriptions can create subscriptions, add monitored items, publish
  values, map quality/status payloads, and raise an MXAccess-like data-change
  event through `MxAsbCompatibilityServer`.
- ASB now has public option objects for connection, write, write completion,
  subscriptions, monitored items, cleanup, and reconnect.

Current native evidence is still required for legacy semantics:

- `MxNativeSession` owns NMX service activation, DCE/RPC transport, callback sink
  registration, heartbeat/recovery, Galaxy metadata resolution, NMX write
  message projection, `Write2`, `WriteSecured2`, supervisory advise, buffered
  registration, and callback parsing.
- `MxNativeCompatibilityServer` models the fuller MXAccess surface:
  `AddItem2`, `AuthenticateUser`, `ArchestrAUserToId`, `Suspend`, `Activate`,
  `AdviseSupervisory`, `OnWriteComplete`, `OperationComplete`, and
  `OnBufferedDataChange`.
- Direct `IASBIDataV2` exposes no activate, suspend, or generic
  `OperationComplete` operation. It only exposes write-completion polling.
- ASB buffered monitored items are accepted by the observed provider, but publish
  still returns one current value rather than a native buffered sample batch.
- Direct system-auth ASB writes did not reproduce the public MXAccess secured
  write rejection path on this VM.

## Recommended Boundary

Create a routing layer above both clients. It should hold compatibility
server/item handles and choose a backend per operation:

- `Register`, `Unregister`, `AddItem`, `RemoveItem`, `Read`, basic `Write`,
  simple `Advise`, `UnAdvise`, and write-completion polling should default to
  ASB when an ASB endpoint is configured and the tag/value shape is supported.
- `Write2`, `WriteSecured2`, `AuthenticateUser`, `ArchestrAUserToId`, `Suspend`,
  `Activate`, `AdviseSupervisory`, buffered items, and native callback-only
  events should route to native NMX until direct ASB evidence exists.
- `OperationComplete` should not be synthesized from ASB write completion. ASB
  write completion can raise a write-complete event, but generic operation
  completion remains native-only until a native trigger and payload mapping are
  proven.
- The facade should expose which backend handled an item or operation so tests,
  probes, logs, and callers can distinguish ASB behavior from native fallback.

## What ASB Should Own

- Endpoint discovery/configuration inputs for the direct `IASBIDataV2` route.
- Connection/authentication, request signing, channel cleanup, reconnect, and
  connection-failure cleanup for ASB.
- ASB item identity creation, register/unregister/read, variant
  encode/decode, and supported scalar/array writes.
- `AsbWriteOptions` and `AsbWriteCompletionOptions` driven write completion,
  including delayed readback when requested.
- ASB subscription creation, monitored item creation/deletion, publish polling,
  quality/status mapping, and basic MXAccess-compatible data-change adaptation.
- ASB-specific result/status summaries that preserve raw provider status while
  exposing named categories for known cases.

## What Native NMX Should Still Own

- DCE/RPC, COM object reference handling, NTLM/SSPI authentication, callback
  export, and NMX service registration.
- Galaxy repository tag resolution and metadata needed for NMX reference handles,
  value-kind projection, and native buffered registration.
- `Write2` and `WriteSecured2` until ASB timestamped and secured-write parity is
  explicitly proven.
- `Suspend`, `Activate`, supervisory advise, native recovery replay, heartbeat
  policy, and callback-derived event surfaces.
- `OnBufferedDataChange` and generic `OperationComplete` until ASB produces
  equivalent runtime evidence.
- Native diagnostic/probe coverage for payloads that ASB does not expose.

## Risks And Unknowns

- ASB endpoint discovery/configuration is environment-specific; fallback to NMX
  must be explicit when no usable endpoint is configured.
- ASB access-denied, no-communication, and other live fault status cases still
  need safe source conditions before they can be treated as complete parity.
- The exact native completion-only byte-to-status mapping is not fully proven.
- ASB buffered publish behavior may vary by provider or configuration; the
  observed provider did not produce multi-sample batches.
- Dual routing can create semantic drift if the facade hides backend choice.
  Backend selection must be visible in diagnostics and test assertions.
- Mixing ASB and native subscriptions for the same logical item can duplicate
  callbacks or produce ordering differences; route each item to one backend at a
  time.

## Staged Migration

1. Add a small shared facade project or class that exposes the MXAccess-style
   handle API and delegates to `MxAsbCompatibilityServer` or
   `MxNativeCompatibilityServer`.
2. Start with opt-in ASB routing for basic register/read/write/simple-advise
   flows. Keep native as the default fallback for unsupported operations.
3. Add route annotations to events and probe output so every data-change,
   write-complete, and fallback decision identifies `asb` or `native`.
4. Port basic compatibility tests to run against the facade with ASB-for-data
   enabled and native fallback enabled. Preserve existing ASB-only and
   native-only tests.
5. Gate any additional replacement on evidence: timestamped ASB write behavior,
   secured-write behavior, buffered sample batches, and native
   operation-complete parity should each require a focused capture or live probe
   before moving from native to ASB.
6. After the facade is stable, treat `MxNativeClient` as the legacy/native
   adapter and `MxAsbClient` as the primary data adapter. Avoid merging their
   transport internals.