# S7 Driver — Implementation Plan

> Source of gap analysis: [featuregaps.md → S7](../featuregaps.md#s7-siemens-s7-3004001200--1500)
>
> Covers Build = Yes items only. Skip-rated rows are noted at the end for context.

## Summary

The S7 driver (`src/ZB.MOM.WW.OtOpcUa.Driver.S7/`) ships a working scaffold over
**S7netplus 0.20**: ISO-on-TCP / S7comm, single-connection-per-PLC (`SemaphoreSlim`),
DB / M / I / Q / T / C address parsing, atomic scalar reads/writes for Bool / Byte
/ I16 / U16 / I32 / U32 / F32, polled `ISubscribable` overlay, `IHostConnectivityProbe`
via `ReadStatusAsync`, and a Snap7-server-backed CI fixture on `localhost:1102`.

The 16 Build = Yes gaps fall into six tractable phases. **The hard one is gap #1
(S7-1500 Optimized DB / Symbolic addressing)** — S7netplus speaks classic S7comm
only and cannot reach optimized DBs at all. Phase 6 calls that out as an explicit
architectural decision: ship the constraint as documentation and the rest as
S7netplus-compatible features, *or* fork to a library that supports S7Plus
(Sharp7-fork, Snap7 v2, custom S7Plus). Phases 1-5 do not depend on that decision
and are landable on the current S7netplus base.

Every PR ships unit-test coverage and — where wire semantics matter — extends the
Snap7-server profile in `Docker/server.py` so the integration fixture exercises
the new path. PRs that need real S7-1500 firmware features the simulator doesn't
mimic (PUT/GET protection, password-tier auth, SZL diagnostic buffer) call that
out and gate the live-firmware test on the dev-box S7-1500 lab rig.

Architectural invariants we explicitly preserve:

- Single connection per PLC; `_gate` (SemaphoreSlim) serializes every PDU.
- Strict address-parse-at-init; bad config fails fast with `FormatException`.
- PUT/GET-disabled mapped to sticky `BadDeviceFailure`, not Polly-retried.
- 100 ms minimum publishing interval (matches CPU mailbox scan reality).
- `WriteIdempotent` per-tag flag is the only retry-policy lever.

## Phased delivery

| Phase | Theme | PRs | Gaps closed |
|------:|-------|-----|-------------|
| 1 | Data-type correctness | PR-S7-A1..A5 | #7, #8, #9, #19 |
| 2 | Performance — multi-tag PDU packing | PR-S7-B1..B2 | #3, #22 |
| 3 | Operability knobs | PR-S7-C1..C5 | #2, #4, #20, #21, #24 |
| 4 | Workflow — symbol import + UDTs | PR-S7-D1..D3 | #5, #6, #10 |
| 5 | Diagnostics & security | PR-S7-E1..E2 | #11, #14 |
| 6 | S7-1500 Optimized DB / Symbolic | PR-S7-F (decision) | #1 |

Phases 1-3 run sequentially because Phase 2 packing and Phase 3 deadbands are
both keyed off the type-decode work in Phase 1. Phase 4 (UDT/symbol import) is
parallelizable with Phase 5; Phase 6 is gated on the library-choice decision
in Open Questions (a).

---

## Per-PR detail

### Phase 1 — Data-type correctness

#### PR-S7-A1 — 64-bit scalar types (LInt / ULInt / LReal / LWord)

Closes gap #9. `Float64`/`Int64`/`UInt64` cases in `S7Driver.ReadOneAsync`/
`WriteOneAsync` currently throw `NotSupportedException`.

- **Files**: `S7Driver.cs` (read + write switch), `S7DriverOptions.cs` (extend
  `S7Size` with `LWord` for 8-byte access), `S7AddressParser.cs` (accept `DBL` /
  `LD` size suffix; S7netplus encodes 8-byte access via byte-array reads, so the
  parser converts `DB1.LD0` to a byte-range read internally).
- **Tests**: unit decode tests for the byte-pattern → `long` / `ulong` / `double`
  conversion; Snap7-server profile gets `f64` and `i64` seed types.
- **Risks**: S7netplus's `ReadAsync(string)` does not accept `LD` natively;
  fallback path is `Plc.ReadBytes(DataType.DataBlock, db, byteOffset, 8)` then
  `BitConverter` with explicit endian flip (S7 is big-endian on the wire,
  `BitConverter` is little-endian on x86/x64).
- **Effort**: M (3-4 days incl. tests).
- **Deps**: none.
- **Docs / fixture / e2e**: extends the type-mapping table in `docs/v2/s7.md`
  with `LInt` / `ULInt` / `LReal` / `LWord` rows; adds the new sizes
  (`LInt`, `ULInt`, `LReal`) to the `read` / `write` cookbook in
  `docs/Driver.S7.Cli.md`; updates `docs/drivers/S7-Test-Fixture.md`
  §"What it actually covers" to list the new 64-bit types and removes them
  from §5 "Data types beyond the scalars"; extends the snap7 seed-type set
  in `tests/ZB.MOM.WW.OtOpcUa.Driver.S7.IntegrationTests/Docker/server.py`
  with `i64`, `u64`, `f64` cases; adds seeds at known offsets
  (e.g. `DB1.DBL40` for i64, `DB1.DBL48` for f64) to
  `Docker/profiles/s7_1500.json`; adds `S7_1500Profile` constants for the
  new tags + a `Driver_reads_seeded_64bit_batch` smoke test in
  `S7_1500SmokeTests`; adds an LInt loopback assertion to
  `scripts/e2e/test-s7.ps1`.

#### PR-S7-A2 — STRING / WSTRING / CHAR / WCHAR

Closes gap #8 (string portion). S7 `STRING(n)` is `[max-len][actual-len][bytes...]`
(2-byte header + ASCII). `WSTRING(n)` is 4-byte header + UTF-16BE bytes. `CHAR`
is 1 byte; `WCHAR` is 2 bytes UTF-16BE.

- **Files**: `S7Driver.cs` (new `ReadStringAsync` / `WriteStringAsync` private
  helpers using `Plc.ReadBytes` for raw byte-range fetch), `S7DriverOptions.cs`
  (already has `StringLength`; add `S7DataType.WString`, `Char`, `WChar`).
- **Tests**: unit tests for header parsing including the "actual-len > max-len"
  PLC bug case (clamp on read, reject on write); Snap7 `ascii` seed type already
  exists, add `wstring` seed.
- **Risks**: write must respect the configured `StringLength` to avoid overrunning
  the DB; mismatched max-len is a common field bug.
- **Effort**: M.
- **Deps**: PR-S7-A1 (byte-range read helper lands there).
- **Docs / fixture / e2e**: extends the type-mapping section in
  `docs/v2/s7.md` with `STRING(n)` / `WSTRING(n)` / `CHAR` / `WCHAR`
  layouts (2-byte vs 4-byte header, UTF-16BE encoding, the "actual-len >
  max-len" PLC bug); extends the `read` / `write` cookbook in
  `docs/Driver.S7.Cli.md` with `--type WString` / `--type Char` / `--type
  WChar` examples and the `--string-length` flag for WString; updates
  `docs/drivers/S7-Test-Fixture.md` §"What it actually covers" to list
  ascii/wstring/char/wchar; adds `wstring`, `char`, `wchar` seed types to
  `Docker/server.py` (existing `ascii` covers STRING); seeds a
  `DB1.WSTRING[256]` and a `DB1.CHAR[300]` in
  `Docker/profiles/s7_1500.json`; adds `Driver_round_trips_string_types`
  smoke test exercising read + write of every variant; adds a string
  round-trip assertion to `scripts/e2e/test-s7.ps1`.

#### PR-S7-A3 — DTL / DATE_AND_TIME / S5TIME / TIME / TOD / DATE

Closes gap #8 (date/time portion).

- DTL is 12 bytes: year(u16) / month / day / weekday / hour / minute / second / nanos(u32).
- DATE_AND_TIME (DT) is 8 bytes BCD: yy mm dd hh mm ss msH msL+dow.
- S5TIME is 16-bit BCD with a 2-bit time-base.
- TIME is `Int32` ms since 1972 (S7-300/400) or signed-ms duration (S7-1200/1500).
- TOD is `UInt32` ms since midnight; DATE is `UInt16` days since 1990-01-01.

- **Files**: `S7Driver.cs` + new `S7DateTimeCodec.cs` static class encapsulating
  every encode/decode (keep the driver lean; codec is unit-testable in isolation).
- **Tests**: round-trip tests per type with golden byte vectors taken from the
  Siemens "STEP 7 V18 — Programming Reference" document. Snap7-server seed
  profile gains `dtl`, `dt`, `s5time`, `time` types.
- **Risks**: BCD parsing must reject invalid month/day combinations; PLC programs
  occasionally write 0x00 0x00 ... when uninitialized — surface as `BadOutOfRange`
  rather than parsing to year 0.
- **Effort**: L (4-5 days incl. all six types and the golden-vector suite).
- **Deps**: PR-S7-A1.
- **Docs / fixture / e2e**: extends `docs/v2/s7.md` with a new "Date / time
  types" subsection documenting DTL / DT (BCD) / S5TIME / TIME / TOD /
  DATE byte layouts and the S7-300/400 vs S7-1200/1500 TIME-encoding
  split; adds `--type Dtl` / `--type DateAndTime` / `--type S5Time` /
  `--type Time` / `--type TimeOfDay` / `--type Date` to the
  `docs/Driver.S7.Cli.md` cookbook; updates
  `docs/drivers/S7-Test-Fixture.md` §"What it actually covers" with the
  new datetime types and removes "DTL / DATE_AND_TIME" from §5 "Data
  types beyond the scalars"; adds `dtl`, `dt`, `s5time`, `time`, `tod`,
  `date` seed types to `Docker/server.py` with golden-byte vectors
  documented in comments; seeds `DB1.DTL[260]`, `DB1.DT[272]`,
  `DB1.S5TIME[280]`, `DB1.TIME[284]`, `DB1.TOD[288]`, `DB1.DATE[292]` in
  `Docker/profiles/s7_1500.json`; adds
  `S7DateTimeCodecTests` (unit) + `Driver_round_trips_datetime_types`
  smoke test; no `scripts/e2e/test-s7.ps1` change required (CLI cookbook
  examples cover the manual surface).

#### PR-S7-A4 — Array tags (ValueRank=1)

Closes gap #7. `S7TagDefinition` currently has no array dimension; `MapDataType`
hard-codes `IsArray: false`.

- **Files**: `S7DriverOptions.cs` (extend `S7TagDefinition` with `ArrayDim` int?
  and `ElementCount` int?), `S7Driver.cs` (read path: detect array tag, issue
  one byte-range read covering N elements, slice client-side; write path: same
  in reverse), `DiscoverAsync` reports `IsArray: true, ArrayDim: [N]`.
- **Tests**: unit tests for `Array[0..9] of Int` and `Array[0..9] of Real`;
  Snap7-server profile adds an array seed type. Round-trip array-write test
  proves slice ordering.
- **Risks**: S7-1500 supports multi-dim arrays; declare ValueRank=1 only and
  document multi-dim as a follow-up. Array-of-UDT lands with PR-S7-D2.
- **Effort**: M.
- **Deps**: PR-S7-A1 (byte-range reads).
- **Docs / fixture / e2e**: adds an "Array tags (ValueRank=1)" subsection
  to `docs/v2/s7.md` documenting `Array[0..N]` syntax + the multi-dim
  follow-up note; extends `docs/Driver.S7.Cli.md` with an
  `--array-count N` flag in the `read` / `write` cookbook and worked
  examples for `Array[0..9] of Int` and `Array[0..9] of Real`; updates
  `docs/drivers/S7-Test-Fixture.md` §"What it actually covers" to list
  array round-trips and removes "arrays of structs" from §5 (struct
  arrays land in PR-S7-D2); extends `Docker/server.py` with an `array`
  meta-seed-type that takes an inner-type + count and lays out N elements
  contiguously; seeds `DB1.ArrayInt[300]` (10×Int) and
  `DB1.ArrayReal[320]` (10×Real) in `Docker/profiles/s7_1500.json`;
  adds `Driver_round_trips_array_int10` + `Driver_round_trips_array_real10`
  smoke tests proving slice ordering; adds an array round-trip assertion
  to `scripts/e2e/test-s7.ps1`.

#### PR-S7-A5 — LOGO! 8 + S7-200 V-memory area

Closes gap #19. `S7AddressParser` currently rejects the `V` area letter.

- **Files**: `S7AddressParser.cs` (add `V` case → maps to `S7Area.DataBlock` with
  `DbNumber=1` for S7-200 / DbNumber per LOGO! VM-mapping table; document the
  conversion), `S7DriverOptions.cs` (note CpuType-dependent meaning of V).
- **Tests**: unit tests for `VW0` / `VD4` / `V0.0` parsing, both S7-200 and
  LOGO! conventions; document caller responsibility to set `CpuType.S7200` or
  `S7200Smart`.
- **Risks**: LOGO! VM base address differs by firmware (V0=0 vs V0=1024 depending
  on block); document the offset table rather than auto-detecting.
- **Effort**: S (1-2 days, mostly parser + tests; no wire changes).
- **Deps**: none.
- **Docs / fixture / e2e**: adds a "LOGO! 8 / S7-200 V-memory" subsection
  to `docs/v2/s7.md` covering the `V` area letter, the `S7200` /
  `S7200Smart` CpuType pre-requisite, the LOGO! VM-mapping table by
  firmware band, and the "V0 = DB1.DBX0.0" semantic; extends the address
  grammar cheat sheet in `docs/Driver.S7.Cli.md` with `VW0` / `VD4` /
  `V0.0` rows and a `-c S7200Smart` worked example; updates
  `docs/drivers/S7-Test-Fixture.md` §"What it does NOT cover" item 4 to
  note S7-200 / LOGO! parser coverage now exists at unit level; adds
  unit-only `S7AddressParserTests` cases — no Snap7 fixture change
  (server.py already exposes DB1, which is where V-memory aliases land);
  no `scripts/e2e/test-s7.ps1` change required (live-LOGO! testing is
  documented as field-only).

### Phase 2 — Performance (multi-tag PDU packing + block coalescing)

#### PR-S7-B1 — Multi-variable PDU packing

Closes gap #3. `ReadAsync(IReadOnlyList<string>)` currently issues one
`plc.ReadAsync` per tag inside the semaphore — N PDUs for N tags.

- **Files**: `S7Driver.cs` (replace per-tag loop with a packer that builds a
  list of `S7.Net.Types.DataItem`, calls `plc.ReadMultipleVarsAsync`, then
  fans the results back to the per-tag decoder). Keep the existing per-tag
  decode switch — only the wire fetch becomes batched.
- **Tests**: integration test that subscribes to 100 tags and asserts the
  packet count seen by the Snap7 server is 1 (or N / packing-budget) rather
  than 100. Unit-level test covers packer chunking when the negotiated PDU
  size won't fit all items.
- **Risks**: `ReadMultipleVarsAsync` errors are per-item; we must surface
  per-tag StatusCodes correctly rather than failing the whole batch on one
  bad tag. Packing budget = `negotiatedPduSize - 18 (header) - per_item(12)`,
  conservatively cap at 19 items per PDU on a 240-byte PDU.
- **Effort**: L (5-6 days incl. the per-item-error fan-out semantics).
- **Deps**: Phase 1 PRs do not block this — but conflicts in `S7Driver.cs`
  are likely, so land Phase 1 first.
- **Docs / fixture / e2e**: adds a "Performance — multi-variable PDU
  packing" subsection to `docs/v2/s7.md` describing
  `ReadMultipleVarsAsync`, the negotiated-PDU packing budget formula
  (`pdu - 18 - 12·N`), the 19-items-per-240-byte-PDU rule of thumb, and
  the per-item-error semantics; no `docs/Driver.S7.Cli.md` change (CLI
  is single-tag); no Snap7-server seed change required (existing seeds
  cover the wire path); adds
  `S7MultiVarPduPackingTests` to the unit suite (planner chunking when
  items don't fit) + a 100-tag perf integration test
  `Driver_packs_100_tags_into_minimum_pdus` that asserts request-count
  reduction; no `scripts/e2e/test-s7.ps1` change required.

#### PR-S7-B2 — Block-read coalescing for contiguous DBs

Closes gap #22. Reading `DB1.DBW0`, `DB1.DBW2`, `DB1.DBW4` should issue one
6-byte byte-range read against DB1 starting at offset 0, sliced client-side.

- **Files**: `S7Driver.cs` adds a planner pass: group same-DB tags by
  contiguous byte ranges (gap-merge threshold = configurable, default 16
  bytes; over-fetching 16 bytes is cheaper than one extra PDU). Merged ranges
  become a single `Plc.ReadBytes` call; the result is sliced per-tag.
- **Tests**: unit tests for the merge planner (input list → expected ranges);
  integration test with 50 contiguous DB words proves wire-level reduction.
- **Risks**: STRINGs / arrays should opt out of merging because the per-tag
  byte size is variable. Add an "opaque-size" flag so the planner skips them.
- **Effort**: M.
- **Deps**: PR-S7-B1 (the multi-var packer). The two interact: the planner
  emits sum-reads, then the packer puts multiple sum-reads on one PDU.
- **Docs / fixture / e2e**: extends the §"Performance" section in
  `docs/v2/s7.md` with a "Block-read coalescing" subsection — the
  default 16-byte gap-merge threshold, the opaque-size opt-out for
  STRINGs / arrays, and operator guidance for tuning the threshold per
  DB; no CLI doc change; no Snap7-server seed change (existing
  contiguous DB1 seeds — DBW0 / DBW10 / DBD20 — already exercise
  contiguous-merge); adds
  `S7BlockCoalescingPlannerTests` (unit) covering the merge planner +
  opaque opt-out; adds a 50-contiguous-DBW integration test
  `Driver_coalesces_contiguous_DBWs_into_single_byte_range_read` that
  asserts wire-level reduction; no `scripts/e2e/test-s7.ps1` change.

### Phase 3 — Operability

#### PR-S7-C1 — PDU size negotiation surfaced

Closes gap #2. S7netplus's `Plc` instance exposes the negotiated PDU size after
`OpenAsync` via `Plc.MaxPDUSize`.

- **Files**: `S7Driver.cs` (read `Plc.MaxPDUSize` after open, store on
  `_health`; expose via `GetHealth().Diagnostics["NegotiatedPduSize"]` —
  this requires adding a `Diagnostics` dictionary to `DriverHealth`, which
  is a Core change). Operator-visible via the Admin UI driver-diagnostics
  panel that already renders Modbus diagnostic stats.
- **Tests**: integration test asserts the value is non-zero after init.
- **Risks**: `DriverHealth` extension must be backward-compatible — existing
  drivers should still compile against the unchanged record. Make the new
  property nullable with a default of `null`.
- **Effort**: S.
- **Deps**: Core `DriverHealth` shape change (single PR coordinated with
  the Modbus diagnostic surface).
- **Docs / fixture / e2e**: adds a "Diagnostics surfacing" subsection to
  `docs/v2/s7.md` documenting the `Diagnostics["NegotiatedPduSize"]`
  surface + how it renders in the Admin UI driver-diagnostics panel;
  no CLI doc change (CLI doesn't expose diagnostics); updates
  `docs/drivers/S7-Test-Fixture.md` §"What it actually covers" with a
  "negotiated PDU size surfaces in driver health" line; no Snap7
  seed-type change (snap7's PDU negotiation is fixed at 240 bytes —
  document the fixture's negotiated size in the README); adds
  `Driver_exposes_negotiated_pdu_size_post_init` smoke test asserting
  the value is non-zero; no `scripts/e2e/test-s7.ps1` change.

#### PR-S7-C2 — TSAP / Connection Type selector

Closes gap #4. S7netplus picks PG-class TSAPs by default; hardened CPUs may
require OP / S7-Basic / Other.

- **Files**: `S7DriverOptions.cs` (new `TsapMode` enum: `Auto` / `Pg` / `Op` /
  `S7Basic` / `Other`; `Auto` preserves current behavior. Optional
  `LocalTsap` / `RemoteTsap` `ushort?` for explicit override). `S7Driver.cs`
  branches on the mode to pick the S7netplus `Plc(CpuType, ...)` constructor
  vs the `Plc(string ip, byte rack, byte slot, ushort localTsap, ushort remoteTsap)`
  raw-TSAP overload. Document the raw-TSAP table in `docs/v2/s7.md`.
- **Tests**: unit test on the mode → TSAP-byte mapping; live-firmware test
  documented but only runnable against the dev-box S7-1500 lab rig.
- **Risks**: wrong TSAP causes connection refused at handshake — same failure
  shape as wrong slot. Document the mapping prominently.
- **Effort**: M.
- **Deps**: none.
- **Docs / fixture / e2e**: adds a "TSAP / Connection Type" section to
  `docs/v2/s7.md` covering the `TsapMode` enum, the raw-TSAP table
  (PG = 0x0100/0x0102, OP = 0x0200/0x0202, S7-Basic = 0x0300/0x0302,
  Other = caller-supplied), and the hardened-CPU motivation; adds
  `--tsap-mode` and `--local-tsap` / `--remote-tsap` flags to
  `docs/Driver.S7.Cli.md`'s common-flags table with a worked example
  hitting an OP-class TSAP; no Snap7 seed change (snap7 accepts any
  TSAP from the CLI, so the unit-level mapping test is sufficient); no
  smoke test change (live-firmware-only); no `scripts/e2e/test-s7.ps1`
  change.

#### PR-S7-C3 — Per-tag scan group / publish rate

Closes gap #20. `SubscribeAsync` takes one publishing interval for the whole
list; mixed 100 ms / 1 s / 10 s tags need three subscribe calls today.

- **Files**: `S7DriverOptions.cs` (extend `S7TagDefinition` with optional
  `ScanGroup` string). `S7Driver.cs` (`SubscribeAsync` partitions the input
  list into one poll loop per distinct interval; `PollGroupEngine`-style
  internal group, but driver-local — same engine the TwinCAT driver uses).
- **Tests**: unit test with three tags at three rates asserts three independent
  poll-tick streams; integration test asserts no group starves the others.
- **Risks**: the `_gate` semaphore still serializes — three poll loops can
  contend. Document the contention as part of the "1 connection / 1 mailbox"
  invariant; if it bites, follow-up adds a fairness queue.
- **Effort**: M.
- **Deps**: none.
- **Docs / fixture / e2e**: adds a "Per-tag scan groups" subsection to
  `docs/v2/s7.md` documenting `S7TagDefinition.ScanGroup`, the multi-rate
  partitioning semantics, and the `_gate` contention caveat; no CLI doc
  change (CLI is single-tag); no Snap7 seed change required (existing
  scalar seeds suffice); adds `S7ScanGroupPartitioningTests` (unit) +
  `Driver_three_scan_groups_publish_independently` smoke test that
  subscribes 3 tags at 100 ms / 1 s / 10 s rates and asserts
  independent tick streams; no `scripts/e2e/test-s7.ps1` change
  (subscribe assertion already covers the polling path).

#### PR-S7-C4 — Deadband / on-change with thresholds

Closes gap #21. `PollOnceAsync` currently does `!Equals(prev, current)` only —
no analog deadband.

- **Files**: `S7DriverOptions.cs` (extend `S7TagDefinition` with
  `DeadbandAbsolute double?` and `DeadbandPercent double?`). `S7Driver.cs`
  (`PollOnceAsync` evaluates per-tag deadband for numeric types; non-numeric
  types fall through to exact equality).
- **Tests**: unit tests for absolute and percent deadbands at edge cases
  (NaN, ±Infinity, sign flip, near-zero percent).
- **Risks**: percent deadband against a zero baseline diverges; document and
  fall back to absolute when |baseline| < 1e-6.
- **Effort**: S.
- **Deps**: PR-S7-C3 helpful but not required.
- **Docs / fixture / e2e**: adds a "Deadband / on-change" subsection to
  `docs/v2/s7.md` documenting `DeadbandAbsolute` / `DeadbandPercent` per
  tag, NaN / ±Infinity / sign-flip / near-zero-percent edge cases, and
  the |baseline| < 1e-6 fallback; no CLI doc change (CLI's `subscribe`
  already polls on change); no Snap7 seed change; adds
  `S7DeadbandTests` (unit) covering all edge cases — no integration test
  required since deadband is pre-publish filtering inside the polling
  loop; no `scripts/e2e/test-s7.ps1` change.

#### PR-S7-C5 — Pre-flight PUT/GET enablement test

Closes gap #24. We currently surface `BadDeviceFailure` only at first read.
Add a pre-flight check during `InitializeAsync` (after `OpenAsync`) that issues
one trivial read (`MW0` or the configured `Probe.ProbeAddress`) and surfaces
the dedicated diagnostic message before declaring `DriverState.Healthy`.

- **Files**: `S7Driver.cs` (`InitializeAsync` adds the probe read; on
  `S7.Net.PlcException` with the PUT/GET-disabled error code, throw a
  typed `S7PutGetDisabledException` with a configuration-fix hint).
- **Tests**: integration test toggles a Snap7 simulator quirk that mimics
  the PUT/GET-disabled response (Snap7 doesn't model this; gate the test
  on a `--with-real-plc` opt-in or document as live-firmware-only).
- **Risks**: pre-flight against a real `Probe.ProbeAddress` requires the
  address to exist in the PLC; document that the default `MW0` is fine for
  most installs but allow `null` / "skip" for sites that haven't wired one.
- **Effort**: S.
- **Deps**: none.
- **Docs / fixture / e2e**: extends the "PUT/GET must be enabled" section
  of `docs/Driver.S7.Cli.md` with the new typed
  `S7PutGetDisabledException` message + the "skip pre-flight" knob;
  adds the same content as a "Pre-flight PUT/GET enablement" subsection
  in `docs/v2/s7.md`; no Snap7 seed change (snap7 doesn't model
  PUT/GET-disabled — the test for the success path uses the existing
  MW0 seed); adds `Driver_preflight_passes_when_probe_address_seeded`
  smoke test; documents the live-firmware test as gated on a
  `--with-real-plc` opt-in flag in `docs/drivers/S7-Test-Fixture.md`
  §"Follow-up candidates"; no `scripts/e2e/test-s7.ps1` change (probe
  test already runs first).

### Phase 4 — Workflow (symbol import + UDTs + instance DBs)

#### PR-S7-D1 — Symbol-table / TIA Portal export browse

Closes gap #5. Operators currently hand-edit `S7TagDefinition` JSON. TIA Portal
exports symbols as **`.s7p` archive → External tags → CSV / SDF**. The lighter
target is the CSV format used by the "Generate source from blocks" exporter.

- **Files**: new `src/ZB.MOM.WW.OtOpcUa.Driver.S7/SymbolImport/` directory:
  - `TiaCsvImporter.cs` — parses TIA Portal "Show all tags" CSV (`Name`,
    `Address`, `Data type`, `Comment`, `Visible in HMI`). Output: list of
    `S7TagDefinition`.
  - `AwlImporter.cs` — best-effort AWL `VAR_GLOBAL` / `DATA_BLOCK` parser
    for legacy STEP 7 Classic projects.
- **Files (Admin UI)**: a "Import S7 symbols" button on the Driver Tags tab
  that POSTs the file to a new `POST /api/drivers/{id}/import-s7-symbols`
  endpoint and reports the diff.
- **Tests**: unit tests with golden-input CSV / AWL fixtures; round-trip
  test that imports → produces tags → reads against simulator.
- **Risks**: TIA Portal CSV is locale-dependent (decimal-comma in DE locale).
  Detect from the header row and accept both. UDT-typed symbols import as
  a placeholder until PR-S7-D2.
- **Effort**: L (5-7 days incl. the Admin UI flow).
- **Deps**: see Open Question (c) — confirm CSV+AWL is the right scope, or
  whether `.s7p` / `.zip` archive parsing is required.
- **Docs / fixture / e2e**: adds new doc
  `docs/drivers/S7-TIA-Import.md` documenting the supported TIA Portal
  CSV format (column names, locale-comma detection, UDT-typed
  placeholders) and the AWL `VAR_GLOBAL` / `DATA_BLOCK` parser scope;
  cross-links it from `docs/v2/s7.md`'s new "Symbol import" section
  and from `docs/Driver.S7.Cli.md` with a future `import` subcommand
  hook; adds golden-input fixtures
  `tests/ZB.MOM.WW.OtOpcUa.Driver.S7.IntegrationTests/Fixtures/sample_tia_export.csv`,
  `sample_tia_export_de_locale.csv`, and `sample_step7_classic.awl`;
  no Snap7 seed change required (existing DB1 seeds support
  the import-then-read round-trip); adds `TiaCsvImporterTests` and
  `AwlImporterTests` (unit) + `Driver_imports_csv_then_reads_seeded_tags`
  integration test that imports the sample CSV → reads via Snap7;
  no `scripts/e2e/test-s7.ps1` change (Admin-UI flow has its own
  end-to-end coverage in the Admin UI test suite).

#### PR-S7-D2 — UDT / STRUCT / nested-DB handling

Closes gap #6. Today's tag map is flat scalar-only; UDT-typed DBs are
unusable without hand-flattening every member.

- **Files**: `S7DriverOptions.cs` (extend `S7TagDefinition` with `UdtName string?`;
  alongside, a new `IReadOnlyList<S7UdtDefinition> Udts` on the options that
  declares the layout: name, ordered members `(Name, Offset, S7DataType, ArrayDim?)`).
  `S7Driver.cs` fans a UDT-typed tag into per-member sub-tags at `InitializeAsync`,
  so the read/write path stays scalar-only.
- **Tests**: unit tests for fan-out with nested UDTs (UDT-of-UDT); integration
  test with a Snap7 DB seeded as a UDT-shape byte array proves the fan-out
  decodes correctly.
- **Risks**: UDT-of-UDT arbitrary nesting depth — cap at 4 levels and reject
  deeper with a clear error. Optimized DBs would let TIA reorder members,
  re-introducing gap #1; document that user-defined UDTs require "Optimized
  block access" off, same as the general DB rule.
- **Effort**: L (1-2 weeks).
- **Deps**: PR-S7-D1 (symbol importer drops UDT-typed entries with a
  placeholder; D2 makes those usable).
- **Docs / fixture / e2e**: adds a "UDT / STRUCT support" section to
  `docs/v2/s7.md` documenting `S7UdtDefinition`, the fan-out
  semantics, the 4-level nesting cap, and the "Optimized block access
  must be off" prerequisite; extends `docs/drivers/S7-TIA-Import.md`
  (created in PR-S7-D1) with a UDT-typed-entry section showing how
  the importer + `Udts` declaration cooperate; updates
  `docs/drivers/S7-Test-Fixture.md` §"What it does NOT cover" item 5 to
  remove "UDT fan-out"; extends `Docker/server.py` with a
  `udt_layout` meta-seed-type that lays out per-member offsets within
  a DB byte range; seeds a `DB1.MyUdt[400]` (e.g. Real + Int + Bool)
  in `Docker/profiles/s7_1500.json`; adds `S7UdtFanOutTests` (unit) +
  `Driver_fans_out_udt_into_member_tags` integration test covering a
  nested-UDT case; adds a UDT-member round-trip assertion to
  `scripts/e2e/test-s7.ps1`.

#### PR-S7-D3 — Instance-DB / FB parameter access

Closes gap #10. Multi-instance FBs are addressed symbolically (`MyFB_Instance.MyParam`)
with no fixed absolute DB byte offset visible without a TIA project export.

- **Files**: extends PR-S7-D1's importer to recognize "instance DB" entries
  (TIA export shows them with a different "DB type" column value); the
  importer translates `MyFB_Instance.MyParam` to the resolved
  `DBn.DBW_offset` based on the FB's interface declaration in the export.
- **Tests**: golden-input test with an FB-instance DB export; resolved
  addresses match Siemens reference.
- **Risks**: when the FB interface changes (TIA "online change"), instance-DB
  layouts shift. Document that re-import is required after any FB-interface
  edit. Eventually surface this as a startup warning when the symbol-table
  hash differs from the imported snapshot — out of scope for this PR.
- **Effort**: M.
- **Deps**: PR-S7-D1, PR-S7-D2.
- **Docs / fixture / e2e**: extends `docs/drivers/S7-TIA-Import.md` with
  an "Instance DBs / FB parameters" section covering the importer's
  `MyFB_Instance.MyParam` → `DBn.DBW_offset` resolution, the "DB type"
  column convention, and the "re-import on FB-interface edit" caveat;
  adds the same caveat as a paragraph in `docs/v2/s7.md`'s "UDT /
  STRUCT" section; adds a golden-input fixture
  `Fixtures/sample_tia_export_with_fb_instance.csv` to the integration
  tests; no Snap7 seed change required (resolved addresses land in DB1
  which the existing seeds back); adds
  `InstanceDbResolverTests` (unit) +
  `Driver_resolves_fb_instance_then_reads_seeded_member` integration
  test; no `scripts/e2e/test-s7.ps1` change (FB-instance lookup is an
  import-time concern).

### Phase 5 — Diagnostics & security

#### PR-S7-E1 — CPU diagnostic buffer / SZL reads

Closes gap #11. SZL (System Status List) IDs surface CPU type, firmware
version, cycle-time min/avg/max, and the diagnostic-buffer entries.

- **Files**: `S7Driver.cs` exposes a small set of "system tags" alongside
  `Tags` — virtual addresses prefixed `@System.` that the read path
  recognizes and dispatches to S7netplus's `ReadSzlAsync` (or, if not
  exposed, a raw `Plc.ReadBytes` against the SZL-via-S7comm sub-protocol):
  - `@System.CpuType`, `@System.Firmware`, `@System.OrderNo` — SZL 0x0011
  - `@System.CycleMs.Min` / `.Max` / `.Avg` — SZL 0x0132 / 0x0432
  - `@System.DiagBuffer[0..N]` — SZL 0x00A0 ring-buffer entries
- **Files (discovery)**: `DiscoverAsync` adds a `Diagnostics/` subfolder
  with the system-tag set when `S7DriverOptions.ExposeSystemTags = true`.
- **Tests**: unit tests for the SZL response parser (golden bytes); live-
  firmware test against the dev-box S7-1500.
- **Risks**: S7netplus's SZL surface is incomplete; may need a raw
  `Plc.ReadBytes` against `0x84` register or a small SZL-PDU helper.
- **Effort**: M-L.
- **Deps**: PR-S7-C1 (`DriverHealth.Diagnostics` dictionary already there).
- **Docs / fixture / e2e**: adds a "CPU diagnostics (SZL)" section to
  `docs/v2/s7.md` listing the exposed `@System.*` virtual addresses, the
  underlying SZL IDs, and the `ExposeSystemTags` opt-in; extends
  `docs/Driver.S7.Cli.md` with a worked `read -a @System.CpuType` example
  in the cookbook; updates `docs/drivers/S7-Test-Fixture.md` §"What it
  does NOT cover" with a note that snap7 does not implement SZL — golden-
  byte unit tests cover the parser, live SZL is gated on a real S7-1500;
  no Snap7 seed change (snap7 returns a fixed handshake banner that the
  test checks for "SZL not supported on simulator" branch); adds
  `S7SzlParserTests` (unit) with golden bytes; documents the live SZL
  test in `docs/drivers/S7-Test-Fixture.md` §"Follow-up candidates"; no
  `scripts/e2e/test-s7.ps1` change.

#### PR-S7-E2 — PLC password / protection-level handling

Closes gap #14. S7-300/400 protection levels 1-3 and S7-1200/1500 connection
mechanisms can require a password on connect.

- **Files**: `S7DriverOptions.cs` (new `Password string?` and `ProtectionLevel`
  enum). `S7Driver.cs` calls S7netplus's `SetPassword` (if the API surfaces it
  — newer S7netplus versions ship `Plc.SendPassword(string)`; if not, raw-PDU
  fallback per Siemens "Communication Function Manual" §5.2).
- **Tests**: live-firmware-gated; password-tier failure modes don't reproduce
  in Snap7. Unit-level coverage for the options-binding shape only.
- **Risks**: S7netplus may not expose password auth — fallback is to call into
  the lower-level `S7.Net.S7Protocol` types or to fork. Land the options
  surface unconditionally, gate the wire path on library support, document
  the limitation if the library doesn't oblige.
- **Effort**: M (S if S7netplus ships it; L if we need a fallback path).
- **Deps**: none.
- **Docs / fixture / e2e**: adds a "PLC password / protection levels"
  section to `docs/v2/s7.md` documenting the `Password` /
  `ProtectionLevel` options + the S7-300/400 levels 1-3 vs S7-1200/1500
  connection-mechanism semantics + the "limitation if S7netplus
  doesn't ship `SendPassword`" note; adds a `--password` flag to
  `docs/Driver.S7.Cli.md`'s common-flags table with a hardened-CPU
  worked example; updates `docs/drivers/S7-Test-Fixture.md` §"What it
  does NOT cover" with a "password / protection levels not modelled by
  snap7" note; no Snap7 seed change (snap7 doesn't enforce protection
  levels); adds options-binding unit tests only — no integration test
  (live-firmware-only); no `scripts/e2e/test-s7.ps1` change.

### Phase 6 — S7-1500 Optimized DB / Symbolic addressing (decision PR)

#### PR-S7-F — Optimized DB / S7Plus

Closes gap #1. **This is an architectural decision PR, not a code PR.**

S7netplus speaks classic S7comm only. Optimized DBs on S7-1500 (default for
new TIA projects) reorder fields and have no fixed byte offsets — absolute
`DB1.DBW0` reads return `BadDeviceFailure`. Three tracks:

1. **Document the constraint and stay on S7netplus.** Operators must uncheck
   "Optimized block access" in TIA Portal for any DB the driver reads. This
   is what the test fixture already documents. Effort: S (docs only).
2. **Migrate to a library that supports S7Plus.**
   - **Snap7 v2 / `Snap7Net`** — C-library wrapper, supports classic S7comm
     only (same limitation as S7netplus). Not a fix.
   - **Sharp7 fork** — community fork of Snap7 with **partial** S7-1200/1500
     PUT/GET semantics. Still classic S7comm.
   - **Custom S7Plus implementation** — Wireshark dissector exists; reverse
     engineering is substantial. Effort: ≥ 4 weeks; ongoing protocol-version
     maintenance. Risk: Siemens has not published S7Plus.
3. **Embed an OPC UA → OPC UA bridge to the S7-1500's onboard OPC UA server.**
   The S7-1500 V2.5+ exposes its own OPC UA server with full symbolic access.
   Our `OPC UA Client driver` (already shipping per memory) could read the
   target CPU's OPC UA server and re-publish — sidesteps S7Plus entirely.
   Effort: S; semantics: requires the customer to license Siemens OPC UA
   on the CPU. Most modern S7-1500 deployments already license it.

**Recommendation**: ship Track 1 docs immediately (closes the operator
expectation gap) and Track 3 as the Optimized-DB workflow path (re-uses
existing OPC UA Client driver). Track 2 (S7Plus reverse-engineering) is
out of scope unless a customer pays for it.

- **Files**: `docs/v2/s7.md` (Optimized DB section + how to disable),
  `docs/featuregaps.md` row #1 updated to reflect the Track 1+3 decision.
- **Tests**: live-firmware test against the dev-box S7-1500 with optimized
  block access toggled both ways, asserting `BadDeviceFailure` vs
  successful read.
- **Risks**: Track 3's OPC-UA-Client-bridging needs Admin UI plumbing to
  configure; that's a larger workstream tracked separately.
- **Effort**: S (docs + decision); L if Track 2 is taken.
- **Deps**: Open Question (a) below.
- **Docs / fixture / e2e**: rewrites `docs/v2/s7.md` to land a
  prominent "Optimized DB constraint" section at the top — explicitly
  documents the S7-1200 V4.0+ / S7-1500 default, the
  `BadDeviceFailure` shape on absolute `DB1.DBW0` reads against an
  optimized DB, the "Uncheck Optimized block access in TIA Portal"
  fix, and the recommended **bridge-via-OpcUaClient** pattern with a
  worked example (Siemens S7-1500 V2.5+ onboard OPC UA server →
  `OpcUaClient` driver → re-publish on the OtOpcUa server's address
  space); updates `docs/featuregaps.md` row #1 to reflect the
  Track 1+3 decision; updates the "Optimized-DB" line of
  `docs/drivers/S7-Test-Fixture.md` §"What it does NOT cover" item 4
  to point at the new doc; no CLI doc change (CLI is a probe tool, not
  the bridging path); no Snap7 fixture change (snap7 has no Optimized-
  DB mode); the live-firmware test toggling Optimized block access on
  / off is recorded as a manual checklist in
  `docs/drivers/S7-Test-Fixture.md` §"Follow-up candidates" and gated
  behind `--with-real-plc`; if Track 2 is taken later, this PR's doc
  surface becomes the migration baseline; no `scripts/e2e/test-s7.ps1`
  change.

---

## Documentation, fixture, and e2e impact

Consolidated view of every per-PR `Docs / fixture / e2e` line above, so a
reviewer can see the cross-cutting churn at a glance and so the doc /
fixture / e2e maintainers can sequence their work alongside the code PRs.

### User-facing documentation churn

| PR | `docs/v2/s7.md` | `docs/Driver.S7.Cli.md` | `docs/drivers/S7-Test-Fixture.md` | New / cross-cut docs |
|----|-----------------|-------------------------|------------------------------------|----------------------|
| PR-S7-A1 (LInt/ULInt/LReal/LWord) | extend type-mapping table | new sizes in cookbook | remove "no 64-bit types" | — |
| PR-S7-A2 (STRING/WSTRING/CHAR/WCHAR) | string layout subsection | `--type WString` / `--string-length` | list new types | — |
| PR-S7-A3 (DTL/DT/S5TIME/TIME/TOD/DATE) | "Date / time types" subsection | datetime cookbook entries | list new types | — |
| PR-S7-A4 (arrays) | "Array tags (ValueRank=1)" subsection | `--array-count` flag + examples | list array round-trips | — |
| PR-S7-A5 (V-memory) | "LOGO! 8 / S7-200 V-memory" subsection | grammar table + S7200Smart example | parser coverage note | — |
| PR-S7-B1 (PDU packing) | "Performance — multi-variable PDU packing" subsection | — | — | — |
| PR-S7-B2 (block coalescing) | "Block-read coalescing" subsection | — | — | — |
| PR-S7-C1 (negotiated PDU diag) | "Diagnostics surfacing" subsection | — | "negotiated PDU size" line | — |
| PR-S7-C2 (TSAP) | "TSAP / Connection Type" section | `--tsap-mode` / `--local-tsap` / `--remote-tsap` flags | — | — |
| PR-S7-C3 (scan groups) | "Per-tag scan groups" subsection | — | — | — |
| PR-S7-C4 (deadband) | "Deadband / on-change" subsection | — | — | — |
| PR-S7-C5 (PUT/GET pre-flight) | "Pre-flight PUT/GET enablement" subsection | extend "PUT/GET must be enabled" | mark live-firmware test | — |
| PR-S7-D1 (TIA CSV / AWL import) | "Symbol import" cross-link | future `import` subcommand stub | — | **new `docs/drivers/S7-TIA-Import.md`** |
| PR-S7-D2 (UDT / STRUCT) | "UDT / STRUCT support" section | — | remove "UDT fan-out" | extend `S7-TIA-Import.md` |
| PR-S7-D3 (instance DB) | re-import-on-FB-edit caveat | — | — | extend `S7-TIA-Import.md` |
| PR-S7-E1 (SZL diagnostics) | "CPU diagnostics (SZL)" section | `read -a @System.CpuType` example | "SZL not modelled by snap7" + Follow-up | — |
| PR-S7-E2 (PLC password) | "PLC password / protection levels" section | `--password` flag | "password not modelled by snap7" | — |
| PR-S7-F (Optimized DB / S7Plus) | top-level "Optimized DB constraint" + bridge-via-OpcUaClient worked example | — | point §"What it does NOT cover" at new doc | also updates `docs/featuregaps.md` row #1 |

### Snap7-server fixture seed-type additions per PR

The snap7 simulator at `localhost:1102` (driven by
`tests/ZB.MOM.WW.OtOpcUa.Driver.S7.IntegrationTests/Docker/server.py` +
`Docker/profiles/s7_1500.json`) has a `seed_buffer` pump with a fixed type
set — `u8 / i8 / u16 / i16 / u32 / i32 / f32 / bool / ascii`. New PRs need
new seed-type cases in `server.py`, new offsets in `s7_1500.json`, and
matching constants in `S7_1500Profile.cs`. The table below names the
delta for each Build-Yes PR:

| PR | New `server.py` seed types | New `s7_1500.json` seed offsets | `S7_1500Profile.cs` additions |
|----|----------------------------|----------------------------------|-------------------------------|
| PR-S7-A1 | `i64`, `u64`, `f64` | `DB1.DBL40` (i64), `DB1.DBL48` (f64), `DB1.DBL56` (u64) | `SmokeI64Tag` / `SmokeU64Tag` / `SmokeF64Tag` |
| PR-S7-A2 | `wstring`, `char`, `wchar` (existing `ascii` covers STRING) | `DB1.WSTRING[256]`, `DB1.CHAR[300]` | `SmokeWStringTag` / `SmokeCharTag` |
| PR-S7-A3 | `dtl`, `dt`, `s5time`, `time`, `tod`, `date` (golden-byte vectors in comments) | `DB1.DTL[260]`, `DB1.DT[272]`, `DB1.S5TIME[280]`, `DB1.TIME[284]`, `DB1.TOD[288]`, `DB1.DATE[292]` | `SmokeDtl` / `SmokeDt` / `SmokeS5Time` / `SmokeTime` / `SmokeTod` / `SmokeDate` |
| PR-S7-A4 | `array` meta-seed (inner-type + count) | `DB1.ArrayInt[300]` 10×Int, `DB1.ArrayReal[320]` 10×Real | `ArrayInt10Tag` / `ArrayReal10Tag` |
| PR-S7-A5 | none (V-memory aliases land in DB1, which `server.py` already exposes) | none | unit-only — no profile change |
| PR-S7-B1 | none | none (existing scalar seeds suffice for packing) | none — perf integration test reuses scalar tags |
| PR-S7-B2 | none | none (existing contiguous DBW0 / DBW10 / DBD20 already test merge) | none |
| PR-S7-C1 | none | none | none |
| PR-S7-C2 | none (snap7 accepts any TSAP) | none | none |
| PR-S7-C3 | none | none | none |
| PR-S7-C4 | none | none | none |
| PR-S7-C5 | none (existing `MK0` MW0 seed covers success path) | none | none |
| PR-S7-D1 | none (CSV import lands tags pointing at existing seeds) | none | possibly add fixture-pointer constants |
| PR-S7-D2 | `udt_layout` meta-seed (per-member offsets) | `DB1.MyUdt[400]` (Real + Int + Bool layout) | `MyUdtTag` + member tags |
| PR-S7-D3 | none (resolved addresses land in DB1) | none | none |
| PR-S7-E1 | none — snap7 doesn't model SZL; unit-level golden bytes cover the parser | none | none |
| PR-S7-E2 | none — snap7 doesn't enforce protection levels; options-binding unit tests only | none | none |
| PR-S7-F | none — snap7 has no Optimized-DB mode; live-firmware checklist instead | none | none |

### E2E `scripts/e2e/test-s7.ps1` impact

`scripts/e2e/test-s7.ps1` runs the five-assertion CLI loopback (probe /
driver-loopback / forward-bridge / reverse-bridge / subscribe-sees-change)
against `DB1.DBW0` Int16. Build-Yes PRs that add CLI surface get a
matching loopback assertion; PRs that touch only internals or admin-UI
flows do not.

| PR | E2E script change |
|----|-------------------|
| PR-S7-A1 | add LInt loopback assertion (write 0x7FFFFFFFFFFFFFFF, read back) |
| PR-S7-A2 | add string round-trip assertion |
| PR-S7-A3 | none (CLI cookbook covers manual surface) |
| PR-S7-A4 | add array round-trip assertion |
| PR-S7-A5 | none (live-LOGO! field-only) |
| PR-S7-B1 | none |
| PR-S7-B2 | none |
| PR-S7-C1 | none |
| PR-S7-C2 | none (live-firmware-only) |
| PR-S7-C3 | none (subscribe assertion already covers polling) |
| PR-S7-C4 | none |
| PR-S7-C5 | none (probe runs first today) |
| PR-S7-D1 | none (Admin UI has its own e2e) |
| PR-S7-D2 | add UDT-member round-trip assertion |
| PR-S7-D3 | none (import-time concern) |
| PR-S7-E1 | none |
| PR-S7-E2 | none (live-firmware-only) |
| PR-S7-F | none (decision PR; live-firmware checklist instead) |

---

## Skip-rated items (for context)

| # | Gap | Skip rationale |
|---|-----|---------------|
| 12 | AS-Alarms / Alarm_S / ProDiag | Alarms are a separate workstream; no `IAlarmSource` shipped on this driver yet, and the gap analysis flags it as a deferred topic. |
| 13 | CPU Run / Stop control / block download | Security and safety risk. PG-class writes that change CPU state are explicitly out of scope. |
| 15 | S7-1500 Secure Communication / TLS | Significant work; S7netplus has no TLS surface. Reconsider when S7Plus track is taken. |
| 16 | S7-400H redundant H-system support | Rare in our deployment scope. Server-level redundancy (`docs/Redundancy.md`) covers the OPC UA layer; H-system driver-level failover is a separate axis. |
| 17 | Multi-CPU rack parallel sessions | One session per CPU works for the deployments we target; multi-CPU racks are an S7-400 niche. |
| 18 | MPI / Profibus / RFC1006-routed transports | Declining use; brownfield only. S7netplus is Ethernet-only. |
| 23 | Connection-resource budget / parallel jobs | One connection works; premature optimization until a deployment hits the cap. |

---

## Open questions

### (a) Library choice for S7Plus

PR-S7-F gates on this decision. Options:

1. **Stay on S7netplus + document Optimized-DB constraint** (preferred default).
2. **Fork to Sharp7 / Snap7 v2** — does *not* solve the S7Plus / Optimized-DB
   problem; both are classic S7comm only. Adopting them buys nothing for this
   gap. Reject unless we want it for unrelated reasons.
3. **Custom S7Plus client over Wireshark-dissected protocol** — large effort,
   ongoing maintenance risk. Only if a customer is paying.
4. **OPC UA → OPC UA bridge via existing OPC UA Client driver** — sidesteps
   S7Plus by re-using Siemens's onboard OPC UA server. Recommended secondary
   track.

Decision needed before Phase 6 PR-S7-F kicks off.

### (b) `WriteIdempotent` semantics for new types

The `WriteIdempotent` per-tag flag (decisions #44, #45, #143) governs replay-
safe writes. New types from Phase 1:

- **STRING / WSTRING** — typically idempotent (recipe / message text).
  Replay-safe by default? **Need confirmation.** Risk: PLC programs that
  treat a new string write as a "new message" event would double-fire.
- **DTL / DT** — usually written from a clock master; replay-safe.
- **Arrays of UDT** — depends on the UDT semantics (recipe = safe, command
  block = unsafe). Inherit `WriteIdempotent` from the parent tag, do not
  add a per-member flag.
- **64-bit types** — same rule as 32-bit equivalents.

Default: keep `WriteIdempotent = false` for everything. Operators flip per
tag based on PLC program semantics. **No semantic extension needed**, but
document the per-type guidance in `docs/v2/s7.md`.

### (c) Symbol-import file format(s)

PR-S7-D1 ships an importer. Which formats?

- **TIA Portal CSV** (Show all tags / Export) — preferred entry point;
  most common. **Confirm.**
- **TIA Portal SDF / Excel** — same data; harder to parse. Skip unless
  customer demand emerges.
- **STEP 7 Classic AWL / SCL `.AWL`** — secondary. Useful for legacy
  S7-300/400 sites still on Classic. **Include in D1?**
- **`.s7p` / `.zap` project archive** — full TIA project. ZIP-shaped;
  symbol export would require unpacking and parsing internal XML. Large
  scope. **Defer.**
- **`.udt` / `.SDF` external tag library** — niche; defer unless asked.

Recommendation: PR-S7-D1 ships **TIA CSV** + **AWL** only. Anything else is
a follow-up. Decision needed before Phase 4 work begins.