import { Decimal } from 'decimal.js-light' import type { LedgerView, PositionEntry, PositionUpdate, Timescale } from '@vpp/domain' import { PositionUpdate as PositionUpdateSchema } from '@vpp/domain' export class LedgerConcurrencyError extends Error { constructor(expected: number, actual: number) { super(`ledger version mismatch: update expected ${expected}, current is ${actual}`) this.name = 'LedgerConcurrencyError' } } export class CascadeViolation extends Error { constructor(message: string) { super(message) this.name = 'CascadeViolation' } } export interface LedgerConfig { /** * Allowed relative deviation of a day-ahead bid's daily energy from the * pro-rata daily share of the monthly contracted position. * OPEN-QUESTION A5: the real Hubei decomposition-band rule may differ in * shape (cumulative month-to-date band? asymmetric?) — see docs/open-questions.md. */ daMonthlyDeviationBand: string // e.g. "0.05" = ±5% clock?: () => string } /** * Position ledger v1 (docs/00 §4, P7): in-memory, optimistic concurrency, * per-timescale views, and the constraint cascade — upper-timescale positions * bound lower-timescale writes. Storage adapter (Postgres) arrives with M3. */ export class LedgerService { private version = 0 private entries: PositionEntry[] = [] constructor(private readonly cfg: LedgerConfig) {} read(): LedgerView { return { version: this.version, entries: [...this.entries] } } viewByTimescale(timescale: Timescale): PositionEntry[] { return this.entries.filter((e) => e.timescale === timescale) } append(update: PositionUpdate): LedgerView { PositionUpdateSchema.parse(update) if (update.expected_version !== this.version) { throw new LedgerConcurrencyError(update.expected_version, this.version) } this.checkCascade(update) const { expected_version: _ignored, ...rest } = update const entry: PositionEntry = { ...rest, recorded_at: this.cfg.clock?.() ?? new Date().toISOString(), } this.entries.push(entry) this.version += 1 return this.read() } /** * Constraint cascade (P7): a DAY_AHEAD bid submission must stay within the * band around the pro-rata daily share of the MONTHLY contracted position. * No monthly position for the month → nothing to cascade from → reject * (bidding without a position of record is a lineage failure, not a default-allow). */ private checkCascade(update: PositionUpdate): void { if (update.kind !== 'BID_SUBMITTED' || update.timescale !== 'DAY_AHEAD') return const month = update.period.slice(0, 7) const monthly = this.entries.filter( (e) => e.timescale === 'MONTHLY' && e.kind === 'CONTRACT' && e.period === month, ) if (monthly.length === 0) { throw new CascadeViolation( `no MONTHLY CONTRACT position recorded for ${month}; day-ahead bid has no cascade anchor`, ) } const contracted = monthly.reduce((sum, e) => sum.add(new Decimal(e.energy_mwh)), new Decimal(0)) const daysInMonth = new Date( Date.UTC(Number(month.slice(0, 4)), Number(month.slice(5, 7)), 0), ).getUTCDate() const dailyShare = contracted.div(daysInMonth) const band = new Decimal(this.cfg.daMonthlyDeviationBand) const min = dailyShare.mul(new Decimal(1).sub(band)) const max = dailyShare.mul(new Decimal(1).add(band)) const bid = new Decimal(update.energy_mwh) if (bid.lt(min) || bid.gt(max)) { throw new CascadeViolation( `day-ahead bid ${bid.toString()} MWh outside monthly cascade band ` + `[${min.toString()}, ${max.toString()}] (contracted ${contracted.toString()} MWh / ${daysInMonth} days ± ${band.mul(100).toString()}%)`, ) } } }