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](https://keepachangelog.com/en/1.1.0/), and this project adheres to
[Semantic Versioning](https://semver.org/spec/v2.0.0.html). 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](docs/exec-plans/active/001-implementation-roadmap.md)).

## [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).

[Unreleased]: https://example.invalid/aquacom-gateway/compare/initial-commit...HEAD