# .NET Native session observations — 2026-10-02

The opt-in `NativeSession.SetWireObserver` observes complete frames from the
production C++ parser and complete successful writes from the native
transport. It forwards borrowed bytes on the owner thread and cannot veto or
modify traffic. The default uses the ordinary parser and no managed observer
callback. Configure it before `Start`; explicit multi-peer and native bypass
transports are refused. TCP/TLS single-peer sessions are supported. An outbound
send batch is one observed buffer and may contain multiple FIX frames.

Managed callback exceptions are retained in `LastNativeHookException`, without
changing the engine's actual send result or reply path. The callback handle is
held until the native owner is closed. Replacing a live observer is refused.
The new exported function is additive; existing callers do not need it.

## Benchmark integration

`ProviderSmoke --observations-file FILE` writes actual per-role admin counters,
complete admin events and twelve cold received/sent application cycles. This
mode requires one fixed split-role TCP session and one run. It refuses pool,
shard, multi-session and open-loop combinations. The shared harness performs
an initial warmup and another before its measured run, so the observations
declare `effective_warmup_cycles: 2 * --warmup`.

The owner's window starts at the measured harness phase. The passive role
opens after its last excluded reply, or on the first application frame with
zero warmup. Each closes on its final measured terminal frame. Logon, later
projection checks and logout are outside the window. Admin counters are checked
against actual events, including the native initiator's Logon acknowledgement;
missing traffic cannot be replaced by inferred zero counts.

`--admin-probe` inserts one midpoint production-engine TestRequest with
`112=NATIVE-S5-PROBE` and waits for the matching Heartbeat. The feed/server
posts through the public command ring so its pinned worker retains ownership.
This mode declares injected traffic and cannot be a report-grade latency run.

The existing server-owned tick clock remains after complete `W` preparation
and before its engine send; its end uses the actual native receive timestamp,
before parsing and benchmark extraction. The observer does not replace those
clocks. Both HFTBRW1 primary and scheduler-delay series are retained by the
shared harness. Comparison-fixture alignment remains explicitly false; the
existing Native market-data generators have not been replaced by this change.

## Retained verification

[Evidence](evidence/native-session-observed-20261002/) retains the compiled
source snapshots, grading code, native-library and managed executable hashes,
build logs, per-role observations, original wire frames and raw samples under
`SHA256SUMS`.

- The native observer unit passes with TLS support both disabled and enabled.
  It exercises the production parser/transport wrapper, inbound admin and
  application frames, exact completed/batched writes, failed-write exclusion,
  lifecycle restrictions and unsupported scope. Its socket-pair fixture is a
  local Unix stream, not physical-link or latency evidence.
- Three actual managed native-provider checks pass, with **zero skips**. They
  verify bilateral exact wire bytes, Logon and TestRequest/Heartbeat traffic,
  a valid ExecutionReport despite an observer exception, clearing before start,
  refusal after start/disposal and refusal of multi-peer observation.
- Twelve fresh functional pairs pass under SCAN's `isol-no-shared` lease:
  every flow with five warmups, no warmup and the admin probe. Each owner retains
  twenty primary and twenty delay samples. Twelve complete received cycles per
  pair pass the canonical wire auditor. Ordinary windows record explicit zero
  admin counts; every probe records one inbound and one outbound admin event on
  each role, with zero ResendRequests.
- The native library and managed executable build successfully. The managed
  checks run on .NET 8.0.30; native compilation uses GCC toolset 14 and the
  session's out-of-tree build root.

These are Stage 4 functional diagnostics. No fresh physical run or report
promotion is claimed. The self-contained .NET 8.0.30 runtime is staged on both hosts (193 files,
complete tree SHA-256 `dc3bd644542097d40ca1c4cf74c54dc9903d0bb43762b855e11280b3e950e94e`).
The fixed launcher and installer pin the complete runtime and native library,
refuse a changed tree and use disjoint host-specific CPU masks. Root admission
and fresh physical runs remain pending.

## Self-contained SCAN diagnostic

The first self-contained matrix retains twelve additional functional pairs and
three 10,000-sample runs per flow. All twelve report-shaped pairs pass the wire,
primary/delay, actual admin and numeric sample checks. Achieved rates are
9,991/s for NOS, MD and tick-to-trade; mixed flow is 9,990–9,991/s. All full
percentile-stability and scheduler-delay checks pass in this diagnostic.

The controller records `quiet_cpu_lease: false`. The outer helper held both
locks, but Python's matrix wrapper closed their descriptors when spawning the
child controller. The journal and original wrapper are retained with the
unmodified observations; this bundle is not quiet-certified or physical
performance evidence. The queued wrappers now pass the inherited descriptors
explicitly, and the fresh SCAN report-shaped repeat certifies `quiet_cpu_lease: true`.
All twelve 10,000-sample pairs again pass at 9,990–9,991/s, with rate, complete
primary/delay observations, measured admin events, all twelve wire cycles and
full percentile stability passing. Its only report blockers are localhost
physical topology and comparison-fixture alignment. HP's matching high-priority quiet job now completes all twelve functional
pairs and three 10,000-sample pairs per flow. Achieved rates are 9,991–9,992/s.
All actual admin, wire, primary/delay and scheduler checks pass. MD, mixed and
tick-to-trade pass full stability; NOS fails full percentile stability, with
its three p99 values at 15.575, 17.949 and 23.620 us. Both retained medium
bundles remain local diagnostics with explicit physical/fixture blockers.

The current physical controller additionally requires exact sent/peer-received
captures, twelve audited cycles, complete bilateral Logon events and valid
admin frame lengths/checksums. It requires the prepared send and native receive
clock declarations. Forty-seven native gate/input/launcher/lease checks pass using
actual retained ordinary, zero-warmup and injected-probe pairs; the combined
native, QuickFIX/J and FIX Antenna regression run passes 104 checks. Instrumented
runs remain `S5 diag` while comparison-fixture alignment is false.


## Physical scheduling

Both hosts pass the fixed installer's read-only `--check`. Frozen controllers
at `cfdf2a05a7b62592d7b6ba4b2a9cdc9c7ea1c4d1` are queued behind the root install
marker, at high priority on HP and normal priority on SCAN. The versioned
`run_dac_dotnet_native_session_matrix.py` preserves both lease descriptors,
requires the selected host and quiet pool, admits all four tiny physical flows
with full evidence, then runs three 10,000-sample report pairs per flow. Root
installation requires the user's sudo password; it has not been inferred from
successful input prechecks.