refactor(meter-values): extract CoherentMeterValuesManager, shrink ICoherentContext, split OCPP16 begin helper (issue #1936 items a, b, e) (#1937)

* refactor(meter-values): extract CoherentMeterValuesManager (issue #1936)

Extract per-station coherent MeterValues lifecycle owner from
ChargingStation into a dedicated singleton-per-station manager,
mirroring the multiton pattern of AutomaticTransactionGenerator /
IdTagsCache / SharedLRUCache (keyed by stationInfo.hashId).

The manager owns the EV profile file, the active-session Map, and
the create/destroy/inject lifecycle. ChargingStation keeps the four
public methods as thin delegators for API stability — external OCPP
handler call sites, the test helper mock, and existing tests are
unchanged.

Behavior is preserved:
- Sessions are still created only when coherentMeterValues=true AND
  a valid EV profile file loads.
- The __injectCoherentSession NODE_ENV production guard is preserved
  on the manager side (BaseError throw).
- Session runtime state is disposed at every reset/stop/disconnect
  path via destroySession, and at station stop/delete via dispose /
  deleteInstance.

Closes issue #1936 item (a).

* refactor(meter-values): thread coherent session, shrink ICoherentContext (issue #1936)

Drop `getCoherentSession` from `ICoherentContext`: the port now
exposes only what the physics chain needs to query about the station
itself. Session lookup moves to the caller (the strategy gate), which
looks up via `ChargingStation.getCoherentSession` — the A1 delegator
that routes through `CoherentMeterValuesManager` in production and
through the test-mock's own Map in tests.

Signature changes:
- `isCoherentModeActive(session): session is CoherentSession` — pure
  type guard replacing the two-tier (stationInfo + session-lookup)
  predicate. The stationInfo gate is implied by session existence
  (sessions are only created via the manager when
  `coherentMeterValues=true`).
- `buildCoherentMeterValue(context, session, ...)` — takes the session
  directly. The internal `context.getCoherentSession` lookup and the
  "missing session" warning branch collapse to a single connector-lookup
  guard.

Strategy gate call sites in `OCPPServiceUtils.buildMeterValue` and
`OCPP16ServiceUtils.buildTransactionBeginMeterValue` are threaded
accordingly.

Behavior preserved: sessions are still only routed to the coherent path
when they exist; random/fixed path is untouched. Test suite invariant
`fail: 0, skipped: 6` holds.

Closes issue #1936 item (b).

* refactor(ocpp16): extract buildCoherentTransactionBeginMeterValue (issue #1936)

Split OCPP16ServiceUtils.buildTransactionBeginMeterValue's dual
responsibility. The coherent short-circuit (route through
buildMeterValue with the vendor StartTxnSampledData override) moves to
a named private static helper; the outer function keeps only the
random/fixed default path plus the strategy gate.

The strategy gate in OCPP 1.6 now lives at a single well-labeled
boundary in this file, mirroring the pattern established by
OCPPServiceUtils.buildMeterValue for the periodic MeterValues path.

Behavior is unchanged: same measurand-key resolution, same
buildMeterValue re-dispatch, same TRANSACTION_BEGIN context.

Closes issue #1936 item (e).

* refactor(meter-values): add peekInstance to avoid phantom manager allocation (issue #1936)

PR-A round-1 Oracle review (lanes A + D converged on this MAJOR
finding): the strategy gate in `OCPPServiceUtils.buildMeterValue`
reaches `ChargingStation.getCoherentSession` unconditionally on every
MeterValue tick, and the delegator was routed through
`CoherentMeterValuesManager.getInstance` — a lazy-create factory.
Result: every station that ever emits a MeterValue allocated a
`CoherentMeterValuesManager` + Map, regardless of the `coherentMeterValues`
opt-in flag. This contradicted the file-header design contract that
'stations with the option off never allocate a manager'.

Fix: add `CoherentMeterValuesManager.peekInstance(cs)` — a lookup-only
sibling of `getInstance` that never constructs. Route the four
read/destroy/dispose sites through `peekInstance`:
- `ChargingStation.createCoherentSession` (opt-in station's manager
  is warmed up at initialize; non-opt-in stations return `undefined`
  without allocating).
- `ChargingStation.destroyCoherentSession`
- `ChargingStation.getCoherentSession` (the strategy-gate hot path).
- `ChargingStation.stop()` finally-block dispose.

Keep `getInstance` (create-if-missing) at:
- `ChargingStation.__injectCoherentSession` — production-guard
  BaseError throw must remain reachable if this test seam is
  accidentally called in prod.
- `ChargingStation.initialize` — the opt-in eager warm-up that surfaces
  EV-profile-file warnings at startup rather than at first transaction.

Also tighten `getInstance` JSDoc to state precisely that `undefined` is
returned iff `stationInfo.hashId` is not yet resolved (the sole failure
mode), and cross-reference `peekInstance` for read paths.

Behavior for opt-in stations is unchanged (warm-up allocates the same
manager, subsequent reads find it in the cache). Non-opt-in stations
no longer allocate. Test invariant `fail: 0, skipped: 6` holds.

Closes issue #1936 item (a) sub-finding from round-1 review.

* docs(meter-values): tighten getInstance/peekInstance JSDoc post round-2 review (issue #1936)

PR-A round-2 Oracle review (lanes A + B converged on JSDoc precision):

- Lane A: `getInstance` JSDoc still listed `createSession` as a caller,
  but the round-1 fix routed `createSession` through `peekInstance`.
  A future reader following the JSDoc could reintroduce the phantom-
  allocation bug at the exact site it was just patched.
- Lane B: JSDoc labeled `destroySession` and `stop()` dispose as
  "read-only paths". Both are actually mutations (Map.delete +
  PRNG-closure disposal). Reword to "paths that must not allocate a
  manager on behalf of non-opt-in stations".
- Lane A NIT: the eager-init invariant is load-bearing — if
  `ChargingStation.initialize` stops warming up the manager for opt-in
  stations, `createCoherentSession` silently no-ops. The invariant was
  implicit; make it explicit in `peekInstance` JSDoc.

Docs-only. No runtime change. Test invariant `fail: 0, skipped: 6` holds.

* fix(meter-values): propagate template reload to coherent manager (issue #1936)

The template file watcher and reset() path already flush sharedLRUCache,
idTagsCache, and OCPPAuthServiceFactory before calling initialize(). The
coherent manager was left behind: getInstance returned the cached
manager for the unchanged hashId, whose evProfiles were snapshotted at
first-construction, so runtime mutations of evProfilesFile or its file
contents did not take effect until process restart.

Wire reloadEvProfiles() into every initialize() invocation so template
mutations propagate. Symmetrically drop the manager entirely when the
coherentMeterValues opt-in flips true to false so cached sessions and
stale profile data do not leak across the config change.

* refactor(meter-values): gate injectSession, harmonize banner and JSDoc (issue #1936)

injectSession test seam now honors the stationInfo.coherentMeterValues
opt-in gate. Pre-refactor, isCoherentModeActive checked the flag on
every tick; post-refactor it trusts session existence. Without the gate,
a test could inject a session on a non-opt-in station and activate the
coherent wire path — contradicting the type-guard precondition.
Production is already protected by the NODE_ENV production throw.

Align copyright banner to the sibling verbatim form
('Partial Copyright Jerome Benoit. 2021-2025').

Harmonize JSDoc: peekInstance MUST-use list now includes createSession
(mirrors getInstance JSDoc); reloadEvProfiles fail-soft description
covers non-opt-in stations and any error; 'cache miss' prose replaced
with 'instances-map miss' to match the field name.

* refactor(meter-values): preserve in-flight coherent sessions across opt-in flag flip (issue #1936)

The previous initialize() logic dropped the CoherentMeterValuesManager
via deleteInstance() when coherentMeterValues flipped true to false.
That immediately disposed every in-flight coherent session — and, in
the template file watcher flow where initialize() runs before
stopAutomaticTransactionGenerator(), that produced mixed-provenance
TransactionEvent frames on OCPP 2.0.x: the Begin frame was coherent,
the Update/End frames after the flip fell through the strategy gate
to random path, and the CSMS saw a discontinuous transaction.

Remove the else branch. New sessions are already blocked by the
coherentMeterValues gate in createSession; existing in-flight
sessions drain naturally via destroyCoherentSession on transaction
end. Provenance is preserved for transactions started before the
flag flip, and the reloadEvProfiles propagation on the true branch
(the round-1 MAJOR fix) is unaffected.

* docs(meter-values): calibrate injectSession JSDoc for mock-helper reality (issue #1936)

The prior JSDoc claimed the opt-in guard means isCoherentModeActive
cannot be tricked into activating the coherent wire path by
injecting on a non-opt-in station. That is true only for the
production-backed injection path (through the real
CoherentMeterValuesManager.injectSession). Tests that mock
ChargingStation write to their own session store bypassing this
seam entirely, so the mock is responsible for enforcing its own
opt-in invariant where relevant. Calibrate the JSDoc scope
accordingly.

Author: jerome-benoit

cspell.config.yaml

@@ -28,6 +28,7 @@ words:
   - unpushed
   - logform
   - mnemonist
+  - multiton
   - poolifier
   - measurand
   - measurands

src/charging-station/ChargingStation.ts

@@ -9,6 +9,8 @@ import { URL } from 'node:url'
 import { parentPort } from 'node:worker_threads'
 import { type RawData, WebSocket } from 'ws'
 
+import type { CoherentSession } from './meter-values/index.js'
+
 import { BaseError, OCPPError } from '../exception/index.js'
 import { PerformanceStatistics } from '../performance/index.js'
 import {
@@ -110,6 +112,7 @@ import {
 } from '../utils/index.js'
 import { AutomaticTransactionGenerator } from './AutomaticTransactionGenerator.js'
 import { ChargingStationWorkerBroadcastChannel } from './broadcast-channel/ChargingStationWorkerBroadcastChannel.js'
+import { CoherentMeterValuesManager } from './CoherentMeterValuesManager.js'
 import {
   addConfigurationKey,
   deleteConfigurationKey,
@@ -132,7 +135,6 @@ import {
   getConnectorChargingProfilesLimit,
   getDefaultConnectorMaximumPower,
   getDefaultVoltageOut,
-  getEvProfilesFile,
   getHashId,
   getIdTagsFile,
   getMaxNumberOfConnectors,
@@ -148,14 +150,6 @@ import {
   validateStationInfo,
 } from './Helpers.js'
 import { IdTagsCache } from './IdTagsCache.js'
-import { disposeCoherentSessionRuntime } from './meter-values/CoherentMeterValuesGenerator.js'
-import {
-  type CoherentSession,
-  createCoherentSession,
-  type EvProfilesFile,
-  loadEvProfilesFile,
-  resolveRootSeed,
-} from './meter-values/index.js'
 import {
   buildBootNotificationRequest,
   createOCPPServices,
@@ -215,8 +209,6 @@ export class ChargingStation extends EventEmitter {
 
   private automaticTransactionGeneratorConfiguration?: AutomaticTransactionGeneratorConfiguration
   private readonly chargingStationWorkerBroadcastChannel: ChargingStationWorkerBroadcastChannel
-  private coherentEvProfiles?: EvProfilesFile
-  private readonly coherentSessions: Map<number | string, CoherentSession>
   private configurationFile!: string
   private configurationFileHash!: string
   private configuredSupervisionUrl!: URL
@@ -252,7 +244,6 @@ export class ChargingStation extends EventEmitter {
     this.sharedLRUCache = SharedLRUCache.getInstance()
     this.idTagsCache = IdTagsCache.getInstance()
     this.chargingStationWorkerBroadcastChannel = new ChargingStationWorkerBroadcastChannel(this)
-    this.coherentSessions = new Map<number | string, CoherentSession>()
 
     this.on(ChargingStationEvents.added, () => {
       parentPort?.postMessage(buildAddedMessage(this))
@@ -316,20 +307,15 @@ export class ChargingStation extends EventEmitter {
 
   /**
    * Injects a pre-built coherent session directly into the session store.
-   * **Test seam only** — never call from production code; enforced at
-   * runtime by a `NODE_ENV === 'production'` guard that throws
-   * {@link BaseError}.
+   * **Test seam only** — delegates to
+   * {@link CoherentMeterValuesManager.injectSession}, which enforces the
+   * `NODE_ENV === 'production'` guard.
    * @param transactionId - Transaction identifier.
    * @param session - Pre-built session.
    * @throws {BaseError} When invoked in a production build.
    */
   public __injectCoherentSession (transactionId: number | string, session: CoherentSession): void {
-    if (process.env.NODE_ENV === 'production') {
-      throw new BaseError(
-        `${this.logPrefix()} ${moduleName}.__injectCoherentSession: test-only seam called in production build`
-      )
-    }
-    this.coherentSessions.set(transactionId, session)
+    CoherentMeterValuesManager.getInstance(this)?.injectSession(transactionId, session)
   }
 
   /**
@@ -377,8 +363,14 @@ export class ChargingStation extends EventEmitter {
 
   /**
    * Creates or returns the coherent MeterValues session for a transaction.
-   * Idempotent. Returns `undefined` when coherent mode is disabled or no
-   * valid EV profile file is loaded.
+   * Idempotent. Delegates to
+   * {@link CoherentMeterValuesManager.createSession}; returns `undefined`
+   * when coherent mode is disabled or no valid EV profile file is loaded.
+   *
+   * Uses `peekInstance` (lookup-only): opt-in stations warm up the
+   * manager at initialize, so subsequent calls find it in the cache;
+   * non-opt-in stations never allocate a manager because
+   * `manager.createSession` would return `undefined` anyway.
    * @param transactionId - Transaction identifier from the CSMS.
    * @param connectorId - Connector on which the transaction is running.
    * @returns The active or newly-created session, or `undefined` when
@@ -388,27 +380,7 @@ export class ChargingStation extends EventEmitter {
     transactionId: number | string,
     connectorId: number
   ): CoherentSession | undefined {
-    const existing = this.coherentSessions.get(transactionId)
-    if (existing != null) {
-      return existing
-    }
-    if (this.stationInfo?.coherentMeterValues !== true) {
-      return undefined
-    }
-    if (this.coherentEvProfiles == null || this.coherentEvProfiles.profiles.length === 0) {
-      return undefined
-    }
-    const rootSeed = resolveRootSeed(this.stationInfo)
-    const session = createCoherentSession(this, {
-      connectorId,
-      profiles: this.coherentEvProfiles.profiles,
-      rootSeed,
-      transactionId,
-    })
-    if (session != null) {
-      this.coherentSessions.set(transactionId, session)
-    }
-    return session
+    return CoherentMeterValuesManager.peekInstance(this)?.createSession(transactionId, connectorId)
   }
 
   /**
@@ -428,6 +400,7 @@ export class ChargingStation extends EventEmitter {
       }
     }
     AutomaticTransactionGenerator.deleteInstance(this)
+    CoherentMeterValuesManager.deleteInstance(this)
     PerformanceStatistics.deleteInstance(this.stationInfo?.hashId)
     OCPPAuthServiceFactory.clearInstance(this)
     if (this.stationInfo != null) {
@@ -467,17 +440,16 @@ export class ChargingStation extends EventEmitter {
 
   /**
    * Removes the coherent session for a transaction. Idempotent — safe to
-   * call from every reset/stop/disconnect path. Also disposes the module-scope
-   * per-session runtime state (voltage-noise PRNG closure).
+   * call from every reset/stop/disconnect path. Delegates to
+   * {@link CoherentMeterValuesManager.destroySession}, which disposes the
+   * module-scope per-session runtime state (voltage-noise PRNG closure).
+   * Uses `peekInstance` so non-opt-in stations never allocate a manager
+   * on a transaction-end tear-down.
    * @param transactionId - Transaction identifier.
    * @returns `true` when a session was removed, `false` otherwise.
    */
   public destroyCoherentSession (transactionId: number | string | undefined): boolean {
-    if (transactionId == null) {
-      return false
-    }
-    disposeCoherentSessionRuntime(this.coherentSessions.get(transactionId))
-    return this.coherentSessions.delete(transactionId)
+    return CoherentMeterValuesManager.peekInstance(this)?.destroySession(transactionId) ?? false
   }
 
   /**
@@ -540,12 +512,17 @@ export class ChargingStation extends EventEmitter {
   }
 
   /**
-   * Retrieves the coherent session for a transaction, if any.
+   * Retrieves the coherent session for a transaction, if any. Delegates
+   * to {@link CoherentMeterValuesManager.getSession}. Uses `peekInstance`
+   * because this method is reached from the unconditional strategy gate
+   * in `OCPPServiceUtils.buildMeterValue` on every MeterValue tick — a
+   * `getInstance` here would allocate a manager for every station that
+   * ever emits a MeterValue, opt-in or not.
    * @param transactionId - Transaction identifier.
    * @returns The session or `undefined` when none exists.
    */
   public getCoherentSession (transactionId: number | string): CoherentSession | undefined {
-    return this.coherentSessions.get(transactionId)
+    return CoherentMeterValuesManager.peekInstance(this)?.getSession(transactionId)
   }
 
   public getConnectionTimeout (): number {
@@ -1314,10 +1291,7 @@ export class ChargingStation extends EventEmitter {
           // Drop any coherent sessions still tracked at shutdown so a
           // subsequent restart cannot resurrect stale state or leak
           // module-scope runtime PRNG closures.
-          for (const session of this.coherentSessions.values()) {
-            disposeCoherentSessionRuntime(session)
-          }
-          this.coherentSessions.clear()
+          CoherentMeterValuesManager.peekInstance(this)?.dispose()
           this.stopping = false
         }
       } else {
@@ -1911,7 +1885,18 @@ export class ChargingStation extends EventEmitter {
       }
     }
     this.saveStationInfo()
-    this.initializeCoherentEvProfiles()
+    // Warm up the coherent MeterValues manager on opt-in so
+    // EV-profile-file warnings surface at startup, and reload profiles
+    // on every subsequent `initialize()` (reset, template file change)
+    // to propagate template mutations. On opt-out we deliberately
+    // leave any pre-existing manager in place: new sessions are
+    // already blocked by the `coherentMeterValues` gate in
+    // `createSession`, and in-flight sessions drain via
+    // `destroyCoherentSession` on transaction end — preserving
+    // provenance of transactions started before the flag flip.
+    if (this.stationInfo.coherentMeterValues === true) {
+      CoherentMeterValuesManager.getInstance(this)?.reloadEvProfiles()
+    }
     this.configuredSupervisionUrl = this.getConfiguredSupervisionUrl()
     if (this.stationInfo.enableStatistics === true) {
       this.performanceStatistics = PerformanceStatistics.getInstance(
@@ -1942,33 +1927,6 @@ export class ChargingStation extends EventEmitter {
     }
   }
 
-  /**
-   * Loads and validates the EV profile file when coherent MeterValues are
-   * enabled. Fail-soft: any error disables coherent mode for this station
-   * (createCoherentSession then becomes a no-op).
-   */
-  private initializeCoherentEvProfiles (): void {
-    this.coherentEvProfiles = undefined
-    if (this.stationInfo?.coherentMeterValues !== true) {
-      return
-    }
-    const evProfilesFile = getEvProfilesFile(this.stationInfo)
-    if (evProfilesFile == null) {
-      logger.warn(
-        `${this.logPrefix()} ${moduleName}.initializeCoherentEvProfiles: coherentMeterValues=true but no evProfilesFile is configured, coherent MeterValues disabled`
-      )
-      return
-    }
-    const loaded = loadEvProfilesFile(evProfilesFile, this.logPrefix())
-    if (loaded == null) {
-      logger.warn(
-        `${this.logPrefix()} ${moduleName}.initializeCoherentEvProfiles: EV profiles could not be loaded, coherent MeterValues disabled`
-      )
-      return
-    }
-    this.coherentEvProfiles = loaded
-  }
-
   private initializeConnectorsFromTemplate (stationTemplate: ChargingStationTemplate): void {
     if (stationTemplate.Connectors == null && isEmpty(this.connectors)) {
       const errorMsg = `No already defined connectors and charging station information from template ${this.templateFile} with no connectors configuration defined`