@enyo-energy/sunspec-sdk 0.0.70 → 0.0.72

package/README.md

@@ -5,6 +5,9 @@ SunSpec Modbus client for reading data from solar inverters, batteries, meters,
 ## Table of Contents
 
 - [Appliance Manager Integration](#appliance-manager-integration)
+- [Battery Feature Modes](#battery-feature-modes)
+- [Battery Calibration](#battery-calibration)
+- [Storage Schedule Control](#storage-schedule-control)
 - [How Addressing Works](#how-addressing-works)
 - [Bulk Register Reading](#bulk-register-reading)
 - [Data Types](#data-types)
@@ -46,6 +49,305 @@ This SDK does not configure the strategy itself — it is the consumer app's res
 
 ---
 
+## Battery Feature Modes
+
+`SunspecBattery` populates `appliance.battery.features` for every connected battery — the list the host's topology / UI reads to decide which control surfaces to render. **The consumer chooses how that list is computed** by passing a required `featureMode` argument to the `SunspecBattery` constructor. There is no default; the choice is explicit so a SunSpec device whose register surface lies (or whose responsiveness is unknown) cannot silently turn into an actionable battery from the host's point of view.
+
+Three kinds are available, exposed via the `SunspecBatteryFeatureModeKind` enum:
+
+| Kind | Calibration allowed? | What appears in `appliance.battery.features` |
+|---|---|---|
+| `Disabled` | No (`configureCalibration` throws) | Exactly the `allowedFeatures` array the consumer passes — register state is ignored. |
+| `RegisterBased` | No (`configureCalibration` throws) | Features the SunSpec registers expose. Filtered down to `allowedFeatures` if that's set. |
+| `CalibrationBased` | Yes (required for controllable features to ever appear) | Same as `RegisterBased` for read-only features. The four controllable features stay hidden until the calibration result store reports the appliance as `calibrated`. |
+
+The four features the SDK treats as **controllable** (the ones calibration gates):
+
+- `EnyoBatteryFeature.GridCharging`
+- `EnyoBatteryFeature.GridDischarging`
+- `EnyoBatteryFeature.ChargeLimitation`
+- `EnyoBatteryFeature.DischargeLimitation`
+
+Every other `EnyoBatteryFeature` is **read-only** from the SDK's perspective and is published as soon as the corresponding register is present (in `RegisterBased` and `CalibrationBased`) or as soon as the consumer lists it (in `Disabled`).
+
+### `Disabled`
+
+Picks no registers, runs no calibration. Whatever the consumer lists in `allowedFeatures` becomes the published list; omit it (or pass `[]`) to publish nothing.
+
+Use when the host has out-of-band knowledge of the battery's capabilities — e.g. a curated commissioning database — and doesn't want the SDK inferring anything from registers it may not trust. Also useful for read-only deployments: omit `allowedFeatures` and the host will treat the battery as observation-only.
+
+```ts
+import { SunspecBattery, SunspecBatteryFeatureModeKind } from '@enyo-energy/sunspec-sdk';
+import { EnyoBatteryFeature } from '@enyo-energy/energy-app-sdk';
+
+const observationOnly = new SunspecBattery(
+    app, name, networkDevice, client, applianceManager,
+    { kind: SunspecBatteryFeatureModeKind.Disabled },
+    // → appliance.battery.features = []
+);
+
+const curated = new SunspecBattery(
+    app, name, networkDevice, client, applianceManager,
+    {
+        kind: SunspecBatteryFeatureModeKind.Disabled,
+        allowedFeatures: [EnyoBatteryFeature.GridCharging],
+    },
+    // → appliance.battery.features = ['grid-charging'], regardless of what the registers say
+);
+```
+
+Calling `configureCalibration(...)` on a `Disabled` battery throws.
+
+### `RegisterBased`
+
+The SDK looks at the SunSpec Model 124 registers and publishes the features whose underlying registers are present:
+
+- `chaGriSet` register present → `EnyoBatteryFeature.GridCharging`
+- `wChaMax` register present → `EnyoBatteryFeature.ChargeLimitation`
+
+Pass `allowedFeatures` to intersect the detected set with a whitelist — useful for hiding features the device exposes but the host doesn't want exercised. The allow-list **never** adds features that the registers don't expose; it is strictly a filter.
+
+```ts
+const trustRegisters = new SunspecBattery(
+    app, name, networkDevice, client, applianceManager,
+    { kind: SunspecBatteryFeatureModeKind.RegisterBased },
+    // → appliance.battery.features reflects whichever Model 124 controls are exposed
+);
+
+const trustRegistersButHideGridCharging = new SunspecBattery(
+    app, name, networkDevice, client, applianceManager,
+    {
+        kind: SunspecBatteryFeatureModeKind.RegisterBased,
+        allowedFeatures: [EnyoBatteryFeature.ChargeLimitation],
+    },
+    // → publishes ChargeLimitation only (even if chaGriSet is present)
+);
+```
+
+Calling `configureCalibration(...)` on a `RegisterBased` battery throws.
+
+### `CalibrationBased`
+
+Same register-driven detection as `RegisterBased` for read-only features, but the four controllable features stay stripped from the published list until `CalibrationResultStore.isCalibrated(applianceId)` returns `true` for this battery. Once the verdict flips, the next `readData()` cycle republishes the full set.
+
+`configureCalibration(...)` must be called after `connect()` — without it, controllable features stay hidden forever (safe-fallback behaviour).
+
+```ts
+const verified = new SunspecBattery(
+    app, name, networkDevice, client, applianceManager,
+    { kind: SunspecBatteryFeatureModeKind.CalibrationBased },
+);
+await verified.connect();
+verified.configureCalibration({ resultStore });   // see "Battery Calibration" below
+trigger.register(verified.getBatteryCalibrator()!);
+// Until trigger.tick() runs a successful test charge, controllable features are absent.
+// After it succeeds, they reappear within one readData() cycle.
+```
+
+See [Battery Calibration](#battery-calibration) for the full wiring of `resultStore`, `trigger`, and `configureCalibration` config.
+
+### Choosing a mode
+
+| Situation | Pick |
+|---|---|
+| Battery is observation-only, or the host already knows its capabilities | `Disabled` |
+| Trust the SunSpec register surface; no responsiveness verification needed | `RegisterBased` |
+| Want a test charge to confirm the battery actually reacts before exposing controls | `CalibrationBased` |
+
+The mode is fixed for the lifetime of the `SunspecBattery` instance. To switch modes, construct a new instance.
+
+---
+
+## Battery Calibration
+
+The SDK integrates [`@enyo-energy/appliance-calibration`](https://www.npmjs.com/package/@enyo-energy/appliance-calibration) to verify that a battery actually responds to control commands before the host action-taker is allowed to send it any. The verification is a short test charge wrapped in a snapshot/restore so a hung or crashed run never leaves writable registers in a half-modified state, and the verdict (`calibrated` / `not-supported` / `failed`) is persisted per appliance so it survives restarts.
+
+The SDK owns the SunSpec-specific pieces — the snapshot service, the vendor driver, the per-battery `BatteryCalibrator`. The **consumer owns the trigger and the result store**, so scheduling, multi-tenant storage namespacing, and command gating stay configurable.
+
+### Architecture
+
+| Piece | Lives in | Who builds it |
+|---|---|---|
+| `SunspecCalibrationStorage` (adapter over `EnergyAppStorage`) | this SDK | consumer (factory: `createSunspecCalibrationStorage(app)`) |
+| `CalibrationResultStore` (persisted verdict map) | `appliance-calibration` | consumer — **one shared instance** across batteries |
+| `SnapshotService<SunspecBatteryControls>` | `appliance-calibration` | SDK (per-battery, inside `SunspecBattery`) |
+| `SunspecBatteryCalibrationDriver` | this SDK | SDK (per-battery, inside `SunspecBattery`) |
+| `BatteryCalibrator<SunspecBatteryControls>` | `appliance-calibration` | SDK — built by `configureCalibration`, exposed via `getBatteryCalibrator` |
+| `CalibrationTrigger` | `appliance-calibration` | consumer — drives `runCalibration()` on its own schedule |
+
+### Feature mode
+
+Calibration is only relevant when `SunspecBattery` is constructed with `SunspecBatteryFeatureModeKind.CalibrationBased` — that's the mode under which the SDK gates controllable features on the calibration verdict. See [Battery Feature Modes](#battery-feature-modes) above for the full mode discussion; the rest of this section assumes the calibration-based mode has been selected.
+
+### Consumer wiring
+
+```ts
+import {
+    SunspecBattery,
+    SunspecBatteryFeatureModeKind,
+    // re-exported from @enyo-energy/appliance-calibration so you don't need a second import:
+    CalibrationResultStore,
+    CalibrationTrigger,
+    createSunspecCalibrationStorage,
+} from '@enyo-energy/sunspec-sdk';
+
+// 1. One storage adapter + one result store for the whole app — sharing the result store
+//    across batteries keeps the persisted verdict map from being clobbered by per-instance writes.
+const storage     = createSunspecCalibrationStorage(app);
+const resultStore = new CalibrationResultStore(storage);
+await resultStore.initialize();
+
+// 2. One trigger that fans out across every registered calibrator.
+const trigger = new CalibrationTrigger({ resultStore });
+
+// 3. Per battery: build it with the desired feature mode, then connect,
+//    then (only in calibration-based mode) configureCalibration + register.
+for (const config of batteryConfigs) {
+    const battery = new SunspecBattery(
+        app, name, networkDevice, client, applianceManager,
+        { kind: SunspecBatteryFeatureModeKind.CalibrationBased },
+        // unitId, port, baseAddress, ...
+    );
+    await battery.connect();
+    battery.configureCalibration({
+        resultStore,
+        // Optional — override any BatteryCalibratorConfig defaults (see "Tuning" below).
+        config: { testPowerW: 300 },
+    });
+    const calibrator = battery.getBatteryCalibrator();
+    if (calibrator) {
+        trigger.register(calibrator);
+    }
+}
+
+// 4. Drive the trigger on your own cadence. tick() runs at most one calibration per call
+//    and is a no-op for any battery that already has a stored result.
+client.useInterval().createInterval('30m', () => trigger.tick());
+```
+
+### Gate commands on the calibration result
+
+In whatever code emits battery commands, check the store synchronously before sending:
+
+```ts
+if (!resultStore.isCalibrated(applianceId)) {
+    console.log(`Skipping ${applianceId}: not calibrated yet`);
+    return;
+}
+// ...send the command
+```
+
+### Per-feature probes
+
+In `calibration-based` mode the SDK runs `SunspecBatteryFeatureCalibrator` (a subclass of the library's `BatteryCalibrator`) which **exercises each of the four controllable features individually** and records the outcomes in `CalibrationResult.notes` as JSON. Only features whose probes pass land in `appliance.battery.features` after calibration.
+
+The session is one snapshot → four probes → one restore. Probes run in this order so the battery has energy to discharge with by the end:
+
+| # | Probe | What it writes | Pass condition |
+|---|---|---|---|
+| 1 | `GridCharging` | `chaGriSet=GRID`, `wChaMax=testPowerW`, `inWRte=100`, `storCtlMod=CHARGE` | Battery power AND grid power both rise above `responseThresholdW` |
+| 2 | `ChargeLimitation` | same as above with `inWRte=50` | Charge power settles within `±responseThresholdW` of `testPowerW × 0.5` |
+| 3 | `DischargeLimitation` | `chaGriSet=PV`, `outWRte=50`, `storCtlMod=DISCHARGE` | Discharge power settles within `±responseThresholdW` of `testPowerW × 0.5` |
+| 4 | `GridDischarging` | `chaGriSet=PV`, `outWRte=100`, `storCtlMod=DISCHARGE` | Battery discharges AND meter shows reverse flow above `responseThresholdW` |
+
+Each probe runs a `writeBatteryControls(...)` then polls the driver's cached battery/grid power until either the predicate passes or `responseTimeoutMs` elapses. Between probes the SDK resets to a neutral state (`storCtlMod=AUTO`, `chaGriSet=PV`, `inWRte/outWRte=100`, `wChaMax=baseline`) so each probe starts cleanly. The final `restoreFromSnapshot` (run by the `SnapshotService` on `stopCalibration`) writes the original pre-calibration register set back regardless of outcome.
+
+#### SoC preconditions
+
+Probes refuse to run outside a useful SoC band and return `not-supported` instead — distinct from `failed` so the host can tell "device won't" apart from "we couldn't even try":
+
+- Charge probes (`GridCharging`, `ChargeLimitation`) need headroom: SoC ≥ 90% → `not-supported`.
+- Discharge probes (`DischargeLimitation`, `GridDischarging`) need energy: SoC ≤ 20% → `not-supported`.
+
+#### Aggregate verdict
+
+The library's `CalibrationResult.state` (one value per appliance) is computed from the four per-feature verdicts:
+
+| Per-feature verdicts | `CalibrationResult.state` |
+|---|---|
+| At least one `passed` | `calibrated` |
+| All `not-supported` | `not-supported` |
+| Otherwise (mix of `failed` / `not-supported`) | `failed` |
+
+`isCalibrated(applianceId)` therefore reads as **"the SDK probed this device and at least something is controllable"** — keep using it as the broad command-emission gate. The per-feature breakdown stored in `notes` is what `resolveAdvertisedFeatures` consults to decide *which* controllable features to publish; `decodeFeatureResults(result.notes)` returns the passing set and is exported for consumers that want to inspect it directly.
+
+#### Other operational notes
+
+- **Republishing cadence**: the controllable features reappear on the next `readData()` cycle after the calibrator persists its result — not synchronously when calibration completes. With a typical 10s/30s/1m poll cadence the appliance metadata follows within one cycle.
+- **Defence in depth**: the feature filter is complementary to the [`isCalibrated` command-gate](#gate-commands-on-the-calibration-result), not a substitute. The consumer's action-taker should still check `resultStore.isCalibrated(applianceId)` synchronously before every command write — the filter keeps the controllable surface off the appliance until the device is verified, but a race window exists between calibration completing and the next readData cycle.
+- **GridDischarge ambiguity**: SunSpec Model 124 has no register to *force* battery output toward the grid versus toward local load. The probe drives the battery into discharge and then watches the meter for export. If the host's local load eats the discharge there will be no export and the probe records `failed` with a note explaining the likely cause. Hosts that know their grid topology can map this to "controllable, but couldn't be verified".
+
+### What `configureCalibration` does under the hood
+
+For each battery it builds:
+
+- A `SunspecBatteryCalibrationDriver` that:
+  - Snapshots writable controls via `readBatteryControls()`.
+  - Restores them via `writeBatteryControls()` (whitelist: `storCtlMod`, `chaGriSet`, `wChaMax`, `inWRte`, `outWRte`, `minRsvPct`).
+  - Runs the test charge with the same 3-step sequence as `handleStartGridCharge` (`enableGridCharging(true)`, `wChaMax = powerW`, `setStorageMode(CHARGE)`).
+  - Reads battery power from a `LatestValueCache` fed by `SunspecBattery.readData()` each cycle.
+  - Reads grid power from a `LatestValueCache` fed by a `MeterValuesUpdateV1` data-bus subscription that's live for the driver's lifetime (so the grid signal works regardless of where the meter actually comes from).
+- A `BatteryCalibrator<SunspecBatteryControls>` wired to the driver, the per-battery `SnapshotService`, and the shared `resultStore`.
+
+Battery `disconnect()` tears the driver subscription down.
+
+### What still happens through the data bus
+
+The SDK also keeps listening for `StartCalibrationV1` / `StopCalibrationV1` data-bus messages so an external orchestrator (e.g. the action-taker) can begin and end a manual calibration session. Those handlers now drive the same `SnapshotService<T>` instance from `@enyo-energy/appliance-calibration`. While a manual session is active, any concurrent `SetInverterFeedInLimitV1` / `SetStorageChargeLimitV1` / etc. call records the field it touched into `modifiedFields`, and only those fields are written back on stop (or on the 5-minute auto-stop). This works exactly as before — the change is purely the implementation underneath.
+
+### Re-running a calibration
+
+The trigger runs each battery **once** — appliances already marked `calibrated`, `not-supported`, or `failed` are skipped on every subsequent `tick()`. To force a re-run, drop the persisted result for that key:
+
+```ts
+await app.useStorage().remove('battery-calibration');   // wipes ALL results (the default key)
+```
+
+If you need targeted invalidation, snapshot the store via `resultStore.snapshot()`, mutate the map, and re-save the survivors. Periodic re-calibration is a host concern — build it on top of `calibrator.runCalibration()` directly rather than going through `CalibrationTrigger`.
+
+### Tuning
+
+Override defaults via `configureCalibration({ resultStore, config })`:
+
+| Key | Default | When to change |
+|---|---|---|
+| `testPowerW` | 500 W | Smaller batteries; PV-only sites where 500 W is visible. |
+| `responseThresholdW` | 200 W | Noisier meters; tighter tolerance for known-good devices. |
+| `ackTimeoutMs` | 10 s | Slow Modbus links. |
+| `responseTimeoutMs` | 20 s | Devices that take longer to ramp. |
+| `pollIntervalMs` | 2 s | Faster polling for short-window tests. |
+
+See [`@enyo-energy/appliance-calibration`'s README](https://www.npmjs.com/package/@enyo-energy/appliance-calibration) for the full crash-safety contract and every result-store / snapshot-service knob.
+
+---
+
+## Storage Schedule Control
+
+`SunspecBattery` reacts to a single data-bus command for control: `EnyoDataBusSetStorageScheduleV1`. The message carries a `mode` (`auto` or `schedule`) and, when `mode` is `schedule`, a sorted `relativeSchedule` of `{seconds, direction, powerW}` entries. Subscription is automatic — each battery wires its own `SunspecBatteryScheduleHandler` (extending the SDK's `StorageScheduleHandler` from `@enyo-energy/energy-app-sdk`) during `connect()`. There is no consumer setup beyond connecting the battery.
+
+### What the SDK does on receipt
+
+1. Acks the message with `Accepted` immediately ("received & queued" — schedule entries play out over time).
+2. Snapshots the writable Model 124 registers (`storCtlMod`, `chaGriSet`, `wChaMax`, `inWRte`, `outWRte`) and persists them to `EnergyAppStorage` for restart-safe rollback.
+3. Activates the first entry immediately, then advances to subsequent entries as their `seconds` offsets elapse on a 1-second tick (driven by `EnergyApp.useInterval()`).
+4. Each `Charge` entry writes `chaGriSet=GRID`, `inWRte = powerW / installedWChaMax × 100`, `storCtlMod=CHARGE`.
+5. Each `Discharge` entry writes `chaGriSet=PV`, `outWRte = powerW / installedWChaMax × 100`, `storCtlMod=DISCHARGE`.
+6. On `mode: auto`, a replacement schedule, `disconnect()`, or process restart with an active schedule still persisted, the SDK restores the snapshotted pre-schedule registers via `onRollback`.
+
+### Power cap
+
+Scheduled `powerW` is clamped to the device's installed `wChaMax` because the handler holds that value stable as the denominator for the percentage math throughout the schedule. To request more than the installed maximum, raise `wChaMax` out-of-band before sending the schedule.
+
+### Calibration coexistence
+
+Each per-entry write is recorded into the calibration `SnapshotService` (when calibration is configured), so a calibration that starts mid-schedule still restores the right register set on stop / auto-stop.
+
+### Legacy messages
+
+The earlier `StartStorageGridChargeV1` / `StopStorageGridChargeV1` / `SetStorageChargeLimitV1` / `SetStorageDischargeLimitV1` family is **no longer handled** by this SDK. Their type defs in `@enyo-energy/energy-app-sdk` are flagged `@deprecated` with pointers to `SetStorageScheduleV1`. Migrate any callers that still emit them.
+
+---
+
 ## How Addressing Works
 
 ### Base Address Detection

package/dist/calibration-snapshot-service.d.ts

@@ -0,0 +1,67 @@
+import { EnergyAppStorage } from "@enyo-energy/energy-app-sdk/dist/packages/energy-app-storage.js";
+import type { SunspecBatteryControls, SunspecInverterControls } from "./sunspec-interfaces.js";
+export type CalibrationDeviceType = "inverter" | "battery";
+/**
+ * Persisted snapshot of a device's writable control registers, taken at the start of a
+ * calibration. Used to roll the device back when calibration ends.
+ *
+ * `modifiedFields` records which control-block field names were touched by *other* write
+ * commands (SetInverterFeedInLimitV1, StartStorageGridChargeV1, etc.) while the calibration
+ * was active — on stop, only those fields are written back, leaving fields the calibration
+ * itself didn't disturb alone.
+ */
+export interface CalibrationSnapshot {
+    applianceId: string;
+    deviceType: CalibrationDeviceType;
+    unitId: number;
+    startedAtIso: string;
+    inverterControls?: SunspecInverterControls;
+    batteryControls?: SunspecBatteryControls;
+    modifiedFields: string[];
+}
+/** Calibration is capped at 5 minutes of wall time, including across restarts. */
+export declare const CALIBRATION_AUTO_STOP_MS: number;
+export type CalibrationRestoreReason = "stop" | "auto";
+export type CalibrationRestoreCallback = (snapshot: CalibrationSnapshot, reason: CalibrationRestoreReason) => Promise<void>;
+/**
+ * Per-appliance service that snapshots a SunSpec device's writable control registers when a
+ * calibration starts, tracks which registers other commands mutate while it is active, and
+ * restores those registers when calibration stops (either explicitly or via the 5-minute
+ * auto-stop timer).
+ *
+ * Snapshots are persisted via `EnergyAppStorage` so a crash/restart mid-calibration does not
+ * leave the device in a calibration state without a rollback. On `initialize()`, any stored
+ * snapshot is reloaded; the auto-stop deadline is computed from `startedAtIso` so total
+ * calibration time remains capped at `autoStopMs` across restarts.
+ */
+export declare class CalibrationSnapshotService {
+    private readonly storage;
+    private readonly applianceId;
+    private readonly onRestore;
+    private readonly autoStopMs;
+    private snapshot?;
+    private autoStopTimer?;
+    constructor(storage: EnergyAppStorage, applianceId: string, onRestore: CalibrationRestoreCallback, autoStopMs?: number);
+    private storageKey;
+    initialize(): Promise<void>;
+    isCalibrating(): boolean;
+    getSnapshot(): CalibrationSnapshot | undefined;
+    startCalibration(input: {
+        deviceType: CalibrationDeviceType;
+        unitId: number;
+        inverterControls?: SunspecInverterControls;
+        batteryControls?: SunspecBatteryControls;
+    }): Promise<void>;
+    recordModification(fields: string[]): Promise<void>;
+    /**
+     * Clear the timer, remove the snapshot from memory + storage, and return the snapshot so
+     * the caller can restore the modified registers. Returns undefined if no calibration was
+     * active.
+     */
+    stopCalibration(): Promise<CalibrationSnapshot | undefined>;
+    private remainingMs;
+    private scheduleAutoStop;
+    private clearAutoStopTimer;
+    private fireAutoStop;
+    private persist;
+}

package/dist/calibration-snapshot-service.js

@@ -0,0 +1,160 @@
+/** Calibration is capped at 5 minutes of wall time, including across restarts. */
+export const CALIBRATION_AUTO_STOP_MS = 5 * 60 * 1000;
+/**
+ * Per-appliance service that snapshots a SunSpec device's writable control registers when a
+ * calibration starts, tracks which registers other commands mutate while it is active, and
+ * restores those registers when calibration stops (either explicitly or via the 5-minute
+ * auto-stop timer).
+ *
+ * Snapshots are persisted via `EnergyAppStorage` so a crash/restart mid-calibration does not
+ * leave the device in a calibration state without a rollback. On `initialize()`, any stored
+ * snapshot is reloaded; the auto-stop deadline is computed from `startedAtIso` so total
+ * calibration time remains capped at `autoStopMs` across restarts.
+ */
+export class CalibrationSnapshotService {
+    storage;
+    applianceId;
+    onRestore;
+    autoStopMs;
+    snapshot;
+    autoStopTimer;
+    constructor(storage, applianceId, onRestore, autoStopMs = CALIBRATION_AUTO_STOP_MS) {
+        this.storage = storage;
+        this.applianceId = applianceId;
+        this.onRestore = onRestore;
+        this.autoStopMs = autoStopMs;
+    }
+    storageKey() {
+        return `sunspec-calibration-snapshot-${this.applianceId}`;
+    }
+    async initialize() {
+        try {
+            const loaded = await this.storage.load(this.storageKey());
+            if (!loaded) {
+                return;
+            }
+            this.snapshot = loaded;
+            console.log(`CalibrationSnapshotService ${this.applianceId}: loaded persisted snapshot (started ${loaded.startedAtIso}, modifiedFields=[${loaded.modifiedFields.join(', ')}])`);
+            const remainingMs = this.remainingMs(loaded);
+            if (remainingMs <= 0) {
+                console.warn(`CalibrationSnapshotService ${this.applianceId}: snapshot exceeded ${this.autoStopMs}ms deadline — auto-restoring immediately`);
+                await this.fireAutoStop();
+            }
+            else {
+                this.scheduleAutoStop(remainingMs);
+            }
+        }
+        catch (error) {
+            console.error(`CalibrationSnapshotService ${this.applianceId}: failed to load persisted snapshot: ${error}`);
+        }
+    }
+    isCalibrating() {
+        return this.snapshot !== undefined;
+    }
+    getSnapshot() {
+        return this.snapshot;
+    }
+    async startCalibration(input) {
+        this.clearAutoStopTimer();
+        this.snapshot = {
+            applianceId: this.applianceId,
+            deviceType: input.deviceType,
+            unitId: input.unitId,
+            startedAtIso: new Date().toISOString(),
+            inverterControls: input.inverterControls,
+            batteryControls: input.batteryControls,
+            modifiedFields: [],
+        };
+        await this.persist();
+        this.scheduleAutoStop(this.autoStopMs);
+        console.log(`CalibrationSnapshotService ${this.applianceId}: calibration started for ${input.deviceType} (auto-stop in ${this.autoStopMs}ms)`);
+    }
+    async recordModification(fields) {
+        if (!this.snapshot) {
+            return;
+        }
+        let added = false;
+        for (const field of fields) {
+            if (!this.snapshot.modifiedFields.includes(field)) {
+                this.snapshot.modifiedFields.push(field);
+                added = true;
+            }
+        }
+        if (added) {
+            await this.persist();
+            console.log(`CalibrationSnapshotService ${this.applianceId}: tracked modified fields [${this.snapshot.modifiedFields.join(', ')}]`);
+        }
+    }
+    /**
+     * Clear the timer, remove the snapshot from memory + storage, and return the snapshot so
+     * the caller can restore the modified registers. Returns undefined if no calibration was
+     * active.
+     */
+    async stopCalibration() {
+        this.clearAutoStopTimer();
+        const snap = this.snapshot;
+        this.snapshot = undefined;
+        if (snap) {
+            try {
+                await this.storage.remove(this.storageKey());
+            }
+            catch (error) {
+                console.error(`CalibrationSnapshotService ${this.applianceId}: failed to remove persisted snapshot: ${error}`);
+            }
+        }
+        return snap;
+    }
+    remainingMs(snap) {
+        const startedAtMs = Date.parse(snap.startedAtIso);
+        if (Number.isNaN(startedAtMs)) {
+            return this.autoStopMs;
+        }
+        return startedAtMs + this.autoStopMs - Date.now();
+    }
+    scheduleAutoStop(delayMs) {
+        this.clearAutoStopTimer();
+        this.autoStopTimer = setTimeout(() => {
+            void this.fireAutoStop();
+        }, delayMs);
+        if (typeof this.autoStopTimer.unref === "function") {
+            this.autoStopTimer.unref();
+        }
+    }
+    clearAutoStopTimer() {
+        if (this.autoStopTimer) {
+            clearTimeout(this.autoStopTimer);
+            this.autoStopTimer = undefined;
+        }
+    }
+    async fireAutoStop() {
+        const snap = this.snapshot;
+        this.snapshot = undefined;
+        this.clearAutoStopTimer();
+        if (!snap) {
+            return;
+        }
+        try {
+            await this.storage.remove(this.storageKey());
+        }
+        catch (error) {
+            console.error(`CalibrationSnapshotService ${this.applianceId}: failed to remove persisted snapshot during auto-stop: ${error}`);
+        }
+        try {
+            await this.onRestore(snap, "auto");
+        }
+        catch (error) {
+            console.error(`CalibrationSnapshotService ${this.applianceId}: auto-stop restore failed: ${error}`);
+        }
+    }
+    async persist() {
+        if (!this.snapshot) {
+            return;
+        }
+        try {
+            await this.storage.save(this.storageKey(), this.snapshot);
+        }
+        catch (error) {
+            console.error(`CalibrationSnapshotService ${this.applianceId}: failed to persist snapshot: ${error}`);
+        }
+    }
+}