@mnemom/mnemom 0.17.7 → 0.17.8

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

@@ -0,0 +1,86 @@
+/**
+ * The realized saving of a session that ran through Mnemom: a replay of what stock Claude
+ * Code would have sent.
+ *
+ * Through the gateway, a transcript's top-level `usage` is the FOLDED, billed size (over
+ * 365k rows, `usage.iterations` matches the top-level fields, so no pre-fold size is ever
+ * recorded). So the client-side size is rebuilt from the fold drops themselves, and stock
+ * Claude Code is replayed on it at its DEFAULT window for the session's model, compacting
+ * whenever it would have. The saving is what stock would have billed minus what was
+ * billed. It can be negative for a session, and is kept negative.
+ *
+ * Pure: rows and compaction records in, numbers out. No I/O.
+ */
+import { type Compaction, type Row } from "./backtest.js";
+/** Main-thread requests with a smaller prompt are side calls (title, summary): ignored. */
+export declare const SIDE_CALL_BELOW = 10000;
+/** A fold: prompt(a) - prompt(b) > this … */
+export declare const FOLD_MIN_DROP = 20000;
+/** … and prompt(b) < this x prompt(a), with no Claude Code compaction in between. */
+export declare const FOLD_MAX_RATIO = 0.7;
+/** Median post-compaction size over 1,460 observed Claude Code compactions. */
+export declare const POST_COMPACT = 17181;
+/** Output tokens of a stock compaction's summary call. */
+export declare const SUMMARY_OUT = 6000;
+export declare const WINDOW_200K = 200000;
+export declare const WINDOW_1M = 1000000;
+/**
+ * Models whose Claude Code default context window is 1M (read out of Claude Code
+ * 2.1.285's binary). Everything else, unknown models included, is 200k. The user's own
+ * autoCompactWindow is deliberately NOT read: the baseline is stock Claude Code.
+ */
+export declare const ONE_M_DEFAULT: RegExp;
+/** Claude Code's default window for a model id (a trailing `[...]` is stripped). */
+export declare function defaultWindow(model: string): number;
+/** The most frequent main-thread model (all rows when none is main); first seen wins a tie. */
+export declare function dominantModel(rows: readonly Row[]): string;
+/** The main-thread requests the replay walks: prompt >= 10k, in timestamp order. */
+export declare function replayRows(rows: readonly Row[]): Row[];
+/** A Claude Code compaction with a timestamp in [ta, tb]. */
+export declare function compactedBetween(ct: readonly number[], ta: number, tb: number): boolean;
+/** The size drop from a to b looks like a fold (the compaction check is separate). */
+export declare function isFoldDrop(a: number, b: number): boolean;
+/** Fold evidence: two consecutive main-thread requests with a fold drop and no compaction. */
+export declare function hasFoldEvidence(rows: readonly Row[], comps: readonly Compaction[]): boolean;
+export interface Replay {
+    /** The baseline window. */
+    window: number;
+    /** Σ (stock size - billed prompt) over the replayed requests. */
+    tokenDiff: number;
+    /** The same, priced at each request's cache-read rate. */
+    usdDiff: number;
+    stockCompactions: number;
+    stockCompactionUsd: number;
+    /** Claude Code compactions recorded in the session. */
+    actualCompactions: number;
+    /** Fold drops the replay found along the main thread. */
+    folds: number;
+    savedTokens: number;
+    savedUsd: number;
+}
+/**
+ * Replay stock Claude Code at window W along the session's main thread.
+ *
+ *   client = billed prompt + what the folds removed so far (reset by a real compaction;
+ *            growth during a fold request counts as 0, the conservative direction)
+ *   stock  = min(client, W) at the first request and after a reset; otherwise it grows
+ *            with client and compacts above W: count it, charge (W x cache read + 6000 x
+ *            output + 17181 x cache write 5m) at the request's model price, and continue
+ *            from 17181 + the overshoot
+ *   saved  = Σ (stock - billed) at cache read + stock compaction cost - the session's own
+ *            compactions x the mean simulated compaction cost (0 if none was simulated)
+ *
+ * The last term is deliberately CONSERVATIVE (operator 2026-10-02). At a real compaction
+ * the replay resets both worlds to the same size, so that compaction's cost is paid on
+ * both sides and cancels. Subtracting it then charges each real compaction against
+ * Mnemom a second time, at the mean simulated stock cost, which is 0 when the replay
+ * simulated none. It can only lower the saving, never raise it, and with more real
+ * compactions than simulated ones it can take the saving below 0.
+ *
+ * A REALIZED saving comes only from detected folds. With none, savedTokens and savedUsd
+ * are capped at 0: a session put through Mnemom by a ledger, window or env signal alone
+ * can never add a saving (it adds its usage to the through bucket and 0 to "That saved"),
+ * but a replay that comes out NEGATIVE (billed above stock's window) still counts against
+ * it, so the cap only ever lowers the bucket total. tokenDiff / usdDiff keep the raw values.
+ */
+export declare function replayStock(rows: readonly Row[], comps: readonly Compaction[], W: number): Replay;

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

@@ -0,0 +1,162 @@
+/**
+ * The realized saving of a session that ran through Mnemom: a replay of what stock Claude
+ * Code would have sent.
+ *
+ * Through the gateway, a transcript's top-level `usage` is the FOLDED, billed size (over
+ * 365k rows, `usage.iterations` matches the top-level fields, so no pre-fold size is ever
+ * recorded). So the client-side size is rebuilt from the fold drops themselves, and stock
+ * Claude Code is replayed on it at its DEFAULT window for the session's model, compacting
+ * whenever it would have. The saving is what stock would have billed minus what was
+ * billed. It can be negative for a session, and is kept negative.
+ *
+ * Pure: rows and compaction records in, numbers out. No I/O.
+ */
+import { origContext, price } from "./backtest.js";
+/** Main-thread requests with a smaller prompt are side calls (title, summary): ignored. */
+export const SIDE_CALL_BELOW = 10_000;
+/** A fold: prompt(a) - prompt(b) > this … */
+export const FOLD_MIN_DROP = 20_000;
+/** … and prompt(b) < this x prompt(a), with no Claude Code compaction in between. */
+export const FOLD_MAX_RATIO = 0.7;
+/** Median post-compaction size over 1,460 observed Claude Code compactions. */
+export const POST_COMPACT = 17_181;
+/** Output tokens of a stock compaction's summary call. */
+export const SUMMARY_OUT = 6_000;
+export const WINDOW_200K = 200_000;
+export const WINDOW_1M = 1_000_000;
+/**
+ * Models whose Claude Code default context window is 1M (read out of Claude Code
+ * 2.1.285's binary). Everything else, unknown models included, is 200k. The user's own
+ * autoCompactWindow is deliberately NOT read: the baseline is stock Claude Code.
+ */
+export const ONE_M_DEFAULT = /^claude-(fable-5|opus-4-[6-9]|opus-[5-9]|sonnet-4-[6-9]|sonnet-[5-9])/;
+/** Claude Code's default window for a model id (a trailing `[...]` is stripped). */
+export function defaultWindow(model) {
+    return ONE_M_DEFAULT.test(model.replace(/\[[^\]]*\]$/, "")) ? WINDOW_1M : WINDOW_200K;
+}
+const isMain = (r) => r.mainThread && !r.subagent;
+/** The most frequent main-thread model (all rows when none is main); first seen wins a tie. */
+export function dominantModel(rows) {
+    const main = rows.filter(isMain);
+    const counts = new Map();
+    let best = "";
+    let bestN = 0;
+    for (const r of main.length ? main : rows) {
+        const n = (counts.get(r.model) ?? 0) + 1;
+        counts.set(r.model, n);
+        if (n > bestN) {
+            best = r.model;
+            bestN = n;
+        }
+    }
+    return best;
+}
+/** The main-thread requests the replay walks: prompt >= 10k, in timestamp order. */
+export function replayRows(rows) {
+    return rows
+        .filter((r) => isMain(r) && origContext(r) >= SIDE_CALL_BELOW)
+        .sort((a, b) => a.t - b.t);
+}
+/** A Claude Code compaction with a timestamp in [ta, tb]. */
+export function compactedBetween(ct, ta, tb) {
+    return ct.some((t) => t >= ta && t <= tb);
+}
+/** The size drop from a to b looks like a fold (the compaction check is separate). */
+export function isFoldDrop(a, b) {
+    return a - b > FOLD_MIN_DROP && b < FOLD_MAX_RATIO * a;
+}
+/** Fold evidence: two consecutive main-thread requests with a fold drop and no compaction. */
+export function hasFoldEvidence(rows, comps) {
+    const m = replayRows(rows);
+    const ct = comps.map((c) => c.t);
+    for (let i = 1; i < m.length; i++) {
+        const a = m[i - 1];
+        const b = m[i];
+        if (isFoldDrop(origContext(a), origContext(b)) && !compactedBetween(ct, a.t, b.t))
+            return true;
+    }
+    return false;
+}
+/**
+ * Replay stock Claude Code at window W along the session's main thread.
+ *
+ *   client = billed prompt + what the folds removed so far (reset by a real compaction;
+ *            growth during a fold request counts as 0, the conservative direction)
+ *   stock  = min(client, W) at the first request and after a reset; otherwise it grows
+ *            with client and compacts above W: count it, charge (W x cache read + 6000 x
+ *            output + 17181 x cache write 5m) at the request's model price, and continue
+ *            from 17181 + the overshoot
+ *   saved  = Σ (stock - billed) at cache read + stock compaction cost - the session's own
+ *            compactions x the mean simulated compaction cost (0 if none was simulated)
+ *
+ * The last term is deliberately CONSERVATIVE (operator 2026-10-02). At a real compaction
+ * the replay resets both worlds to the same size, so that compaction's cost is paid on
+ * both sides and cancels. Subtracting it then charges each real compaction against
+ * Mnemom a second time, at the mean simulated stock cost, which is 0 when the replay
+ * simulated none. It can only lower the saving, never raise it, and with more real
+ * compactions than simulated ones it can take the saving below 0.
+ *
+ * A REALIZED saving comes only from detected folds. With none, savedTokens and savedUsd
+ * are capped at 0: a session put through Mnemom by a ledger, window or env signal alone
+ * can never add a saving (it adds its usage to the through bucket and 0 to "That saved"),
+ * but a replay that comes out NEGATIVE (billed above stock's window) still counts against
+ * it, so the cap only ever lowers the bucket total. tokenDiff / usdDiff keep the raw values.
+ */
+export function replayStock(rows, comps, W) {
+    const m = replayRows(rows);
+    const ct = comps.map((c) => c.t);
+    let removed = 0;
+    let prev = null;
+    let clientPrev = 0;
+    let st = 0;
+    let tokenDiff = 0;
+    let usdDiff = 0;
+    let n = 0;
+    let ccost = 0;
+    let folds = 0;
+    for (const r of m) {
+        const p = origContext(r);
+        const [, po, pr, w5] = price(r.model);
+        let reset = prev === null;
+        if (prev !== null) {
+            if (compactedBetween(ct, prev.t, r.t)) {
+                removed = 0;
+                reset = true;
+            }
+            else if (isFoldDrop(origContext(prev), p)) {
+                removed += origContext(prev) - p;
+                folds++;
+            }
+        }
+        const client = p + removed;
+        if (reset) {
+            st = Math.min(client, W);
+        }
+        else {
+            st += Math.max(client - clientPrev, 0);
+            while (st > W) {
+                n++;
+                ccost += (W * pr + SUMMARY_OUT * po + POST_COMPACT * w5) / 1e6;
+                st = POST_COMPACT + (st - W);
+            }
+        }
+        tokenDiff += st - p;
+        usdDiff += ((st - p) * pr) / 1e6;
+        prev = r;
+        clientPrev = client;
+    }
+    // Conservative: see the doc comment. Never raises savedUsd (each >= 0).
+    const each = n ? ccost / n : 0;
+    const usd = usdDiff + ccost - comps.length * each;
+    return {
+        window: W,
+        tokenDiff,
+        usdDiff,
+        stockCompactions: n,
+        stockCompactionUsd: ccost,
+        actualCompactions: comps.length,
+        folds,
+        savedTokens: folds ? tokenDiff : Math.min(tokenDiff, 0),
+        savedUsd: folds ? usd : Math.min(usd, 0),
+    };
+}

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

@@ -1,34 +1,52 @@
 /**
  * The first-run screen: one plain terminal screen (at most 22 lines of at most 78
- * columns, ASCII) built from the backtest numbers. Pure — no I/O — so every layout is
+ * columns, ASCII; with the command's blank line above and below, 24 rows) 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.
  *
- * Exactly three variations (operator v1, 2026-10-01); every number has one source and no
- * two lines make the same claim:
- *   A  saving   the shown saving is >= $5 and >= 5%: the usage at API prices, with Mnemom,
- *               the saving, the biggest session; plus ONE subscription sentence for a Team /
- *               Enterprise subscriber whose usage cut rounds to >= 5%. Where sessions ran
- *               through Mnemom (launch ledger), that part is said to be SAVED: what it
- *               saved you, and what it would have saved on the rest (operator 2026-10-02).
- *   B  small    >= $5 of usage at API prices but a smaller saving: the usage, the honest
- *               "wouldn't have changed that much" line, and the forward line.
- *   C  none     too little history: the forward line only.
- * All three end with the price line and the live lines.
+ * Sessions come in two buckets (index.ts): THROUGH Mnemom (launch ledger, a window / env
+ * signal, or fold evidence), whose saving is REALIZED (replay.ts: stock Claude Code
+ * replayed at its default window, can be negative), and NOT through Mnemom, whose saving
+ * is the POTENTIAL one (backtest.ts: the flat S46 rule, 23.8% of every request at or
+ * above 60k, for dollars and for tokens alike). Tokens and dollars are both shown
+ * (operator 2026-10-02). Percentages drop their decimals (rounded DOWN).
  *
- * 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.
- *   - Every kept session is priced at API list prices whatever it was billed on, and the
- *     screen says "at API prices". A subscriber gets a usage %, never a seat bill, an
- *     overage dollar figure or a limit-hit count.
+ * Variations; every number has one source and no two lines make the same claim:
+ *   A        no through-Mnemom usage, and the potential saving qualifies: the usage in
+ *            tokens and at API prices, the cut with Mnemom, the biggest session.
+ *   mixed    both buckets have usage: one block per bucket, each with its saving line
+ *            only if that BUCKET's saving qualifies, then the largest dollar saving
+ *            across the shown buckets, worded by its bucket ("biggest saving ... of"
+ *            through, "biggest session ... less with Mnemom" not through).
+ *   through  only through-Mnemom usage: its block alone, then its biggest saving.
+ *   B        >= $5 of usage but no saving line qualifies: the usage, the honest "wouldn't
+ *            have changed that much" line (no through usage) or the bucket usage lines,
+ *            and the forward line.
+ *   C        too little history: the forward line only.
+ * A saving qualifies iff it rounds DOWN to >= $5 and its token percent to >= 5%. A
+ * Team / Enterprise subscriber also gets the subscription line whenever a saving line is
+ * shown; its overage clause only when the account has extra usage enabled. All end with
+ * the price line and the live lines.
+ *
+ * Layout (operator 2026-10-02): a blank line between every block (each bucket's usage
+ * and saving lines, the biggest line, the subscriber lines, the price line, the live
+ * lines); the saving lines are not indented.
+ *
+ * Operator rulings (2026-09-30 .. 2026-10-02), binding:
+ *   - Cost and usage only. Nothing about conduct ("habits", "caught", "checked").
+ *   - Round DOWN, never overstate. A through session's saving may be negative: the
+ *     bucket total is the honest sum, never floored per session.
+ *   - Every session is priced at API list prices whatever it was billed on, and the
+ *     screen says "at API prices". A subscriber never gets a seat bill, an overage dollar
+ *     figure or a limit-hit count.
  *   - No live counter is promised: `mnemom agent` has no status bar today.
  */
 export declare const WIDTH = 78;
 export declare const MAX_LINES = 22;
 /** Less history than this (API prices, in the window) is too little to backtest. */
 export declare const MIN_HISTORY_USD = 5;
-/** Variation A iff the shown saving is at least this many dollars and this many percent. */
+/** A saving line is shown iff its saving rounds to at least this many dollars and percent. */
 export declare const STRONG_MIN_USD = 5;
 export declare const STRONG_MIN_PCT = 5;
 export declare const DAYS = 30;
@@ -42,6 +60,14 @@ export declare const FORWARD_LINE = "Long sessions are where Mnemom saves the mo
 /** Prices, promotions and plan allocations move; the saving is in usage (operator 2026-10-01). */
 export declare const PRICE_LINE = "Prices and plan limits change. Mnemom cuts what you use, so you stay ahead.";
 /** What `mnemom agent` does today: routes through the gateway, records, keeps context lean. */
+/**
+ * The subscriber lines, fixed like the live lines: the operator's break, so the overage
+ * form reads as two lines and never as one 78-column line.
+ */
+export declare const SUB_LINES: {
+    limit: string[];
+    overage: string[];
+};
 export declare const LIVE_LINES: string[];
 /** 2 significant figures, rounded DOWN; 0 below $1. */
 export declare function sig2(x: number): number;
@@ -56,31 +82,41 @@ export declare function pair(total: number, saved: number): [number, number, num
 export declare function pctDown(part: number, whole: number): number;
 export declare function day(t: number): string;
 export declare function usd(n: number): string;
+/** A token count rounded DOWN to 2 significant figures (the number it stands for). */
+export declare function tokShown(n: number): number;
+/**
+ * A token count in words, 2 significant figures DOWN: "9.0 billion", "39 billion",
+ * "450 million", "12 thousand"; below a thousand, the plain number.
+ */
+export declare function tokens(n: number): string;
 export declare function clean(s: string): string;
 /** A short, safe project label from Claude Code's encoded project dir, or null. */
 export declare function labelFor(pretty: string): string | null;
 export declare function wrap(text: string, width?: number): string[];
-/** One kept session's requests in the window, priced at API list prices. */
+/** One session's requests in the window, priced at API list prices. */
 export interface SessionCost {
     label: string | null;
     end: number;
+    /** What it used, at API prices (through Mnemom: the folded, billed size). */
     actual: number;
+    /** Tokens it used: prompt + output. */
+    tokens: number;
+    /** Through: the realized saving vs stock Claude Code (may be negative). Not: potential. */
     saved: number;
-    /** The launch ledger proves it ran through Mnemom: its saving is said to be SAVED. */
-    viaMnemom?: boolean;
+    savedTokens: number;
+    /** It ran through Mnemom (index.ts throughEvidence). */
+    through: boolean;
 }
-/** A Team / Enterprise subscriber's usage, at API prices (local evidence only). */
-export interface SubUsage {
-    /** Subscription-billed sessions in the window (all sessions when none is tagged). */
-    sessions: number;
-    actual: number;
-    saved: number;
+/** A Team / Enterprise subscriber (local evidence only). */
+export interface SubInfo {
+    /** The account has extra usage (overage) enabled: `hasExtraUsageEnabled`. */
+    extraUsage: boolean;
 }
 export interface ScreenInput {
-    /** Every kept session with requests in the window. */
+    /** Every session with requests in the window. */
     sessions: SessionCost[];
     /** null: not a Team / Enterprise subscriber. */
-    sub: SubUsage | null;
+    sub: SubInfo | null;
 }
 export interface AuditEntry {
     shown: unknown;
@@ -88,7 +124,7 @@ export interface AuditEntry {
     method: string;
 }
 export type Audit = Record<string, AuditEntry>;
-export type Variation = "A" | "B" | "C";
+export type Variation = "A" | "mixed" | "through" | "B" | "C";
 /** -> the screen lines, the variation and the audit of every number on them. */
 export declare function buildScreen(inp: ScreenInput): {
     lines: string[];