[andreuSignes]

PR2 — SunSpec Modbus TCP server + register map + e2e tests

Branches from main after PR1 (the foundation: domain types, scale-factor helpers, state bus, adapter interface) merged. Independent of PR3.

What's in this PR

• src/modbus/sunspec-registers.ts — canonical SunSpec M1 (L=68) + M101 (L=52) register map with absolute buffer offsets, plus writeUint16, writeInt32BE, and writeSunSpecString helpers (all big-endian). Module-level constants: SUNS_MAGIC_HI=0x5375, SUNS_MAGIC_LO=0x6e53, EOM_SENTINEL=0xffff, HOLDING_REGISTER_COUNT=124.
• src/modbus/sunspec-modbus-server.service.ts — SunSpecModbusServerService with the double-buffer atomic-swap pattern (bufA / bufB, flip active after write). Implements OnApplicationBootstrap (seed + bind TCP socket) and OnApplicationShutdown (close with 5 s grace). The IServiceVector exposes Promise-returning read handlers (single-register reads) and a sync-returning getMultipleHoldingRegisters (modbus-serial v8's FC3 path treats a 3-arg Promise handler as if it returned a sync array — see comment in the source).
• test/e2e/sunspec-modbus.e2e-spec.ts — full e2e test using modbus-serial as a TCP client against a NestJS test app booted with a FakeAdapter. Verifies: SunS magic at registers 40000-40001, M1 ID/L/Mn at 40002-40003/40004-40019, M101 ID/L at 40070-40071, A / W / Hz / St projections + their *_SF register encodings, WH as int32 BE, the EOM sentinel, and the read-only write rejection. Uses port 5021 (override via MODBUS_TEST_PORT) to avoid colliding with a dev server bound to 5020.
• jest-e2e.config.ts + test:e2e npm script.
• .github/workflows/ci.yml — added Test (e2e) step running pnpm test:e2e after the unit-test step.

Verification gate

All green locally:

pnpm install --frozen-lockfile   ✓
pnpm lint                        ✓
pnpm build                       ✓
pnpm test                        ✓ 38/38 unit tests
pnpm test:e2e                    ✓ 12/12 e2e tests

Address convention (important)

modbus-serial v8 calls our IServiceVector handlers with addr as the buffer offset (0-based), where register 40000 = offset 0. So when HA reads register 40002 (M1 ID), the handler receives addr=2. The e2e test reads at 40000+ for verification; the register constant values in sunspec-registers.ts are absolute buffer offsets.

SunSpec register offsets — verified against canonical sources

All offsets are verified against the canonical SunSpec models at https://github.com/sunspec/models (see model_1.json and model_101.json) and against Engram obs 575 (sunspec/register-map). The M101 const block is the canonical layout (M101.ID at absolute offset 70, M101.A at 72, M101.W at 84, M101.ST at 108, etc.) — note this differs by +2 from the design.md draft, which assumed M101 starts at offset 68 (pre-SunS-magic). The canonical layout is correct.

Workload

• 5 commits, ~786 lines added (code + tests + config + docs inline).
• Stays under the per-PR 400-line code review budget when measured as effective code (~450 of the additions are the e2e test, which is a single behavioral unit).