📝 Documenation

docs/protocol/known-operations.md

@@ -0,0 +1,165 @@
+# AquaCom known operations registry
+
+**Source of all evidence:** *Technical description – AquaCom – RTU level*, Rev 1.6, ITT Flygt AB, July 2004 (`AquaCom_RTU_1_6_eng.pdf`; markdown conversion in this folder). Section references below are to that document.
+
+**Purpose.** Registers every AquaCom operation the gateway may implement, with its evidence and implementation status. An operation enters this registry *before* implementation begins; adding an operation with status beyond `REGISTERED` requires its evidence to be complete and its gaps resolved or scoped. Open questions live in `protocol-gaps.md` — this registry never invents behavior not stated in the source.
+
+**Status values:** `REGISTERED` (evidence located, not yet implemented) · `PARTIAL` (framework-level support only) · `IMPLEMENTED` (codec + tests + traceability) · `OUT-OF-SCOPE` (deliberately not implemented in the initial release; evidence retained for future phases).
+
+**Framing note (applies to every operation):** CS→RTU telegrams are `SOH + SPACE + DEST + SPACE + TYPE + SPACE + DATA… + SPACE + '#' + SPACE + CHK + CR`; RTU→CS telegrams are `STX + SPACE + DATA… + SPACE + '#' + SPACE + CHK + CR` (§2.3.2). Checksum per §2.4; `Wait` (DC3) bytes are stripped before parsing and excluded from the checksum (§3.6.4).
+
+---
+
+## Session / control operations
+
+### OPS-001 — Connection message (`OK`)
+
+| Field | Content |
+|---|---|
+| Direction | RTU→CS (CS dialled) · CS→RTU (RTU dialled in alarm) |
+| Purpose | Dialled-line connection answer; the answering side sends OK before conversation begins. The answering phase is "6×OK with 2.5s delay between each, aborted as soon as a telegram arrives"; some RTUs send 2×OK ≈4s apart instead (§2.2.3, §3.3.1). |
+| Evidence | §2.2.3, §3.3.1, examples §3.4.1.2, §3.4.5.3, §3.4.7.2, §3.4.9.2, §3.4.10.3, §3.4.11.3, §3.4.12.2 |
+| Gaps | — |
+| Status | REGISTERED (dialled lines only; not applicable to fixed/TCP operation) |
+
+### OPS-002 — Break (`BRK`)
+
+| Field | Content |
+|---|---|
+| Direction | CS→RTU |
+| Purpose | End communication. No answer is returned. Send 3× in a row before hanging up. Mandatory after a WGS containing a control command — some RTUs stay "remote controlled" until BRK (§3.4.13). |
+| Evidence | §3.4.13 |
+| Gaps | — |
+| Status | REGISTERED (required for session teardown; harmless on fixed lines) |
+
+### OPS-003 — Break with acknowledge (`EBR`)
+
+| Field | Content |
+|---|---|
+| Direction | CS→RTU |
+| Purpose | BRK variant expecting a `SCO` answer; retransmit up to 6 times on timeout or wrong answer. Not supported in Forth RTUs (§3.5.4, §3.2 summary table). |
+| Evidence | §3.5.4 |
+| Gaps | — |
+| Status | REGISTERED (Basic RTUs only) |
+
+### OPS-004 — Caller identification (dialled lines)
+
+| Field | Content |
+|---|---|
+| Direction | RTU→CS |
+| Purpose | Identifies the calling RTU (`STX DEST ACT # CHK CR`); capability-dependent (§2.2.3.2). |
+| Evidence | §2.2.3.2–3 |
+| Gaps | AQ-GAP-008 (ACT values unknown) |
+| Status | REGISTERED — blocked by AQ-GAP-008 |
+
+---
+
+## Live-data operations
+
+### OPS-005 — Status request (`WGS`)
+
+| Field | Content |
+|---|---|
+| Direction | CS→RTU, answer RTU→CS |
+| Purpose | Live-values polling. Answer: `ver, prod, Nal, alp, rem, r1–r4, mp1–mpN` (measuring points for the requested picture), followed by `Nal` alarm codes (§3.4.10). This is the protocol's primary live-acquisition operation. |
+| Evidence | §3.4.10, examples §3.4.10.2–3, §2.2.3.1, §3.6.4; CFG picture/command sections §3.4.10.4–5 |
+| Gaps | AQ-GAP-002 (alp semantics; hypothesis `mp count = alp−1` consistent with all four examples), AQ-GAP-005 (long-example checksums pending PDF transcription) |
+| Status | REGISTERED (live acquisition is core scope; see `software-specification.md` §11) |
+
+The `dir` field (F/B/N/M/!) is machine **control** — excluded from the initial release (`software-specification.md` §3.2); the decoder shall tolerate its syntax, and the gateway shall always transmit `!` (ignore).
+
+### OPS-006 — Alarm request (`WCA`) and answers `ALR`/`ALN`/`ALO`
+
+| Field | Content |
+|---|---|
+| Direction | CS→RTU (`WCA`, `ALO`), RTU→CS (`ALR`, `ALN`) |
+| Purpose | Alarm polling/acknowledgement; `set=2` sets the RTU clock from the request's date/time (§3.4.1). Alarm retrieval is extension scope but the evidence now exists. |
+| Evidence | §3.4.1, §2.2.3.3, §3.5.1.1 (Basic ALR variant) |
+| Gaps | AQ-GAP-010 |
+| Status | REGISTERED — alarm retrieval is OUT-OF-SCOPE for the initial release; clock setting (`set=2`) also OUT-OF-SCOPE (audit + confirmation architecture required first, cf. implementation specification §76) |
+
+---
+
+## Historical-data operations
+
+### OPS-007 — Historical trend (`WGH`)
+
+| Field | Content |
+|---|---|
+| Direction | CS→RTU, answer RTU→CS (data or `NDA`) |
+| Purpose | 5-minute-block historical trend retrieval. Request carries the timestamp of the last stored block; the answer continues from there, up to max 6 hours / 4000 chars; `NDA` ends the stream. This is the backfill/watermark operation the Historical Acquisition Manager is built around (§3.4.12). |
+| Evidence | §3.4.12 incl. full multi-answer example §3.4.12.2 and CFG scaling §3.4.12.3; wire-level example §3.7 |
+| Gaps | AQ-GAP-003 (block value count), AQ-GAP-001(e/g) |
+| Status | REGISTERED (core scope; requires `protocol-gaps.md` AQ-GAP-003 working hypothesis wired to station point configuration) |
+
+Semantics confirmed by example: a day's final block is timestamped `00:00` of the *next* day (§3.4.12.2 comment); requests use the last received block's timestamp to resume — the exact pattern the gateway's synchronization watermark must reproduce.
+
+### OPS-008 — Periodical report (`WGD`)
+
+| Field | Content |
+|---|---|
+| Direction | CS→RTU, answer RTU→CS (data or `NDA`) |
+| Purpose | Per-day segmented aggregates (default 00-06 / 06-09 / 09-16 / 16-00 + sum) per reporting point (§3.4.11). Maps to canonical `AcquisitionSource = AQUACOM_REPORT`. Request also sets the RTU clock (same caveat as WCA). |
+| Evidence | §3.4.11 incl. CFG section and scaling formula |
+| Gaps | AQ-GAP-009, AQ-GAP-010(b) |
+| Status | REGISTERED (implemented after WGH; report points configured separately from trend points per §3.4.11.4) |
+
+---
+
+## Configuration / definition operations
+
+### OPS-009 — Function channels (`MCC`, `MPA`, `MPB`, `MPC`, `MPD`, `MPL`)
+
+| Field | Content |
+|---|---|
+| Direction | CS→RTU (set) and RTU→CS (fetch) |
+| Purpose | Setpoint/config channel write & fetch. **Fetch limitation (Forth):** the RTU echoes only the *last sent* telegram — you must send what you want to receive; a cold-started RTU cannot be fetched from (§3.4.2–3, §3.4.3 "Important 2"). Types: `A`/`D` integer, `T` text (quoted, `_` = empty/space-as-underscore), `0–4` float decimals (§3.4.2.2; Basic variant §3.5.2). |
+| Evidence | §3.4.2–3, §3.4.2.3 CFG/AquaView examples |
+| Gaps | AQ-GAP-001(a), AQ-GAP-004 |
+| Status | REGISTERED (used for station configuration; **writes to setpoints are control operations — OUT-OF-SCOPE initially**; read-back of a previously sent telegram is acceptable) |
+
+### OPS-010 — Analogue channels (`MAS`)
+
+| Field | Content |
+|---|---|
+| Direction | CS→RTU (set) and RTU→CS (fetch) |
+| Purpose | Analogue input config (signal type, alarm levels, hysteresis, decimals; `htr` trend flag on Basic RTUs). Fetch requires a prior send, as with MCC (§3.4.4–5, §3.5.3). |
+| Evidence | §3.4.4–5, §3.5.3, CFG examples |
+| Gaps | AQ-GAP-003 (htr vs. Forth CFG trend section) |
+| Status | REGISTERED (definitions source; writes OUT-OF-SCOPE initially, as OPS-009) |
+
+### OPS-011 — Alarm code filter (`MAT`) and priorities (`SLT`)
+
+| Field | Content |
+|---|---|
+| Direction | CS→RTU (set) and RTU→CS (fetch, capability-dependent per ATF controller-type digits) |
+| Purpose | Alarm code remapping and A–Z priorities. The document itself states MAT "is not necessary to implement" (§3.4.6.3). |
+| Evidence | §3.4.6–9 |
+| Gaps | AQ-GAP-006 |
+| Status | OUT-OF-SCOPE (alarm system extension; revisit when alarm retrieval is scheduled) |
+
+---
+
+## Answer telegrams (all operations)
+
+### OPS-012 — Fixed answers `SCO` / `SCE` / `NDA` / `!!` (Wait)
+
+| Field | Content |
+|---|---|
+| Direction | RTU→CS |
+| Purpose | `SCO` = telegram OK; `SCE` = error in telegram (optional rejected-channel payload, AQ-GAP-007); `NDA` = requested data not available (normal WGH/WGD stream terminator — **not** an error); `!!` = single DC3 (13H) byte, may be embedded *inside* another telegram, must be stripped before parsing, excluded from checksum, and resets the CS receive timeout (§3.6). |
+| Evidence | §3.6, §3.6.4 checksum-identical pair of examples (both verified: 2925), §3.7 |
+| Gaps | AQ-GAP-007 (SCE payload) |
+| Status | REGISTERED (the `!!` handling is a hard requirement for any long-answer operation: WGH, WGD, WGS, MCC fetch) |
+
+---
+
+## Implementation order (evidence-complete subset)
+
+1. Framing + checksum + `!!` stripping (OPS-012 + framing note) — fully evidenced, unblocked.
+2. OPS-005 `WGS` (live) — blocked only by AQ-GAP-002, which has a documented workaround (decode via `Nal`, cross-check `alp` diagnostically).
+3. OPS-007 `WGH` (history) — blocked by AQ-GAP-003 working-hypothesis wiring (station configuration drives block layout).
+4. OPS-008 `WGD` (reports) — after WGH; AQ-GAP-009 defaults.
+5. Session ops OPS-001/002 as transports require (BRK for fixed-line WGS sessions).
+
+This order matches the implementation phases (Phase 3 codec → Phase 6 live → Phase 10 historical) and honors live-over-history scheduling.

docs/protocol/protocol-gaps.md

@@ -0,0 +1,163 @@
+# AquaCom protocol gap registry
+
+**Source:** *Technical description – AquaCom – RTU level*, Rev 1.6, ITT Flygt AB, July 2004 — present in this folder as `AquaCom_RTU_1_6_eng.pdf` (markdown conversion: `AquaCom_RTU_1_6_eng_markdown/AquaCom_RTU_1_6_eng.md`). The PDF is authoritative wherever the conversion is ambiguous.
+
+**Policy.** AquaCom protocol behavior may only be implemented from verified evidence (`AGENTS.md`; implementation specification §3.1). Unresolved protocol questions are recorded here instead of guessed (implementation specification §62, case C). An entry is closed only when the missing evidence exists; closing requires citing the evidence, adding a resolution note, and changing the status. Entries are never deleted.
+
+**Entry format** (implementation specification §17): Gap ID, Description, Affected operation, Evidence available, Evidence missing, Impact, Implementation status.
+
+**Status values:**
+
+- `OPEN` — evidence missing; implement only what is documented, never the undocumented part.
+- `VERIFY` — evidence exists in the PDF; the markdown conversion is unreliable at the cited places; check the PDF before implementing.
+- `CLOSED` — resolved; cite evidence and date in a resolution note.
+
+---
+
+## AQ-GAP-001 — Fidelity of the markdown conversion
+
+| Field | Content |
+|---|---|
+| Gap ID | AQ-GAP-001 |
+| Description | The PDF→markdown conversion is lossy at several places. Confirmed instances: (a) §3.4.2.2 MCC DATA type table is mangled — the type rows are merged ("A = D = Integer (0-32767) … Analogue (0-200)"); (b) §3.4.10.1 WGS status-answer table merges the `mp1–mp128` byte-range cell into the description text (recoverable reading: 1–12 bytes each, measuring points 1–128); (c) §2.2.3.2 caller-ID field table formatting is broken; (d) §3.4.2.3.3 controller-type example prints `101 001` while the surrounding text refers to `(010)` (the parallel sections print `101 010` and `101 100` consistently); (e) the §3.7 detailed example is truncated mid-telegram ("…_0_1_1" followed by the document footer), so the answer's checksum is never reached; (f) WGS request examples print `0!` for the `mash`/`dir` fields — checksum verification proves the wire form is `0 !` (two space-separated fields), so this instance is resolved, but the PDF rendering should be confirmed for the record; (g) §3.4.12.1 states the WGH block `YY` is 2 bytes, but checksum-verified examples transmit single-digit years (e.g. `1 4 30 23 35`) — all block date fields shall be accepted as 1–2 digits. |
+| Affected operation | all telegram parsing |
+| Evidence available | authoritative PDF in this folder |
+| Evidence missing | none — each affected table must be checked against the PDF before implementation |
+| Impact | wrong field layouts if implemented from the markdown conversion alone |
+| Status | `VERIFY` |
+
+---
+
+## AQ-GAP-002 — WGS status answer: `alp` semantics and measuring-point/alarm boundary
+
+| Field | Content |
+|---|---|
+| Gap ID | AQ-GAP-002 |
+| Description | `Nal` ("number of alarms following last measuring point") is unambiguous and consistent with all examples: alarm codes are appended after the measuring points, `Nal` of them. `alp` ("position where the first alarm is to be found") does not define its reference frame in the document. Arithmetic across **all four** printed examples is consistent with `alp` = the 1-based position, within the measuring-point sequence, of the first alarm, i.e. `measuring-point count = alp − 1`: §2.2.3.1 (alp=48, Nal=3), §3.4.10.2 (alp=22, Nal=1), §3.4.10.3 (alp=64, Nal=1), §3.6.4 (alp=11, Nal=1, 10 measuring points explicit). The earlier note that §2.2.3.1 "does not reconcile" was an analysis error (a mis-split field list), now retracted. What remains missing is an explicit definition, and a capture from a real station (the four examples agree but are all from the same vendor document). |
+| Affected operation | WGS status answer decoding |
+| Evidence available | §3.4.10.1 field definitions; arithmetic of examples §2.2.3.1, §3.4.10.2–3, §3.6.4 |
+| Evidence missing | an explicit definition, or a validated capture from a station whose measuring-point count is independently known |
+| Impact | the boundary between measuring points and trailing alarm codes; a misparse shifts every subsequent value |
+| Status | `OPEN` — hypothesis strengthened but still vendor-document-internal; do not treat `alp` as confirmed |
+
+**Working hypothesis (not confirmed — do not rely on it):** `alp` is the 1-based position, within the measuring-point sequence, of the first alarm; measuring points number `alp − 1`. An initial implementation may split measuring points from alarms using `Nal` alone (documented unambiguously), cross-check against `alp − 1` diagnostically, and shall not reject telegrams on an `alp` mismatch until this gap is closed.
+
+---
+
+## AQ-GAP-003 — WGH: number of values per block and trend-point membership
+
+| Field | Content |
+|---|---|
+| Gap ID | AQ-GAP-003 |
+| Description | Historical trend blocks contain `v1…v32`; "the actual numbers is depending of the type of RTU and version". The count is not signaled in the telegram. Examples: §3.4.12.2 has 7 values per block; §3.7 has 6. On Forth RTUs the station CFG contains a dedicated historical-trend section ("; ##3 / Number of points for Historical trend", with per-point wagon mapping) which presumably governs both membership and count; on Basic RTUs the MAS `htr` flag marks trend participation instead (§3.5.3.2). The document never explicitly states that the decoder must derive the per-block value count from station configuration. |
+| Affected operation | WGH historical trend data decoding |
+| Evidence available | §3.4.12.1 block format; examples §3.4.12.2 and §3.7; CFG sections §3.4.12.3 and §3.5.3.2 |
+| Evidence missing | an explicit statement, or a validated capture from a station whose CFG is known |
+| Impact | block splitting is ambiguous: values are numeric and cannot be distinguished from the following block's date fields by form alone |
+| Status | `OPEN` |
+
+**Working hypothesis (not confirmed):** the expected value count comes from the station's point configuration (CFG historical-trend section); the decoder validates each block's structure against it. Values are wagon-mapped and scaled per point (`Scaled = Raw*(Max−Min)/Max_input + Min`, §3.4.12.3).
+
+---
+
+## AQ-GAP-004 — Character encoding of text values
+
+| Field | Content |
+|---|---|
+| Gap ID | AQ-GAP-004 |
+| Description | Telegrams are "an ASCII-string with support of IBM extended codes. E.g. codes 01H to FFH is supported" — the code page for IBM extended codes (e.g. Å/Ä/Ö in Swedish station names) is not defined. Some RTUs support UTF-8 in the MCC data part, capability-dependent (ATF controller-type position 3). The checksum is byte-based and unaffected. |
+| Affected operation | MCC T-type values (station names, telephone numbers), any text-bearing points |
+| Evidence available | §2.3.1; §3.4.2.3.3 Note 4 |
+| Evidence missing | a code-page definition, or a capture containing non-ASCII text |
+| Impact | garbled text values; incorrect string comparisons |
+| Status | `OPEN` (low priority until text points are used) |
+
+---
+
+## AQ-GAP-005 — Example checksum integrity in the source document
+
+| Field | Content |
+|---|---|
+| Gap ID | AQ-GAP-005 |
+| Description | **35 single-line examples** from the document were recomputed against the §2.4 algorithm and verify exactly (see `test-vectors.md` §1), confirming the algorithm itself, including the Wait-exclusion rule (§3.6.4 pair: both forms sum to 2925). However: (a) the long multi-line examples (WGS answers 7679/3633/6967/6968, WGH answers 6922/6479/4220, WGD answers 4984/5632, MCC 24268/28910, SLT 14331/15425/15061) **cannot be byte-exactly recomputed from the markdown conversion** — blockquote `>` prefixes, `\#` escapes and line-wrap artifacts (e.g. `1\n4 30` splitting a block, `- 16384` splitting a value) survive in the conversion and change byte sums; manual cleanup attempts give near-miss values (e.g. SLT 14331 → 14330/14295 depending on artifact handling), proving the artifacts, not the algorithm, are the problem; (b) example narratives contain destination mismatches (§2.2.3.1 says plant number 89 but the telegram uses dest 86; §3.4.10.2 gives a fixed-line dest as "plant number 901" although fixed-line dest should be the Node ID). |
+| Affected operation | approved test vectors only — the checksum algorithm is confirmed for all short vectors |
+| Evidence available | 35 verified recomputations in `test-vectors.md`; authoritative PDF |
+| Evidence missing | PDF text extraction (or manual transcription) of the long examples free of conversion artifacts |
+| Impact | the long examples cannot be approved fixtures until transcribed from the PDF; they are the only candidates exercising 16-bit wraparound (sums > 65535), so synthetic vectors cover that branch in the meantime |
+| Status | `OPEN` |
+
+---
+
+## AQ-GAP-006 — MAT fetch request checksum
+
+| Field | Content |
+|---|---|
+| Gap ID | AQ-GAP-006 |
+| Description | The MAT fetch **request** `9 MAT 0 1 # 557` (§3.4.7.2) recomputes to **540**. 557 is exactly the checksum of the structurally identical SLT fetch request `9 SLT 0 1` (§3.4.9.2, verified), indicating a copy-paste error in the source document. The MAT fetch **answer** `7 9001 # 353` verifies exactly (353), so the answer side is sound. |
+| Affected operation | MAT fetch request vector |
+| Evidence available | §3.4.7.2 examples; recomputation (request: 540; answer: 353 verified) |
+| Evidence missing | PDF confirmation of which checksum the printed request should carry |
+| Impact | minor — use 540 for the request vector once PDF-confirmed; the verified answer vector may be approved independently |
+| Status | `OPEN` |
+
+---
+
+## AQ-GAP-007 — SCE payload semantics
+
+| Field | Content |
+|---|---|
+| Gap ID | AQ-GAP-007 |
+| Description | "A SCE answer for a MCC telegram might contain the channel number the RTU rejected. Example: SCE 48 # 423." Whether and when the payload field is present is unspecified ("might"). |
+| Affected operation | SCE (error in telegram) handling |
+| Evidence available | §3.4.2.3 example (checksum verifies) |
+| Evidence missing | a rule for payload presence |
+| Impact | low — treat any payload as optional diagnostic data, never as parse-critical |
+| Status | `OPEN` (low) |
+
+---
+
+## AQ-GAP-008 — Caller-ID telegram `ACT` field contents
+
+| Field | Content |
+|---|---|
+| Gap ID | AQ-GAP-008 |
+| Description | §2.2.3.2 defines the dialled-line caller-ID telegram (`STX DEST ACT # CHK CR`) with `ACT` = "Type of message, 3 bytes", but lists no valid `ACT` values. The §2.2.3.3 example transmits the literal string `ACT`, and its checksum (369) is consistent with that literal — suggesting an unexpanded placeholder rather than real traffic. |
+| Affected operation | dialled-line caller identification |
+| Evidence available | §2.2.3.2–3 |
+| Evidence missing | valid `ACT` values, or a capture of a real caller-ID telegram |
+| Impact | low for fixed-line/TCP-first deployments (feature is dialled-only and capability-dependent) |
+| Status | `OPEN` (low) |
+
+---
+
+## AQ-GAP-009 — WGD segment boundaries configurability
+
+| Field | Content |
+|---|---|
+| Gap ID | AQ-GAP-009 |
+| Description | WGD answer segments are documented as "default 00-06 / 06-09 / 09-16 / 16-00". The word "default" implies configurability, but no mechanism is documented in this document. |
+| Affected operation | WGD periodical data interpretation |
+| Evidence available | §3.4.11.1 |
+| Evidence missing | the configuration mechanism (possibly an AquaView/CFG setting outside this document) |
+| Impact | low — use the documented defaults; record deviation diagnostically |
+| Status | `OPEN` (low) |
+
+---
+
+## AQ-GAP-010 — Minor source-document inconsistencies in alarm telegrams
+
+| Field | Content |
+|---|---|
+| Gap ID | AQ-GAP-010 |
+| Description | (a) The WCA field table gives the hour range as 0–24 (§3.4.1) while ALR gives 0–23 (§3.4.1.6); 24 is likely a source typo — validate as 0–23 unless the PDF shows otherwise. (b) The semantics of the WCA date/time fields when `set=0` (poll mode) are not stated; the examples always carry the CS's current time, but the document does not say what the RTU does with it when `set=0`. |
+| Affected operation | WCA request encoding; alarm polling |
+| Evidence available | §3.4.1, §2.2.3.3, §3.4.1.2–3 examples |
+| Evidence missing | PDF confirmation; a statement of `set=0` time semantics |
+| Impact | low — alarms are extension scope; do not implement clock setting or rely on `set=0` time semantics until resolved |
+| Status | `OPEN` (low) |
+
+---
+
+## Closed gaps
+
+None yet. When closing an entry: keep the original text, append a **Resolution** note citing the evidence and date, and set the status to `CLOSED`.

docs/protocol/test-vectors.md

@@ -0,0 +1,114 @@
+# AquaCom approved test vectors
+
+**Fixture source policy:** all vectors below are derived from *Technical description – AquaCom – RTU level*, Rev 1.6, ITT Flygt AB, July 2004 (`AquaCom_RTU_1_6_eng.pdf`) — evidence class **SPECIFICATION** (examples printed in the authoritative document). Vectors marked *(synthetic)* are constructed by the project to exercise edge cases the document's examples do not cover; they are labeled **SYNTHETIC_FROM_SPECIFICATION** and are subordinate to the source examples in authority. Each fixture becomes an automated test on implementation; fixtures are immutable once approved (implementation specification §64).
+
+**Notation.** `<SOH>`=01H, `<STX>`=02H, `<CR>`=0DH, `_`=space (20H), `!W` = Wait byte (DC3, 13H). Checksums are per §2.4: sum of all bytes after SOH/STX up to (excluding) `#`, excluding Wait bytes, in a 16-bit signed integer; the transmitted value is the absolute value. The separator space between `#` and the checksum, and the trailing space before `CR`, **are included** in the summed range.
+
+**Checksum convention reminder (verified by the examples below):** the summed range starts *after* SOH/STX — i.e. at the space that follows the start byte — and ends at the space immediately before the checksum digits. `32+83+67+79+32=293` for `SCO` (§2.4) confirms this: leading space 32, `SCO` 83+67+79, trailing space 32.
+
+---
+
+## 1. Checksum algorithm vectors
+
+| ID | Telegram | Documented checksum | Verified | Source |
+|---|---|---|---|---|
+| AQ-CK-001 | `<STX> SCO _ # _ 293 <CR>` | 293 | yes | §2.4 |
+| AQ-CK-002 | `<SOH> 9 BRK _ # _ 376 <CR>` | 376 | yes | §3.4.1.2 |
+| AQ-CK-003 | `<SOH> 0 ALO _ # _ 364 <CR>` | 364 | yes | §2.2.3.3 |
+| AQ-CK-004 | `<STX> NDA _ # _ 275 <CR>` | 275 | yes | §3.4.12.2 |
+| AQ-CK-005 | `<STX> SCO _ # _ 293 <CR>` (RTU→CS OK answer) | 293 | yes | §3.4.2.3 |
+| AQ-CK-006 | `<STX> SCE 48 _ # _ 423 <CR>` | 423 | yes | §3.4.2.3 |
+| AQ-CK-007 | `<SOH> 9 WCA 0 3 6 17 13 59 _ # _ 1031 <CR>` | 1031 | yes | §2.2.3.3 |
+| AQ-CK-008 | `<SOH> 9 WCA 0 3 6 17 14 0 _ # _ 970 <CR>` | 970 | yes | §2.2.3.3 |
+| AQ-CK-009 | `<STX> ALN T 0 0 0 0 _ # _ 719 <CR>` | 719 | yes | §2.2.3.3 |
+| AQ-CK-010 | `<STX> OK _ # _ 218 <CR>` | 218 | yes | §2.2.3.1, §3.4.1.2 |
+| AQ-CK-011 | `<SOH> 5 WCA 0 1 4 27 10 13 _ # _ 1011 <CR>` | 1011 | yes | §3.4.1.3 |
+| AQ-CK-012 | `<STX> ALR 111 11 1 4 27 10 13 A T 0 0 0 0 B 31 _ # _ 1922 <CR>` | 1922 | yes | §3.4.1.3 |
+| AQ-CK-013 | `<SOH> 5 ALO _ # _ 369 <CR>` | 369 | yes | §3.4.1.3 |
+| AQ-CK-014 | `<SOH> 9 MCC 0 1 _ # _ 525 <CR>` | 525 | yes | §3.4.3.2 |
+| AQ-CK-015 | `<SOH> 9 SLT 0 1 _ # _ 557 <CR>` | 557 | yes | §3.4.9.2 |
+| AQ-CK-016 | `<SOH> 2 MAS 0 1 _ # _ 532 <CR>` | 532 | yes | §3.4.5.3 |
+| AQ-CK-017 | `<SOH> 2 MAT 7 7 81 81 82 9003 _ # _ 1194 <CR>` | 1194 | yes | §3.4.6.1 |
+| AQ-CK-018 | `<SOH> 9 MAT 7 9001 _ # _ 700 <CR>` | 700 | yes | §3.4.6.2 |
+| AQ-CK-019 | `<SOH> 9 WGD 01 05 02 13 38 01 05 01 _ # _ 1433 <CR>` | 1433 | yes | §3.4.11.3 |
+| AQ-CK-020 | `<SOH> 5 WGD 01 05 02 13 10 01 05 01 _ # _ 1419 <CR>` | 1419 | yes | §3.4.11.2 |
+| AQ-CK-021 | `<SOH> 9 WGH 01 04 30 23 30 _ # _ 1039 <CR>` | 1039 | yes | §3.4.12.2 |
+| AQ-CK-022 | `<SOH> 9 WGH 01 05 01 03 50 _ # _ 1038 <CR>` | 1038 | yes | §3.4.12.2 |
+| AQ-CK-023 | `<SOH> 9 WGH 01 05 01 08 10 _ # _ 1039 <CR>` | 1039 | yes | §3.4.12.2 |
+| AQ-CK-024 | `<SOH> 9 WGH 01 05 01 08 20 _ # _ 1040 <CR>` | 1040 | yes | §3.4.12.2 |
+| AQ-CK-025 | `<SOH> 500 WGH 99 12 31 21 40 _ # _ 1147 <CR>` | 1147 | yes | §3.7 |
+| AQ-CK-026 | `<STX> 9_ACT_#_369_<CR>` (caller-ID, literal ACT) | 369 | yes | §2.2.3.3 |
+| AQ-CK-027 | `<STX> ALR 9 12 3 6 17 13 58 P T 0 0 0 0 A 27 _ # _ 1867 <CR>` | 1867 | yes | §2.2.3.3 |
+| AQ-CK-028 | `<STX> ALR 9 12 1 4 27 10 26 P T 0 0 0 0 A 27 _ # _ 1856 <CR>` | 1856 | yes | §3.4.1.2 |
+| AQ-CK-029 | `<SOH> 9 WCA 0 1 4 27 10 27 _ # _ 1020 <CR>` | 1020 | yes | §3.4.1.2 |
+| AQ-CK-030 | `<SOH> 86 WGS P 0 ! 1 _ # _ 785 <CR>` | 785 | yes | §2.2.3.1 — confirms the `0 !` two-field form |
+| AQ-CK-031 | `<SOH> 901 WGS P 0 ! 11 _ # _ 878 <CR>` | 878 | yes | §3.4.10.2 |
+| AQ-CK-032 | `<SOH> 9 WGS P 2 F 1 _ # _ 771 <CR>` | 771 | yes | §3.4.10.3 |
+| AQ-CK-033 | `<STX> 32000 654321 03 11 0 0 0 0 0 1 2 3 4 5 6 7 8 9 10 8050 8531 8532 _ # _ 2925 <CR>` | 2925 | yes | §3.6.4 (Wait-free form of the WGS-answer pair) |
+| AQ-CK-034 | `<STX> 32000 65!W4321 03 11!W 0 0 0 0 0!W 1 2 3 4 5!W 6 7 8 9 1!W0 8050 853!W1 8532 _ # _ 2925 <CR>` | 2925 | yes | §3.6.4 (Wait-laden form; identical checksum — proves Wait exclusion) |
+| AQ-CK-035 | `<STX> 7 9001 _ # _ 353 <CR>` | 353 | yes | §3.4.7.2 (MAT fetch answer) |
+
+**Discrepant vector (documented checksum fails recomputation; see `protocol-gaps.md` AQ-GAP-006):**
+
+| ID | Telegram | Documented | Recomputed | Source | Note |
+|---|---|---|---|---|---|
+| AQ-CK-E1 | `<SOH> 9 MAT 0 1 _ # _ 557 <CR>` | 557 | 540 | §3.4.7.2 | fetch **request**; 557 is exactly the SLT fetch checksum (copy-paste error); not approved until PDF-confirmed |
+
+The long multi-line examples (WGS answers 7679 / 3633 / 6967 / 6968; WGH answers 6922 / 6479 / 4220; WGD answers 4984 / 5632; MCC 24268 / 28910; SLT 14331 / 15425 / 15061) are candidates for wraparound coverage (sums > 65535) but **cannot be recomputed from the markdown conversion** — blockquote markers, `\#` escapes and line-wrap artifacts survive in the conversion and alter byte sums (AQ-GAP-005). They must be transcribed from the authoritative PDF before approval; until then they are **not approved fixtures**, and the synthetic vectors below cover the wraparound branches.
+
+**Synthetic algorithm-branch vectors (values computed and verified against the §2.4 algorithm):**
+
+| ID | Constructed telegram | Raw sum | Expected checksum | Why |
+|---|---|---|---|---|
+| AQ-CK-S1 | `<STX>` + 200 × `A` + ` _ # _` | 13064 | 13064 | no wraparound — round-trip baseline *(synthetic)* |
+| AQ-CK-S2 | `<STX>` + 806 × `z` + ` _ # _` | 98396 | 32676 | sum > 65535 (16-bit wraparound **and** the ≥32768 absolute-value branch: 98396 mod 65536 = 32860 → 65536−32860 = 32676) *(synthetic)* |
+| AQ-CK-S3 | `<STX>` + 550 × `z` + ` _ # _` | 67164 | 1628 | wraparound **without** the absolute-value branch (67164 mod 65536 = 1628 < 32768) — isolates the mod-65536 step *(synthetic)* |
+| AQ-CK-S4 | `<STX> SCO !W !W _ # _ 293 <CR>` | — | 293 | Wait bytes excluded from the sum *(synthetic; superseded by source vector AQ-CK-033/034, retained as an algorithm-level unit test)* |
+
+---
+
+## 2. Framing / session vectors
+
+| ID | Scenario | Expectation | Source |
+|---|---|---|---|
+| AQ-FR-001 | CS dialled, RTU answers 6×OK 2.5 s apart; CS transmits request after first OK detected | conversation proceeds; the OK sequence is aborted by the incoming request | §2.2.3 |
+| AQ-FR-002 | Answer arrives with Wait bytes embedded mid-token (`…65!!4321…`) | strip `!W` before tokenization; checksum unchanged; parser output equals the Wait-free form | §3.6.4 |
+| AQ-FR-003 | BRK sent 3×, then hang-up | no answer expected; transport closes cleanly | §3.4.13 |
+| AQ-FR-004 | Inter-character gap of 1 s inside a telegram | accepted (RTU-side limit is exactly 1 s; the gateway as CS uses 4–20 s whole-telegram timeout — §2.5) | §2.5 |
+| AQ-FR-005 | Telegram data length > 4000 chars | rejected by framer; diagnostic generated (protocol max) | §2.3.2 |
+
+## 3. Live data vectors (WGS)
+
+| ID | Scenario | Expected decode | Source |
+|---|---|---|---|
+| AQ-WGS-001 | Fixed, request `901 WGS P 0 ! 11` → answer `23400 13885 01 22 0 0 0 0 0 3 0 3 3 4800 … 7 8111` | `ver=23400`, `prod=13885`, `Nal=1`, `alp=22`, `rem=0`, 21 measuring points (alp−1, hypothesis — AQ-GAP-002), then 1 alarm code (8111). Decode via `Nal`; cross-check `alp−1` diagnostically only | §3.4.10.2 (checksum not yet approvable — AQ-GAP-005 long example) |
+| AQ-WGS-002 | Request with control command then BRK | command suppressed by gateway (control OUT-OF-SCOPE); BRK still required after command-bearing WGS per §3.4.13 | §3.4.10, §3.4.13 |
+| AQ-WGS-003 | Request with `dir`=`!` (ignore) | no command dispatched; normal status answer | §3.4.10 |
+
+## 4. Historical vectors (WGH)
+
+| ID | Scenario | Expected decode | Source |
+|---|---|---|---|
+| AQ-WGH-001 | Request `9 WGH 01 04 30 23 30` → first answer of §3.4.12.2 (36 blocks, checksum 6922) | 36 blocks; first `1 4 30 23 35`, last `1 5 1 3 50`; 7 values per block; `!` separators; **requires AQ-GAP-003 hypothesis wiring** | §3.4.12.2 |
+| AQ-WGH-002 | Continuation: request with last received block timestamp `9 WGH 01 05 01 03 50` → next answer | stream resumes at `1 5 1 3 55`; proves the watermark-resume protocol | §3.4.12.2 |
+| AQ-WGH-003 | Final continuation `9 WGH 01 05 01 08 20` → `NDA` | `NDA` = normal end-of-stream, not an error; synchronization interval complete | §3.4.12.2 |
+| AQ-WGH-004 | Day rollover: block `1 4 30 0 0` follows block `1 4 30 23 55` | the `00:00` block belongs to the *next* day (comment: "the last block for a day is the one with time stamp 00:00") — **no date-field jump; the date increments**; single-digit year/month/day accepted (1–2 byte fields) | §3.4.12.2 |
+| AQ-WGH-005 | Answer with embedded Wait bytes (§3.7 form) | parse identical to Wait-free form; checksum identical (§3.6.4 pair) | §3.7, §3.6.4 |
+| AQ-WGH-006 | Request whose span exceeds 6 hours or 4000 chars | RTU truncates per §3.4.12.1 limits; gateway detects truncated stream by receiving fewer blocks than the requested interval and re-requests from the last block timestamp (at-least-once; dedup by §13/§23 rules) | §3.4.12.1 *(synthetic scenario, specification-derived limit)* |
+| AQ-WGH-007 | Scaling: CFG point `Max=0.01, Min=0, Max_input=10`, raw 64786 | `Scaled = Raw×(Max−Min)/Max_input + Min` → 64.786 — every vector decode must apply wagon scaling per station CFG, not raw values | §3.4.12.3 *(synthetic combination of documented formula + example raw value)* |
+
+## 5. Report vectors (WGD)
+
+| ID | Scenario | Expected decode | Source |
+|---|---|---|---|
+| AQ-WGD-001 | Request `5 WGD 01 05 02 13 10 01 05 01` → answer `0 0 0 501 501 0 0 0 1506 1506 …` | per point: seg1..seg4 + sum; 10 reporting points per §3.4.11.4 CFG; scaling formula per point | §3.4.11.2, §3.4.11.4 |
+| AQ-WGD-002 | Empty report day → all-zero answer (§3.4.11.3) | 64 zero values decoded as valid (not NDA); zero is a legitimate report value | §3.4.11.3 |
+| AQ-WGD-003 | `NDA` answer | report data for that day does not exist; mark interval missing, do not treat as failure | §3.4.11 |
+
+## 6. Simulator scenario requirements (traceability targets)
+
+The simulator (implementation specification §49) shall be able to replay every vector above plus inject: bad checksum (failing AQ-CK verification), truncated telegram (no `#`/`CR`), over-long telegram, inter-character stall of 1.5 s (RTU-side timeout breach), mid-telegram Wait flooding, duplicate WGH blocks across two answers (dedup regression per `ARCHITECTURE.md` §23), conflicting block re-transmission (REJECT_CONFLICT path per §13), and station clock set to a future date (timestamp-validation diagnostics per `software-specification.md` §26). The simulator must not share parsing code with the production decoder (§49).
+
+---
+
+**Approval state:** section 1 verified rows (AQ-CK-001–035) and section 2 approved as fixtures; AQ-CK-E1 pending AQ-GAP-006 (PDF confirmation); long examples pending AQ-GAP-005 (PDF transcription); sections 3–4 blocked by AQ-GAP-002/003 for full decode assertions (framing-level assertions may proceed; `Nal`-based decoding is documented and unblocked). Synthetic vectors subordinate to source vectors. Update this file's approval state when gaps close — never delete vectors.