lmxopcua/docs/plans/2026-06-18-focas-figure-ww-poison-abcip-gate-design.md

# FOCAS cnc_getfigure + Wonderware poison-event status + AbCip nested-UDT live-gate — Design

**Date:** 2026-06-18
**Branch:** `feat/focas-figure-ww-poison-abcip-gate` (off master `274ba2b1`)
**Backlog items:** `stillpending.md` §A #3 (FOCAS `cnc_getfigure`), #5 (Wonderware poison-event sidecar wire), #6 (AbCip nested-struct prod live-gate)

Three independent backlog items bundled into one phase. They touch disjoint projects
(Driver.FOCAS + its python sim / Driver.Historian.Wonderware{,.Client} + Core.AlarmHistorian /
Driver.AbCip.IntegrationTests + docs), so they are independently implementable and parallelizable.

---

## Standing constraints (in force)

- **NO Commons wire/proto contract change**, NO Core.Abstractions / breaking interface contract change,
  NO EF migration, NO bUnit (Razor proven only by live `/run` — N/A this phase, no Razor touched).
- Stage by explicit path, never `git add .`; never stage the never-stage files (`sql_login.txt`,
  `src/Server/.../Host/pki/`, `pending.md`, `current.md`, `stillpending.md`, `docker-dev/docker-compose.yml`).
- No force-push, no `--no-verify`. Never echo/commit secrets. Finish = merge to master + push.
- `dangerouslyDisableSandbox: true` for all build/test/rig commands.

---

## Component A — FOCAS `cnc_getfigure` wire command (backlog #3)

### The finding that makes this safe

`WireFocasClient` (the pure-managed FOCAS/2 Ethernet client) is the **production path to real CNCs**
(not the Fwlib P/Invoke path). Its `GetPositionFiguresAsync` is a hard-coded empty-list stub
(`Wire/WireFocasClient.cs:287-297`). The consumer wraps it in a graceful probe:

```csharp
// FocasDriver.cs:662
state.PositionFigures = await SafeProbe(() => client.GetPositionFiguresAsync(ct), []);
```

and `AxisFactor` (`FocasDriver.cs:~853`) uses a per-axis figure **only when present and ≥ 0**, else falls
back to the `PositionDecimalPlaces` config knob. So a wire command that errors or returns empty degrades to
**exactly today's behavior** — implementing it is monotonic and cannot regress real hardware.

The `.NET FocasWireClient` and the python `focas_mock` (`tests/.../FOCAS.IntegrationTests/Docker/focas-mock/`)
speak a **co-designed, internally-consistent** wire protocol: the mock dispatches on command codes in
`server.py:_wire_payload` (0x56=servo-meter, 0x26=axis position, 0x89=axis names, 0x120=timer, …). The
protocol is validated **against the sim**, not against real Fanuc hardware — that validation is bench-CNC-gated
for the *entire* wire backend (`docs/v2/implementation/focas-wire-protocol.md`), not unique to this command.

### Approach (driver-internal + sim; NO interface change — `IFocasClient.GetPositionFiguresAsync` already exists)

1. **`FocasWireClient.ReadPositionFiguresAsync(...)`** — mirror `ReadServoMeterAsync` (`FocasWireClient.cs:351-386`):
   send the figure request **paired with the axis-name request (`0x0089`)** so figures align positionally to
   axes (exactly how servo-meter pairs `0x0056`+`0x0089`). Pick a wire command id **currently unused by both
   the client and the mock** (the mock uses 0x0E/0x10/0x15/0x16/0x18/0x19/0x1A/0x1C/0x1D/0x23/0x24/0x25/0x26/
   0x35/0x40/0x56/0x57/0x89/0x8A/0x98/0xE1/0xFC/0x120/0x8001/0x8002 — choose a clearly-unused code, e.g. `0x00D3`,
   and document it as sim-consistent / bench-CNC-unvalidated). Response payload = per-axis `short dec`
   (decimal-place count); parse into `IReadOnlyList<int>`. `rc != 0` → empty list (graceful).
2. **`WireFocasClient.GetPositionFiguresAsync`** — replace the stub: call the new client method, return its list;
   any failure path returns empty (never throws — the `SafeProbe` + per-axis fallback contract is preserved).
   Rewrite the now-stale `<returns>` doc.
3. **`focas_mock`** — add a `cnc_getfigure` admin/handler entry + a `_wire_payload` branch for the chosen code
   returning per-axis `short dec` from a **new data-store key `position_figures`** (default **0 per axis** →
   `10^0 = 1.0` factor → no scaling → every existing integration assertion preserved). Register the method name
   in `constants.py:IMPLEMENTED_FOCAS_METHODS` + the server handler map + profile `exports` as needed.

### Testing

- **Driver consumption is already covered offline** by `FocasPositionAutoScaleTests` (FakeFocasClient returns
  figures → asserts scaled vs. fallback). No change needed there.
- **New end-to-end proof** = a skip-gated integration test in `Series/WireBackendCoverageTests.cs` (the
  established pattern, `[Collection(FocasSimCollection.Name)]` + `if (_fx.SkipReason is not null) Assert.Skip(...)`):
  `mock_patch` non-zero `position_figures`, init the wire-backed `FocasDriver`, assert the published
  `AbsolutePosition` is the **scaled** value (raw ÷ 10^dec), not the raw integer.
- **Live `/run` for A** = bring the focas-mock up locally on the Mac
  (`docker compose -f tests/.../FOCAS.IntegrationTests/Docker/docker-compose.yml up -d --build`) and run the
  FOCAS integration suite; the new test executes (does not skip) and passes.

### Honest boundary (documented, not built)

Real-Fanuc validation of the chosen wire code/payload stays bench-CNC-gated — same status as the whole wire
backend. Worst case on real hardware = graceful fallback to the config knob (i.e. no regression).

---

## Component B — Wonderware poison-event per-event status (backlog #5)

### The finding that shapes it

The sidecar IPC reply `WriteAlarmEventsReply.PerEventOk` is a `bool[]` on **both** ends — which are **both in
this repo** (`...Wonderware.Client/Ipc/Contracts.cs` + `...Wonderware/Ipc/Contracts.cs`, MessagePack over TCP;
**not** a Commons proto). The client (`WonderwareHistorianClient.WriteBatchAsync:340-369`) can therefore only
produce `Ack`/`RetryPlease`, never `PermanentFail`, so a poison event loops to the retry cap instead of
dead-lettering immediately. The `HistorianWriteOutcome` enum **already has `PermanentFail`** and the sink
(`SqliteStoreAndForwardSink.cs:456-465`) **already dead-letters it immediately**. The sidecar writer seam
`IAlarmEventWriter.WriteAsync` returns only `bool[]` and its sole real impl is the **infra-gated**
`AahClientManagedAlarmEventWriter` (AAH SDK).

### Approach (additive IPC field + sidecar classifier; NO `IAlarmEventWriter` change, NO Commons)

1. **Additive wire field (both Contracts.cs):** add `[Key(4)] byte[] PerEventStatus` to `WriteAlarmEventsReply`
   (0=Ack, 1=Retry, 2=Permanent). **Keep `PerEventOk [Key(3)]`** populated for rolling-deploy back-compat
   (new client ↔ old sidecar: empty Key(4) → fall back to PerEventOk; old client ↔ new sidecar: ignores Key(4)).
2. **Sidecar `HistorianFrameHandler.HandleWriteAlarmEventsAsync`:** add a pure `ClassifyEvents(events)` step —
   an event that is **structurally malformed** (empty `SourceName`, empty `AlarmType`, or `EventTimeUtcTicks <= 0`)
   can never persist → mark **Permanent** and **exclude it from the writer batch** (mirrors the client's existing
   corrupt-row exclusion). Remaining events go to the writer; `true`→Ack, `false`→Retry. Populate **both**
   `PerEventOk` (Ack→true else false) and `PerEventStatus`.
3. **Client `WriteBatchAsync`:** when `reply.PerEventStatus.Length == batch.Count`, map 0/1/2 →
   `Ack`/`RetryPlease`/`PermanentFail`; else fall back to the existing `PerEventOk` path. Rewrite the stale
   `<remarks>` + inline "PermanentFail is never emitted" comments.

### Testing (fully offline — no rig)

- Sidecar: pure `ClassifyEvents` unit test (malformed → Permanent + excluded; valid → delegated; writer
  false → Retry).
- Client: a `FakeSidecarServer` reply with `PerEventStatus=[2]` → `WriteBatchAsync` returns `PermanentFail`;
  a reply with empty `PerEventStatus` → falls back to `PerEventOk` (back-compat).
- End-to-end sink: an existing `SqliteStoreAndForwardSink` test already proves `PermanentFail` → immediate
  dead-letter; add/confirm a test that a Permanent classification dead-letters on the **first** drain (vs. the
  retry-cap path the finding-002 regression test covers).

### Honest boundary (documented)

SDK-**semantic** permanent rejections (a structurally-valid event the AAH SDK rejects, e.g. unknown tag) still
map to Retry→cap until the infra-gated `AahClientManagedAlarmEventWriter` surfaces richer per-event status — a
noted follow-up. This phase closes the **structurally-malformed (poison)** case the finding describes.

---

## Component C — AbCip nested-struct live-gate (backlog #6)

### Verdict (from the feasibility pass)

A **local** live-gate is architecturally impossible: `ab_server` (the libplctag CIP sim used by the default
`abserver` tier) does **not** implement the CIP Template Object service (class 0x6C) that nested-UDT discovery
depends on. The decode + threading already **shipped** (`3d8ce4e8`/`d203f31c`; `AbCipUdtMember.NestedTemplateId`
→ existing `@udt/{id}` fetch) and 301 offline tests pass. The honest close formalizes the gate at the existing
**Emulate** fidelity tier (Logix Emulate / real ControlLogix).

### Approach (skip-gated test + docs; NO runtime change)

1. **New `AbCipEmulateNestedUdtTests`** (mirror `AbCipEmulateUdtReadTests` + `AbServerProfileGate.SkipUnless(Emulate)`):
   drives `FocasDriver`-equivalent AbCip discovery against a nested-UDT-bearing Emulate project and asserts the
   nested struct's atomic leaves are addressable (`Parent.Status.Code`, `Parent.Status.Running`) + the nested
   sub-folder materializes. Skips cleanly on the default `abserver` tier (which can't serve Template Object).
2. **`docs/drivers/AbCip.md`** — document nested-struct support as **Emulate-tier verified** (ab_server lacks
   CIP Template Object), referencing the new test + the existing offline unit coverage.

### Testing

The Emulate test **compiles and skips** locally (no Logix Emulate on this Mac) — proving it is wired into the
suite. The decode/threading risk is already pinned by the shipped offline unit tests
(`CipTemplateObjectDecoderTests` + `AbCipDriverDiscoveryTests`).

---

## Component D — Reconcile + finish

- `stillpending.md` (never-staged): mark #3 (FOCAS wire command shipped + sim-proven), #5 (Wonderware
  poison-event structurally-malformed close + the SDK-semantic follow-up boundary), #6 (AbCip live-gate
  formalized as the Emulate skip-gated test).
- Update memory (`project_stillpending_backlog.md` + `MEMORY.md` index line).
- Build clean + targeted tests green (FOCAS + Wonderware + AbCip) + Component A live `/run` (focas-mock) +
  merge to master + push.

---

## Task slicing (independent → parallelizable)

| Task | Component | Project(s) | Class | Parallel with |
|---|---|---|---|---|
| T1 | FOCAS wire `cnc_getfigure` (client method + stub wire-in + mock handler) | Driver.FOCAS + focas-mock (py) | standard | T2, T3 |
| T2 | Wonderware per-event status (DTO ×2 + sidecar classifier + client consume + tests) | Wonderware{,.Client} + Core.AlarmHistorian.Tests | standard | T1, T3 |
| T3 | AbCip Emulate nested-UDT skip-gated test + AbCip.md | AbCip.IntegrationTests + docs | small | T1, T2 |
| T4 | FOCAS integration test (mock) + live `/run` verify | FOCAS.IntegrationTests | small | none (after T1) |
| T5 | Reconcile stillpending #3/#5/#6 + memory + finish (build, tests, merge+push) | docs (never-staged) | small | none |

Parallel implementers use **worktree isolation** (the shared-tree git-race lesson) since T1/T2/T3 touch disjoint
projects. T4 depends on T1; T5 runs last.

## Done =

Build clean + `dotnet test` green (Driver.FOCAS + Wonderware client/sink + AbCip) + Component A live `/run`
(focas-mock integration test executes & passes) + Components B/C offline-proven + merged to master + pushed.