waterplane 0.0.1 → 0.1.6

package/node_modules/@waterplane/shared/dist/sessioncost/costcold.d.ts

@@ -0,0 +1,99 @@
+/**
+ * How much of the previous context a request must re-write before it counts as
+ * a rebuild, and how little of it it must read.
+ *
+ * Both halves are needed, and the second one is the half that took three
+ * attempts to get right. `cacheWrite > cacheRead` is NOT this test: every cold
+ * resume still reads the tools-and-system preamble, a separate cache entry kept
+ * warm by sibling sessions in the same repo and measured at 32.5k-36.8k on this
+ * desktop. A 60k conversation coming back cold reads 36.8k and writes 30.6k —
+ * write below read, and stone cold. What separates the two cases is whether the
+ * read covers the CONVERSATION's own previous context.
+ *
+ * So `REBUILD_READ` is the real test — the read did not cover what was carried
+ * — and it is a HIGH bar, not a half: a warm turn reads back essentially all of
+ * it (measured: 359,309 read against 358,973 carried, the read being the
+ * larger because the turn before it also grew). Half would have called a 66k
+ * conversation warm on a 36.8k preamble read alone, which is the exact case
+ * that makes this rule necessary.
+ *
+ * `REBUILD_WROTE` is then measured against what the read LEFT OVER rather than
+ * against the whole window, because the preamble is most of a small
+ * conversation and none of a large one.
+ *
+ * That second half also catches a compaction nobody wrote a boundary for: the
+ * window was thrown away, so the request after it writes far less than the gap
+ * between what it carried and what it read back, and it is not counted. Two
+ * independent defences against the one error that would make this figure look
+ * big and be wrong — the boundary flag is the other.
+ */
+export declare const REBUILD_WROTE = 0.5;
+export declare const REBUILD_READ = 0.8;
+/**
+ * Did this request re-write a window it had already cached?
+ *
+ * `prevTok` is what the PREVIOUS request in the same conversation carried — the
+ * context that was in the cache and could have been read back at a tenth of the
+ * rate. Absent or zero means there is nothing to have lost: the first request
+ * of any conversation writes its baseline, and that is the price of starting
+ * anywhere, not a rebuild.
+ *
+ * `afterCompaction` excludes the one case that looks identical and is not. A
+ * compaction drops the window to a fraction, so the request after it writes a
+ * small number against a large `prevTok` — the tokens were not re-written, they
+ * were thrown away on purpose, and `CompactionLedger` already accounts for that
+ * rebuild separately. Counting it here would bill compacting twice.
+ */
+export declare function isColdRebuild(prevTok: number | null | undefined, req: {
+    cacheRead: number;
+    cacheWrite: number;
+}, opts?: {
+    afterCompaction?: boolean;
+}): boolean;
+/**
+ * What the rebuilds in one conversation — or on a whole desktop — amount to.
+ *
+ * Every figure is a FLOOR for the reasons every figure derived from these logs
+ * is: a truncated log has rebuilds outside what was read, and a conversation
+ * that was forked continues in a file this one cannot see.
+ */
+export interface ColdStarts {
+    /** Requests that re-wrote a cached window. */
+    count: number;
+    /** Tokens they wrote — the ones that could have been cache reads. */
+    tok: number;
+    /** What those writes cost at list prices, on each record's own model and
+     *  day. Absent when nothing could be priced — never 0, which reads as free. */
+    usd?: number;
+    /**
+     * What they cost ABOVE re-reading the same tokens — the part that a resume
+     * inside the hour would not have paid at all.
+     *
+     * This is the number the feature exists for: `usd` includes tokens the
+     * conversation was always going to send, and only the premium is money that
+     * the clock, rather than the work, decided to spend.
+     */
+    premiumUsd?: number;
+    /** When the newest one happened, and how much it wrote. */
+    lastAt?: number;
+    lastTok?: number;
+}
+/**
+ * The rebuilds as a sentence — the ONE wording, on all three screens.
+ *
+ * Null when there were none: a zero here is not a fact worth a line, it is the
+ * normal state of a conversation nobody left sitting overnight.
+ *
+ * It never says "wasted". A long gap is usually somebody sleeping, and a
+ * conversation worth coming back to a day later is worth what it costs to come
+ * back to; what this can say is what the gap cost, which is a fact, and leave
+ * the judgement to whoever reads it.
+ */
+export declare function coldStartText(c: ColdStarts | null | undefined, scope: "session" | "corpus"): string | null;
+/**
+ * The same fact as a chip: `12 rebuilds`, or null.
+ *
+ * Tokens rather than money, because the two screens that show a chip already
+ * decide their own units — and null rather than `0` for `costChip`'s reason.
+ */
+export declare function coldStartChip(c: ColdStarts | null | undefined): string | null;

package/node_modules/@waterplane/shared/dist/sessioncost/costcold.js

@@ -0,0 +1,94 @@
+// Cut from sessioncost.ts (move only): cold rebuilds
+// The one door stays `./sessioncost.js`; this slice imports its siblings directly, never the barrel.
+import { fmtUsd } from "../pricing.js";
+import { fmtTok } from "./costwords.js";
+// ── The turns that re-wrote a window they had already paid to cache ─────────
+/**
+ * How much of the previous context a request must re-write before it counts as
+ * a rebuild, and how little of it it must read.
+ *
+ * Both halves are needed, and the second one is the half that took three
+ * attempts to get right. `cacheWrite > cacheRead` is NOT this test: every cold
+ * resume still reads the tools-and-system preamble, a separate cache entry kept
+ * warm by sibling sessions in the same repo and measured at 32.5k-36.8k on this
+ * desktop. A 60k conversation coming back cold reads 36.8k and writes 30.6k —
+ * write below read, and stone cold. What separates the two cases is whether the
+ * read covers the CONVERSATION's own previous context.
+ *
+ * So `REBUILD_READ` is the real test — the read did not cover what was carried
+ * — and it is a HIGH bar, not a half: a warm turn reads back essentially all of
+ * it (measured: 359,309 read against 358,973 carried, the read being the
+ * larger because the turn before it also grew). Half would have called a 66k
+ * conversation warm on a 36.8k preamble read alone, which is the exact case
+ * that makes this rule necessary.
+ *
+ * `REBUILD_WROTE` is then measured against what the read LEFT OVER rather than
+ * against the whole window, because the preamble is most of a small
+ * conversation and none of a large one.
+ *
+ * That second half also catches a compaction nobody wrote a boundary for: the
+ * window was thrown away, so the request after it writes far less than the gap
+ * between what it carried and what it read back, and it is not counted. Two
+ * independent defences against the one error that would make this figure look
+ * big and be wrong — the boundary flag is the other.
+ */
+export const REBUILD_WROTE = 0.5;
+export const REBUILD_READ = 0.8;
+/**
+ * Did this request re-write a window it had already cached?
+ *
+ * `prevTok` is what the PREVIOUS request in the same conversation carried — the
+ * context that was in the cache and could have been read back at a tenth of the
+ * rate. Absent or zero means there is nothing to have lost: the first request
+ * of any conversation writes its baseline, and that is the price of starting
+ * anywhere, not a rebuild.
+ *
+ * `afterCompaction` excludes the one case that looks identical and is not. A
+ * compaction drops the window to a fraction, so the request after it writes a
+ * small number against a large `prevTok` — the tokens were not re-written, they
+ * were thrown away on purpose, and `CompactionLedger` already accounts for that
+ * rebuild separately. Counting it here would bill compacting twice.
+ */
+export function isColdRebuild(prevTok, req, opts) {
+    if (opts?.afterCompaction)
+        return false;
+    if (prevTok == null || !(prevTok > 0))
+        return false;
+    // Read back nearly everything it carried: warm, whatever it wrote.
+    if (req.cacheRead >= prevTok * REBUILD_READ)
+        return false;
+    return req.cacheWrite >= (prevTok - req.cacheRead) * REBUILD_WROTE;
+}
+/**
+ * The rebuilds as a sentence — the ONE wording, on all three screens.
+ *
+ * Null when there were none: a zero here is not a fact worth a line, it is the
+ * normal state of a conversation nobody left sitting overnight.
+ *
+ * It never says "wasted". A long gap is usually somebody sleeping, and a
+ * conversation worth coming back to a day later is worth what it costs to come
+ * back to; what this can say is what the gap cost, which is a fact, and leave
+ * the judgement to whoever reads it.
+ */
+export function coldStartText(c, scope) {
+    if (!c || c.count <= 0 || c.tok <= 0)
+        return null;
+    const n = c.count;
+    const where = scope === "session"
+        ? `${n === 1 ? "One turn" : `${n} turns`} here `
+        : `${n === 1 ? "One request" : `${n} requests`} across this desktop `;
+    const money = c.premiumUsd != null && c.premiumUsd > 0
+        ? ` That is ${fmtUsd(c.premiumUsd)} more than re-reading them would have cost at list prices${c.usd != null && c.usd > 0 ? `, out of ${fmtUsd(c.usd)} for the writes themselves` : ""}.`
+        : "";
+    return `${where}came back to a cache that had expired and re-WROTE ${fmtTok(c.tok)} tokens instead of re-reading them.${money}`;
+}
+/**
+ * The same fact as a chip: `12 rebuilds`, or null.
+ *
+ * Tokens rather than money, because the two screens that show a chip already
+ * decide their own units — and null rather than `0` for `costChip`'s reason.
+ */
+export function coldStartChip(c) {
+    return c && c.count > 0 ? `${c.count} re-write${c.count > 1 ? "s" : ""}` : null;
+}
+//# sourceMappingURL=costcold.js.map

package/node_modules/@waterplane/shared/dist/sessioncost/costcold.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"costcold.js","sourceRoot":"","sources":["../../src/sessioncost/costcold.ts"],"names":[],"mappings":"AAAA,qDAAqD;AACrD,qGAAqG;AAErG,OAAO,EAAE,MAAM,EAAE,MAAM,eAAe,CAAC;AACvC,OAAO,EAAE,MAAM,EAAE,MAAM,gBAAgB,CAAC;AAExC,+EAA+E;AAE/E;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,GAAG,CAAC;AACjC,MAAM,CAAC,MAAM,YAAY,GAAG,GAAG,CAAC;AAEhC;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,aAAa,CAC3B,OAAkC,EAClC,GAA8C,EAC9C,IAAoC;IAEpC,IAAI,IAAI,EAAE,eAAe;QAAE,OAAO,KAAK,CAAC;IACxC,IAAI,OAAO,IAAI,IAAI,IAAI,CAAC,CAAC,OAAO,GAAG,CAAC,CAAC;QAAE,OAAO,KAAK,CAAC;IACpD,mEAAmE;IACnE,IAAI,GAAG,CAAC,SAAS,IAAI,OAAO,GAAG,YAAY;QAAE,OAAO,KAAK,CAAC;IAC1D,OAAO,GAAG,CAAC,UAAU,IAAI,CAAC,OAAO,GAAG,GAAG,CAAC,SAAS,CAAC,GAAG,aAAa,CAAC;AACrE,CAAC;AA+BD;;;;;;;;;;GAUG;AACH,MAAM,UAAU,aAAa,CAAC,CAAgC,EAAE,KAA2B;IACzF,IAAI,CAAC,CAAC,IAAI,CAAC,CAAC,KAAK,IAAI,CAAC,IAAI,CAAC,CAAC,GAAG,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC;IAClD,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC;IAClB,MAAM,KAAK,GAAG,KAAK,KAAK,SAAS;QAC/B,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,GAAG,CAAC,QAAQ,QAAQ;QAChD,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,GAAG,CAAC,WAAW,uBAAuB,CAAC;IACxE,MAAM,KAAK,GAAG,CAAC,CAAC,UAAU,IAAI,IAAI,IAAI,CAAC,CAAC,UAAU,GAAG,CAAC;QACpD,CAAC,CAAC,YAAY,MAAM,CAAC,CAAC,CAAC,UAAU,CAAC,4DAA4D,CAAC,CAAC,GAAG,IAAI,IAAI,IAAI,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC,YAAY,MAAM,CAAC,CAAC,CAAC,GAAG,CAAC,4BAA4B,CAAC,CAAC,CAAC,EAAE,GAAG;QACxL,CAAC,CAAC,EAAE,CAAC;IACP,OAAO,GAAG,KAAK,sDAAsD,MAAM,CAAC,CAAC,CAAC,GAAG,CAAC,sCAAsC,KAAK,EAAE,CAAC;AAClI,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,aAAa,CAAC,CAAgC;IAC5D,OAAO,CAAC,IAAI,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,YAAY,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;AAClF,CAAC"}

package/node_modules/@waterplane/shared/dist/sessioncost/costcompact.d.ts

@@ -0,0 +1,125 @@
+/**
+ * The compaction ledger folded into one reading — both triggers together.
+ *
+ * The wire splits auto from manual because "was typing `/compact` worth it" is
+ * only answerable if the CLI's own decisions are counted apart. Most sentences
+ * are about the pair, so the fold lives here rather than at each call site,
+ * and the money fields come back null — never 0 — for `costChip`'s reason.
+ */
+export interface CompactionReading {
+    /** Compactions in the figures: both triggers, `unmeasured` excluded. */
+    count: number;
+    manual: number;
+    /** Boundaries the log did not describe well enough to price — see
+     *  `CompactionLedger.unmeasured`. In none of the figures below. */
+    unmeasured: number;
+    shedTok: number;
+    savedTok: number;
+    savedUsd: number | null;
+    rebuildTok: number;
+    rebuildUsd: number | null;
+}
+/** Fold the two rows. Null money where nothing was priced or nothing saved. */
+export declare function compactionReading(l: {
+    auto: CompactionRow;
+    manual: CompactionRow;
+    unmeasured: number;
+}): CompactionReading;
+/** The shape `compactionReading` folds — `CompactionCost` structurally, so this
+ *  module stays readable without the wire file. */
+export interface CompactionRow {
+    count: number;
+    shedTok: number;
+    savedTok: number;
+    savedUsd?: number;
+    rebuildTok: number;
+    rebuildUsd?: number;
+}
+/**
+ * How many compactions, and how many of them somebody asked for — one line.
+ *
+ * Null when none have run, because "0 compactions" is a panel's worth of
+ * chrome around nothing; the caller says that in a sentence instead.
+ */
+export declare function compactionCountText(r: CompactionReading): string | null;
+/**
+ * Compactions in NO figure, as their own sentence — never a number folded into
+ * the rows above.
+ *
+ * `unpricedTok`'s posture applied to a count: what could not be measured is
+ * named, because the alternative is a ledger that silently reads as complete.
+ */
+export declare function compactionUnmeasuredText(r: CompactionReading): string | null;
+/**
+ * A ledger row's numbers, as the chips it wears.
+ *
+ * Built here rather than in the component for the reason `costChip` is: this is
+ * where "no figure" is decided. A `saved 0 · cost 0` row is the token spelling
+ * of the `$0` this file refuses everywhere else — it reads as a verdict on
+ * compacting, when the fact is that no turn has run since. So a zero side is
+ * DROPPED, and a row with neither says which state it is in.
+ */
+export declare function compactionRowFacts(c: CompactionRow): string[];
+/**
+ * What compacting has saved, in one sentence.
+ *
+ * The saving is a COUNTERFACTUAL and is worded as one: these are tokens no
+ * request had to re-send, so unlike everything else on the screen the money is
+ * not in any total — it was never spent. "so far" for `usageText`'s reason and
+ * for one more: the figure grows with every turn that follows, because every
+ * one of them re-sends a window this much smaller.
+ *
+ * Null while nothing has been saved yet — a compaction with no turn after it.
+ * That is a real state with its own sentence (`compactionPendingText`), not a
+ * `$0` to print.
+ */
+export declare function compactionSavedText(r: CompactionReading): string | null;
+/** Compacted, but nothing has run since — so nothing is saved YET. */
+export declare function compactionPendingText(r: CompactionReading): string | null;
+/**
+ * What compacting cost, in one sentence — and what that figure leaves out.
+ *
+ * Two things a reader would otherwise get wrong, so both are in the words:
+ * this money IS in the session's own total (the cache write happened), and
+ * the summarising request is NOT in it, because the CLI does not write that
+ * call to the conversation log. Measured, not assumed: between the boundary
+ * and the next prompt there is no assistant record at all.
+ */
+export declare function compactionCostText(r: CompactionReading): string | null;
+/**
+ * The two sides as a ratio, where one exists — the reading somebody is
+ * actually after.
+ *
+ * Only in money, and only when both sides could be priced: the token counts
+ * compare a cache read with a cache write, which differ by up to twenty times
+ * in price, so their ratio is a number that means nothing.
+ */
+export declare function compactionRatioText(r: CompactionReading): string | null;
+/**
+ * Where the counterfactual stops being a saving and starts being the only way
+ * the conversation could have continued.
+ *
+ * An uncompacted window of 1.4M is not an expensive conversation, it is a
+ * refused request — so past the model's own window the money above is not what
+ * you would have paid, it is what those turns would have cost if they could
+ * have run at all. That is a stronger statement than the saving and it has to
+ * be said where it is true, which is most long conversations.
+ *
+ * Null when the window is unknown (`windowTok` null) — nothing is claimed
+ * about a ceiling nobody measured.
+ */
+export declare function compactionWindowText(r: CompactionReading, tok: number | null, windowTok: number | null): string | null;
+/**
+ * How both figures were arrived at, and which way each one errs.
+ *
+ * Not a disclaimer: it is the reason the reading can be trusted in the
+ * direction it will be used in. Somebody reads this panel to decide whether to
+ * keep typing `/compact`, so both estimates are deliberately biased AGAINST
+ * the answer "yes" — the saving priced at the cheapest thing those tokens
+ * could have been, the cost counting a write the turn partly owed anyway. A
+ * ratio built the other way round would be an advertisement.
+ */
+export declare function compactionMethodText(): string;
+/** The label a ledger row wears. Plural-aware, and the manual one names the
+ *  command, because "manual" is the wire's word and not a person's. */
+export declare function compactionRowLabel(kind: "auto" | "manual", count: number): string;

package/node_modules/@waterplane/shared/dist/sessioncost/costcompact.js

@@ -0,0 +1,184 @@
+// Cut from sessioncost.ts (move only): what compacting saved and cost
+// The one door stays `./sessioncost.js`; this slice imports its siblings directly, never the barrel.
+import { fmtUsd } from "../pricing.js";
+import { fmtMultiple, fmtTok } from "./costwords.js";
+/** Fold the two rows. Null money where nothing was priced or nothing saved. */
+export function compactionReading(l) {
+    const usd = (a, b) => {
+        const n = (a ?? 0) + (b ?? 0);
+        return n > 0 ? n : null;
+    };
+    return {
+        count: l.auto.count + l.manual.count,
+        manual: l.manual.count,
+        unmeasured: l.unmeasured,
+        shedTok: l.auto.shedTok + l.manual.shedTok,
+        savedTok: l.auto.savedTok + l.manual.savedTok,
+        savedUsd: usd(l.auto.savedUsd, l.manual.savedUsd),
+        rebuildTok: l.auto.rebuildTok + l.manual.rebuildTok,
+        rebuildUsd: usd(l.auto.rebuildUsd, l.manual.rebuildUsd),
+    };
+}
+/**
+ * How many compactions, and how many of them somebody asked for — one line.
+ *
+ * Null when none have run, because "0 compactions" is a panel's worth of
+ * chrome around nothing; the caller says that in a sentence instead.
+ */
+export function compactionCountText(r) {
+    // MEASURED ones only. A boundary the log did not describe is not "the CLI's
+    // own" — nothing here knows who asked for it, and folding it into the other
+    // row is how a count becomes a claim nobody measured. It gets its own
+    // sentence, beside these figures rather than inside them.
+    const n = r.count;
+    if (n <= 0)
+        return null;
+    const who = n === 1
+        ? (r.manual === 1 ? "One compaction, and you asked for it." : "One compaction, the CLI's own.")
+        : r.manual === 0 ? `${n} compactions, none of them yours.`
+            : r.manual === n ? `${n} compactions, all of them yours.`
+                : `${n} compactions — ${r.manual} you asked for, ${n - r.manual} the CLI's own.`;
+    const shed = r.shedTok > 0
+        ? ` ${n === 1 ? "It took" : "Together they took"} ${fmtTok(r.shedTok)} out of the window.`
+        : "";
+    return who + shed;
+}
+/**
+ * Compactions in NO figure, as their own sentence — never a number folded into
+ * the rows above.
+ *
+ * `unpricedTok`'s posture applied to a count: what could not be measured is
+ * named, because the alternative is a ledger that silently reads as complete.
+ */
+export function compactionUnmeasuredText(r) {
+    if (r.unmeasured <= 0)
+        return null;
+    const n = r.unmeasured === 1
+        ? "One more compaction is"
+        : `${r.unmeasured} more compactions are`;
+    return `${n} in none of these figures — the log did not record both sides of the drop, so there is nothing to measure them from.`;
+}
+/**
+ * A ledger row's numbers, as the chips it wears.
+ *
+ * Built here rather than in the component for the reason `costChip` is: this is
+ * where "no figure" is decided. A `saved 0 · cost 0` row is the token spelling
+ * of the `$0` this file refuses everywhere else — it reads as a verdict on
+ * compacting, when the fact is that no turn has run since. So a zero side is
+ * DROPPED, and a row with neither says which state it is in.
+ */
+export function compactionRowFacts(c) {
+    const out = [];
+    if (c.savedTok > 0) {
+        out.push(`saved ${fmtTok(c.savedTok)}${c.savedUsd != null ? ` · ${fmtUsd(c.savedUsd)}` : ""}`);
+    }
+    if (c.rebuildTok > 0) {
+        out.push(`cost ${fmtTok(c.rebuildTok)}${c.rebuildUsd != null ? ` · ${fmtUsd(c.rebuildUsd)}` : ""}`);
+    }
+    return out.length ? out : ["nothing back yet"];
+}
+/**
+ * What compacting has saved, in one sentence.
+ *
+ * The saving is a COUNTERFACTUAL and is worded as one: these are tokens no
+ * request had to re-send, so unlike everything else on the screen the money is
+ * not in any total — it was never spent. "so far" for `usageText`'s reason and
+ * for one more: the figure grows with every turn that follows, because every
+ * one of them re-sends a window this much smaller.
+ *
+ * Null while nothing has been saved yet — a compaction with no turn after it.
+ * That is a real state with its own sentence (`compactionPendingText`), not a
+ * `$0` to print.
+ */
+export function compactionSavedText(r) {
+    if (r.savedTok <= 0)
+        return null;
+    const money = r.savedUsd != null
+        ? `, worth ${fmtUsd(r.savedUsd)} at list prices — the one figure here that was never actually spent`
+        : "";
+    return `Every request since has carried that much less: ${fmtTok(r.savedTok)} tokens not re-sent${money}.`;
+}
+/** Compacted, but nothing has run since — so nothing is saved YET. */
+export function compactionPendingText(r) {
+    if (r.count <= 0 || r.savedTok > 0)
+        return null;
+    return "No turn has run since, so nothing has been saved back yet — the saving is what the next requests will not have to carry.";
+}
+/**
+ * What compacting cost, in one sentence — and what that figure leaves out.
+ *
+ * Two things a reader would otherwise get wrong, so both are in the words:
+ * this money IS in the session's own total (the cache write happened), and
+ * the summarising request is NOT in it, because the CLI does not write that
+ * call to the conversation log. Measured, not assumed: between the boundary
+ * and the next prompt there is no assistant record at all.
+ */
+export function compactionCostText(r) {
+    if (r.rebuildTok <= 0)
+        return null;
+    const money = r.rebuildUsd != null ? ` (${fmtUsd(r.rebuildUsd)})` : "";
+    return `Rebuilding the window afterwards wrote ${fmtTok(r.rebuildTok)} tokens${money} — real spend, already counted in this session's total. The summarising request itself is not in the CLI's log, so it is in neither figure.`;
+}
+/**
+ * The two sides as a ratio, where one exists — the reading somebody is
+ * actually after.
+ *
+ * Only in money, and only when both sides could be priced: the token counts
+ * compare a cache read with a cache write, which differ by up to twenty times
+ * in price, so their ratio is a number that means nothing.
+ */
+export function compactionRatioText(r) {
+    if (r.savedUsd == null || r.rebuildUsd == null || r.rebuildUsd <= 0)
+        return null;
+    const m = r.savedUsd / r.rebuildUsd;
+    if (!(m >= 1))
+        return `That is ${fmtUsd(r.rebuildUsd - r.savedUsd)} more than it has saved back so far.`;
+    return `${fmtMultiple(m)} what it cost.`;
+}
+/**
+ * Where the counterfactual stops being a saving and starts being the only way
+ * the conversation could have continued.
+ *
+ * An uncompacted window of 1.4M is not an expensive conversation, it is a
+ * refused request — so past the model's own window the money above is not what
+ * you would have paid, it is what those turns would have cost if they could
+ * have run at all. That is a stronger statement than the saving and it has to
+ * be said where it is true, which is most long conversations.
+ *
+ * Null when the window is unknown (`windowTok` null) — nothing is claimed
+ * about a ceiling nobody measured.
+ */
+export function compactionWindowText(r, tok, windowTok) {
+    // "Those turns could not have run" is a sentence about the turns SINCE, so a
+    // conversation that compacted and then stopped has none to make it about —
+    // and the reading would be asserting a consequence for work nobody did.
+    if (!(r.savedTok > 0) || !(r.shedTok > 0))
+        return null;
+    if (!(windowTok && windowTok > 0) || !(tok && tok > 0))
+        return null;
+    const would = tok + r.shedTok;
+    if (would <= windowTok)
+        return null;
+    return `Uncompacted it would be carrying ${fmtTok(would)} — past the ${fmtTok(windowTok)} window, so those turns could not have run at all.`;
+}
+/**
+ * How both figures were arrived at, and which way each one errs.
+ *
+ * Not a disclaimer: it is the reason the reading can be trusted in the
+ * direction it will be used in. Somebody reads this panel to decide whether to
+ * keep typing `/compact`, so both estimates are deliberately biased AGAINST
+ * the answer "yes" — the saving priced at the cheapest thing those tokens
+ * could have been, the cost counting a write the turn partly owed anyway. A
+ * ratio built the other way round would be an advertisement.
+ */
+export function compactionMethodText() {
+    return "The saving prices those tokens as cache reads — the cheapest they could have been; a conversation resumed after the cache expired re-writes its window at up to twenty times that rate. The cost counts the whole first write after each boundary, part of which the next turn would have paid anyway. Both err against compacting looking worthwhile.";
+}
+/** The label a ledger row wears. Plural-aware, and the manual one names the
+ *  command, because "manual" is the wire's word and not a person's. */
+export function compactionRowLabel(kind, count) {
+    if (kind === "manual")
+        return count === 1 ? "you typed /compact" : `you typed /compact ${count}×`;
+    return count === 1 ? "the CLI compacted" : `the CLI compacted ${count}×`;
+}
+//# sourceMappingURL=costcompact.js.map

package/node_modules/@waterplane/shared/dist/sessioncost/costcompact.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"costcompact.js","sourceRoot":"","sources":["../../src/sessioncost/costcompact.ts"],"names":[],"mappings":"AAAA,sEAAsE;AACtE,qGAAqG;AAErG,OAAO,EAAE,MAAM,EAAE,MAAM,eAAe,CAAC;AACvC,OAAO,EAAE,WAAW,EAAE,MAAM,EAAE,MAAM,gBAAgB,CAAC;AA0BrD,+EAA+E;AAC/E,MAAM,UAAU,iBAAiB,CAAC,CAEjC;IACC,MAAM,GAAG,GAAG,CAAC,CAAU,EAAE,CAAU,EAAE,EAAE;QACrC,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC;QAC9B,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IAC1B,CAAC,CAAC;IACF,OAAO;QACL,KAAK,EAAE,CAAC,CAAC,IAAI,CAAC,KAAK,GAAG,CAAC,CAAC,MAAM,CAAC,KAAK;QACpC,MAAM,EAAE,CAAC,CAAC,MAAM,CAAC,KAAK;QACtB,UAAU,EAAE,CAAC,CAAC,UAAU;QACxB,OAAO,EAAE,CAAC,CAAC,IAAI,CAAC,OAAO,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO;QAC1C,QAAQ,EAAE,CAAC,CAAC,IAAI,CAAC,QAAQ,GAAG,CAAC,CAAC,MAAM,CAAC,QAAQ;QAC7C,QAAQ,EAAE,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,QAAQ,EAAE,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC;QACjD,UAAU,EAAE,CAAC,CAAC,IAAI,CAAC,UAAU,GAAG,CAAC,CAAC,MAAM,CAAC,UAAU;QACnD,UAAU,EAAE,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,UAAU,EAAE,CAAC,CAAC,MAAM,CAAC,UAAU,CAAC;KACxD,CAAC;AACJ,CAAC;AAaD;;;;;GAKG;AACH,MAAM,UAAU,mBAAmB,CAAC,CAAoB;IACtD,4EAA4E;IAC5E,4EAA4E;IAC5E,sEAAsE;IACtE,0DAA0D;IAC1D,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC;IAClB,IAAI,CAAC,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC;IACxB,MAAM,GAAG,GAAG,CAAC,KAAK,CAAC;QACjB,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,uCAAuC,CAAC,CAAC,CAAC,gCAAgC,CAAC;QAC/F,CAAC,CAAC,CAAC,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,mCAAmC;YACxD,CAAC,CAAC,CAAC,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,kCAAkC;gBACvD,CAAC,CAAC,GAAG,CAAC,kBAAkB,CAAC,CAAC,MAAM,mBAAmB,CAAC,GAAG,CAAC,CAAC,MAAM,iBAAiB,CAAC;IACvF,MAAM,IAAI,GAAG,CAAC,CAAC,OAAO,GAAG,CAAC;QACxB,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,oBAAoB,IAAI,MAAM,CAAC,CAAC,CAAC,OAAO,CAAC,qBAAqB;QAC1F,CAAC,CAAC,EAAE,CAAC;IACP,OAAO,GAAG,GAAG,IAAI,CAAC;AACpB,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,wBAAwB,CAAC,CAAoB;IAC3D,IAAI,CAAC,CAAC,UAAU,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC;IACnC,MAAM,CAAC,GAAG,CAAC,CAAC,UAAU,KAAK,CAAC;QAC1B,CAAC,CAAC,wBAAwB;QAC1B,CAAC,CAAC,GAAG,CAAC,CAAC,UAAU,uBAAuB,CAAC;IAC3C,OAAO,GAAG,CAAC,sHAAsH,CAAC;AACpI,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,kBAAkB,CAAC,CAAgB;IACjD,MAAM,GAAG,GAAa,EAAE,CAAC;IACzB,IAAI,CAAC,CAAC,QAAQ,GAAG,CAAC,EAAE,CAAC;QACnB,GAAG,CAAC,IAAI,CAAC,SAAS,MAAM,CAAC,CAAC,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,QAAQ,IAAI,IAAI,CAAC,CAAC,CAAC,MAAM,MAAM,CAAC,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;IACjG,CAAC;IACD,IAAI,CAAC,CAAC,UAAU,GAAG,CAAC,EAAE,CAAC;QACrB,GAAG,CAAC,IAAI,CAAC,QAAQ,MAAM,CAAC,CAAC,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,UAAU,IAAI,IAAI,CAAC,CAAC,CAAC,MAAM,MAAM,CAAC,CAAC,CAAC,UAAU,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;IACtG,CAAC;IACD,OAAO,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,kBAAkB,CAAC,CAAC;AACjD,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,mBAAmB,CAAC,CAAoB;IACtD,IAAI,CAAC,CAAC,QAAQ,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC;IACjC,MAAM,KAAK,GAAG,CAAC,CAAC,QAAQ,IAAI,IAAI;QAC9B,CAAC,CAAC,WAAW,MAAM,CAAC,CAAC,CAAC,QAAQ,CAAC,qEAAqE;QACpG,CAAC,CAAC,EAAE,CAAC;IACP,OAAO,mDAAmD,MAAM,CAAC,CAAC,CAAC,QAAQ,CAAC,sBAAsB,KAAK,GAAG,CAAC;AAC7G,CAAC;AAED,sEAAsE;AACtE,MAAM,UAAU,qBAAqB,CAAC,CAAoB;IACxD,IAAI,CAAC,CAAC,KAAK,IAAI,CAAC,IAAI,CAAC,CAAC,QAAQ,GAAG,CAAC;QAAE,OAAO,IAAI,CAAC;IAChD,OAAO,0HAA0H,CAAC;AACpI,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,kBAAkB,CAAC,CAAoB;IACrD,IAAI,CAAC,CAAC,UAAU,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC;IACnC,MAAM,KAAK,GAAG,CAAC,CAAC,UAAU,IAAI,IAAI,CAAC,CAAC,CAAC,KAAK,MAAM,CAAC,CAAC,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;IACvE,OAAO,0CAA0C,MAAM,CAAC,CAAC,CAAC,UAAU,CAAC,UAAU,KAAK,6IAA6I,CAAC;AACpO,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,mBAAmB,CAAC,CAAoB;IACtD,IAAI,CAAC,CAAC,QAAQ,IAAI,IAAI,IAAI,CAAC,CAAC,UAAU,IAAI,IAAI,IAAI,CAAC,CAAC,UAAU,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC;IACjF,MAAM,CAAC,GAAG,CAAC,CAAC,QAAQ,GAAG,CAAC,CAAC,UAAU,CAAC;IACpC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;QAAE,OAAO,WAAW,MAAM,CAAC,CAAC,CAAC,UAAU,GAAG,CAAC,CAAC,QAAQ,CAAC,sCAAsC,CAAC;IACzG,OAAO,GAAG,WAAW,CAAC,CAAC,CAAC,gBAAgB,CAAC;AAC3C,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,oBAAoB,CAClC,CAAoB,EACpB,GAAkB,EAClB,SAAwB;IAExB,6EAA6E;IAC7E,2EAA2E;IAC3E,wEAAwE;IACxE,IAAI,CAAC,CAAC,CAAC,CAAC,QAAQ,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,OAAO,GAAG,CAAC,CAAC;QAAE,OAAO,IAAI,CAAC;IACvD,IAAI,CAAC,CAAC,SAAS,IAAI,SAAS,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,GAAG,IAAI,GAAG,GAAG,CAAC,CAAC;QAAE,OAAO,IAAI,CAAC;IACpE,MAAM,KAAK,GAAG,GAAG,GAAG,CAAC,CAAC,OAAO,CAAC;IAC9B,IAAI,KAAK,IAAI,SAAS;QAAE,OAAO,IAAI,CAAC;IACpC,OAAO,oCAAoC,MAAM,CAAC,KAAK,CAAC,eAAe,MAAM,CAAC,SAAS,CAAC,oDAAoD,CAAC;AAC/I,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,oBAAoB;IAClC,OAAO,wVAAwV,CAAC;AAClW,CAAC;AAED;uEACuE;AACvE,MAAM,UAAU,kBAAkB,CAAC,IAAuB,EAAE,KAAa;IACvE,IAAI,IAAI,KAAK,QAAQ;QAAE,OAAO,KAAK,KAAK,CAAC,CAAC,CAAC,CAAC,oBAAoB,CAAC,CAAC,CAAC,sBAAsB,KAAK,GAAG,CAAC;IAClG,OAAO,KAAK,KAAK,CAAC,CAAC,CAAC,CAAC,mBAAmB,CAAC,CAAC,CAAC,qBAAqB,KAAK,GAAG,CAAC;AAC3E,CAAC"}

package/node_modules/@waterplane/shared/dist/sessioncost/costofseries.d.ts

@@ -0,0 +1,21 @@
+import type { SessionCostReading } from "./costtypes.js";
+import { type CacheAge } from "./costreading.js";
+/**
+ * The same reading straight off a `ContextSpark`, which is what every screen
+ * actually holds.
+ *
+ * Kept here rather than at the call sites so the three fields the spark carries
+ * for this are read one way: `pts` is DOWNSAMPLED, so on a conversation that
+ * compacted early its first entry is that bucket's PEAK and not the session's
+ * first reading — exactly the mistake that would inflate every baseline and
+ * quietly understate every multiple. `baseTok` is the true first reading and is
+ * carried separately for that reason.
+ */
+export declare function sessionCostOf(spark: {
+    pts: number[];
+    baseTok?: number;
+    turns?: number;
+    spentTok?: number;
+    usageTok?: number;
+    agentTok?: number;
+} | null | undefined, live?: CacheAge | null): SessionCostReading | null;

package/node_modules/@waterplane/shared/dist/sessioncost/costofseries.js

@@ -0,0 +1,31 @@
+// Cut from sessioncost.ts (move only): the reading off a context spark
+// The one door stays `./sessioncost.js`; this slice imports its siblings directly, never the barrel.
+import { sessionCost, coldFrom } from "./costreading.js";
+/**
+ * The same reading straight off a `ContextSpark`, which is what every screen
+ * actually holds.
+ *
+ * Kept here rather than at the call sites so the three fields the spark carries
+ * for this are read one way: `pts` is DOWNSAMPLED, so on a conversation that
+ * compacted early its first entry is that bucket's PEAK and not the session's
+ * first reading — exactly the mistake that would inflate every baseline and
+ * quietly understate every multiple. `baseTok` is the true first reading and is
+ * carried separately for that reason.
+ */
+export function sessionCostOf(spark, live) {
+    if (!spark || !spark.pts.length)
+        return null;
+    const tok = spark.pts[spark.pts.length - 1];
+    if (!(tok > 0))
+        return null;
+    return sessionCost({
+        tok,
+        baseTok: spark.baseTok ?? null,
+        turns: spark.turns ?? null,
+        spentTok: spark.spentTok ?? null,
+        usageTok: spark.usageTok ?? null,
+        agentTok: spark.agentTok ?? null,
+        cacheCold: coldFrom(live),
+    });
+}
+//# sourceMappingURL=costofseries.js.map

package/node_modules/@waterplane/shared/dist/sessioncost/costofseries.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"costofseries.js","sourceRoot":"","sources":["../../src/sessioncost/costofseries.ts"],"names":[],"mappings":"AAAA,uEAAuE;AACvE,qGAAqG;AAGrG,OAAO,EAAE,WAAW,EAAE,QAAQ,EAAiB,MAAM,kBAAkB,CAAC;AAExE;;;;;;;;;;GAUG;AACH,MAAM,UAAU,aAAa,CAAC,KAOV,EAAE,IAAsB;IAC1C,IAAI,CAAC,KAAK,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,MAAM;QAAE,OAAO,IAAI,CAAC;IAC7C,MAAM,GAAG,GAAG,KAAK,CAAC,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IAC5C,IAAI,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC;QAAE,OAAO,IAAI,CAAC;IAC5B,OAAO,WAAW,CAAC;QACjB,GAAG;QACH,OAAO,EAAE,KAAK,CAAC,OAAO,IAAI,IAAI;QAC9B,KAAK,EAAE,KAAK,CAAC,KAAK,IAAI,IAAI;QAC1B,QAAQ,EAAE,KAAK,CAAC,QAAQ,IAAI,IAAI;QAChC,QAAQ,EAAE,KAAK,CAAC,QAAQ,IAAI,IAAI;QAChC,QAAQ,EAAE,KAAK,CAAC,QAAQ,IAAI,IAAI;QAChC,SAAS,EAAE,QAAQ,CAAC,IAAI,CAAC;KAC1B,CAAC,CAAC;AACL,CAAC"}