@mnemom/mnemom 0.17.33 → 0.17.34-next.2

package/dist/lib/scan/spend/anthropic-usage.js

@@ -0,0 +1,244 @@
+// MNE-9298 Tier 1: the CTO's own Anthropic Admin key, used LOCALLY, to read measured usage. Port of
+// mnemom-api src/org-scan/usage/usage-client.ts (two read-only GETs: usage_report/messages grouped by
+// context_window, and cost_report) with the server-only parts (egress allowlist, WIF) dropped.
+//
+// The key is held in memory for the length of the two reads. It is never stored, logged, written to disk,
+// echoed, put in argv, a URL or an error message, and is sent only to api.anthropic.com (a constant, not
+// configurable) in the x-api-key header. Every failure surfaces as a fixed sentence: the thrown value, the
+// response body and the key never reach the terminal.
+export const ANTHROPIC_ADMIN_ORIGIN = "https://api.anthropic.com";
+export const ADMIN_KEY_ENV = "ANTHROPIC_ADMIN_KEY";
+const ANTHROPIC_VERSION = "2023-06-01";
+const USAGE_PATH = "/v1/organizations/usage_report/messages";
+const COST_PATH = "/v1/organizations/cost_report";
+export const DEFAULT_MAX_PAGES = 20;
+/** One shared deadline for a request including its retries (not N x timeout). */
+export const DEFAULT_TIMEOUT_MS = 15_000;
+export const DEFAULT_MAX_RETRIES = 2;
+const MAX_RETRY_WAIT_MS = 5_000;
+const ADMIN_KEY_RE = /^sk-ant-admin[A-Za-z0-9_-]{8,}$/;
+/** Shape check only; the key is never echoed, even on a mismatch. */
+export const isAdminKeyShape = (k) => typeof k === "string" && ADMIN_KEY_RE.test(k.trim());
+const FAILURE_TEXT = {
+    key_invalid: "The Anthropic admin key is not an Admin API key (it should start with sk-ant-admin).",
+    key_refused: "Anthropic refused the admin key (401/403).",
+    rate_limited: "Anthropic rate limit reached.",
+    timeout: "Anthropic did not answer in time.",
+    network: "Anthropic was unreachable.",
+    upstream: "Anthropic usage could not be read.",
+    malformed: "Anthropic returned usage in a shape this CLI does not recognise.",
+    too_large: "Anthropic usage for this period is too large to read completely.",
+};
+/** Fixed sentence for a failure reason. */
+export const usageFailureText = (r) => FAILURE_TEXT[r];
+/** Carries only a reason tag. Its message is the fixed sentence: nothing upstream can reach it. */
+export class AnthropicUsageError extends Error {
+    reason;
+    constructor(reason) {
+        super(FAILURE_TEXT[reason]);
+        this.reason = reason;
+        this.name = "AnthropicUsageError";
+    }
+}
+const bad = () => {
+    throw new AnthropicUsageError("malformed");
+};
+const rec = (v) => v && typeof v === "object" && !Array.isArray(v) ? v : bad();
+function reqNum(r, k) {
+    const v = r[k];
+    return typeof v === "number" && Number.isFinite(v) && v >= 0 ? v : bad();
+}
+/** Optional counter inside an optional object: absent is 0, present-but-wrong is an error. */
+function optNum(o, k) {
+    if (o === undefined || o === null)
+        return 0;
+    if (typeof o !== "object")
+        return bad();
+    const v = o[k];
+    if (v === undefined || v === null)
+        return 0;
+    return typeof v === "number" && Number.isFinite(v) && v >= 0 ? v : bad();
+}
+export function parseUsageRow(raw) {
+    const r = rec(raw);
+    const cw = r.context_window;
+    if (cw !== null && cw !== undefined && cw !== "0-200k" && cw !== "200k-1M")
+        bad();
+    return {
+        tokens: reqNum(r, "uncached_input_tokens") +
+            reqNum(r, "cache_read_input_tokens") +
+            reqNum(r, "output_tokens") +
+            optNum(r.cache_creation, "ephemeral_1h_input_tokens") +
+            optNum(r.cache_creation, "ephemeral_5m_input_tokens"),
+        contextWindow: (cw ?? null),
+    };
+}
+const CENT = /^-?\d+(\.\d+)?$/;
+export function parseCostRow(raw) {
+    const r = rec(raw);
+    if (typeof r.amount !== "string" || !CENT.test(r.amount))
+        bad();
+    if (typeof r.currency !== "string" || r.currency === "")
+        bad();
+    return { cents: Number(r.amount), currency: r.currency };
+}
+const DAY_MS = 86_400_000;
+/** Buckets are UTC-aligned: floor so a mid-day start reads the whole bucket it falls in. */
+export function alignStartingAt(startingAt) {
+    const t = Date.parse(startingAt);
+    if (!Number.isFinite(t))
+        return startingAt;
+    return new Date(Math.floor(t / DAY_MS) * DAY_MS).toISOString().replace(".000Z", "Z");
+}
+const backoff = (attempt) => Math.min(250 * 2 ** (attempt - 1), MAX_RETRY_WAIT_MS);
+function retryWait(res, attempt) {
+    const ra = Number(res.headers.get("retry-after"));
+    return Number.isFinite(ra) && ra > 0 ? ra * 1000 : backoff(attempt);
+}
+class Reader {
+    key;
+    fetchImpl;
+    sleep;
+    maxPages;
+    timeoutMs;
+    maxRetries;
+    constructor(key, deps) {
+        this.key = key;
+        this.fetchImpl = deps.fetchImpl ?? ((...a) => fetch(...a));
+        this.sleep = deps.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+        this.maxPages = deps.maxPages ?? DEFAULT_MAX_PAGES;
+        this.timeoutMs = deps.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+        this.maxRetries = deps.maxRetries ?? DEFAULT_MAX_RETRIES;
+    }
+    async walk(path, base, parse, callMaxPages) {
+        const ceiling = typeof callMaxPages === "number" && Number.isFinite(callMaxPages) && callMaxPages >= 1
+            ? Math.min(this.maxPages, Math.floor(callMaxPages))
+            : this.maxPages;
+        const rows = [];
+        let page = null;
+        let pages = 0;
+        for (;;) {
+            const params = new URLSearchParams(base);
+            if (page)
+                params.set("page", page);
+            const body = await this.request(`${ANTHROPIC_ADMIN_ORIGIN}${path}?${params.toString()}`);
+            pages += 1;
+            if (!Array.isArray(body.data))
+                bad();
+            for (const raw of body.data) {
+                const b = rec(raw);
+                if (typeof b.starting_at !== "string" || typeof b.ending_at !== "string")
+                    bad();
+                if (!Array.isArray(b.results))
+                    bad();
+                for (const r of b.results)
+                    rows.push(parse(r));
+            }
+            const more = body.has_more;
+            if (more !== undefined && more !== null && typeof more !== "boolean")
+                bad();
+            if (more !== true)
+                return { rows, truncated: false, pages };
+            if (typeof body.next_page !== "string" || body.next_page === "")
+                bad();
+            if (pages >= ceiling)
+                return { rows, truncated: true, pages };
+            page = body.next_page;
+        }
+    }
+    async request(url) {
+        const deadline = AbortSignal.timeout(this.timeoutMs);
+        for (let attempt = 0;;) {
+            let res;
+            try {
+                res = await this.fetchImpl(url, {
+                    method: "GET",
+                    headers: {
+                        "x-api-key": this.key,
+                        "anthropic-version": ANTHROPIC_VERSION,
+                        accept: "application/json",
+                    },
+                    // A redirect would carry the x-api-key header to wherever it points: refuse to follow one.
+                    redirect: "error",
+                    signal: deadline,
+                });
+            }
+            catch {
+                // Never surface the thrown value: it can carry the request.
+                if (deadline.aborted)
+                    throw new AnthropicUsageError("timeout");
+                if (attempt++ < this.maxRetries) {
+                    await this.sleep(backoff(attempt));
+                    continue;
+                }
+                throw new AnthropicUsageError("network");
+            }
+            if (res.ok) {
+                let json;
+                try {
+                    json = await res.json();
+                }
+                catch {
+                    throw new AnthropicUsageError("upstream");
+                }
+                return rec(json);
+            }
+            await res.body?.cancel().catch(() => { });
+            if (res.status === 401 || res.status === 403)
+                throw new AnthropicUsageError("key_refused");
+            const retryable = res.status === 429 || res.status >= 500;
+            const wait = retryable ? retryWait(res, attempt + 1) : 0;
+            if (retryable &&
+                !deadline.aborted &&
+                wait <= MAX_RETRY_WAIT_MS &&
+                attempt++ < this.maxRetries) {
+                await this.sleep(wait);
+                continue;
+            }
+            throw new AnthropicUsageError(res.status === 429 ? "rate_limited" : "upstream");
+        }
+    }
+}
+const validDay = (d) => /^\d{4}-\d{2}-\d{2}$/.test(d) && Number.isFinite(Date.parse(`${d}T00:00:00Z`));
+/**
+ * The same two reads mnemom-api made: usage grouped by context_window (the exact >200k share) and cost
+ * (total spend). The key is shape-checked before any call so a regular API key never leaves the machine.
+ * Throws AnthropicUsageError only. A walk stopped by the page cap is an error, never a short total.
+ */
+export async function fetchMeasuredUsage(key, period, deps = {}) {
+    const k = key?.trim();
+    if (!k || !isAdminKeyShape(k))
+        throw new AnthropicUsageError("key_invalid");
+    if (!validDay(period.start) || !validDay(period.end))
+        throw new AnthropicUsageError("malformed");
+    const startingAt = alignStartingAt(`${period.start}T00:00:00Z`);
+    const endingAt = new Date(Date.parse(`${period.end}T00:00:00Z`) + DAY_MS).toISOString();
+    const reader = new Reader(k, deps);
+    const up = new URLSearchParams({
+        starting_at: startingAt,
+        ending_at: endingAt,
+        bucket_width: "1d",
+    });
+    up.append("group_by[]", "context_window");
+    const usage = await reader.walk(USAGE_PATH, up, parseUsageRow);
+    if (usage.truncated)
+        throw new AnthropicUsageError("too_large");
+    const cp = new URLSearchParams({ starting_at: startingAt, ending_at: endingAt });
+    const cost = await reader.walk(COST_PATH, cp, parseCostRow);
+    if (cost.truncated)
+        throw new AnthropicUsageError("too_large");
+    let total = 0;
+    let over = 0;
+    for (const r of usage.rows) {
+        total += r.tokens;
+        if (r.contextWindow === "200k-1M")
+            over += r.tokens;
+    }
+    let cents = 0;
+    for (const r of cost.rows) {
+        if (r.currency !== "USD")
+            throw new AnthropicUsageError("malformed");
+        cents += r.cents;
+    }
+    return { usd: Math.round(cents) / 100, over200kShare: total > 0 ? over / total : null };
+}

package/dist/lib/scan/spend/cost-corpus.v1.d.ts

@@ -0,0 +1,56 @@
+declare const _default: {
+    readonly schema_version: 1;
+    readonly as_of: "2026-10-28T00:00:00Z";
+    readonly source: "ADW 'Run cost' PR comments (cost_report.py) on merged fleet PRs (org-wide GitHub search for run-cost comments, plus shipped PRs from the eval sets); cost_usd sums distinct runs and is a floor";
+    readonly candidates: 236;
+    readonly rows: readonly [{
+        readonly repo: "aap";
+        readonly pr: 100;
+        readonly additions: 117;
+        readonly deletions: 68;
+        readonly cost_usd: 0.4;
+        readonly runs: 1;
+        readonly models: readonly ["sonnet"];
+    }, {
+        readonly repo: "mnemom-api";
+        readonly pr: 1816;
+        readonly additions: 239;
+        readonly deletions: 0;
+        readonly cost_usd: 0.55;
+        readonly runs: 1;
+        readonly models: readonly ["haiku", "sonnet"];
+    }, {
+        readonly repo: "mnemom-api";
+        readonly pr: 3639;
+        readonly additions: 2260;
+        readonly deletions: 0;
+        readonly cost_usd: 5.42;
+        readonly runs: 1;
+        readonly models: readonly ["sonnet"];
+    }, {
+        readonly repo: "mnemom-research-grade";
+        readonly pr: 112;
+        readonly additions: 73;
+        readonly deletions: 10;
+        readonly cost_usd: 0.35;
+        readonly runs: 1;
+        readonly models: readonly ["haiku", "sonnet"];
+    }, {
+        readonly repo: "mnemom-website";
+        readonly pr: 1668;
+        readonly additions: 78;
+        readonly deletions: 119;
+        readonly cost_usd: 0.23;
+        readonly runs: 1;
+        readonly models: readonly ["sonnet"];
+    }, {
+        readonly repo: "mnemom-website";
+        readonly pr: 1669;
+        readonly additions: 126;
+        readonly deletions: 22;
+        readonly cost_usd: 0.28;
+        readonly runs: 1;
+        readonly models: readonly ["sonnet"];
+    }];
+};
+export default _default;

package/dist/lib/scan/spend/cost-corpus.v1.js

@@ -0,0 +1,64 @@
+// Cost corpus (port of mnemom-api src/org-scan/spend/cost-corpus.v1.json, as_of 2026-10-28T00:00:00Z). A TS module, not a
+// JSON asset, so the build needs no copy-assets entry.
+export default {
+    schema_version: 1,
+    as_of: "2026-10-28T00:00:00Z",
+    source: "ADW 'Run cost' PR comments (cost_report.py) on merged fleet PRs (org-wide GitHub search for run-cost comments, plus shipped PRs from the eval sets); cost_usd sums distinct runs and is a floor",
+    candidates: 236,
+    rows: [
+        {
+            repo: "aap",
+            pr: 100,
+            additions: 117,
+            deletions: 68,
+            cost_usd: 0.4,
+            runs: 1,
+            models: ["sonnet"],
+        },
+        {
+            repo: "mnemom-api",
+            pr: 1816,
+            additions: 239,
+            deletions: 0,
+            cost_usd: 0.55,
+            runs: 1,
+            models: ["haiku", "sonnet"],
+        },
+        {
+            repo: "mnemom-api",
+            pr: 3639,
+            additions: 2260,
+            deletions: 0,
+            cost_usd: 5.42,
+            runs: 1,
+            models: ["sonnet"],
+        },
+        {
+            repo: "mnemom-research-grade",
+            pr: 112,
+            additions: 73,
+            deletions: 10,
+            cost_usd: 0.35,
+            runs: 1,
+            models: ["haiku", "sonnet"],
+        },
+        {
+            repo: "mnemom-website",
+            pr: 1668,
+            additions: 78,
+            deletions: 119,
+            cost_usd: 0.23,
+            runs: 1,
+            models: ["sonnet"],
+        },
+        {
+            repo: "mnemom-website",
+            pr: 1669,
+            additions: 126,
+            deletions: 22,
+            cost_usd: 0.28,
+            runs: 1,
+            models: ["sonnet"],
+        },
+    ],
+};

package/dist/lib/scan/spend/prices.d.ts

@@ -0,0 +1,33 @@
+export type AiTool = "claude_code" | "codex" | "copilot" | "gemini";
+export interface TokenPrice {
+    /** USD per 1M input tokens. */
+    inputPerMTok: number;
+    /** USD per 1M output tokens. */
+    outputPerMTok: number;
+    model: string;
+}
+export interface PriceBand {
+    low: TokenPrice;
+    high: TokenPrice;
+    /** Page the prices were read from. */
+    source: string;
+}
+export declare const PRICES_AS_OF = "2026-10-28";
+export declare const TOOL_PRICES: Record<Exclude<AiTool, "copilot">, PriceBand>;
+/**
+ * GitHub Copilot bills per premium request, not per token
+ * (https://docs.github.com/en/copilot/concepts/billing/copilot-requests),
+ * so it has no token price of its own. Its agent routes to the other vendors' models, so its band is
+ * the union of the other three: cheapest low to dearest high. An assumption, stated here once.
+ */
+export declare function copilotBand(): PriceBand;
+/**
+ * Share of billed tokens that are input (the rest output). Agent loops re-read large context and
+ * write little, so input dominates. An ASSUMPTION used both to turn our known run cost into
+ * tokens-per-line and to price those tokens for each tool; it cancels to first order when the
+ * tool's input/output price ratio matches ours, and is the main source of the range's width.
+ */
+export declare const INPUT_SHARE = 0.9;
+export declare function bandFor(tool: AiTool): PriceBand;
+/** USD per token at the assumed input/output mix. */
+export declare function blendedUsdPerToken(p: TokenPrice): number;

package/dist/lib/scan/spend/prices.js

@@ -0,0 +1,57 @@
+// MNE-9268: public list prices for the AI coding tools the Tier-3 spend estimator can name.
+// Constants, not magic numbers: every row carries its source page and the date it was read.
+// USD per million tokens (input / output), standard (non-batch) list price. A band is the cheapest
+// and the dearest model a tool's coding agent plausibly runs on, so the estimate is a RANGE.
+// Re-read the pages and bump PRICES_AS_OF when they move; a stale price widens nothing silently,
+// it just shifts the range, which is why the date ships with the estimate's method text.
+export const PRICES_AS_OF = "2026-10-28";
+export const TOOL_PRICES = {
+    claude_code: {
+        source: "https://platform.claude.com/docs/en/about-claude/pricing",
+        low: { model: "Claude Sonnet 5.5", inputPerMTok: 2, outputPerMTok: 10 },
+        high: { model: "Claude Opus 5", inputPerMTok: 5, outputPerMTok: 25 },
+    },
+    codex: {
+        source: "https://developers.openai.com/api/docs/pricing",
+        low: { model: "gpt-5.3-codex (standard)", inputPerMTok: 1.75, outputPerMTok: 14 },
+        high: { model: "gpt-5.3-codex (fast)", inputPerMTok: 3.5, outputPerMTok: 28 },
+    },
+    gemini: {
+        source: "https://ai.google.dev/gemini-api/docs/pricing",
+        // Gemini 3.8 Flash is $0.75/$3.75 through 2026-12-31 and $1.50/$7.50 from 2027-01-01; the
+        // post-promotion price is used so the lower bound does not expire in two months.
+        low: { model: "Gemini 3.8 Flash (from 2027-01-01)", inputPerMTok: 1.5, outputPerMTok: 7.5 },
+        high: { model: "Gemini 3.1 Pro (prompts up to 200k)", inputPerMTok: 2, outputPerMTok: 12 },
+    },
+};
+/**
+ * GitHub Copilot bills per premium request, not per token
+ * (https://docs.github.com/en/copilot/concepts/billing/copilot-requests),
+ * so it has no token price of its own. Its agent routes to the other vendors' models, so its band is
+ * the union of the other three: cheapest low to dearest high. An assumption, stated here once.
+ */
+export function copilotBand() {
+    const bands = Object.values(TOOL_PRICES);
+    const blend = (p) => p.inputPerMTok * INPUT_SHARE + p.outputPerMTok * (1 - INPUT_SHARE);
+    const low = bands.map((b) => b.low).sort((a, b) => blend(a) - blend(b))[0];
+    const high = bands.map((b) => b.high).sort((a, b) => blend(b) - blend(a))[0];
+    return {
+        low,
+        high,
+        source: "union of the claude_code, codex and gemini bands (per-request billing)",
+    };
+}
+/**
+ * Share of billed tokens that are input (the rest output). Agent loops re-read large context and
+ * write little, so input dominates. An ASSUMPTION used both to turn our known run cost into
+ * tokens-per-line and to price those tokens for each tool; it cancels to first order when the
+ * tool's input/output price ratio matches ours, and is the main source of the range's width.
+ */
+export const INPUT_SHARE = 0.9;
+export function bandFor(tool) {
+    return tool === "copilot" ? copilotBand() : TOOL_PRICES[tool];
+}
+/** USD per token at the assumed input/output mix. */
+export function blendedUsdPerToken(p) {
+    return (p.inputPerMTok * INPUT_SHARE + p.outputPerMTok * (1 - INPUT_SHARE)) / 1_000_000;
+}

package/dist/lib/scan/spend/spend-estimate.d.ts

@@ -0,0 +1,30 @@
+import { type AiTool } from "./prices.js";
+import { type TokenRate } from "./token-rate.js";
+/** AI-assisted PRs needed before a range is worth printing. */
+export declare const MIN_AI_PRS = 10;
+/** Per-PR input. `markText` is commit messages / PR body, read for tool marks and dropped. */
+export interface SpendPrInput {
+    additions: number;
+    deletions: number;
+    markText: string;
+    /** Tools already detected inside the PR source (so the body never leaves it). Wins over markText. */
+    tools?: AiTool[];
+}
+export type NoSpendReason = "too_few_ai_prs" | "no_rate" | "invalid_input";
+export type SpendEstimate = {
+    kind: "range";
+    lowUsd: number;
+    highUsd: number;
+    aiPrs: number;
+    scannedPrs: number;
+    byTool: Partial<Record<AiTool, number>>;
+    /** One line, labelled estimate, passes claim-lint. */
+    line: string;
+} | {
+    kind: "none";
+    reason: NoSpendReason;
+    aiPrs: number;
+    scannedPrs: number;
+    line: string;
+};
+export declare function estimateSpend(prs: unknown, rate?: TokenRate | null): SpendEstimate;

package/dist/lib/scan/spend/spend-estimate.js

@@ -0,0 +1,70 @@
+// MNE-9268: Tier-3 spend RANGE estimator. Pure and in-memory: takes per-PR counts and mark text, returns
+// one labelled estimate line or an explicit "no estimate". Nothing is stored, fetched or logged.
+//
+// No line is produced when there are too few AI-assisted PRs to price (MIN_AI_PRS). That is a
+// data-sufficiency threshold on the evidence behind the range, nothing to do with how large a
+// reporting cohort is. Default-OFF behind ORG_SCAN_MODE via estimateSpendIfEnabled.
+import { AI_TOOLS, detectAiTools } from "./ai-tool-detect.js";
+import { PRICES_AS_OF, bandFor, blendedUsdPerToken } from "./prices.js";
+import { DERIVED_TOKEN_RATE } from "./token-rate.js";
+/** AI-assisted PRs needed before a range is worth printing. */
+export const MIN_AI_PRS = 10;
+/** Fixed strings only: a failure never carries input or an error message into the output. */
+const NONE_LINES = {
+    too_few_ai_prs: "No spend estimate: too few AI-assisted PRs in this scan to price a range.",
+    no_rate: "No spend estimate: the cost reference data is not sufficient to price a range.",
+    invalid_input: "No spend estimate: the PR counts could not be read.",
+};
+const isCount = (n) => typeof n === "number" && Number.isFinite(n) && n >= 0;
+function none(reason, aiPrs, scannedPrs) {
+    return { kind: "none", reason, aiPrs, scannedPrs, line: NONE_LINES[reason] };
+}
+function validPr(p) {
+    if (typeof p !== "object" || p === null)
+        return false;
+    const o = p;
+    return (isCount(o.additions) &&
+        isCount(o.deletions) &&
+        typeof o.markText === "string" &&
+        (o.tools === undefined ||
+            (Array.isArray(o.tools) && o.tools.every((t) => AI_TOOLS.includes(t)))));
+}
+/** Two significant figures so the range does not claim precision it lacks ($2.4, not $2; 0 stays $0). */
+function usd(n) {
+    return `$${n.toLocaleString("en-US", { maximumSignificantDigits: 2 })}`;
+}
+export function estimateSpend(prs, rate = DERIVED_TOKEN_RATE) {
+    if (!Array.isArray(prs))
+        return none("invalid_input", 0, 0);
+    const scanned = prs.length;
+    if (!prs.every(validPr))
+        return none("invalid_input", 0, scanned);
+    let aiPrs = 0;
+    let low = 0;
+    let high = 0;
+    const byTool = {};
+    for (const p of prs) {
+        const tools = p.tools ?? detectAiTools(p.markText);
+        if (tools.length === 0)
+            continue;
+        aiPrs += 1;
+        for (const t of tools)
+            byTool[t] = (byTool[t] ?? 0) + 1;
+        if (!rate)
+            continue;
+        const lines = p.additions + p.deletions;
+        // A PR carrying several marks is priced once, across the widest band of the tools named.
+        const bands = tools.map(bandFor);
+        const lo = Math.min(...bands.map((b) => blendedUsdPerToken(b.low)));
+        const hi = Math.max(...bands.map((b) => blendedUsdPerToken(b.high)));
+        low += lines * rate.low * lo;
+        high += lines * rate.high * hi;
+    }
+    if (aiPrs < MIN_AI_PRS)
+        return none("too_few_ai_prs", aiPrs, scanned);
+    if (!rate)
+        return none("no_rate", aiPrs, scanned);
+    const line = `Estimate, AI tool spend: ${usd(low)} to ${usd(high)} across ${aiPrs} AI-assisted PRs ` +
+        `(public list prices as of ${PRICES_AS_OF} times a tokens-per-line rate from our own agents' PRs; not billing data).`;
+    return { kind: "range", lowUsd: low, highUsd: high, aiPrs, scannedPrs: scanned, byTool, line };
+}

package/dist/lib/scan/spend/spend-tiers.d.ts

@@ -0,0 +1,25 @@
+import type { SpendEstimate } from "./spend-estimate.js";
+export declare const ORG_SCAN_ENV = "MNEMOM_ORG_SCAN_MODE";
+/** Default OFF: only the exact string "true" turns the tiers on. */
+export declare const isSpendTiersEnabled: (env?: NodeJS.ProcessEnv) => boolean;
+export declare const NOT_ENABLED_MSG = "The spend fallback is not enabled.";
+export declare const SPEND_INVALID_MSG = "Monthly spend must be a dollar amount above zero, like 5000.";
+export declare const SPEND_NO_TERMINAL_MSG = "Pass --monthly-spend <usd> (there is no terminal to ask on).";
+export declare const MAX_MONTHLY_SPEND_USD = 10000000;
+/** Dollars, or null if the text is not a positive, plausible amount. */
+export declare function parseMonthlySpendUsd(raw: string): number | null;
+export type SpendTier = 1 | 2 | 3;
+export interface SpendSelection {
+    /** null when the evidence is too thin: print nothing. */
+    tier: SpendTier | null;
+    line: string | null;
+    /** May this line leave the machine in a share payload? Never for a self-reported figure. */
+    shareable: boolean;
+}
+export declare function selectSpend(i: {
+    measuredUsd?: number;
+    /** Fraction of measured tokens from requests over 200k context; shown only with a measured figure. */
+    over200kShare?: number | null;
+    selfReportedUsd?: number | null;
+    estimate: SpendEstimate;
+}): SpendSelection;

package/dist/lib/scan/spend/spend-tiers.js

@@ -0,0 +1,42 @@
+export const ORG_SCAN_ENV = "MNEMOM_ORG_SCAN_MODE";
+/** Default OFF: only the exact string "true" turns the tiers on. */
+export const isSpendTiersEnabled = (env = process.env) => env[ORG_SCAN_ENV] === "true";
+export const NOT_ENABLED_MSG = "The spend fallback is not enabled.";
+export const SPEND_INVALID_MSG = "Monthly spend must be a dollar amount above zero, like 5000.";
+export const SPEND_NO_TERMINAL_MSG = "Pass --monthly-spend <usd> (there is no terminal to ask on).";
+export const MAX_MONTHLY_SPEND_USD = 10_000_000;
+const SPEND_RE = /^\$?\s*(\d{1,3}(,\d{3})+|\d+)(\.\d{1,2})?$/;
+/** Dollars, or null if the text is not a positive, plausible amount. */
+export function parseMonthlySpendUsd(raw) {
+    const t = raw.trim();
+    if (!SPEND_RE.test(t))
+        return null;
+    const n = Number(t.replace(/[$,\s]/g, ""));
+    return Number.isFinite(n) && n > 0 && n <= MAX_MONTHLY_SPEND_USD ? n : null;
+}
+const usd = (n) => `$${n.toLocaleString("en-US", { maximumFractionDigits: 2 })}`;
+const isUsd = (n) => typeof n === "number" && Number.isFinite(n) && n > 0;
+const pct = (f) => `${Math.round(f * 100)}%`;
+const isShare = (n) => typeof n === "number" && Number.isFinite(n) && n >= 0 && n <= 1;
+export function selectSpend(i) {
+    if (isUsd(i.measuredUsd)) {
+        return {
+            tier: 1,
+            line: `Tier 1, measured: ${usd(i.measuredUsd)} of Anthropic usage over the period${isShare(i.over200kShare)
+                ? ` (${pct(i.over200kShare)} of tokens in requests over 200k context)`
+                : ""}.`,
+            shareable: true,
+        };
+    }
+    if (isUsd(i.selfReportedUsd)) {
+        return {
+            tier: 2,
+            line: `Tier 2, self-reported: about ${usd(i.selfReportedUsd)} a month (given by you; not verified, not sent, not saved).`,
+            shareable: false,
+        };
+    }
+    if (i.estimate.kind === "range") {
+        return { tier: 3, line: `Tier 3, ${i.estimate.line}`, shareable: true };
+    }
+    return { tier: null, line: null, shareable: false };
+}

package/dist/lib/scan/spend/token-rate.d.ts

@@ -0,0 +1,30 @@
+/** Rows needed before the rate is trusted at all (data sufficiency, not a group size). */
+export declare const MIN_CORPUS_ROWS = 5;
+export interface CostRowShape {
+    repo: string;
+    pr: number;
+    additions: number;
+    deletions: number;
+    cost_usd: number;
+    runs: number;
+    models: string[];
+}
+export interface TokenRate {
+    /** Price-equivalent tokens per changed (added + deleted) line: 25th percentile. */
+    low: number;
+    median: number;
+    /** 75th percentile. */
+    high: number;
+    rows: number;
+}
+/** Linear-interpolated quantile of a sorted array. */
+export declare function quantile(sorted: number[], q: number): number;
+/**
+ * Derive the rate from corpus rows: per-row tokens/line, then the 25th, 50th and 75th percentile.
+ * Rows that fail validation are dropped (not repaired); fewer than MIN_CORPUS_ROWS valid rows
+ * returns null, never a rate built on a handful.
+ */
+export declare function deriveTokenRate(rows: unknown): TokenRate | null;
+export declare const CORPUS_AS_OF: string;
+/** The shipped rate: derived once from the committed fixture. */
+export declare const DERIVED_TOKEN_RATE: TokenRate | null;