aquacom-gateway-suite/CHANGELOG.md

Changelog

All notable changes to the AquaCom Integration Gateway project are documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning. Until the first implementation release, changes are grouped per working session; version numbers begin with the first production-capable release (roadmap G14, see ExecPlan 001).

Unreleased

2026-10-06 — Project surface

Added

• README.md — project overview: capabilities, architecture summary (Mermaid), documentation map with precedence, protocol-evidence policy, current repository layout, status checklist, third-party copyright notice for the vendor protocol document, license placeholder.
• CHANGELOG.md — this file.
• docs/exec-plans/active/001-implementation-roadmap.md — ExecPlan 001, the umbrella implementation roadmap: verified current-state snapshot; open decisions D-001 (technology selection — blocking) through D-006; phase/gate table for Phases 0–14 (G0–G14) with exit criteria and gap dependencies; §79 task mapping (T001–T020); protocol-gap consumption schedule; failure-handling, testing and compatibility commitments; progress log; decisions log (DR-001…DR-011); acceptance-evidence plan for the §77 DoD.

2026-10-05 — Protocol evidence layer

Added

• docs/protocol/AquaCom_RTU_1_6_eng.pdf — authoritative AquaCom protocol source: Technical description – AquaCom – RTU level, Rev 1.6, ITT Flygt AB, July 2004 (evidence class: SPECIFICATION).
• docs/protocol/AquaCom_RTU_1_6_eng_markdown/ — markdown conversion of the source (lossy at specific tables; PDF is authoritative — see gap registry AQ-GAP-001).
• docs/protocol/known-operations.md — operations registry: OPS-001…OPS-012 (session ops OK/BRK/EBR/caller-ID; live WGS; alarms WCA/ALR/ALN/ALO; history WGH; reports WGD; configuration MCC/MAS/MAT/SLT; fixed answers SCO/SCE/NDA/Wait), each with evidence sections, scope status (control/setpoint writes OUT-OF-SCOPE) and an evidence-complete implementation order.
• docs/protocol/protocol-gaps.md — gap registry with 10 entries (AQ-GAP-001…010) in the mandated entry format, including working hypotheses for WGS alp semantics and WGH block value counts.
• docs/protocol/test-vectors.md — test-vector catalogue: 35 source checksum vectors verified by recomputation against the §2.4 algorithm (including the §3.6.4 Wait-byte pair), framing/session vectors, WGS/WGH/WGD decode scenarios, simulator scenario requirements, and 4 synthetic vectors covering the 16-bit wraparound branches (values computed and verified).

Verified

• Checksum algorithm (§2.4): exact match on all 35 single-line source examples — confirms summed range (after SOH/STX, excluding #), space inclusion around #, and Wait-byte (DC3) exclusion.
• §3.6.4 Wait-byte pair: both forms sum to 2925 — proves in-telegram Wait bytes must be stripped and are excluded from the checksum.

Found (in the 2004 source document)

• MAT fetch request prints checksum 557; recomputes to 540 (557 is the SLT fetch checksum — copy-paste error). The MAT fetch answer verifies exactly (353).
• Narrative/destination mismatches in examples (§2.2.3.1 "plant number 89" vs telegram dest 86; §3.4.10.2 fixed-line dest given as plant number).
• WCA hour range typo (0–24 vs ALR's 0–23).
• All findings recorded in the gap registry with handling instructions; none block implementation.

2026-10-05 — Documentation baseline (commit 08d44ba, "Update documents")

Fixed

• Markdown formatting restored in all five guidance documents — the files had been JSON-escaped (\#, \*\*,   entities, # -prefixed lines in ARCHITECTURE.md, double-escaping in the implementation specification). Approximately 25,500 lines of escaped text normalized to clean Markdown; verified zero residual artifacts.

Changed

• AGENTS.md reduced from a 35-section duplicate specification (1,403 lines) to the short entry-point form (≈70 lines) its own specification mandates (§4/§6): document table with roles, non-negotiable rules, evidence rules, testing/security/uncertainty guidance.
• ARCHITECTURE.md §1 now defines document roles and precedence (software-spec = requirements; ARCHITECTURE = structure; implementation-spec = process; configuration-reference = config semantics; AGENTS.md never overrides).
• Watermark semantics defined precisely (§21): advances on durable spool commit, not final delivery — new invariants INV-013…INV-016 added (out-of-order arrival, watermark scope, dedup across restart, timestamp quarantine).
• software-specification.md: RFC 2119 keyword definitions added (§2); REJECT_CONFLICT made the default duplicate strategy (§13); missing-timestamp records quarantined with diagnostics (§10); shared/multi-drop transport requirement with arbitration (§5.1); repository interface naming aligned to ARCHITECTURE.md §25.
• Implementation specification made agent-neutral ("the implementation agent"); config-key naming aligned (maxValuesPerRead); conflict-policy mapping documented; evidence-acquisition plan added (§17) — resolved the next day by the arrival of the Rev 1.6 source.
• configuration-reference.md: default storage routing made deterministic (§60); overflow policies that discard data must emit diagnostics (§27.5); administrative channel defined as config-file mechanism until a real interface is specified (§81).

Added

• missing_docs.md — registry of planned documents that do not exist yet, with references and priorities; updated as items are created.

2026-10-05 — Initial documentation set (commit fbec27f, "Initial commit")

Added

• ARCHITECTURE.md — system structure, boundaries, canonical model, timestamp discipline, historical pipeline, OPC UA architecture, invariants INV-001…INV-012.
• docs/product/software-specification.md — functional requirements with design objectives and the requirement summary table (AQG-001…AQG-030).
• docs/product/codex-implementation-specification.md — implementation process: phases 0–14, task sizing, test pyramid, completion criteria, ExecPlan requirements.
• docs/configuration/configuration-reference.md — full configuration model with field-by-field semantics, validation rules and examples.
• AGENTS.md (original, long form — replaced in the 2026-10-05 documentation-baseline session above).