[andreuSignes]

PR1 v2 — domain types, state bus, scale-factor, pnpm, ESLint, CI

Foundation slice of the sunspec-modbus-gateway change.

What this PR delivers

Domain types (src/state/inverter-state.types.ts)

• InverterState interface with all numeric fields renamed to design.md §3:
  acPowerWatts, acVoltageVolts, acCurrentAmps, gridFrequencyHz,
  lifetimeEnergyKwh, operatingState (numeric union 1..8), isStale,
  lastUpdatedAt (ms epoch).
• vendorName and modelName fields added per design.md §3.
• M101_ST const enum mapping SunSpec St enum values (1..8).
• InverterAdapter abstract class with vendorName, modelName, read().
• INVERTER_ADAPTER DI token.

State bus (src/state/inverter-state.service.ts)

• InverterStateService with publish() and snapshot() (renamed from
  setState()/getState()).
• publish() owns lastUpdatedAt: stamps Date.now() on fresh publishes,
  preserves the previous timestamp on stale publishes so the time-based
  stale check trips correctly.
• snapshot() zeroes ALL production fields on stale (acPowerWatts,
  acVoltageVolts, acCurrentAmps, gridFrequencyHz, operatingState → OFF=1),
  preserves lifetimeEnergyKwh and identity fields (vendorName, modelName,
  serialNumber).

Scale-factor math (src/modbus/scale-factor.ts)

• chooseScaleFactor algorithm: integer values prefer SF=0; fractional
  values prefer the most-negative SF that fits; overflow downgrades to
  positive SF; clamps at SF_FLOOR (-10).
• applyScaleFactor uses 10^(-sf) to recover the raw register value
  (e.g. 230.5 V with SF=-1 → raw 2305).
• encode() one-shot helper returning { value, scaleFactor }.
• splitAcc32() returns a named { hi, lo } object (BE: upper 16 bits in hi).

Review-blocking issues resolved (v1 review)

1. Field renames in InverterState match design.md §3 exactly.
2. Method renames on InverterAdapter (fetchState → read) and
   InverterStateService (setState/getState → publish/snapshot).
3. Scale-factor algorithm — precision-preserving implementation
   that handles 230.5 → SF=-1, 50000 → SF=1, 1e15 → SF=-10 (clamp).
4. Stale-zeroing completeness — snapshot() zeros all four production
   fields, preserves lifetimeEnergyKwh and identity.

Strategy pivot (new in v2)

• pnpm 11 as package manager (packageManager field in package.json,
  .npmrc with shamefully-hoist=true for NestJS deps, pnpm-lock.yaml
  replaces package-lock.json).
• ESLint v9 flat config (eslint.config.mjs with @eslint/js +
  typescript-eslint, lint script, pnpm lint).
• GitHub Actions CI (.github/workflows/ci.yml — lint + build + test
  on every PR and push to main, Node 20, pnpm via corepack).
• GitHub Flow: each PR targets main directly. PR2/PR3 renamed
  from pr2/.../pr3/... to feat/...; merge sequence updated in
  tasks.md. PR1 branch keeps its name because the PR is already open.

Verification

pnpm install --frozen-lockfile
pnpm lint          # clean
pnpm build         # tsc strict
pnpm test          # 38/38 passing

Coverage: 94.36% statements / 88.88% branches / 94.82% lines.

CI workflow runs the same commands on every PR; ready for review.

Files

• src/state/inverter-state.types.ts (new)
• src/state/inverter-state.service.ts (rewritten)
• src/modbus/scale-factor.ts (rewritten)
• src/gateway/inverters/inverter.adapter.ts (re-export shim)
• src/domain/inverter-state.ts (deleted — moved)
• test/unit/scale-factor.spec.ts (expanded)
• test/unit/inverter-state.service.spec.ts (rewritten)
• eslint.config.mjs (new)
• .github/workflows/ci.yml (new)
• package.json, .npmrc, pnpm-lock.yaml, pnpm-workspace.yaml
• openspec/changes/sunspec-modbus-gateway/{design,tasks}.md (updated)

Refs: openspec/changes/sunspec-modbus-gateway/