FOCAS — retire Tier-C split, inline managed wire client, make read-only

Migration closes the FOCAS Tier-C architecture. OtOpcUa previously had
`Driver.FOCAS.Host` (NSSM-wrapped Windows service loading Fwlib64.dll via
P/Invoke) + `Driver.FOCAS.Shared` (MessagePack IPC contracts) + a C shim
DLL stand-in for unit tests. All of it is deleted; the driver is now a
single in-process managed assembly talking the FOCAS/2 Ethernet binary
protocol directly on TCP:8193.

Architecture

- Pure-managed `FocasWireClient` inlined at `src/.../Driver.FOCAS/Wire/`
  (owner-imported — see Wire/FocasWireClient.cs for the full surface).
  Opens two TCP sockets, runs the initiate handshake, serialises requests
  on socket 2 through a semaphore, closes cleanly with PDU + socket
  teardown. Both sync `IDisposable` and async `IAsyncDisposable`.
- `WireFocasClient` (same folder) adapts the wire client to OtOpcUa's
  `IFocasClient` surface — fixed-tree reads, PARAM/MACRO/PMC addresses,
  alarms. Writes return `BadNotWritable` by design — OtOpcUa is read-only
  against FOCAS.
- `FocasDriverFactoryExtensions` now accepts `"Backend": "wire"` (default)
  and `"Backend": "unimplemented"`. Legacy `ipc` and `fwlib` backends are
  rejected at startup with a diagnostic pointing at the migration doc.

Deletions

- `src/ZB.MOM.WW.OtOpcUa.Driver.FOCAS.Host/` — whole project + Ipc/,
  Backend/, Stability/, Program.cs.
- `src/ZB.MOM.WW.OtOpcUa.Driver.FOCAS.Shared/` — Contracts/, FrameReader,
  FrameWriter, whole project.
- `tests/...Driver.FOCAS.Host.Tests/` + `.Shared.Tests/` — whole projects.
- `src/.../Driver.FOCAS/FwlibNative.cs` + `FwlibFocasClient.cs` — 21
  P/Invokes + 7 `Pack=1` marshalling structs + the Fwlib-backed
  `IFocasClient` implementation.
- `src/.../Driver.FOCAS/Ipc/` + `Supervisor/` — IPC client wrapper +
  Host-process supervisor (backoff, circuit breaker, heartbeat, post-
  mortem reader, process launcher).
- `scripts/install/Install-FocasHost.ps1` — NSSM service installer.
- `tests/.../Driver.FOCAS.Tests/{IpcFocasClientTests, IpcLoopback,
  FwlibNativeHelperTests, PostMortemReaderCompatibilityTests,
  SupervisorTests, FocasDriverFactoryExtensionsTests}.cs` — tests that
  exercised the retired surfaces.
- `tests/.../Driver.FOCAS.IntegrationTests/Shim/` — the zig-built C shim
  DLL that masqueraded as Fwlib64.dll.

Solution changes

- `ZB.MOM.WW.OtOpcUa.slnx` drops the 4 retired project refs.
- `src/.../Driver.FOCAS.csproj` drops the Shared ProjectReference, adds
  `Microsoft.Extensions.Logging.Abstractions` for the optional `ILogger`
  hook in `FocasWireClient`.
- `src/.../Driver.FOCAS.Cli.csproj` drops the six `<Content Include>`
  entries that copied `vendor/fanuc/*.dll` into the CLI bin. CLI now uses
  `WireFocasClient` directly.
- `FocasDriver` default factory flips to `Wire.WireFocasClientFactory`.

Integration tests

- New `tests/.../Driver.FOCAS.IntegrationTests/` project covering fixed-
  tree reads (identity, axes, dynamic, program, operation mode, timers,
  spindle load + max RPM, servo meters), user-authored PARAM / MACRO /
  PMC reads, `DiscoverAsync` emission, `SubscribeAsync` + `OnDataChange`,
  `IAlarmSource` raise/clear transitions, and `ProbeAsync` /
  `OnHostStatusChanged`. 9 e2e tests against the focas-mock fixture
  (Docker container with the vendored Python mock's native FOCAS/2
  Ethernet responder).
- `scripts/integration/run-focas.ps1` orchestrates compose up → tests →
  compose down. Dropped the shim-build stage + DLL-copy step + the split
  testhost workaround (the latter only existed because of native-DLL
  lifecycle bugs the shim tripped).
- Docker compose collapses from 11 per-series services to one `focas-sim`
  service. Tests seed per-series state via `mock_load_profile` at test
  start.
- Vendored focas-mock snapshot refreshed to pick up upstream's native
  FOCAS/2 Ethernet responder (was 660 lines, now 1018) — the
  pre-refresh snapshot only spoke the JSON admin protocol.

Tests

- 145/145 unit tests in `Driver.FOCAS.Tests` pass (was 208 pre-deletion;
  63 removed tests exercised the retired IPC/shim/supervisor/Fwlib
  surfaces).
- 9/9 integration tests pass against the refreshed mock.
- `FocasScaffoldingTests.Unimplemented_factory_throws_on_Create…` updated
  to assert the new diagnostic message pointing at
  `docs/drivers/FOCAS.md` rather than the now-gone `Fwlib64.dll`.

Docs

- `docs/drivers/FOCAS.md` rewritten for the managed wire topology —
  deployment collapses to one `"Backend": "wire"` config block, no
  separate service, no DLL deployment, no pipe ACL.
- `docs/drivers/FOCAS-Test-Fixture.md` updated — single TCP probe skip
  gate instead of TCP + shim probe; fewer moving parts.
- `docs/drivers/README.md` row for FOCAS reflects the Tier-A managed
  topology (previously listed Tier-C + `Fwlib64.dll` P/Invoke).
- `docs/Driver.FOCAS.Cli.md` drops the Tier-C architecture-note section.
- `docs/v2/implementation/focas-isolation-plan.md` marked historical —
  the plan it documents was executed then superseded by the wire client.
- `docs/v2/v2-release-readiness.md` re-audited 2026-04-24. Phase 5
  driver complement closed. FOCAS change-log entry added.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

tests/ZB.MOM.WW.OtOpcUa.Driver.FOCAS.IntegrationTests/Docker/focas-mock/README.md

@@ -0,0 +1,191 @@
+# focas-mock
+
+`focas-mock` is a Python TCP mock server for testing higher-level FOCAS clients without a real FANUC control.
+
+The project is built from two inputs:
+
+- The 64-bit FANUC-related DLLs downloaded from [Ladder99/fanuc-cnc-api](https://github.com/Ladder99/fanuc-cnc-api)
+- The vendor `fwlib.cs` interop file, used as the callable surface reference
+
+The DLLs are not reimplemented at the binary ABI level. Instead, this project extracts their export tables, builds per-version capability profiles, exposes a JSON-over-TCP mock API, and implements the targeted native FOCAS Ethernet wire protocol used by OtOpcUa fixed-tree tests.
+
+## What is included
+
+- Vendored 64-bit DLLs under `vendor/fanuc-cnc-api/64bit/`
+- A profile extractor that inspects PE exports with `pefile`
+- A Windows P/Invoke shim source under `shim/` for clients that load `FWLIB64.dll` directly
+- Built-in profiles for:
+  - `FWLIB64`
+  - `fwlib0DN64`
+  - `fwlib0iD64`
+  - `fwlib30i64`
+  - `fwlibe64`
+  - `fwlibNCG64`
+- A stateful mock server with:
+  - version/profile switching
+  - forced error injection
+  - runtime state patching
+  - built-in default mock data
+  - auto-detected native FOCAS Ethernet PDU handling for the targeted API subset
+
+## Quick start
+
+Install in editable mode:
+
+```powershell
+python -m pip install -e .
+```
+
+List the generated profiles:
+
+```powershell
+focas-mock list-profiles
+```
+
+Start the mock server with the 30i profile:
+
+```powershell
+focas-mock serve --profile fwlib30i64 --host 127.0.0.1 --port 8193
+```
+
+Start with a JSON patch file that overrides the default data:
+
+```powershell
+focas-mock serve --profile fwlib30i64 --data examples/mock-30i.json
+```
+
+## Protocol
+
+The server accepts two protocols on the same port:
+
+- newline-delimited JSON for fixture control and shim tests
+- native FOCAS Ethernet binary PDUs from the real `fwlibe64.dll`
+
+JSON requests are one object per line:
+
+```json
+{"id":1,"method":"cnc_allclibhndl3","params":{"ipaddr":"127.0.0.1","port":8193,"timeout":10}}
+```
+
+Example response:
+
+```json
+{"id":1,"method":"cnc_allclibhndl3","rc":0,"message":"EW_OK","result":{"FlibHndl":1,"profile":"fwlib30i64"}}
+```
+
+Supported admin methods:
+
+- `mock_get_state`
+- `mock_patch`
+- `mock_reset`
+- `mock_load_profile`
+- `mock_list_methods`
+- `mock_schedule_alarms`
+
+Example patch request:
+
+```json
+{"id":2,"method":"mock_patch","params":{"state":{"parameters":{"6711":{"type":"long","value":1234,"decimal":0}}}}}
+```
+
+Native FOCAS Ethernet clients do not use the JSON request format. Seed profile
+and fixture state with JSON first, then point `cnc_allclibhndl3` at the same
+host and port. Wire-level details are documented in
+`docs/FOCAS_WIRE_PROTOCOL.md`.
+
+For clients that should avoid FANUC DLL loading entirely, `dotnet/Focas.Wire`
+contains a native C# read-only TCP client for the verified wire subset. It does
+not expose write APIs; use the JSON control channel to preset fixture state.
+
+Example test setup over TCP:
+
+```json
+{"id":1,"method":"mock_load_profile","params":{"profile":"FWLIB64"}}
+{"id":2,"method":"mock_patch","params":{"state":{"pmc":{"R":{"100":{"type":"byte","value":1}}},"parameters":{"6711":{"type":"long","value":1234,"decimal":0}},"macros":{"500":{"value":42000,"decimal":3}},"statinfo":{"run":3,"aut":1,"emergency":0},"alarms":[{"alm_no":100,"type":1,"axis":0,"msg":"TEST ALARM"}]}}}
+{"id":3,"method":"cnc_allclibhndl3","params":{"ipaddr":"127.0.0.1","port":8193,"timeout":10}}
+{"id":4,"method":"pmc_rdpmcrng","params":{"FlibHndl":1,"area":"R","data_type":"byte","start":100,"end":100}}
+```
+
+## Regenerating profiles
+
+The built-in JSON profiles are generated from the vendored binaries:
+
+```powershell
+python -m focas_mock.cli extract-profiles
+```
+
+By default this reads:
+
+- `vendor/fanuc-cnc-api/64bit/*.dll`
+- `upstream/fwlib.cs`
+
+and writes:
+
+- `src/focas_mock/builtin_profiles/*.json`
+
+## Testing Direct P/Invoke Clients
+
+If a client directly P/Invokes FANUC's 64-bit DLLs, point it at the shim DLLs built from `shim/` instead of the real vendor DLLs. The shim exports the small FOCAS surface used by the client and forwards calls to this Python server over JSON/TCP.
+
+```powershell
+focas-mock serve --profile FWLIB64 --host 127.0.0.1 --port 8193
+.\shim\build.ps1
+$env:FOCAS_MOCK_HOST = "127.0.0.1"
+$env:FOCAS_MOCK_PORT = "8193"
+```
+
+Before running the client, seed profile/state with `mock_load_profile` and `mock_patch` as shown above.
+
+Detailed documentation for the supported FOCAS subset is in `docs/USED_FOCAS_API.md`.
+Native Ethernet wire notes are in `docs/FOCAS_WIRE_PROTOCOL.md`.
+OtOpcUa-specific setup notes are in `docs/OTOPCUA_DOTNET_INTEGRATION.md`.
+
+## Implemented mock calls
+
+The server currently implements a practical subset of the surface observed in the exported DLLs and the C# wrapper:
+
+- `cnc_allclibhndl`
+- `cnc_allclibhndl2`
+- `cnc_allclibhndl3`
+- `cnc_freelibhndl`
+- `cnc_sysinfo`
+- `cnc_statinfo`
+- `cnc_rddynamic2`
+- `cnc_actf`
+- `cnc_acts`
+- `cnc_acts2`
+- `cnc_getpath`
+- `cnc_setpath`
+- `cnc_rdaxisname`
+- `cnc_rdspdlname`
+- `cnc_rdparam`
+- `cnc_wrparam`
+- `cnc_rdmacro`
+- `cnc_wrmacro`
+- `cnc_rdalmmsg2`
+- `pmc_rdpmcrng`
+- `pmc_wrpmcrng`
+- `cnc_rdopmsg`
+- `cnc_rdopmode`
+- `cnc_rdprgnum`
+- `cnc_exeprgname2`
+- `cnc_rdexecprog`
+- `cnc_rdseqnum`
+- `cnc_rdblkcount`
+- `cnc_rdproginfo`
+- `cnc_rdprogdir3`
+- `cnc_rdtimer`
+- `cnc_rdspmeter`
+- `cnc_rdsvmeter`
+- `cnc_rdspload`
+- `cnc_rdspgear`
+- `cnc_rdspmaxrpm`
+- `cnc_rddiagnum`
+- `cnc_rddiaginfo`
+- `cnc_diagnoss`
+
+## Limitations
+
+- This is not a binary-compatible replacement for FANUC's DLLs.
+- Native FOCAS Ethernet support is intentionally scoped to the targeted API subset documented in `docs/FOCAS_WIRE_PROTOCOL.md`.
+- The per-version profiles are grounded in exported symbol tables plus the published interop wrapper, while some defaults such as axis-count hints are inferred from filename families and documented as heuristics.