waterplane 0.0.1 → 0.1.11

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

@@ -0,0 +1,169 @@
+/**
+ * What a repo costs to have open, before anyone types anything.
+ *
+ * ── The thing being measured ────────────────────────────────────────────────
+ *
+ * `CLAUDE.md` is re-read on every turn of every session and every subagent, so
+ * its size is multiplied by everything the repo ever does. Measured on this
+ * desktop: one repo's had grown to 148,582 chars — ~37k tokens — and was **21%
+ * of every token that repo spent in a week**. Nobody did that on purpose. Each
+ * edit added a clause, every clause was worth writing, and none of them was the
+ * one that broke it.
+ *
+ * That is the shape of a problem a CHECK catches and a person does not: it has
+ * no moment of failure, only a slope.
+ *
+ * ── Always-on is not the same as total ─────────────────────────────────────
+ *
+ * A skill's BODY is loaded only when the skill is invoked, so a 20k skill costs
+ * nothing on a turn that never needed it. Its DESCRIPTION is in the listing on
+ * every turn. So the weight that matters is
+ *
+ *     CLAUDE.md + every skill's description
+ *
+ * and the skill bodies are reported beside it as what was successfully moved
+ * OFF the always-on path — a large body is evidence the split is working, not a
+ * problem. Counting them together would tell somebody who did the right thing
+ * that they had made it worse.
+ *
+ * ── Why it warns and never fails ───────────────────────────────────────────
+ *
+ * There is no correct size. A repo with genuine hard-won invariants may need a
+ * bigger file than a scratch project, and the person who wrote it is the only
+ * one who can say which half is reference. So this produces a number, a
+ * comparison and a sentence; the fix is a judgement call and is offered as a
+ * prompt, never applied.
+ */
+/** Chars per token, near enough for prose+markdown. Only ever used to SAY what
+ *  a size costs, never to decide anything — the thresholds are in chars. */
+export declare const CHARS_PER_TOKEN = 4;
+export interface ContextWeightLimits {
+    /** Always-on chars (CLAUDE.md + skill descriptions) before this warns. */
+    maxChars: number;
+    /** Always-on chars before it is called out loudly. */
+    hardChars: number;
+    /** Skills before their descriptions alone are worth a mention. */
+    maxSkills: number;
+}
+/**
+ * The defaults, and where they come from.
+ *
+ * `maxChars` 16,000 ≈ 4k tokens on every turn. Calibrated against the repo this
+ * was written in, after its reference had been moved into skills: 9,672 chars of
+ * CLAUDE.md plus 2,762 of skill descriptions = 12,434. A threshold that flags a
+ * repo which has already done the right thing is a threshold people learn to
+ * ignore, and the 2,762 is GOOD spend — it is what keeps 58k of reference off
+ * every turn. So the line sits above a well-organised repo and well below the
+ * 148k (37k tokens a turn) that prompted any of this.
+ *
+ * `hardChars` 40,000 ≈ 10k tokens a turn, where the cost stops being a rounding
+ * error on anything. `maxSkills` 30 is about descriptions, not bodies; they are
+ * already counted in `maxChars`, so the count trips only a listing that is itself
+ * a page — a router-plus-sub-skills split (24 here) is the shape the chars rule
+ * asks for.
+ *
+ * Override per host with `WATERPLANE_CONTEXT_WARN_CHARS` / `WATERPLANE_CONTEXT_HARD_CHARS` /
+ * `WATERPLANE_CONTEXT_MAX_SKILLS`.
+ */
+export declare const DEFAULT_CONTEXT_LIMITS: ContextWeightLimits;
+export interface SkillWeight {
+    name: string;
+    /** Frontmatter `description:` length — the part that is ALWAYS loaded. */
+    descChars: number;
+    /** Whole file. On-demand, reported as context, never counted against. */
+    bodyChars: number;
+}
+export interface ContextWeightInput {
+    /** `CLAUDE.md` plus any `.claude/CLAUDE.md`, in chars. */
+    claudeMdChars: number;
+    skills: SkillWeight[];
+}
+export type ContextWeightVerdict = "lean" | "heavy" | "steep";
+export interface ContextWeightReading {
+    verdict: ContextWeightVerdict;
+    /** What every turn carries: CLAUDE.md + all skill descriptions. */
+    alwaysOnChars: number;
+    alwaysOnTokens: number;
+    /** What was moved off the always-on path. Evidence, not debt. */
+    onDemandChars: number;
+    skillCount: number;
+    /** One sentence of fact. */
+    note: string;
+    /** What to do, when there is something worth doing. */
+    advice: string | null;
+}
+export declare function weighContext(input: ContextWeightInput, limits?: ContextWeightLimits, 
+/** Where each of those numbers came from. Absent = all shipped defaults,
+ *  which is what a caller with no store to consult is looking at. */
+sources?: Partial<ContextLimitSources>): ContextWeightReading;
+/**
+ * A file's YAML frontmatter as raw lines, or null when it has none. Tolerates what YAML loaders
+ * do — a UTF-8 BOM, blank lines before the opening `---`, CRLF and an empty block — because a
+ * strict match read such a skill's description as 0 chars and its whole text as body.
+ */
+export declare function frontmatterLines(text: string): string[] | null;
+/**
+ * The always-loaded length of one skill file: its `description:` frontmatter.
+ *
+ * Walked line by line rather than matched with one regex, because the obvious
+ * `/^description:([\s\S]*?)(?=\n\w+:|$)/m` is wrong in a way that reads as right:
+ * under `/m` the `$` is a LINE end, so a description wrapped across three lines
+ * measures as its first line — reporting a third of the cost of exactly the
+ * skills whose descriptions are worth looking at.
+ */
+export declare function skillDescChars(text: string): number;
+export type ContextLimitSource = "default" | "env" | "repo";
+export type ContextLimitSources = Record<keyof ContextWeightLimits, ContextLimitSource>;
+/** What the check used, where each number came from, and what is on file for
+ *  this repo — everything an editor needs to open on the right values without
+ *  hardcoding a default the host may change. */
+export interface ContextLimitsView {
+    /** The numbers the reading was actually taken against. */
+    effective: ContextWeightLimits;
+    source: ContextLimitSources;
+    /** The shipped defaults, for a truthful "back to default" label. */
+    defaults: ContextWeightLimits;
+    /** The env layer, as set on this host (absent fields = not exported). Shown
+     *  so a repo override that is being shadowed... cannot happen (repo wins),
+     *  but so "you set 20k on this host" is visible when a repo has no override. */
+    env: Partial<ContextWeightLimits>;
+    /** This repo's stored override, or null when it has none. The editor opens on
+     *  THIS, never on `effective`: they differ whenever env is doing the work. */
+    repo: Partial<ContextWeightLimits> | null;
+    /** Set only when resolution had to move a number the user gave — today the
+     *  single case is a `hardChars` left below a raised `maxChars`. Never silent. */
+    note?: string;
+}
+/** Bounds for a hand-typed threshold. Wide on purpose: this is a guard against a
+ *  typo and a zero, not an opinion about the right size — the module's whole
+ *  premise is that there isn't one. */
+export declare const CONTEXT_LIMIT_BOUNDS: Record<keyof ContextWeightLimits, {
+    min: number;
+    max: number;
+}>;
+/** A refusal sentence for one field, or null when the value is usable. Words,
+ *  not a clamp: a silently corrected threshold is a threshold that reports a
+ *  number the user never chose. */
+export declare function contextLimitError(field: keyof ContextWeightLimits, value: unknown): string | null;
+/**
+ * Read a client's patch into an override.
+ *
+ * A field that is absent or `null` is "leave it to the layer below" — that is
+ * how one knob is overridden without freezing the other two at whatever they
+ * happen to be today. An out-of-range field is REFUSED and named; the caller
+ * writes nothing and says so, rather than storing a repaired number.
+ */
+export declare function sanitizeContextLimits(patch: unknown): {
+    limits: Partial<ContextWeightLimits>;
+    errors: string[];
+};
+/**
+ * The three layers, resolved: repo override > host env > shipped default.
+ *
+ * `hardChars` below `maxChars` would make "steep" swallow "heavy" and leave the
+ * warn number quoted in a sentence that can never fire — the likely way to get
+ * there is raising a repo's warn line above the default hard line, i.e. the
+ * exact thing this feature is for. It is raised to match, and the move is
+ * REPORTED in `note` rather than applied quietly.
+ */
+export declare function resolveContextLimits(env?: Partial<ContextWeightLimits>, repo?: Partial<ContextWeightLimits> | null): ContextLimitsView;

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

@@ -0,0 +1,247 @@
+/**
+ * What a repo costs to have open, before anyone types anything.
+ *
+ * ── The thing being measured ────────────────────────────────────────────────
+ *
+ * `CLAUDE.md` is re-read on every turn of every session and every subagent, so
+ * its size is multiplied by everything the repo ever does. Measured on this
+ * desktop: one repo's had grown to 148,582 chars — ~37k tokens — and was **21%
+ * of every token that repo spent in a week**. Nobody did that on purpose. Each
+ * edit added a clause, every clause was worth writing, and none of them was the
+ * one that broke it.
+ *
+ * That is the shape of a problem a CHECK catches and a person does not: it has
+ * no moment of failure, only a slope.
+ *
+ * ── Always-on is not the same as total ─────────────────────────────────────
+ *
+ * A skill's BODY is loaded only when the skill is invoked, so a 20k skill costs
+ * nothing on a turn that never needed it. Its DESCRIPTION is in the listing on
+ * every turn. So the weight that matters is
+ *
+ *     CLAUDE.md + every skill's description
+ *
+ * and the skill bodies are reported beside it as what was successfully moved
+ * OFF the always-on path — a large body is evidence the split is working, not a
+ * problem. Counting them together would tell somebody who did the right thing
+ * that they had made it worse.
+ *
+ * ── Why it warns and never fails ───────────────────────────────────────────
+ *
+ * There is no correct size. A repo with genuine hard-won invariants may need a
+ * bigger file than a scratch project, and the person who wrote it is the only
+ * one who can say which half is reference. So this produces a number, a
+ * comparison and a sentence; the fix is a judgement call and is offered as a
+ * prompt, never applied.
+ */
+/** Chars per token, near enough for prose+markdown. Only ever used to SAY what
+ *  a size costs, never to decide anything — the thresholds are in chars. */
+export const CHARS_PER_TOKEN = 4;
+/**
+ * The defaults, and where they come from.
+ *
+ * `maxChars` 16,000 ≈ 4k tokens on every turn. Calibrated against the repo this
+ * was written in, after its reference had been moved into skills: 9,672 chars of
+ * CLAUDE.md plus 2,762 of skill descriptions = 12,434. A threshold that flags a
+ * repo which has already done the right thing is a threshold people learn to
+ * ignore, and the 2,762 is GOOD spend — it is what keeps 58k of reference off
+ * every turn. So the line sits above a well-organised repo and well below the
+ * 148k (37k tokens a turn) that prompted any of this.
+ *
+ * `hardChars` 40,000 ≈ 10k tokens a turn, where the cost stops being a rounding
+ * error on anything. `maxSkills` 30 is about descriptions, not bodies; they are
+ * already counted in `maxChars`, so the count trips only a listing that is itself
+ * a page — a router-plus-sub-skills split (24 here) is the shape the chars rule
+ * asks for.
+ *
+ * Override per host with `WATERPLANE_CONTEXT_WARN_CHARS` / `WATERPLANE_CONTEXT_HARD_CHARS` /
+ * `WATERPLANE_CONTEXT_MAX_SKILLS`.
+ */
+export const DEFAULT_CONTEXT_LIMITS = {
+    maxChars: 16_000,
+    hardChars: 40_000,
+    maxSkills: 30,
+};
+/** `750` / `3k` / `12.4k` / `148k`. One decimal only when it says something —
+ *  "3.0k chars" reads as a measurement precise to a hundred characters, which
+ *  it is not. */
+function shorten(n) {
+    if (n < 1_000)
+        return String(n);
+    const k = n / 1_000;
+    if (k >= 10)
+        return `${Math.round(k)}k`;
+    const one = Math.round(k * 10) / 10;
+    return `${Number.isInteger(one) ? one : one.toFixed(1)}k`;
+}
+const fmtTok = shorten;
+const fmtChars = shorten;
+/**
+ * How a threshold is referred to in the sentence that quotes it.
+ *
+ * "you asked to be warned at" is true of a number the user actually set and a
+ * lie about a shipped default — and it was being said about the default on
+ * every desktop, which is how a check ends up crediting somebody with a
+ * decision they were never offered. `repo` is named as a repo decision because
+ * the whole point of setting one is that this repo is not like the others.
+ */
+function attributed(kind, value, source) {
+    const at = kind === "size" ? `over the ${value}` : `past the ${value}`;
+    if (source === "repo")
+        return `${at} you set for this repo`;
+    if (source === "env")
+        return `${at} you asked to be warned at`;
+    return `${at} default`;
+}
+export function weighContext(input, limits = DEFAULT_CONTEXT_LIMITS, 
+/** Where each of those numbers came from. Absent = all shipped defaults,
+ *  which is what a caller with no store to consult is looking at. */
+sources = {}) {
+    const descChars = input.skills.reduce((n, s) => n + s.descChars, 0);
+    const alwaysOnChars = Math.max(0, input.claudeMdChars) + descChars;
+    const onDemandChars = input.skills.reduce((n, s) => n + Math.max(0, s.bodyChars - s.descChars), 0);
+    const alwaysOnTokens = Math.round(alwaysOnChars / CHARS_PER_TOKEN);
+    const skillCount = input.skills.length;
+    const verdict = alwaysOnChars >= limits.hardChars ? "steep"
+        : alwaysOnChars >= limits.maxChars || skillCount > limits.maxSkills ? "heavy"
+            : "lean";
+    const moved = onDemandChars > 0
+        ? ` ${fmtChars(onDemandChars)} more is in ${skillCount} skill${skillCount === 1 ? "" : "s"}, loaded only when needed.`
+        : "";
+    if (verdict === "lean") {
+        return {
+            verdict, alwaysOnChars, alwaysOnTokens, onDemandChars, skillCount,
+            note: `Every turn here carries ${fmtChars(alwaysOnChars)} chars of agent instructions (~${fmtTok(alwaysOnTokens)} tokens).${moved}`,
+            advice: null,
+        };
+    }
+    // The count can be the only thing over, and then the size sentence would be
+    // reporting a number that is inside its limit — say which one actually tripped.
+    const overSize = alwaysOnChars >= limits.maxChars;
+    const note = overSize
+        ? `Every turn here carries ${fmtChars(alwaysOnChars)} chars of agent instructions (~${fmtTok(alwaysOnTokens)} tokens), ${attributed("size", fmtChars(limits.maxChars), sources.maxChars ?? "default")}.${moved}`
+        : `${skillCount} skills, ${attributed("skills", String(limits.maxSkills), sources.maxSkills ?? "default")} — their descriptions are loaded on every turn even when no skill is.${moved}`;
+    return {
+        verdict, alwaysOnChars, alwaysOnTokens, onDemandChars, skillCount,
+        note,
+        advice: overSize
+            ? "This is paid on every turn of every session and every subagent here. What has to stay is what is dangerous not to know before acting; reference belongs in a skill and reasoning in the docs. The “groom CLAUDE.md” fan-out preset does exactly that."
+            : "Descriptions are the always-on part of a skill. Merging near-duplicates, or shortening the descriptions of ones you rarely load, costs nothing on-demand.",
+    };
+}
+const DESC_KEY = /^["']?description["']?[ \t]*:[ \t]*/;
+/**
+ * A file's YAML frontmatter as raw lines, or null when it has none. Tolerates what YAML loaders
+ * do — a UTF-8 BOM, blank lines before the opening `---`, CRLF and an empty block — because a
+ * strict match read such a skill's description as 0 chars and its whole text as body.
+ */
+export function frontmatterLines(text) {
+    const fm = /^(?:[ \t]*\r?\n)*---[ \t]*\r?\n(?:([\s\S]*?)\r?\n)?---[ \t]*(?:\r?\n|$)/.exec(text.replace(/^\uFEFF/, ""));
+    return fm ? (fm[1] ?? "").split(/\r?\n/) : null;
+}
+/**
+ * The always-loaded length of one skill file: its `description:` frontmatter.
+ *
+ * Walked line by line rather than matched with one regex, because the obvious
+ * `/^description:([\s\S]*?)(?=\n\w+:|$)/m` is wrong in a way that reads as right:
+ * under `/m` the `$` is a LINE end, so a description wrapped across three lines
+ * measures as its first line — reporting a third of the cost of exactly the
+ * skills whose descriptions are worth looking at.
+ */
+export function skillDescChars(text) {
+    const lines = frontmatterLines(text);
+    if (!lines)
+        return 0;
+    const start = lines.findIndex((l) => DESC_KEY.test(l));
+    if (start < 0)
+        return 0;
+    // A `>` / `|` block-scalar indicator is YAML syntax, not words the model reads.
+    const first = lines[start].replace(DESC_KEY, "").trim();
+    const parts = /^[>|][+-]?\d*$/.test(first) ? [] : [first];
+    for (let i = start + 1; i < lines.length; i++) {
+        if (/^[A-Za-z_-]+:/.test(lines[i]))
+            break; // the next top-level key
+        parts.push(lines[i].trim());
+    }
+    return parts.join(" ").trim().length;
+}
+/** Bounds for a hand-typed threshold. Wide on purpose: this is a guard against a
+ *  typo and a zero, not an opinion about the right size — the module's whole
+ *  premise is that there isn't one. */
+export const CONTEXT_LIMIT_BOUNDS = {
+    maxChars: { min: 1_000, max: 2_000_000 },
+    hardChars: { min: 1_000, max: 4_000_000 },
+    maxSkills: { min: 1, max: 500 },
+};
+const LIMIT_KEYS = ["maxChars", "hardChars", "maxSkills"];
+/** A refusal sentence for one field, or null when the value is usable. Words,
+ *  not a clamp: a silently corrected threshold is a threshold that reports a
+ *  number the user never chose. */
+export function contextLimitError(field, value) {
+    const b = CONTEXT_LIMIT_BOUNDS[field];
+    const n = Number(value);
+    if (!Number.isFinite(n))
+        return `${field} must be a number.`;
+    if (!Number.isInteger(n))
+        return `${field} must be a whole number.`;
+    if (n < b.min)
+        return `${field} must be at least ${b.min}.`;
+    if (n > b.max)
+        return `${field} must be at most ${b.max}.`;
+    return null;
+}
+/**
+ * Read a client's patch into an override.
+ *
+ * A field that is absent or `null` is "leave it to the layer below" — that is
+ * how one knob is overridden without freezing the other two at whatever they
+ * happen to be today. An out-of-range field is REFUSED and named; the caller
+ * writes nothing and says so, rather than storing a repaired number.
+ */
+export function sanitizeContextLimits(patch) {
+    const out = {};
+    const errors = [];
+    const rec = (patch && typeof patch === "object" ? patch : {});
+    for (const k of LIMIT_KEYS) {
+        const v = rec[k];
+        if (v === undefined || v === null || v === "")
+            continue;
+        const err = contextLimitError(k, v);
+        if (err) {
+            errors.push(err);
+            continue;
+        }
+        out[k] = Number(v);
+    }
+    return { limits: out, errors };
+}
+/**
+ * The three layers, resolved: repo override > host env > shipped default.
+ *
+ * `hardChars` below `maxChars` would make "steep" swallow "heavy" and leave the
+ * warn number quoted in a sentence that can never fire — the likely way to get
+ * there is raising a repo's warn line above the default hard line, i.e. the
+ * exact thing this feature is for. It is raised to match, and the move is
+ * REPORTED in `note` rather than applied quietly.
+ */
+export function resolveContextLimits(env = {}, repo = null) {
+    const effective = { ...DEFAULT_CONTEXT_LIMITS };
+    const source = { maxChars: "default", hardChars: "default", maxSkills: "default" };
+    for (const k of LIMIT_KEYS) {
+        if (typeof env[k] === "number") {
+            effective[k] = env[k];
+            source[k] = "env";
+        }
+        if (repo && typeof repo[k] === "number") {
+            effective[k] = repo[k];
+            source[k] = "repo";
+        }
+    }
+    let note;
+    if (effective.hardChars < effective.maxChars) {
+        note = `The steep line (${fmtChars(effective.hardChars)}) was below the warn line (${fmtChars(effective.maxChars)}), so it is being read as ${fmtChars(effective.maxChars)}. Set a steep line above the warn line to make it mean something.`;
+        effective.hardChars = effective.maxChars;
+    }
+    return { effective, source, defaults: { ...DEFAULT_CONTEXT_LIMITS }, env: { ...env }, repo: repo ? { ...repo } : null, ...(note ? { note } : {}) };
+}
+//# sourceMappingURL=contextweight.js.map

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

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

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

@@ -0,0 +1,216 @@
+/**
+ * The cost window, read: where a span's money went, cut the ways a person asks.
+ *
+ * `GET /api/costwindow` hands the phone a `CostWindowDoc` (wire/costwindow.ts):
+ * hours, conversations and totals for an arbitrary `[from, to)`. This module is
+ * everything both ends must agree on about it, so the host's push and the
+ * phone's card cannot say two different things about one week:
+ *
+ *  - **the hour** (`hourFloor`/`hourKey`/`hourKeyMs`) — the finest bucket on
+ *    record, host-local, one copy;
+ *  - **the one bucketing function** (`weekCut`) — the number on an hour and the
+ *    list that hour opens come from the same predicate over `CostConvo.byHour`,
+ *    because a count on a control is a filter;
+ *  - **what launched it** (`foldLaunches`) — a fan-out run is ONE row, not the
+ *    thirty-six sessions it opened;
+ *  - **repos ranked with their sessions** (`rankRepos`);
+ *  - **weekly points** (`ptsCalibration`) — dollars per point of the weekly
+ *    limit, from the usage log's climb against the ledger's cost over the same
+ *    hours. A HEURISTIC, so it refuses (in words) rather than guessing: too few
+ *    readings, too short, unstable, or disagreeing with the per-reading level
+ *    calibration is a refusal, never a number;
+ *  - two per-session/per-run sentences (`agentModelInsight`, `fanoutHintText`).
+ *
+ * No clock in here: anything that needs "now" takes it. Every output is a
+ * reading or a sentence — nothing applies itself.
+ */
+import type { CostBreakdown } from "./pricing.js";
+import type { ModelSlice, TokenGroup, TokenTotals, UsageSample } from "./wire/telemetry.js";
+import type { CostConvo, CostConvoRest, CostHour, CostHourRepo, CostLaunch, CostWindowDoc } from "./wire/costwindow.js";
+import type { FanoutRun } from "./wire/work.js";
+export declare const HOUR_MS = 3600000;
+/**
+ * Conversations a `CostWindowDoc` carries whole; the rest are folded into
+ * `rest` by repo × launch. A week here was 591 conversations and 782 KB, nearly
+ * all of it per-conversation hour and model splits nobody scrolls to; the
+ * dearest 60 are what a person opens, and the fold keeps every total whole.
+ */
+export declare const COST_CONVOS_CAP = 60;
+/** Top of the local hour `t` is in. Same as host `hourFloorMs` / web `hourFloor`. */
+export declare function hourFloor(t: number): number;
+/**
+ * Where a cut of hour buckets starts for a window that opened at `openedAt`: the NEAREST local
+ * hour boundary, never always the floor. An hour is the finest bucket on record, so a window
+ * opening mid-hour cannot be cut at its own minute; flooring counted the whole opening hour —
+ * a week resetting Thu 18:59 counted 59 minutes of the PREVIOUS week (measured: ≈ 4 weekly
+ * points on a 35% week). Rounding bounds the edge error at 30 minutes either way, and a window
+ * that resets at the next window's start then tiles with it: `[windowStartHour(opened),
+ * windowStartHour(resets))` is each window, no hour in two.
+ *
+ * THE one rule for every window edge — the live session/week cut, the heat grid cells (host
+ * `windowCells`), the week card's and the Totals box's `/api/costwindow` `from`. Idempotent on
+ * an hour boundary, so the host's `hourFloor(from)` is the identity on what the phone sends.
+ * Ties (exactly :30) go to the later hour, `Math.round`'s way.
+ */
+export declare function windowStartHour(openedAt: number): number;
+/** `YYYY-MM-DDTHH` in the LOCAL zone — the host's `localHour`, one copy both ends use. */
+export declare function hourKey(t: number): string;
+/** `YYYY-MM-DDTHH` → the local top of that hour, epoch ms (`tokens.ts`' `hourToMs`). */
+export declare function hourKeyMs(key: string): number;
+export interface WeekBucket {
+    hour: string;
+    t: number;
+    usd: number;
+    tok: number;
+    byRepo: CostHourRepo[];
+    /** Only CARRIED conversations — a folded one has no row to open (`restConvos` counts those). */
+    convoIds: string[];
+    /** Conversations with a turn in this hour that the cap folded into `rest` (0 when none). */
+    restConvos: number;
+}
+export interface WeekCut {
+    /** One per hour WITH activity, ascending. An hour nothing ran in is absent, never a zero bucket. */
+    buckets: WeekBucket[];
+    /** The conversations in one bucket (null = no filter = all), in the document's order. Built
+     *  from the same predicate as `buckets[i].convoIds`, so "n of N" is the list it opens. */
+    convosIn(hour: string | null): CostConvo[];
+    /** `3 of 41 sessions · Tue 14:00–15:00`, or null when unfiltered. N is every conversation in
+     *  the window, carried or folded (`convosTotal`); the hour is the bucket's own `t`, never the
+     *  key re-parsed on this device's clock. */
+    filterText(hour: string | null): string | null;
+    /** Every conversation in the window — the N of "n of N" (`convosTotal ?? convos.length`). */
+    total: number;
+    /** "4 more sessions in this hour are not listed" / "531 cheaper sessions not listed · $12.40",
+     *  or null when the cap folded nothing there. Says what the list is hiding. */
+    restText(hour: string | null): string | null;
+}
+export declare function weekCut(doc: CostWindowDoc): WeekCut;
+/** A launch row's kind: what opened it, or `unrecorded` — nothing on this host says (the
+ *  daemon's own `claude -p` calls, a session past the closed stack's limit). Never "by hand". */
+export type LaunchKind = CostLaunch["kind"] | "unrecorded";
+/** The one wording of a launch kind, both ends. */
+export declare const LAUNCH_KIND_WORD: Record<LaunchKind, string>;
+export interface LaunchRow {
+    /** `runId ?? itemId ?? c:<conversation id>`; `rest:<repo>:<kind>` for folded conversations with no id to group by. */
+    key: string;
+    kind: LaunchKind;
+    /** "architect review · 36 repos" / a backlog label / a session title. */
+    label: string;
+    /** Distinct repo keys. */
+    repos: number;
+    /** Descending by cost. Only the CARRIED conversations; `more` counts the folded ones. */
+    convos: CostConvo[];
+    /** Conversations of this launch the cap folded into `rest` — in the totals, not in `convos`. */
+    more: number;
+    totals: TokenTotals;
+    cost: CostBreakdown;
+    agentTotals: TokenTotals;
+    agentCost: CostBreakdown;
+    firstAt: number | null;
+    lastAt: number | null;
+}
+/**
+ * A launch row's name. `fanout`: the run's label (else the first words of a
+ * session's title) and how many repos it reached; `backlog`/`schedule`/`agent`:
+ * the label, a sweep across several repos saying how many; a hand session (or
+ * one nobody labelled): its title, else `repo · id8`.
+ */
+export declare function launchLabel(row: Omit<LaunchRow, "label">, rest?: readonly CostConvoRest[]): string;
+/**
+ * Called ONCE per list, never per row (fanoutruns.ts' rule). Descending by cost.
+ * Pass the document's `rest` so a launch whose conversations the cap folded is
+ * still whole — forty cheap fan-out targets are one dear run.
+ */
+export declare function foldLaunches(convos: readonly CostConvo[], rest?: readonly CostConvoRest[]): LaunchRow[];
+export interface RepoRow {
+    repo: string;
+    label: string;
+    totals: TokenTotals;
+    cost: CostBreakdown;
+    agentCost: CostBreakdown;
+    /** Descending by cost. Only the CARRIED conversations; `more` counts the folded ones. */
+    convos: CostConvo[];
+    /** This repo's conversations the cap folded into `rest` — in the totals, not in `convos`. */
+    more: number;
+    byModel: ModelSlice[];
+}
+/** Descending by cost, tokens tie-break. Pass the document's `rest` so a repo's total keeps
+ *  the sessions the cap folded. */
+export declare function rankRepos(convos: readonly CostConvo[], rest?: readonly CostConvoRest[]): RepoRow[];
+/** A `RepoRow` as a `TokenGroup`, so `Bars`/`topGroups` draw it unchanged. */
+export declare function repoRowAsGroup(r: RepoRow): TokenGroup;
+export interface PtsCalibration {
+    usdPerPt: number;
+    /** Pooled over the stretches that qualified. */
+    usd: number;
+    dPts: number;
+    stretches: number;
+    /** The level calibration it was checked against (`weekUsdPerPct`), when there was one. */
+    levelUsdPerPt?: number | null;
+}
+export type PtsRefusal = {
+    why: "noSamples" | "shortStretches" | "smallDelta" | "unstable" | "disagreesWithLevel" | "noCost";
+};
+/** A stretch shorter than this is edge noise (the cost side is hour buckets). */
+export declare const CAL_MIN_SPAN_MS: number;
+/** A stretch must climb this many points to count at all. */
+export declare const CAL_MIN_DPTS = 5;
+/** One stretch alone must climb this many. */
+export declare const CAL_SINGLE_MIN_DPTS = 10;
+/** Every stretch within ±35% of the pooled rate. */
+export declare const CAL_SPREAD = 0.35;
+/** And the pooled rate within ±40% of the level calibration. */
+export declare const CAL_LEVEL_SPREAD = 0.4;
+export declare function isPtsCal(x: PtsCalibration | PtsRefusal | null | undefined): x is PtsCalibration;
+/**
+ * Dollars per weekly point from Δw (the usage log's `w`) against the ledger's
+ * cost over the same hours.
+ *
+ * Readings are cut into STRETCHES by `usageStretches(samples, "week")` — a reset
+ * (`wr` moved past `RESET_EPS_MS`, or `w` fell past `DROP_EPS_PCT`) ends one —
+ * so a reset inside the span never contributes a negative Δ. A stretch's
+ * dollars are Σ `hours[].cost.total` for hours whose top is in
+ * `[hourFloor(a.t), hourFloor(b.t))`: the partial last hour is left out and
+ * `CAL_MIN_SPAN_MS` bounds the edge error. A stretch qualifies when it is long
+ * enough, climbed enough and the ledger has cost in it; the qualifying ones are
+ * pooled. Refused — never a number — when none qualify, when a lone stretch
+ * climbed under `CAL_SINGLE_MIN_DPTS`, when any stretch's rate is outside
+ * `CAL_SPREAD` of the pooled one, or when a level calibration exists and
+ * disagrees past `CAL_LEVEL_SPREAD`.
+ */
+export declare function ptsCalibration(samples: readonly UsageSample[], hours: readonly CostHour[], levelUsdPerPct?: number | null): PtsCalibration | PtsRefusal;
+/** `≈ 15 pts` (2 significant figures; `<0.1 pt` under 0.05; `≈ 1 pt` singular). Null without a
+ *  calibration or a positive figure — absent, never a zero. */
+export declare function ptsText(usd: number | null | undefined, cal: PtsCalibration | PtsRefusal | null | undefined): string | null;
+/** One sentence per refusal — a statement of what is missing, never a hint. */
+export declare function ptsRefusalText(r: PtsRefusal): string;
+export declare const AGENT_MODEL_MIN_PCT = 15;
+/**
+ * "Opus subagents: 62% of this session's cost" — the dearest agent model
+ * family, only when it is at least `AGENT_MODEL_MIN_PCT` of `cost.total` and
+ * that is above zero. Null otherwise, and null when the slices add up to more
+ * than the total (an inconsistent reading is absent, never a wrong share).
+ * Takes anything with `cost` + `agentByModel`, so `TokenConvo` and `CostConvo`
+ * both feed it.
+ */
+export declare function agentModelInsight(c: {
+    cost: CostBreakdown;
+    agentByModel?: ModelSlice[] | null;
+}): string | null;
+/** Whitespace-collapsed, lower-cased text — "same prompt" for the hint. Not promptid's (that is a box fingerprint). */
+export declare function fanoutTextKey(text: string): string;
+/** The most recent FINISHED run with the same text key, else the most recent finished run, else null.
+ *  A run still going is never the comparison — its cost is not known yet. */
+export declare function pickSimilarRun(runs: readonly FanoutRun[], text: string): FanoutRun | null;
+/**
+ * "last similar run (36 repos): $218.00 ≈ 15% of week, 66% subagents" /
+ * "last run (different prompt, 36 repos): …". `weekPct` null (or not a
+ * positive figure) ⇒ the `≈` clause is omitted, never "0%".
+ */
+export declare function fanoutHintText(args: {
+    same: boolean;
+    usd: number;
+    weekPct: number | null;
+    agentPct: number;
+    repos: number;
+}): string;