@mnemom/mnemom 0.17.4-next.3 → 0.17.4-next.4

package/dist/lib/first-run/screen.js

@@ -0,0 +1,324 @@
+/**
+ * The first-run screen: one plain terminal screen (at most 16 lines of at most 78
+ * columns, ASCII) built from the backtest numbers. Pure — no I/O — so every layout is
+ * unit-tested. Every number on it is recorded in the audit with its raw value and
+ * method.
+ *
+ * Operator rulings (2026-09-30 / 2026-10-01), binding:
+ *   - Cost only. Nothing about conduct ("habits", "caught", "checked").
+ *   - Round DOWN, never overstate; frame the number around the biggest session.
+ *   - API-key sessions: dollars. Team / Enterprise subscription sessions: usage-limit
+ *     headroom (more work per window, fewer limit stops, less overage) plus the saving
+ *     at API list price, labelled as such — never a lower seat bill.
+ *   - A saving that rounds below $1 gets the honest "won't change … much" line.
+ *   - No live counter is promised: `mnemom agent` has no status bar today.
+ */
+import { ESTIMATOR_METHOD } from "./backtest.js";
+export const WIDTH = 78;
+export const MAX_LINES = 16;
+/** Less history than this (list price, in the window) is too little to backtest. */
+export const MIN_HISTORY_USD = 5;
+/** The biggest session is shown only if it ran this long and saved at least this much. */
+export const BIGGEST_MIN_SECONDS = 1800;
+export const BIGGEST_MIN_SAVED_USD = 5;
+export const DAYS = 30;
+/**
+ * Source: mnemom-adw scratchpad/wow-first-run/COST-REPORT.md, measured chain45 total
+ * bill (S44 C2 fold-only -15.8%, S43 C2 -19.5%, S43 C1 -15.7%), stated as the rounded-down
+ * range. The d240p1 ~45% figure is NOT used (its re-bill undercounts output).
+ */
+export const FORWARD_LINE = "Long sessions are where Mnemom saves the most: about 15 to 20% in our tests.";
+const FORWARD_SOURCE = "COST-REPORT.md measured chain45 total bill: S44 C2 -15.8%, S43 C2 -19.5%, S43 C1 -15.7%; " +
+    "stated as 15 to 20%";
+/** What `mnemom agent` does today: routes through the gateway, records, keeps context lean. */
+export const LIVE_LINES = [
+    "From now on it's live: your sessions run through Mnemom, which keeps long",
+    "conversations lean and puts each tool call your agent makes on the record.",
+];
+export const SUPPORTED_LINE = "Mnemom works with an API key or a Claude Team or Enterprise login.";
+// ── rounding (never inflate) ─────────────────────────────────────────────────
+/** 2 significant figures, rounded DOWN; 0 below $1. */
+export function sig2(x) {
+    if (!(x >= 1))
+        return 0;
+    const step = 10 ** Math.max(Math.floor(Math.log10(x)) - 1, 0);
+    return Math.floor(x / step + 1e-9) * step;
+}
+/** 3 significant figures, rounded DOWN; 0 below $1. */
+export function sig3(x) {
+    if (!(x >= 1))
+        return 0;
+    const step = 10 ** Math.max(Math.floor(Math.log10(x)) - 2, 0);
+    return Math.floor(x / step + 1e-9) * step;
+}
+/**
+ * (total shown, saved shown, with-Mnemom shown) with total - saved === with EXACTLY on
+ * screen. The implied saving is the shown saving, which never exceeds the raw saving.
+ */
+export function pair(total, saved) {
+    const sv = sig2(Math.max(saved, 0));
+    const tot = sig3(total);
+    return [tot, Math.min(sv, tot), Math.max(tot - sv, 0)];
+}
+/** part / whole as a percentage rounded DOWN to a multiple of 5. */
+export function pct5(part, whole) {
+    if (whole <= 0 || part <= 0)
+        return 0;
+    return Math.floor((100 * part) / whole / 5 + 1e-9) * 5;
+}
+/** Wall-clock length rounded DOWN: "11 h", "1.5 h", "40 min". */
+export function hoursDown(sec) {
+    const h = sec / 3600;
+    if (h >= 2)
+        return `${Math.floor(h)} h`;
+    if (h >= 1)
+        return `${(Math.floor(h * 10) / 10).toFixed(1)} h`;
+    return `${Math.max(Math.floor(sec / 60), 1)} min`;
+}
+const MONTHS = ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"];
+export function day(t) {
+    const d = new Date(t * 1000);
+    return `${d.getUTCDate()} ${MONTHS[d.getUTCMonth()]}`;
+}
+export function usd(n) {
+    return `$${Math.floor(n).toLocaleString("en-US")}`;
+}
+// ── output hygiene ───────────────────────────────────────────────────────────
+const SECRETS = /(sk-[A-Za-z0-9_-]{6,}|ghp_[A-Za-z0-9]{6,}|mnm_[A-Za-z0-9_-]{6,}|op:\/\/\S+|Bearer\s+\S+|\b[0-9a-f]{40,}\b|\b[A-Za-z0-9+/]{48,}={0,2})/g;
+const PATHISH = /(\/Users\/\S+|\/home\/\S+|\/private\/\S+|~\/\S+)/g;
+export function clean(s) {
+    return s.replace(SECRETS, "[REDACTED]").replace(PATHISH, "[path]");
+}
+/** A short, safe project label from Claude Code's encoded project dir, or null. */
+export function labelFor(pretty) {
+    let base = pretty.replace(/-{1,2}\.?worktrees-/g, "/").replace(/^-+|-+$/g, "");
+    base = base.replace(/-?\d{8}T\d{6}Z/g, "").replace(/-?[0-9a-f]{12,}/g, "");
+    if (base.includes("/"))
+        base = base.slice(base.lastIndexOf("/") + 1);
+    if (!base || clean(base) !== base || !/^[A-Za-z0-9._ -]+$/.test(base))
+        return null;
+    return base.length <= 36 ? base : `${base.slice(0, 35)}~`;
+}
+export function wrap(text, width = WIDTH) {
+    const out = [];
+    let cur = "";
+    for (const w of text.split(/\s+/).filter(Boolean)) {
+        if (cur && cur.length + 1 + w.length > width) {
+            out.push(cur);
+            cur = w;
+        }
+        else {
+            cur = cur ? `${cur} ${w}` : w;
+        }
+    }
+    if (cur)
+        out.push(cur);
+    return out;
+}
+const SPENT_METHOD = "transcript usage x Claude Code 2.1.285's price table, deduped by message id, requests in the " +
+    "last 30 days; 3 sig figs DOWN; a lower bound (side calls not in transcripts are missing)";
+const SAVED_METHOD = `backtest.estimate(): ${ESTIMATOR_METHOD}; 2 sig figs DOWN`;
+function apiBlock(api, both, A) {
+    const [a, s, e] = pair(api.actual, api.saved);
+    const p = pct5(api.saved, api.actual);
+    const who = both ? "On your API key you spent" : "You spent";
+    A("api_spent_usd", { shown: a, raw: api.actual, method: SPENT_METHOD });
+    if (s < 1) {
+        A("api_small_saving", { shown: true, raw: api.saved, method: "saving rounds below $1" });
+        return wrap(`${who} about ${usd(a)}. Mnemom won't change your bill much.`);
+    }
+    A("api_saved_usd", { shown: s, raw: api.saved, method: SAVED_METHOD });
+    A("api_with_mnemom_usd", {
+        shown: e,
+        raw: api.actual - api.saved,
+        method: "spent shown - saved shown",
+    });
+    A("api_saved_pct", {
+        shown: p,
+        raw: (100 * api.saved) / api.actual,
+        method: "rounded DOWN to 5s",
+    });
+    const pctPart = p >= 5 ? `, ${p}%,` : "";
+    return [
+        ...wrap(`${who} about ${usd(a)}. With Mnemom: about ${usd(e)}.`),
+        ...wrap(`That's about ${usd(s)} back${pctPart} and you don't change how you work.`),
+    ];
+}
+/** The seat-evidence line: overage paid (real dollars) or limit stops. At most 2 lines. */
+function seatEvidence(seat, A) {
+    const ov = seat.flatMap((x) => (x.overage ? [x.overage] : []));
+    const paid = ov.reduce((t, o) => t + o.paidUsd, 0);
+    if (paid >= 1) {
+        const wm = ov.reduce((t, o) => t + o.withMnemomUsd, 0);
+        const [p, , w] = pair(paid, paid - wm);
+        A("seat_overage_usd", { shown: p, raw: paid, method: ov[0].method });
+        A("seat_overage_with_mnemom_usd", { shown: w, raw: wm, method: "paid shown - avoided shown" });
+        return wrap(`You paid about ${usd(p)} in extra usage. With Mnemom, about ${usd(w)} of extra usage.`);
+    }
+    const hs = seat.flatMap((x) => (x.hits ? [x.hits] : []));
+    const n = hs.reduce((t, h) => t + h.n, 0);
+    if (n < 1)
+        return [];
+    const wm = hs.reduce((t, h) => t + h.withMnemom, 0);
+    const fewer = hs.reduce((t, h) => t + h.notInferableWithSaving, 0);
+    const hrs = Math.floor(hs.reduce((t, h) => t + h.waitedS, 0) / 3600);
+    A("seat_limit_hits", {
+        shown: n,
+        raw: n,
+        method: "Claude Code's own limit records, last 30 days",
+    });
+    A("seat_hits_with_mnemom", { shown: wm, raw: wm, method: hs[0].method });
+    A("seat_waited_hours", {
+        shown: hrs,
+        raw: hs.reduce((t, h) => t + h.waitedS, 0) / 3600,
+        method: "hours DOWN",
+    });
+    const wait = hrs >= 1 ? ` and waited about ${hrs} hour${hrs === 1 ? "" : "s"}` : "";
+    let tail = "";
+    if (wm < n)
+        tail = ` With Mnemom, about ${wm}.`;
+    else if (fewer)
+        tail = " With Mnemom, fewer.";
+    return wrap(`You hit your plan's usage limit ${n} time${n === 1 ? "" : "s"}${wait}.${tail}`);
+}
+function subBlock(sub, A) {
+    const [u, s, w] = pair(sub.actual, sub.saved);
+    const p = pct5(sub.saved, sub.actual);
+    const n = sub.sessions;
+    A("sub_usage_list_usd", {
+        shown: u,
+        raw: sub.actual,
+        method: `${SPENT_METHOD}; list-price equivalent, not a bill`,
+    });
+    const head = wrap(`On your Claude ${sub.plan} plan: ${n} session${n === 1 ? "" : "s"}, about ${usd(u)} of usage at API list price.`);
+    if (s < 1) {
+        A("sub_small_saving", { shown: true, raw: sub.saved, method: "saving rounds below $1" });
+        return { lines: [...head, "Mnemom won't change your usage much."], evidence: [] };
+    }
+    A("sub_saved_list_usd", { shown: s, raw: sub.saved, method: SAVED_METHOD });
+    A("sub_with_mnemom_list_usd", {
+        shown: w,
+        raw: sub.actual - sub.saved,
+        method: "usage shown - saved shown",
+    });
+    // Using a fraction f less per request fits 1/(1-f) - 1 >= f more work in a window; we
+    // state f itself, rounded down to 5s, which never exceeds the true headroom.
+    A("sub_headroom_pct", {
+        shown: p,
+        raw: (100 * sub.saved) / sub.actual,
+        method: "states the usage saving %, rounded DOWN to 5s: a lower bound on the extra work per window, " +
+            "which is saved / (usage - saved)",
+    });
+    const room = p >= 5
+        ? `room for about ${p}% more work in each usage window before a limit.`
+        : "a little more room in each usage window before a limit.";
+    return {
+        lines: [
+            ...head,
+            ...wrap(`With Mnemom: about ${usd(w)} at list price (not your bill), so ${room}`),
+        ],
+        evidence: seatEvidence(sub.seat, A),
+    };
+}
+function biggestBlock(b, A) {
+    const [a, , e] = pair(b.actual, b.saved);
+    const hrs = hoursDown(b.end - b.start);
+    const lp = b.billing === "subscription" ? " at list price" : "";
+    A("biggest_session_usd", {
+        shown: a,
+        raw: b.actual,
+        method: "largest bill among sessions >= 30 min with >= $5 saved; 3 sig figs DOWN",
+    });
+    A("biggest_session_with_mnemom_usd", {
+        shown: e,
+        raw: b.actual - b.saved,
+        method: "its bill shown - its saving (2 sig figs DOWN)",
+    });
+    A("biggest_session_hours", {
+        shown: hrs,
+        raw: (b.end - b.start) / 3600,
+        method: "first to last request, wall clock; DOWN",
+    });
+    const head = b.label
+        ? `Your biggest session: ${b.label}, ${day(b.end)}, ${hrs}, ${usd(a)}${lp}.`
+        : `Your biggest session, on ${day(b.end)}: ${hrs}, ${usd(a)}${lp}.`;
+    const tail = b.billing === "subscription"
+        ? `With Mnemom it would have used about ${usd(e)} of that.`
+        : `With Mnemom it would have cost about ${usd(e)}.`;
+    return [...wrap(head), tail];
+}
+/** -> the screen lines and the audit of every number on them. */
+export function buildScreen(inp) {
+    const audit = {};
+    const A = (k, e) => {
+        audit[k] = e;
+    };
+    const apiOk = !!inp.api && inp.api.actual >= MIN_HISTORY_USD;
+    const subOk = !!inp.sub && inp.sub.actual >= MIN_HISTORY_USD;
+    const sections = [];
+    // drop: 0 = never dropped; higher = dropped first when the screen is over budget.
+    const push = (lines, drop = 0) => {
+        sections.push({ lines: ["", ...lines], drop });
+    };
+    sections.push({ lines: ["Welcome to Mnemom."], drop: 0 });
+    let anySaving = false;
+    if (apiOk || subOk) {
+        push(wrap(`We looked at your last ${DAYS} days of Claude Code. It all stayed on this machine.`));
+        // Frame the number around the biggest session: it leads.
+        if (inp.biggest)
+            push(biggestBlock(inp.biggest, A), 2);
+        else
+            A("biggest_session_omitted", {
+                shown: true,
+                raw: null,
+                method: "no session >= 30 min with >= $5 saved",
+            });
+        if (apiOk && inp.api) {
+            const lines = apiBlock(inp.api, subOk, A);
+            anySaving ||= "api_saved_usd" in audit;
+            push(lines);
+        }
+        if (subOk && inp.sub) {
+            const { lines, evidence } = subBlock(inp.sub, A);
+            anySaving ||= "sub_saved_list_usd" in audit;
+            push(lines);
+            if (evidence.length)
+                sections[sections.length - 1].lines.push(...evidence);
+        }
+        if (!anySaving) {
+            push([FORWARD_LINE], 3);
+            A("forward_range_pct", {
+                shown: "15 to 20",
+                raw: [15.7, 15.8, 19.5],
+                method: FORWARD_SOURCE,
+            });
+        }
+    }
+    else {
+        push(["We looked at your recent Claude Code sessions. It all stayed on this machine."]);
+        if (inp.unsupported > 0)
+            push([SUPPORTED_LINE]);
+    }
+    push(LIVE_LINES);
+    A("sessions", {
+        shown: null,
+        raw: {
+            api: inp.api?.sessions ?? 0,
+            subscription: inp.sub?.sessions ?? 0,
+            unsupported: inp.unsupported,
+            unknown: inp.unknown,
+        },
+        method: "kept (ungoverned) sessions with requests in the window, by billing class",
+    });
+    const count = () => sections.reduce((t, s) => t + s.lines.length, 0);
+    for (const level of [3, 2]) {
+        if (count() <= MAX_LINES)
+            break;
+        for (let i = sections.length - 1; i >= 0; i--) {
+            if (sections[i].drop === level)
+                sections.splice(i, 1);
+        }
+    }
+    const lines = sections.flatMap((s) => s.lines).map(clean);
+    return { lines, audit };
+}

package/dist/lib/first-run/seat.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Seat economics for Team / Enterprise subscription sessions. A seat is flat-rate up to
+ * its usage limits; past them the user either STOPS until the window resets, or (extra
+ * usage on) keeps going and pays overage at API list rates. So for a seat user Mnemom's
+ * lower usage means more work per window, fewer or shorter stops and less overage —
+ * never a lower seat bill.
+ *
+ * Sources (Claude Code 2.1.285 binary):
+ *   windows  rateLimitType five_hour | seven_day (+ per-model weekly caps, folded into the
+ *            weekly window); display names "session limit" / "weekly limit".
+ *   stop     a plan-limit 429 is written as an API-error assistant record whose text is
+ *            "You've hit your <limit name> · resets <time>" (also "Usage limit reached …").
+ *   overage  "… now using usage credits instead of your plan limits" / "You're now using
+ *            extra usage" mark the switch to paid overage. Measured 2026-09-30: UI-only
+ *            today — no transcript records one — so an allowance is pinned only when a
+ *            record does carry it.
+ *
+ * Only records Claude Code itself writes (system, API-error, or `<synthetic>` assistant
+ * records) count — a user or model message that merely discusses limits never does.
+ * Read-only; no network.
+ */
+import { type Row } from "./backtest.js";
+export declare const WINDOW_S: {
+    readonly five_hour: number;
+    readonly seven_day: number;
+};
+export type WindowType = keyof typeof WINDOW_S;
+export declare const DAYS = 30;
+export interface LimitEvent {
+    t: number;
+    kind: "hit" | "extra_on" | "extra_cap";
+    wtype: WindowType | null;
+    blockedS: number;
+}
+/** Limit / extra-usage events from Claude Code's own records, sorted by time. */
+export declare function limitEvents(paths: readonly string[]): LimitEvent[];
+export interface SeatSessionInput {
+    rows: readonly Row[];
+    /** Screen rate per row (backtest.ruleRate(...).screen). */
+    rates: readonly number[];
+    paths: readonly string[];
+}
+export interface SeatAnalysis {
+    extraUsage: boolean | null;
+    requests30d: number;
+    usageListUsd30d: number;
+    withMnemomListUsd30d: number;
+    events30d: {
+        hit: number;
+        extra_on: number;
+        extra_cap: number;
+    };
+    allowance: Partial<Record<WindowType, {
+        usd: number;
+        source: string;
+    }>>;
+    overage?: {
+        paidUsd: number;
+        withMnemomUsd: number;
+        overPeriods: number;
+        stayedInside: number;
+        method: string;
+    };
+    hits?: {
+        n: number;
+        waitedS: number;
+        avoided: number;
+        notInferable: number;
+        notInferableWithSaving: number;
+        withMnemom: number;
+        method: string;
+    };
+}
+/** One account's seat sessions → the seat block's numbers and their method. */
+export declare function analyzeSeat(sessions: readonly SeatSessionInput[], extraUsage: boolean | null, now?: number, days?: number): SeatAnalysis;

package/dist/lib/first-run/seat.js

@@ -0,0 +1,250 @@
+/**
+ * Seat economics for Team / Enterprise subscription sessions. A seat is flat-rate up to
+ * its usage limits; past them the user either STOPS until the window resets, or (extra
+ * usage on) keeps going and pays overage at API list rates. So for a seat user Mnemom's
+ * lower usage means more work per window, fewer or shorter stops and less overage —
+ * never a lower seat bill.
+ *
+ * Sources (Claude Code 2.1.285 binary):
+ *   windows  rateLimitType five_hour | seven_day (+ per-model weekly caps, folded into the
+ *            weekly window); display names "session limit" / "weekly limit".
+ *   stop     a plan-limit 429 is written as an API-error assistant record whose text is
+ *            "You've hit your <limit name> · resets <time>" (also "Usage limit reached …").
+ *   overage  "… now using usage credits instead of your plan limits" / "You're now using
+ *            extra usage" mark the switch to paid overage. Measured 2026-09-30: UI-only
+ *            today — no transcript records one — so an allowance is pinned only when a
+ *            record does carry it.
+ *
+ * Only records Claude Code itself writes (system, API-error, or `<synthetic>` assistant
+ * records) count — a user or model message that merely discusses limits never does.
+ * Read-only; no network.
+ */
+import { rowCost } from "./backtest.js";
+import { forEachLine, isoSeconds, parseJson } from "./lines.js";
+export const WINDOW_S = { five_hour: 5 * 3600, seven_day: 7 * 86400 };
+const TYPE_BY_NAME = [
+    ["session limit", "five_hour"],
+    ["weekly limit", "seven_day"],
+    ["opus limit", "seven_day"],
+    ["sonnet limit", "seven_day"],
+];
+const HIT_MARKERS = ["hit your limit", "usage limit reached", "limit reached again"];
+const ON_MARKERS = [
+    "now using extra usage",
+    "extra usage is now covering",
+    "now using usage credits instead of your plan",
+    "is drawing from usage credits",
+    "now uses usage credits",
+];
+const CAP_MARKERS = ["out of extra usage"];
+export const DAYS = 30;
+function textOf(m) {
+    if (typeof m === "string")
+        return m;
+    const c = m?.content;
+    if (typeof c === "string")
+        return c;
+    if (Array.isArray(c)) {
+        return c
+            .map((x) => (x && typeof x === "object" && typeof x.text === "string" ? x.text : ""))
+            .join(" ");
+    }
+    return "";
+}
+/** Limit / extra-usage events from Claude Code's own records, sorted by time. */
+export function limitEvents(paths) {
+    const ev = [];
+    for (const fp of paths) {
+        const recs = [];
+        forEachLine(fp, (line) => {
+            const d = parseJson(line);
+            if (!d)
+                return;
+            const t = isoSeconds(d.timestamp);
+            if (t === null)
+                return;
+            const m = d.message;
+            const own = d.type === "system" ||
+                d.isApiErrorMessage === true ||
+                (d.type === "assistant" && !!m && typeof m === "object" && m.model === "<synthetic>");
+            let txt = "";
+            if (own)
+                txt = textOf(m) || (typeof d.content === "string" ? d.content : "");
+            recs.push({ t, own, txt });
+        });
+        recs.sort((a, b) => a.t - b.t);
+        recs.forEach((r, i) => {
+            if (!r.own || !r.txt)
+                return;
+            const low = r.txt.toLowerCase();
+            const isHit = HIT_MARKERS.some((k) => low.includes(k)) ||
+                (low.includes("limit") && low.includes("resets"));
+            const kind = isHit
+                ? "hit"
+                : ON_MARKERS.some((k) => low.includes(k))
+                    ? "extra_on"
+                    : CAP_MARKERS.some((k) => low.includes(k))
+                        ? "extra_cap"
+                        : null;
+            if (!kind)
+                return;
+            const wtype = TYPE_BY_NAME.find(([n]) => low.includes(n))?.[1] ?? null;
+            let blockedS = 0;
+            if (kind === "hit") {
+                // The stop lasts until the session's next record not written by Claude Code itself,
+                // capped at the window; a session that ended at the stop waited 0 (never guessed).
+                const next = recs.slice(i + 1).find((x) => !x.own);
+                blockedS = next ? Math.min(next.t - r.t, WINDOW_S[wtype ?? "five_hour"]) : 0;
+            }
+            ev.push({ t: r.t, kind, wtype, blockedS });
+        });
+    }
+    return ev.sort((a, b) => a.t - b.t);
+}
+/** Usage windows start at the first request after the previous window ended. */
+function windowIndex(ts, length) {
+    const out = [];
+    let start = null;
+    let k = -1;
+    for (const t of ts) {
+        if (start === null || t >= start + length) {
+            start = t;
+            k++;
+        }
+        out.push(k);
+    }
+    return out;
+}
+/** One account's seat sessions → the seat block's numbers and their method. */
+export function analyzeSeat(sessions, extraUsage, now = Date.now() / 1000, days = DAYS) {
+    const cut = now - days * 86400;
+    const reqs = [];
+    for (const s of sessions) {
+        s.rows.forEach((r, i) => {
+            const c = rowCost(r);
+            reqs.push([r.t, c, c * (1 - (s.rates[i] ?? 0))]);
+        });
+    }
+    reqs.sort((a, b) => a[0] - b[0]);
+    const ev = limitEvents(sessions.flatMap((s) => s.paths));
+    const ev30 = ev.filter((e) => e.t >= cut);
+    const in30 = reqs.filter((x) => x[0] >= cut);
+    const out = {
+        extraUsage,
+        requests30d: in30.length,
+        usageListUsd30d: in30.reduce((a, x) => a + x[1], 0),
+        withMnemomListUsd30d: in30.reduce((a, x) => a + x[2], 0),
+        events30d: {
+            hit: ev30.filter((e) => e.kind === "hit").length,
+            extra_on: ev30.filter((e) => e.kind === "extra_on").length,
+            extra_cap: ev30.filter((e) => e.kind === "extra_cap").length,
+        },
+        allowance: {},
+    };
+    const ts = reqs.map((x) => x[0]);
+    const win = {
+        five_hour: windowIndex(ts, WINDOW_S.five_hour),
+        seven_day: windowIndex(ts, WINDOW_S.seven_day),
+    };
+    const firstAtOrAfter = (t) => {
+        const j = ts.findIndex((x) => x >= t);
+        return j === -1 ? ts.length : j;
+    };
+    // Allowance: usage in the window before an extra-usage transition record. An untyped
+    // marker is pinned to the shorter window; the LARGEST pin wins (less overage avoided).
+    for (const e of ev) {
+        if (e.kind !== "extra_on" || !reqs.length)
+            continue;
+        const w = e.wtype ?? "five_hour";
+        const i = firstAtOrAfter(e.t);
+        if (i === 0)
+            continue;
+        const k = win[w][i - 1];
+        let before = 0;
+        for (let j = 0; j < i; j++)
+            if (win[w][j] === k)
+                before += reqs[j][1];
+        const prev = out.allowance[w]?.usd ?? 0;
+        out.allowance[w] = { usd: Math.max(prev, before), source: "extra-usage transition record" };
+    }
+    // Overage (extra usage on): a request is overage once ANY window with a known allowance
+    // is used up. Same windows in both worlds (request times do not move).
+    const allow = Object.entries(out.allowance);
+    if (extraUsage && allow.length) {
+        const walk = (col) => {
+            const used = new Map();
+            let over = 0;
+            const periods = new Set();
+            reqs.forEach((x, j) => {
+                let isOver = false;
+                for (const [w, cap] of allow) {
+                    const id = `${w}:${win[w][j]}`;
+                    if ((used.get(id) ?? 0) >= cap.usd) {
+                        isOver = true;
+                        if (x[0] >= cut)
+                            periods.add(id);
+                    }
+                    used.set(id, (used.get(id) ?? 0) + x[col]);
+                }
+                if (isOver && x[0] >= cut)
+                    over += x[col];
+            });
+            return { over, periods };
+        };
+        const a = walk(1);
+        const b = walk(2);
+        out.overage = {
+            paidUsd: a.over,
+            withMnemomUsd: b.over,
+            overPeriods: a.periods.size,
+            stayedInside: [...a.periods].filter((p) => !b.periods.has(p)).length,
+            method: "overage = list-price usage past the allowance in its window; with Mnemom the same walk on " +
+                "usage x (1 - rate); a period stays inside when it has no overage left",
+        };
+    }
+    // Stops: a hit is AVOIDED only if the saving in its window before the stop covers the
+    // FULL list cost of the work done in the 5 h after the stop ended.
+    const hits = ev30.filter((e) => e.kind === "hit");
+    if (hits.length) {
+        let avoided = 0;
+        let unknown = 0;
+        let unknownSaving = 0;
+        for (const e of hits) {
+            const w = e.wtype ?? "five_hour";
+            const i = firstAtOrAfter(e.t);
+            if (i === 0) {
+                unknown++;
+                continue;
+            }
+            const k = win[w][i - 1];
+            let saved = 0;
+            for (let j = 0; j < i; j++)
+                if (win[w][j] === k)
+                    saved += reqs[j][1] - reqs[j][2];
+            const resume = e.t + e.blockedS;
+            const cont = e.blockedS
+                ? reqs.filter((x) => resume <= x[0] && x[0] < resume + WINDOW_S.five_hour)
+                : [];
+            if (!cont.length) {
+                unknown++;
+                if (saved > 0)
+                    unknownSaving++;
+                continue;
+            }
+            if (saved >= cont.reduce((a, x) => a + x[1], 0))
+                avoided++;
+        }
+        out.hits = {
+            n: hits.length,
+            waitedS: hits.reduce((a, e) => a + e.blockedS, 0),
+            avoided,
+            notInferable: unknown,
+            notInferableWithSaving: unknownSaving,
+            withMnemom: hits.length - avoided,
+            method: "a hit is avoided only if the list-price saving in its window before the stop >= the full " +
+                "list-price cost of the work done in the 5 h after the stop ended; a hit whose overshoot " +
+                "cannot be inferred counts as NOT avoided",
+        };
+    }
+    return out;
+}