@genesislcap/ai-assistant 15.6.2 → 15.7.1

package/src/utils/banked-usage-baselines.ts

@@ -0,0 +1,90 @@
+import type { AggregateUsage } from '@genesislcap/foundation-ai';
+
+/**
+ * Per-session banked baselines for the cost ledger (GENC-1475) — the spend a project had
+ * accrued *before* the transcript currently in memory. Module-level and keyed by the session
+ * `stateKey`, exactly like the diagnostics cursors and the meta-event buffer.
+ *
+ * The lifetime is the point of this module. A baseline is only meaningful paired with the
+ * transcript it complements: `row.usage = baseline + whatever that transcript proves`. The
+ * transcript lives in the per-key session store, so the baseline must live and die with that
+ * store — which means module state keyed the same way, NOT element state.
+ *
+ * Held on the element it silently double-counted. Element instances are created and destroyed
+ * many times inside one session (the assistant is remounted as the host re-renders its layout,
+ * and a popped-out bubble and a docked panel can be wired to the same session at once), and each
+ * new instance re-derived the baseline from the ledger rows. By then those rows contain the
+ * instance-before-last's own upserts, whose `usage` already includes the live transcript — so
+ * where the transcript is NOT restored on load (`resolveBankedUsage`'s "bank the whole prior
+ * total" branch, i.e. persistence off) the live session was banked as its own baseline. Lifetime
+ * then jumped by the whole session-to-date on every remount while the live figure kept climbing
+ * normally, which is the "the two totals went up by different amounts" report.
+ *
+ * Module state dies with the JS realm, so a real page reload starts clean — exactly right, since
+ * that is also when the transcript starts over.
+ *
+ * @internal
+ */
+const baselinesByKey = new Map<string, AggregateUsage>();
+
+/**
+ * The baseline resolved for `key`, or `undefined` when this session has not resolved one yet.
+ *
+ * `undefined` rather than an empty usage: "nothing banked" is a legitimate resolved value (a
+ * project's first ever session), and it must not be mistaken for "not resolved", or every write
+ * would re-derive and hit the double-count above.
+ *
+ * Returns a copy — see `setBankedBaseline` for why both ends of this map are cloned.
+ *
+ * @internal
+ */
+export function getBankedBaseline(key: string): AggregateUsage | undefined {
+  const usage = baselinesByKey.get(key);
+  return usage ? { ...usage } : undefined;
+}
+
+/**
+ * Record the baseline for `key`, replacing any previous one.
+ *
+ * Stores a copy, and `getBankedBaseline` hands back a copy, so nothing outside this module can
+ * reach the object the map holds. Both ends have to clone, because a baseline is aliased at both:
+ * `resolveBankedUsage` returns a *reference into a ledger row* (`row.banked` or `row.usage`),
+ * which is what gets stored here, and the caller then assigns what it reads back onto the NEXT
+ * row's `banked` field. Uncloned, one object is reachable from page-global state, two rows, and —
+ * since the row list is public and gets handed to a host's `saveCostHistory` — from host code.
+ * Whoever mutated it would silently rewrite this project's baseline for the rest of the page.
+ *
+ * A shallow spread is a complete copy: `AggregateUsage` is five flat numbers, no nested state.
+ *
+ * @internal
+ */
+export function setBankedBaseline(key: string, usage: AggregateUsage): void {
+  baselinesByKey.set(key, { ...usage });
+}
+
+/**
+ * Drop the baseline for `key`, so the next write re-derives it from the ledger rows.
+ *
+ * For when the pairing is broken deliberately at the *row* end — the row this baseline came from
+ * has been deleted, or the whole ledger cleared — and for a session teardown, where the store
+ * (and with it the transcript) is disposed and a later return re-restores from scratch.
+ *
+ * NOT for a mid-session reload of the rows: those rows already include this session's own
+ * upserts, so re-deriving from them folds the live transcript into its own baseline.
+ *
+ * @internal
+ */
+export function deleteBankedBaseline(key: string): void {
+  baselinesByKey.delete(key);
+}
+
+/**
+ * Forget every baseline — the page-load boundary, which production gets for free from module
+ * state dying with the realm. Exists so tests can model separate page loads (and so one test's
+ * session key cannot leak a baseline into the next).
+ *
+ * @internal
+ */
+export function resetBankedBaselines(): void {
+  baselinesByKey.clear();
+}