mxaccess/work_remain.md

Core Remaining Work

Current Baseline

The pure managed .NET 10 x64 ASB path is feasible and live-proven. It can:

• read the ASB solution shared secret through DPAPI,
• authenticate to the live IASBIDataV2 net.tcp endpoint,
• register/read TestChildObject.TestInt,
• reject null public collection arguments before touching client state in the main multi-item APIs,
• decode/read/write the core scalar and array ASB type matrix,
• write Int32 values and read them back,
• write through either positional write parameters or AsbWriteOptions,
• poll PublishWriteComplete for write completion,
• create a subscription, add monitored items, publish updates, and delete the monitored items/subscription,
• configure subscription creation and monitored-item registration through stable option records while preserving the original positional overloads,
• map publish responses into callback-ready values with decoded value, timestamp, quality, ASB status elements, and item-id-to-tag-name resolution,
• expose publish result summaries and value-presence helpers alongside the raw publish response and mapped values,
• expose derived publish/data-change status summaries and item-status array summary mapping while preserving raw statuses,
• raise mapped publish updates through the MxAsbClient PublishedValueReceived event,
• adapt ASB publish updates into an MXAccess-like server/item-handle DataChanged facade,
• advise compatibility items through either positional subscription parameters or the shaped AsbSubscriptionOptions / AsbMonitoredItemOptions overload,
• map known ASB global and item error codes to named AsbErrorCode values,
• summarize ASB status payload quality/category/detail while preserving raw unknown values,
• wait for async write completion by handle with timeout, poll interval, and optional delayed readback without retrying the write,
• cancel write-completion polling before the next poll or during polling/ readback delays through AsbWriteCompletionOptions.CancellationToken,
• perform idempotent best-effort ASB cleanup with signed Disconnect, independent channel/factory close-or-abort handling, and cleanup result reporting,
• explicitly reconnect by cleaning up the current ASB channel, retrying connection creation with caller-controlled attempts/delay, returning a fresh client, and preserving attempt plus cleanup evidence without replaying operations,
• connect through a stable AsbConnectionOptions API object with early endpoint validation and matching compatibility-server register/advise options overloads,
• keep payload serialization diagnostics out of the public API surface while retaining friend-only probe/test access,
• bound ASB cleanup disconnect and close operations with caller-controlled timeouts,
• cancel ASB cleanup before graceful disconnect/close by aborting local channel/factory objects when the cleanup token is already canceled,
• live-prove canceled cleanup on an opened ASB connection, including skipped disconnect, local channel/factory abort, and RequiresNewConnection,
• test cleanup partial-failure behavior for closed objects, faulted objects, close failure with abort fallback, abort failure reporting, and configured close timeout propagation,
• capture safe connection-failure evidence for refused ASB endpoints without destabilizing the live provider,
• clean up partially-created WCF channel/factory objects when ASB connection setup fails before a disposable client is returned,
• match installed AVEVA proxy behavior for UnregisterItems,
• register/read multiple tags in one request.
• document the supported ASB Variant wire format, scalar/array payload layouts, timestamp/duration handling, and quality/status payload parsing in docs\ASB-Variant-Wire-Format.md,
• document the recommended ASB/native integration boundary and staged migration in docs\ASB-Native-Integration-Decision.md.

Recent NMX Warning Triage

System Platform warning:

NMX Header ... buffer size pktHeader.dwDataSize 381 doesn't match received message size of 46

The warning is emitted by NmxAdptr.dll in the ProcessDataReceived path, not by the pure ASB client. The 46 byte received size matches the standalone NMX TransferData envelope size. A valid TransferData operation must send the 46-byte envelope plus the declared inner body; if the service receives only the envelope, or any envelope whose inner-length field does not match the actual body length, the adapter logs this class of header-size warning.

Mitigation now applied:

• src\NmxComHarness no longer sends a default self-transfer body. The --self-transfer path requires explicit --transfer-body-hex, validates the 46-byte envelope length field, and rejects empty/header-only transfers unless --allow-empty-transfer is explicitly supplied for a controlled probe.
• src\MxNativeClient validates low-level TransferData bodies before sending through both COM and managed DCE/RPC paths.
• src\MxNativeClient.Probe now requires explicit validated --transfer-body-hex for managed TransferData probes.

Build/test verification after mitigation:

• dotnet build src\NmxComHarness\NmxComHarness.csproj
• dotnet build src\MxNativeClient\MxNativeClient.csproj
• dotnet build src\MxNativeClient.Probe\MxNativeClient.Probe.csproj
• dotnet run --project src\MxNativeClient.Tests\MxNativeClient.Tests.csproj
• dotnet run --project src\MxNativeCodec.Tests\MxNativeCodec.Tests.csproj

Remaining Core Work

1. ASB type matrix

   • Core scalar/array decode, live read, and live write coverage is complete for Boolean, Int32, Float, Double, String, DateTime, Duration, and deployed array tags.
   • Remaining work is adding less common ASB types only as needed by real deployed tags.
   • ASB variant type IDs, payload layout, timestamp handling, duration handling, and quality/status payload parsing are documented in docs\ASB-Variant-Wire-Format.md.

2. ASB subscriptions and publish

   • CreateSubscription, AddMonitoredItems, Publish, DeleteMonitoredItems, and DeleteSubscription are implemented and live-proven.
   • AsbSubscriptionOptions and AsbMonitoredItemOptions now provide stable option-object overloads for subscription creation and monitored-item registration.
   • Mapped publish updates are exposed through a .NET event and a handle-based data-change facade.
   • The compatibility Advise facade also accepts AsbSubscriptionOptions and AsbMonitoredItemOptions; the probe path can exercise this options overload and live compatibility subscribe has been verified through it.
   • AsbPublishResult now carries a derived result summary and HasValues helper while retaining the raw PublishResponse.
   • AsbPublishedValue and MxAsbDataChangeEvent expose derived StatusSummary helpers for callers that want named status categories without losing raw status elements.
   • Item identity mapping and basic cleanup behavior are live-proven; continue validating callback/update ordering under churn.

3. Status and error mapping

   • Success-path publish quality/status decoding is implemented for ASB status elements, including MxQuality.
   • Named global/item ASB error-code mapping is implemented, and live probes cover InvalidMonitoredItems, OperationFailed, MonitoredItemsNotFound, WriteFailedBadTypeMismatch, invalid subscription delete global 0x000C, publish 0x0020, and bad-quality value status.
   • Status summaries classify good/uncertain/bad quality, known MX status categories, request timeout detail, and platform/no-communication detail.
   • Broaden remaining live non-success ASB ArchestrAError, item status, quality bytes, and known detail cases into the managed status model when safe source conditions are available, especially access denied and no communication.
   • Safe current-VM probes did not produce access denied or no communication: same-value direct ASB writes to secured/verified booleans succeeded, and a read-only sweep of 20 protected-value tags returned good quality.
   • Preserve unknown payloads without guessing.
   • Tests now cover success, invalid item, wrong-type write completion, invalid cleanup evidence inputs, access denied, timeout, no communication, and async write completion statuses.

4. Write variants

   • Core scalar and deployed array writes are live-proven beyond basic Int32.
   • AsbWriteOptions now provides an option-object overload for basic writes while preserving the existing positional overloads.
   • Add timestamp/status/comment handling where the provider supports it.
   • Write completion polling by handle with timeout, optional delayed readback, option validation, and caller cancellation is implemented and live-proven for Int32; extend evidence across other supported write shapes.

5. OperationComplete parity

   • Basic write completion through PublishWriteComplete is proven.
   • Direct IASBIDataV2 has no activate/suspend or generic OperationComplete contract, and create-subscription, add-monitored, publish, delete-monitored, and delete-subscription operations do not enqueue PublishWriteComplete records.
   • Continue trigger search outside the direct IDataV2 write-completion queue if a safe runtime candidate appears.
   • Do not synthesize OperationComplete for operations until native behavior is proven.

5a. Completion-only operation status

• One-byte NMX completion-only frames are preserved as raw, unpromoted statuses, including 0x00, 0x41, and 0xEF.
• Only the observed 5-byte status-word frame 00 00 50 80 00 maps to MxStatus.WriteCompleteOk and can raise the MXAccess-compatible write-complete event.
• Exact native MXSTATUS_PROXY[] conversion for completion-only bytes still needs decompiled mapping evidence or a native public event capture before promotion.
• Current available decompiled/Ghidra outputs did not expose a mapping table for completion-only bytes.

6. Buffered data

   • Find a runtime/source condition that emits buffered sample batches.
   • ASB MonitoredItem.Buffered is now exposed and live-proven against TestMachine_001.TestHistoryValue, but the observed publish response still carries one current value rather than a multi-sample buffered batch.
   • Map any proven batch payloads into the compatibility event model.

7. Production cleanup

   • Reduce trace verbosity and make SOAP/body dumps opt-in.
   • Channel/factory disposal now sends best-effort signed Disconnect, closes channel/factory independently with caller-controlled timeouts, and records cleanup results.
   • Cleanup cancellation is implemented for cancellation requested before graceful disconnect/close starts; already-running synchronous WCF cleanup calls remain bounded by configured timeouts.
   • Canceled cleanup is live-proven on an opened ASB channel and completes via local abort without hanging.
   • Explicit reconnect is implemented and live-proven for the normal cleanup and reconnect path.
   • Resolve additional live partial cleanup behavior after ASB channel failures when a safe provider condition is available.
   • Safe refused-endpoint connection failure evidence is captured; source-level no-communication evidence still needs a safe provider condition.
   • Partial ASB connection setup failure now runs channel/factory close-or-abort cleanup before rethrowing.

8. Public library shaping

   • The main probe-grade API primitives have been shaped into stable public option/helper surfaces; continue only for concrete caller gaps.
   • AsbConnectionOptions now fronts MxAsbDataClient.Connect, the string overload delegates to it, and MxAsbCompatibilityServer.Register accepts the same options object.
   • AsbWriteOptions now fronts the basic write path while preserving the existing positional write overloads.
   • MxAsbCompatibilityServer.Advise now has an options overload, and the probe can route compatibility subscribe through it.
   • AsbPayloadDebug has been narrowed to an internal friend-only diagnostic helper for test/probe assemblies.
   • AsbWriteCompletionOptions now owns timeout/poll/readback validation and exposes a cancellation token for caller-controlled polling waits.
   • AsbSubscriptionOptions and AsbMonitoredItemOptions now avoid extending positional primitive overloads as subscription policy grows.
   • AsbPublishResult now exposes common summary helpers without hiding raw response details.
   • AsbPublishedValue, MxAsbDataChangeEvent, and AsbResultMapper now expose derived status-summary helpers for common caller paths.
   • Public collection null guards are explicit for the main multi-item APIs.
   • docs\ASB-Native-Integration-Decision.md records the current integration decision: use MxAsbClient as the preferred regular tag data-plane adapter behind a higher-level compatibility routing facade, while keeping native NMX responsible for callback-only and not-yet-proven MXAccess semantics.
   • Focused non-live tests now cover public options defaults/validation, compatibility overload visibility, write-completion/readback DTO shape, and publish-result helpers. Add deeper request-construction tests only where future API growth makes them necessary.
   • Keep compatibility behavior documented where the deployed provider differs from ideal success semantics.