waterplane 0.0.1 → 0.1.6

package/node_modules/@waterplane/shared/dist/tokens.d.ts

@@ -0,0 +1,198 @@
+import type { TokenGroup, TokenTotals } from "./wire/telemetry.js";
+/** An empty tally, for a fold's seed and for a group nobody has written to. */
+export declare function zeroTotals(): TokenTotals;
+/** Add `b` into `a`, in place. The one fold every aggregate uses. */
+export declare function addTotals(a: TokenTotals, b: Partial<TokenTotals>): TokenTotals;
+/**
+ * Every token that passed through, of any kind. Never shown without the split
+ * beside it — see the header.
+ *
+ * `cacheWrite1h` is deliberately absent: it is a SUBSET of `cacheWrite`, kept
+ * only so the cost estimate can charge the 2× tier correctly. Adding it here
+ * would double-count 84% of the cache writes.
+ */
+export declare function tokenTotal(t: TokenTotals): number;
+export type TokenKind = "input" | "output" | "cacheRead" | "cacheWrite";
+/**
+ * The four kinds, in a FIXED order.
+ *
+ * Fixed because the order IS the colour assignment: a categorical hue follows
+ * the entity and never its rank, so a filter or a re-sort must not repaint the
+ * survivors. The `slot` is an index into the chart palette, owned by the web
+ * side; this file names the entity, not the colour.
+ */
+export declare const TOKEN_KINDS: {
+    id: TokenKind;
+    slot: number;
+    name: string;
+    what: string;
+}[];
+/**
+ * A `ContextSample.kinds` tuple as the shape everything else here speaks.
+ *
+ * The ONE reader of that tuple's order, and the reason it may be a tuple at
+ * all: 1,200 samples × four key names is most of a document's bytes, but a
+ * positional array read in two places is a chart with the right numbers in the
+ * wrong colours the first time somebody reorders `TOKEN_KINDS`. So the order
+ * lives here, beside the list it has to match, and nothing else indexes it.
+ *
+ * `turns: 1` because a sample IS one request — the same denominator
+ * `tokenstats.ts` counts, so a per-request figure means the same thing on the
+ * per-session screen and the corpus one.
+ */
+export declare function sampleTotals(k: readonly [number, number, number, number]): TokenTotals;
+/**
+ * How much of the context the cache carried, 0..100, or null when there is
+ * nothing to divide.
+ *
+ * Deliberately over `cacheRead / (cacheRead + cacheWrite + input)` — the three
+ * kinds that make up what went IN. Output is not context and putting it in the
+ * denominator would make the ratio drift with how talkative the model was
+ * rather than with how well the cache worked.
+ */
+export declare function cacheHitPct(t: TokenTotals): number | null;
+/** Mean tokens per assistant turn, or null with no turns. */
+export declare function perTurn(t: TokenTotals): number | null;
+/**
+ * ── Is a 96% cache-read share GOOD, or is it context pollution? ─────────────
+ *
+ * The question this screen invites and could not answer. A reader who sees one
+ * kind at 96% of the tokens and 55% of the money reasonably asks whether that
+ * is the cache doing its job or the same bloated conversation being re-read for
+ * ever, and those are two different facts that happen to look identical in a
+ * share.
+ *
+ * **The share cannot tell them apart, so it is never asked to.** A cache read
+ * bills at `CACHE_READ_MULT` — a tenth of the input rate — so context arriving
+ * as a cache read rather than as fresh input is the CHEAP shape of the same
+ * traffic, and a share near 100% is what a healthy corpus looks like. The share
+ * would only fall by re-sending that context at full price. There is no number
+ * of cache reads that is "too many" in itself.
+ *
+ * Two ratios underneath it do carry a verdict, and both are arithmetic over
+ * counts already on the wire rather than a judgement:
+ *
+ *   • **Reuse** — `cacheRead / cacheWrite`, how many times each token written
+ *     into the cache was read back. A write costs 1.25× (5-minute) or 2×
+ *     (1-hour) the input rate against 0.1× for a read, so a write pays for
+ *     itself at `mult / (1 - CACHE_READ_MULT)` reads — about 1.4 and 2.2. Below
+ *     that the caching is LOSING money against simply sending the tokens fresh,
+ *     which is a real and nameable failure: sessions dying before their prefix
+ *     is read back, or a window invalidated every turn.
+ *   • **Context per turn** — what a turn actually carried. THIS is the pollution
+ *     number: the measurement in `sessioncost.ts`'s header found conversations
+ *     past ~200k carrying 76% of every token spent on this desktop. It is the
+ *     size of the window, not the share of it served from cache, that makes a
+ *     turn expensive.
+ *
+ * The caveat travels with it because it is the same measurement: this is a MEAN
+ * over every turn on disk, and the distribution it came from was 1.4% of
+ * conversations holding 76% of the tokens. A lean average does not mean there
+ * are no monsters — `sessionCost` is the per-conversation reading and the only
+ * one that can name one.
+ *
+ * Sentences, never a gate, for the reason `sessioncost.ts` states at length.
+ */
+/** Context per turn at which the corpus's own measurement says a conversation
+ *  has become the expensive kind. Read off that measurement, not chosen. */
+export declare const CTX_PER_TURN_HEAVY = 200000;
+/** Below this a mean turn is nowhere near the heavy tail. */
+export declare const CTX_PER_TURN_LEAN = 100000;
+export type CachePosture = "lean" | "ordinary" | "heavy";
+export interface CacheReading {
+    /** `cacheHitPct`, carried so a caller states the share it is judging. */
+    sharePct: number;
+    /** Reads per written token, or null when nothing was written. */
+    reuse: number | null;
+    /** Reads a write must earn back to beat sending the tokens fresh, blended
+     *  across the two TTL tiers actually used. Null when nothing was written. */
+    payback: number | null;
+    /** Mean context carried per turn — read + write + input over turns. Null when
+     *  no turns were counted, and then there is no posture either. */
+    perTurnCtx: number | null;
+    posture: CachePosture | null;
+    /** What the share means. */
+    cacheNote: string;
+    /** What the per-turn context means, or null when turns are unknown. */
+    contextNote: string | null;
+    /** The one thing worth doing about it, when there is one. */
+    advice: string | null;
+}
+/**
+ * WHOSE tokens are being read — which changes two sentences and nothing else.
+ *
+ * `corpus` is every conversation on the desktop (the all-sessions screen), and
+ * there the mean's caveat can point at the per-session reading as the place to
+ * name a monster. On the context sheet that reading IS the screen the reader is
+ * on, so the same sentence sends them where they already are, and the advice
+ * duplicates the cost panel sitting six lines above it with its own button.
+ * The arithmetic, the thresholds and the share sentence are identical — this
+ * only decides what the mean's caveat says and whether an advice line is
+ * offered at all.
+ */
+export type CacheScope = "corpus" | "session";
+/**
+ * The whole reading. Null when nothing went in at all — absent rather than a
+ * verdict about zero.
+ */
+export declare function cacheReading(t: TokenTotals, scope?: CacheScope): CacheReading | null;
+/**
+ * Keep the biggest `n` groups and fold the tail into one "Other".
+ *
+ * The categorical palette runs out at eight, and a ninth hue is never generated
+ * — it is indistinguishable from an existing one under CVD. So the tail folds,
+ * and "Other" is NAMED with its count so the chart never quietly drops rows:
+ * "Other (12 repos)" is a legend entry, "12 rows missing" is a bug.
+ */
+export declare function topGroups(groups: TokenGroup[], n: number, otherLabel?: string): TokenGroup[];
+/**
+ * A share as a percentage label — `27%`, `<1%`, `>99%`, `0%`.
+ *
+ * The distinction matters on exactly this data: a model with 21 million tokens
+ * against a 13.6-billion total rounds to `0%`, which reads as "did not happen"
+ * next to a bar that is visibly there. Something small is not nothing, and the
+ * label has to be able to say so.
+ *
+ * The same rule at the OTHER end, for the same reason: 99.8% rounds to `100%`,
+ * which reads as "and nothing else" beside a list that visibly has four more
+ * rows in it. Only an exact whole is `100%`.
+ */
+export declare function fmtShare(fraction: number): string;
+/**
+ * The running total, day by day — the "cumulative" the whole screen is for.
+ *
+ * Over the DAYS PRESENT, not over a filled calendar: a gap in the series is a
+ * weekend, and a flat line drawn across it says the same thing at a tenth of
+ * the points. The caller draws it as a step/area over real dates, so the gap
+ * still reads as elapsed time.
+ */
+export declare function cumulative(days: {
+    day: string;
+    total: number;
+}[]): {
+    day: string;
+    total: number;
+    sum: number;
+}[];
+/** `YYYY-MM-DD` → epoch ms at LOCAL midnight. The days were bucketed in the
+ *  host's local zone (see `TokenDay`), so they must be read back in one. */
+export declare function dayToMs(day: string): number;
+/** `YYYY-MM-DDTHH` → epoch ms at the LOCAL top of that hour. Same zone
+ *  argument as `dayToMs`, one level down. */
+export declare function hourToMs(hour: string): number;
+/** The day an hour key belongs to. A prefix, never a re-derivation — that is
+ *  the whole point of nesting the two keys. */
+export declare function hourDay(hour: string): string;
+/**
+ * `13.6B` / `459M` / `29.8M` / `68.8k` / `84`. Big numbers, three significant
+ * figures — this is a readout, not a ledger.
+ *
+ * One decimal below 100 and none above, which is what keeps the HERO figure
+ * honest: at 0 decimals a 13.62-billion total renders "14B", and rounding away
+ * 380 million tokens in the one number the screen exists to show is not a
+ * formatting choice.
+ */
+export declare function fmtCount(n: number): string;
+/** The same number in full, grouped — for the one place a reader wants to see
+ *  every digit (the hero's own tooltip, the table view). */
+export declare function fmtExact(n: number): string;

package/node_modules/@waterplane/shared/dist/tokens.js

@@ -0,0 +1,320 @@
+/**
+ * What a pile of token counts MEANS — the derived figures and the words for
+ * them, in one place because both ends say them.
+ *
+ * ── The one way this readout can lie ────────────────────────────────────────
+ *
+ * Measured across one machine's 9,444 conversation logs: 13.65 billion tokens
+ * total, of which **13.15 billion — 96% — were cache reads**. Output was 29.7M
+ * and fresh input was 1.0M. So "tokens used" as a single number is, almost
+ * entirely, the conversation being re-read out of the prompt cache on every
+ * turn. That is a real thing that really happened and it is worth showing, but
+ * a reader who takes it for "what I spent" is out by two orders of magnitude.
+ *
+ * Every rule here follows from that: the four kinds are never merged in a
+ * store or a DTO, the total always ships beside its split, and `TOKEN_KINDS`
+ * carries a sentence per kind so no screen has to invent one.
+ */
+import { CACHE_READ_MULT, CACHE_WRITE_1H_MULT, CACHE_WRITE_5M_MULT, addCost, zeroCost } from "./pricing.js";
+/** An empty tally, for a fold's seed and for a group nobody has written to. */
+export function zeroTotals() {
+    return { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cacheWrite1h: 0, turns: 0 };
+}
+/** Add `b` into `a`, in place. The one fold every aggregate uses. */
+export function addTotals(a, b) {
+    a.input += b.input ?? 0;
+    a.output += b.output ?? 0;
+    a.cacheRead += b.cacheRead ?? 0;
+    a.cacheWrite += b.cacheWrite ?? 0;
+    a.cacheWrite1h += b.cacheWrite1h ?? 0;
+    a.turns += b.turns ?? 0;
+    return a;
+}
+/**
+ * Every token that passed through, of any kind. Never shown without the split
+ * beside it — see the header.
+ *
+ * `cacheWrite1h` is deliberately absent: it is a SUBSET of `cacheWrite`, kept
+ * only so the cost estimate can charge the 2× tier correctly. Adding it here
+ * would double-count 84% of the cache writes.
+ */
+export function tokenTotal(t) {
+    return t.input + t.output + t.cacheRead + t.cacheWrite;
+}
+/**
+ * The four kinds, in a FIXED order.
+ *
+ * Fixed because the order IS the colour assignment: a categorical hue follows
+ * the entity and never its rank, so a filter or a re-sort must not repaint the
+ * survivors. The `slot` is an index into the chart palette, owned by the web
+ * side; this file names the entity, not the colour.
+ */
+export const TOKEN_KINDS = [
+    {
+        id: "input", slot: 0, name: "Input",
+        what: "Fresh prompt tokens — the part of each request that was not already in the cache. The smallest of the four by a wide margin, and the one closest to “what I typed”.",
+    },
+    {
+        id: "output", slot: 1, name: "Output",
+        what: "Everything the model generated: replies, tool calls, thinking. The number that tracks how much work came back.",
+    },
+    {
+        id: "cacheRead", slot: 2, name: "Cache read",
+        what: "Context served out of the prompt cache. Usually the overwhelming majority — every turn re-reads the whole conversation — which is why a single “tokens used” figure is mostly this.",
+    },
+    {
+        id: "cacheWrite", slot: 3, name: "Cache write",
+        what: "Context written into the cache so later turns can read it back. Rises when a conversation grows or is compacted.",
+    },
+];
+/**
+ * A `ContextSample.kinds` tuple as the shape everything else here speaks.
+ *
+ * The ONE reader of that tuple's order, and the reason it may be a tuple at
+ * all: 1,200 samples × four key names is most of a document's bytes, but a
+ * positional array read in two places is a chart with the right numbers in the
+ * wrong colours the first time somebody reorders `TOKEN_KINDS`. So the order
+ * lives here, beside the list it has to match, and nothing else indexes it.
+ *
+ * `turns: 1` because a sample IS one request — the same denominator
+ * `tokenstats.ts` counts, so a per-request figure means the same thing on the
+ * per-session screen and the corpus one.
+ */
+export function sampleTotals(k) {
+    return { input: k[0], output: k[1], cacheRead: k[2], cacheWrite: k[3], cacheWrite1h: 0, turns: 1 };
+}
+/**
+ * How much of the context the cache carried, 0..100, or null when there is
+ * nothing to divide.
+ *
+ * Deliberately over `cacheRead / (cacheRead + cacheWrite + input)` — the three
+ * kinds that make up what went IN. Output is not context and putting it in the
+ * denominator would make the ratio drift with how talkative the model was
+ * rather than with how well the cache worked.
+ */
+export function cacheHitPct(t) {
+    const served = t.cacheRead + t.cacheWrite + t.input;
+    return served > 0 ? (t.cacheRead / served) * 100 : null;
+}
+/** Mean tokens per assistant turn, or null with no turns. */
+export function perTurn(t) {
+    return t.turns > 0 ? tokenTotal(t) / t.turns : null;
+}
+/**
+ * ── Is a 96% cache-read share GOOD, or is it context pollution? ─────────────
+ *
+ * The question this screen invites and could not answer. A reader who sees one
+ * kind at 96% of the tokens and 55% of the money reasonably asks whether that
+ * is the cache doing its job or the same bloated conversation being re-read for
+ * ever, and those are two different facts that happen to look identical in a
+ * share.
+ *
+ * **The share cannot tell them apart, so it is never asked to.** A cache read
+ * bills at `CACHE_READ_MULT` — a tenth of the input rate — so context arriving
+ * as a cache read rather than as fresh input is the CHEAP shape of the same
+ * traffic, and a share near 100% is what a healthy corpus looks like. The share
+ * would only fall by re-sending that context at full price. There is no number
+ * of cache reads that is "too many" in itself.
+ *
+ * Two ratios underneath it do carry a verdict, and both are arithmetic over
+ * counts already on the wire rather than a judgement:
+ *
+ *   • **Reuse** — `cacheRead / cacheWrite`, how many times each token written
+ *     into the cache was read back. A write costs 1.25× (5-minute) or 2×
+ *     (1-hour) the input rate against 0.1× for a read, so a write pays for
+ *     itself at `mult / (1 - CACHE_READ_MULT)` reads — about 1.4 and 2.2. Below
+ *     that the caching is LOSING money against simply sending the tokens fresh,
+ *     which is a real and nameable failure: sessions dying before their prefix
+ *     is read back, or a window invalidated every turn.
+ *   • **Context per turn** — what a turn actually carried. THIS is the pollution
+ *     number: the measurement in `sessioncost.ts`'s header found conversations
+ *     past ~200k carrying 76% of every token spent on this desktop. It is the
+ *     size of the window, not the share of it served from cache, that makes a
+ *     turn expensive.
+ *
+ * The caveat travels with it because it is the same measurement: this is a MEAN
+ * over every turn on disk, and the distribution it came from was 1.4% of
+ * conversations holding 76% of the tokens. A lean average does not mean there
+ * are no monsters — `sessionCost` is the per-conversation reading and the only
+ * one that can name one.
+ *
+ * Sentences, never a gate, for the reason `sessioncost.ts` states at length.
+ */
+/** Context per turn at which the corpus's own measurement says a conversation
+ *  has become the expensive kind. Read off that measurement, not chosen. */
+export const CTX_PER_TURN_HEAVY = 200_000;
+/** Below this a mean turn is nowhere near the heavy tail. */
+export const CTX_PER_TURN_LEAN = 100_000;
+/** Reads a cache write must earn back before it beats paying full input price
+ *  for the same tokens, at the tier mix actually written. */
+function paybackReads(t) {
+    if (t.cacheWrite <= 0)
+        return null;
+    const w1h = Math.min(t.cacheWrite1h, t.cacheWrite);
+    const mult = ((t.cacheWrite - w1h) * CACHE_WRITE_5M_MULT + w1h * CACHE_WRITE_1H_MULT) / t.cacheWrite;
+    return mult / (1 - CACHE_READ_MULT);
+}
+/**
+ * The whole reading. Null when nothing went in at all — absent rather than a
+ * verdict about zero.
+ */
+export function cacheReading(t, scope = "corpus") {
+    const share = cacheHitPct(t);
+    if (share == null)
+        return null;
+    const payback = paybackReads(t);
+    const reuse = t.cacheWrite > 0 ? t.cacheRead / t.cacheWrite : null;
+    const served = t.cacheRead + t.cacheWrite + t.input;
+    const perTurnCtx = t.turns > 0 ? served / t.turns : null;
+    const posture = perTurnCtx == null
+        ? null
+        : perTurnCtx >= CTX_PER_TURN_HEAVY ? "heavy" : perTurnCtx >= CTX_PER_TURN_LEAN ? "ordinary" : "lean";
+    const thin = reuse != null && payback != null && reuse < payback;
+    const cacheNote = thin
+        ? `Cache reads are ${Math.round(share)}% of everything sent in, but each token written into the cache was read back only ${reuse.toFixed(1)}× — under the ${payback.toFixed(1)}× a write has to earn back before it beats paying full input price. That is sessions ending or being invalidated before their context is re-read, not a context that is too big.`
+        : reuse != null
+            ? `Cache reads are ${Math.round(share)}% of everything sent in, and each token written into the cache was read back ${reuse >= 10 ? Math.round(reuse) : reuse.toFixed(1)}× — well past the ${payback.toFixed(1)}× that makes a write worth writing. A high share is the cheap shape of this traffic, not a symptom: a cache read bills at a tenth of the input rate, and the only way to lower the share is to re-send the same context at full price.`
+            : `Cache reads are ${Math.round(share)}% of everything sent in. A cache read bills at a tenth of the input rate, so a high share is the cheap shape of the same traffic rather than a symptom.`;
+    const mark = `the ~${fmtCount(CTX_PER_TURN_HEAVY)} mark where this desktop's own logs found the spend concentrating (the conversations past 200k were 1.4% of them and 76% of every token)`;
+    // A mean is stated as a mean, every time. The distribution it came out of is
+    // the most skewed in this repo's measurements, and a reader who takes 190k
+    // for "my turns are 190k" has read a ceiling off an average.
+    const tail = scope === "session"
+        // One conversation's own mean. The corpus wording's escape hatch — go and
+        // read the per-session figure — is this screen, so it names what the mean
+        // is over instead: a session that spent its first hour small and its last
+        // one at 900k averages to something neither half ever carried.
+        ? "A mean is not a ceiling: this is every request this conversation logged, the small early ones averaged in with whatever the window grew to. The curve above is where it actually went."
+        : "A mean is not a ceiling: the long conversations are averaged in with the short ones, and only the per-session reading on the context screen can name one.";
+    const contextNote = perTurnCtx == null
+        ? null
+        : posture === "heavy"
+            ? `The mean turn carried ${fmtCount(perTurnCtx)} of context — past ${mark}. What makes a turn expensive is the size of the window, not the share of it served from cache. ${tail}`
+            : posture === "ordinary"
+                ? `The mean turn carried ${fmtCount(perTurnCtx)} of context, just under ${mark}. ${tail}`
+                // The corpus can say what its norm is; one conversation has no norm to
+                // be, so the session wording stops at the comparison it can make.
+                : `The mean turn carried ${fmtCount(perTurnCtx)} of context, well under ${mark}${scope === "session" ? "" : " — long sessions are not the norm here"}. ${tail}`;
+    // On one session there is already an advice line with a DOOR next to it —
+    // the cost panel and its "new session in this repo" button — so a second
+    // paragraph saying the same thing without one is noise. The reading keeps
+    // its two facts and offers nothing.
+    const advice = scope === "session"
+        ? null
+        : thin
+            ? "Worth a look at what ends sessions after a turn or two, or at anything rewriting the start of the prompt between turns."
+            : posture === "heavy"
+                ? "The lever is the length of a conversation, not the cache: work that does not need what is already in the window is cheaper in a new session. The per-session reading on the context screen names the ones that grew."
+                : null;
+    return { sharePct: share, reuse, payback, perTurnCtx, posture, cacheNote, contextNote, advice };
+}
+/**
+ * Keep the biggest `n` groups and fold the tail into one "Other".
+ *
+ * The categorical palette runs out at eight, and a ninth hue is never generated
+ * — it is indistinguishable from an existing one under CVD. So the tail folds,
+ * and "Other" is NAMED with its count so the chart never quietly drops rows:
+ * "Other (12 repos)" is a legend entry, "12 rows missing" is a bug.
+ */
+export function topGroups(groups, n, otherLabel = "repos") {
+    const sorted = [...groups].sort((a, b) => tokenTotal(b) - tokenTotal(a));
+    // Folding a tail of ONE is worse than not folding: it replaces a row that had
+    // a name with a row that says "Other (1)", which is strictly less information
+    // in the same amount of space.
+    if (sorted.length <= n + 1)
+        return sorted;
+    const head = sorted.slice(0, n);
+    const tail = sorted.slice(n);
+    const singular = otherLabel.replace(/s$/, "");
+    const other = {
+        key: "__other__",
+        label: `Other (${tail.length} ${tail.length === 1 ? singular : otherLabel})`,
+        ...zeroTotals(),
+        cost: zeroCost(),
+    };
+    for (const g of tail) {
+        addTotals(other, g);
+        addCost(other.cost, g.cost);
+    }
+    return [...head, other];
+}
+/**
+ * A share as a percentage label — `27%`, `<1%`, `>99%`, `0%`.
+ *
+ * The distinction matters on exactly this data: a model with 21 million tokens
+ * against a 13.6-billion total rounds to `0%`, which reads as "did not happen"
+ * next to a bar that is visibly there. Something small is not nothing, and the
+ * label has to be able to say so.
+ *
+ * The same rule at the OTHER end, for the same reason: 99.8% rounds to `100%`,
+ * which reads as "and nothing else" beside a list that visibly has four more
+ * rows in it. Only an exact whole is `100%`.
+ */
+export function fmtShare(fraction) {
+    if (!Number.isFinite(fraction) || fraction <= 0)
+        return "0%";
+    const pct = fraction * 100;
+    if (pct < 1)
+        return "<1%";
+    if (pct < 100 && Math.round(pct) === 100)
+        return ">99%";
+    return `${Math.round(pct)}%`;
+}
+/**
+ * The running total, day by day — the "cumulative" the whole screen is for.
+ *
+ * Over the DAYS PRESENT, not over a filled calendar: a gap in the series is a
+ * weekend, and a flat line drawn across it says the same thing at a tenth of
+ * the points. The caller draws it as a step/area over real dates, so the gap
+ * still reads as elapsed time.
+ */
+export function cumulative(days) {
+    let sum = 0;
+    return days.map((d) => {
+        sum += d.total;
+        return { ...d, sum };
+    });
+}
+/** `YYYY-MM-DD` → epoch ms at LOCAL midnight. The days were bucketed in the
+ *  host's local zone (see `TokenDay`), so they must be read back in one. */
+export function dayToMs(day) {
+    const [y, m, d] = day.split("-").map(Number);
+    return new Date(y, (m || 1) - 1, d || 1).getTime();
+}
+/** `YYYY-MM-DDTHH` → epoch ms at the LOCAL top of that hour. Same zone
+ *  argument as `dayToMs`, one level down. */
+export function hourToMs(hour) {
+    const [y, m, d] = hour.slice(0, 10).split("-").map(Number);
+    const h = Number(hour.slice(11, 13));
+    return new Date(y, (m || 1) - 1, d || 1, Number.isFinite(h) ? h : 0).getTime();
+}
+/** The day an hour key belongs to. A prefix, never a re-derivation — that is
+ *  the whole point of nesting the two keys. */
+export function hourDay(hour) {
+    return hour.slice(0, 10);
+}
+/**
+ * `13.6B` / `459M` / `29.8M` / `68.8k` / `84`. Big numbers, three significant
+ * figures — this is a readout, not a ledger.
+ *
+ * One decimal below 100 and none above, which is what keeps the HERO figure
+ * honest: at 0 decimals a 13.62-billion total renders "14B", and rounding away
+ * 380 million tokens in the one number the screen exists to show is not a
+ * formatting choice.
+ */
+export function fmtCount(n) {
+    if (!Number.isFinite(n))
+        return "?";
+    const a = Math.abs(n);
+    const unit = a >= 1e9 ? ["B", 1e9] : a >= 1e6 ? ["M", 1e6] : a >= 1e3 ? ["k", 1e3] : null;
+    if (!unit)
+        return String(Math.round(n));
+    const v = n / unit[1];
+    return `${v.toFixed(Math.abs(v) < 100 ? 1 : 0).replace(/\.0$/, "")}${unit[0]}`;
+}
+/** The same number in full, grouped — for the one place a reader wants to see
+ *  every digit (the hero's own tooltip, the table view). */
+export function fmtExact(n) {
+    return Math.round(n).toLocaleString();
+}
+//# sourceMappingURL=tokens.js.map

package/node_modules/@waterplane/shared/dist/tokens.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tokens.js","sourceRoot":"","sources":["../src/tokens.ts"],"names":[],"mappings":"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"}

package/node_modules/@waterplane/shared/dist/transcriptfold.d.ts

@@ -0,0 +1,50 @@
+/**
+ * The caps and the two pure folds every conversation reader shares — claude's
+ * jsonl reader (`host/transcript.ts`, `host/ctxlog.ts`) and any backend's store
+ * reader a plugin contributes (`HostPluginApi.storeReader`).
+ *
+ * Here and not in the host because a store reader lives in an extension, which
+ * reaches core only through `@waterplane/shared`: the reader view and the
+ * context graph must cap, label and thin a second backend's conversation by the
+ * SAME rule as claude's, and two copies of a cap are two opinions about how long
+ * a turn may be. Moved verbatim from the host; the host re-exports every name.
+ */
+import type { ContextSample } from "./wire/session.js";
+import type { TranscriptBlock } from "./wire/transcript.js";
+/** Newest N turns are returned; older ones are dropped (with `truncated`). */
+export declare const MAX_TURNS = 500;
+export declare const TOOL_INPUT_CAP = 1200;
+export declare const TOOL_RESULT_CAP = 4000;
+export declare const TEXT_CAP = 200000;
+/** A row label's length, in characters. */
+export declare const LABEL_CAP = 160;
+/**
+ * Context-series points returned at most.
+ *
+ * A 20 MB conversation measured 1,365 distinct turns, so the cap is not the
+ * common case — it is the bound that keeps this response small enough to cache
+ * on a phone whatever the log does next.
+ */
+export declare const MAX_SAMPLES = 1200;
+/** Whitespace squashed to single spaces, capped with an ellipsis. */
+export declare const oneLine: (s: string, cap?: number) => string;
+/** One-line form of a prompt, for a row label. */
+export declare function promptLabel(text: string, cap?: number): string;
+/**
+ * A turn's gist WITHOUT an AI call: the first sentence of its last substantive
+ * assistant text, markdown stripped. Deliberately dumb and instant — the point
+ * of the outline is to skim a long conversation, not to re-summarize it.
+ */
+export declare function summarize(blocks: TranscriptBlock[]): string | undefined;
+/**
+ * Cut a long series down to the cap WITHOUT flattening it.
+ *
+ * A stride sample ("every 3rd point") is the obvious way and the wrong one
+ * here: the shape this graph is about is a sawtooth, and the two points that
+ * carry the whole story of each tooth — the peak just before a compaction and
+ * the floor just after — are exactly the ones a stride is most likely to step
+ * over. So each bucket contributes its highest and its lowest reading, emitted
+ * in the order they occurred, which preserves the envelope and the direction of
+ * every drop while still bounding the count.
+ */
+export declare function downsample(samples: ContextSample[], cap?: number): ContextSample[];