@open-everywhere/core 0.1.0

package/dist/agent/spend/reporting.js

@@ -0,0 +1,674 @@
+// Shared plumbing for the reporting tools (session_cost / spend_report / usage_report,
+// agent/tools/) and their control-plane sibling (usage_summary in control/views.ts) —
+// Batch B1 of build-2026-07-04-rbac-skills-cost.md's D6. Nothing here is a tool itself;
+// this is the "how do we scope + price + predict from usage_events rows" logic the three
+// tools and the control view all need, kept in one place so it's tested once.
+//
+// SCOPE GATING (D2): domain scope = "anyone in the domain" — the caller's channel
+// resolving to a domain at all IS the gate, no further role check. Reuses
+// skills/domain-skills.ts's resolveSkillDomainDetailed for that resolution (same
+// dm/mpim/external/unassigned exclusions a runtime skill author is held to — see that
+// module's header for why), but supplies its own refusal wording: "can't author a
+// skill" would be a misleading error from a read-only report. Org scope = org-admin
+// (access/roles.ts's requireOrgAdmin, unchanged).
+//
+// DOMAIN BUCKETING OF USAGE ROWS: a usage_events row only carries a surfaceKey + a
+// best-effort `kind` (agent/hooks/spend.ts's turnKind), not a full SurfaceBinding, so
+// it can't be run through skillDomainFor directly. domainOfUsageRow mirrors that
+// policy's SHAPE (explicit domain wins; an internal/unassigned surface falls to the
+// `org` pseudo-domain) using `kind` as the mode signal: kind==="dm" is excluded (no
+// memory domain, matching skillDomainFor's dm exclusion) and everything else resolves
+// like an ordinary channel. This is an approximation for mpim/external surfaces (usage
+// rows can't distinguish them from an unassigned internal channel, so they fall into
+// the org bucket) — acceptable because nothing here is an access decision, only a
+// read-only report's grouping.
+//
+// HONEST ESTIMATES: every number this module derives beyond a straight token/event SUM
+// is labelled as an estimate in its own shape (a `note`/`skippedReason` string, or a
+// `projected`/`approx` field name) — no dollar figure or count is fabricated; an
+// unresolvable one is omitted or explained, never guessed (same evidence discipline as
+// spend/pricing.ts's D5).
+import { resolvePartition } from "../memory/partition.js";
+import { requireOrgAdmin } from "../access/roles.js";
+import { domainForChannel, criteriaDomain } from "../memory/domain.js";
+import { resolveSkillDomainDetailed, skillDomainFor } from "../skills/domain-skills.js";
+import { getOperationalStore } from "../operational/provider.js";
+import { getConfig } from "../access/config.js";
+import { parseCron, cronMatches, DISPATCH_TICK_MINUTES } from "../routines/schedule.js";
+import { modelPricing, estimateCostUsd, soleConfiguredModel } from "./pricing.js";
+import { UNKNOWN_MODEL, periodOf } from "./spend.js";
+import { foldDisclosure } from "./dm-mask.js";
+import { spendRollup } from "./store.js";
+/** A tool-facing refusal for a report request that can't resolve a domain — parallel
+ *  to domain-skills.ts's domainSkillRefusalMessage, reworded for a read-only report
+ *  (that function's wording is about AUTHORING a skill, which would be misleading
+ *  here). */
+export function reportDomainRefusalMessage(reason) {
+    switch (reason) {
+        case "dm":
+            return 'Domain-scoped reporting isn\'t available from a DM (a DM has no memory domain) — ask from a channel in the domain, or pass scope:"org" if you\'re an org admin.';
+        case "mpim":
+            return "Domain-scoped reporting isn't available from a group chat (execution-only, no memory domain) — ask from a channel in the domain instead.";
+        case "external":
+            return "Domain-scoped reporting isn't available from an externally-shared or unconfirmed channel.";
+        case "unassigned":
+            return 'This channel isn\'t in any memory domain and no org-wide default domain is configured — there\'s no domain to report on. Try scope:"org" if you\'re an org admin.';
+    }
+}
+/**
+ * Gate + resolve a report call's scope. scope="org" requires org-admin
+ * (requireOrgAdmin throws a named, model-friendly error otherwise); scope="domain"
+ * requires the caller's channel to resolve to a memory domain at all — succeeding IS
+ * the gate ("anyone in the domain" per D2), so a plain member gets their own domain's
+ * numbers but never another domain's or the org-wide view.
+ */
+export function resolveReportScope(ctx, scope) {
+    const org = resolvePartition(ctx).org;
+    if (scope === "org") {
+        requireOrgAdmin(ctx);
+        return { org };
+    }
+    const resolved = resolveSkillDomainDetailed(ctx);
+    if (resolved.domain === null)
+        throw new Error(reportDomainRefusalMessage(resolved.reason));
+    return { org, domain: resolved.domain };
+}
+// --- domain bucketing of usage rows --------------------------------------------------
+/**
+ * Which domain a usage_events row belongs to, for report filtering (see file header
+ * for the mirrored-not-identical relationship to skillDomainFor). Undefined when the
+ * row can't be attributed to any domain (a dm-kind row, or an internal/unassigned
+ * surface with no `org` pseudo-domain configured).
+ *
+ * GRAIN NOTE (item 22): rows are stamped at SPEND grain — a Discord thread turn's
+ * surfaceKey is its PARENT channel (hooks/spend.ts) — so this hop just works. Rows
+ * written BEFORE that landed carry the thread's own channel id and attribute to the
+ * org fallback here; they age out with usage_events retention (90d default) and the
+ * gate's calendar-month window, so no backfill/re-mapping is done.
+ */
+export function domainOfUsageRow(surfaceKey, kind, domains) {
+    if (kind === "dm")
+        return undefined;
+    return domainForChannel(surfaceKey, domains)?.name ?? criteriaDomain("org", domains)?.name;
+}
+/** Filter usage rows to the ones belonging to `domainName` (per domainOfUsageRow). */
+export function filterToDomain(rows, domainName, domains) {
+    return rows.filter((r) => domainOfUsageRow(r.surfaceKey, r.kind, domains) === domainName);
+}
+// --- the unprivileged domain spend scan (OPE-1631) ----------------------------------
+//
+// WHAT IT IS. One read that answers "what has my domain spent lately" for a caller who holds no
+// admin role at all — the read `/oe budget raise` runs so the requester proposes a cap against a
+// number instead of against a guess. It is UNPRIVILEGED in exactly the sense `resolveReportScope`'s
+// domain arm already is (D2, "anyone in the domain"): resolving to a domain IS the gate, and the
+// caller gets that domain and no other.
+//
+// 🔴 "THEIR DOMAIN" CAN BE THE `org` PSEUDO-DOMAIN, AND THAT BUCKET IS WIDE. Say it plainly rather
+// than claiming a narrowness the resolver does not give. `skillDomainFor` falls an INTERNAL,
+// UNASSIGNED channel through to the `org` criteria domain, and this repo ships exactly that domain
+// (`agent/memory/config/domains/org.ts`). A caller in a channel no explicit domain claims therefore
+// resolves to `org`, and the sum below covers every ledger row no explicit domain claims — every
+// other unassigned surface, and DM rows too, because a `spend_ledger` row carries no `kind` and so
+// cannot take the `dm` exclusion `filterToDomain` applies to usage rows (tools/set_spend_limit.ts
+// states that asymmetry).
+//
+// THE FIGURE IS THEN ORG-SCALE, NOT WORKSPACE-SCALE. `criteriaDomain` is
+// `domains.find((d) => d.match === "org")` (memory/domain.ts) — it never looks at a surface key —
+// so the `org` bucket claims every unmatched key on EVERY workspace and EVERY platform this
+// deployment serves, and the rollup read narrows by org and by PERIOD alone — the period range
+// bounds how much history the read costs, and bounds the DISCLOSURE not at all. `/oe budget` is a
+// STRICTLY NARROWER disclosure and is not the precedent for this one: its workspace line sums the
+// `${workspaceKey}/` prefix (spend/store.ts), which is one platform and one workspace. The bucket
+// is not new — `spend_report`'s `scope: "domain"` arm resolves through this same `skillDomainFor`
+// and renders that same bucket PER SURFACE — but nothing here may be read as bounded by the room
+// or the workspace the command was typed in. Whether the scan should refuse the `org` bucket and
+// run only for an EXPLICIT domain is a policy question OPE-1631 does not settle, and it is raised
+// on the ticket rather than decided here.
+//
+// 🔴 THREE NARROWINGS, AND THE RETURN TYPE ENFORCES THE LAST TWO.
+//   1. OWN DOMAIN ONLY. {@link reportDomainForBinding} resolves the caller's domain from their own
+//      binding — a caller never names one — and the row filter then keeps that domain's rows alone.
+//      The resolver is `skills/domain-skills.ts`'s `skillDomainFor`, the SAME policy the
+//      `spend_report` / `usage_report` domain scope resolves through (`resolveReportScope` →
+//      `resolveSkillDomainDetailed` → `skillDomainFor`), so a DM, a group chat, an external channel
+//      and an unassigned channel with no `org` pseudo-domain all resolve to NO domain and the scan
+//      does not run. Two different resolutions here would be the defect: the label and the filter
+//      must name one domain, decided once.
+//   2. AGGREGATE ONLY. The window sums to ONE set of totals. There is no per-surface and no
+//      per-principal breakdown, so nothing here identifies a person or a room. That is why this
+//      read needs no anti-doxxing masking of its own — it EMITS NO KEY, not because DM rows are
+//      absent from the data. They are present, folded into the `org` bucket per the note above.
+//      `spend_report` renders per-surface rows and therefore does mask DM keys, through
+//      `maskDmSurfaceKey`.
+//   3. THE CAP LEDGER ONLY. `spendRollup` reads `spend_ledger` — the durable, keyed table the
+//      caps themselves sum — never `usage_events`. So the figure the requester reads is derived
+//      from the same rows the gate enforces against, which is the whole point of showing it beside
+//      a cap proposal.
+//
+// 🔴 THE WINDOW IS MONTH-GRAINED, AND THAT IS STATED, NEVER ROUNDED AWAY. A `spend_ledger` row is
+// keyed by `period` — "YYYY-MM" (operational/store.ts) — so the ledger CANNOT answer a rolling
+// 30-day question at all; the finest window it holds is a calendar month. This scan therefore sums
+// the calendar months the last-N-days window touches, which is one month or two, and reports those
+// period names in {@link DomainSpendWindow.periods} so every caller renders what was actually
+// summed. It over-covers rather than under-covers, and a caller that printed "the last 30 days"
+// without the periods would be making a claim the ledger cannot support.
+/** The calendar-month periods ("YYYY-MM") a window of `days` back from `nowISO` touches, oldest
+ *  first. One or two entries for a 30-day window, depending on where in the month `nowISO` falls. */
+export function periodsCoveringDays(nowISO, days) {
+    const now = new Date(nowISO);
+    if (Number.isNaN(now.getTime()))
+        throw new Error(`periodsCoveringDays: not an ISO instant: ${JSON.stringify(nowISO)}`);
+    if (!Number.isFinite(days) || days < 0)
+        throw new Error(`periodsCoveringDays: days must be a non-negative finite number, got ${days}`);
+    const start = new Date(now.getTime() - days * 86_400_000);
+    // COUNT the months between the two ends, then emit that many — never a walk that steps a live
+    // cursor forward and stops when it recognises the end month. A stepping cursor keeps its
+    // day-of-month, so `setUTCMonth(+1)` from the 30th of January lands on 2 March and February
+    // vanishes from the window: a whole month of the domain's spend silently missing from the answer.
+    // `Date.UTC` normalises an out-of-range month index, so the addition below rolls the year itself.
+    const span = (now.getUTCFullYear() - start.getUTCFullYear()) * 12 + (now.getUTCMonth() - start.getUTCMonth());
+    const periods = [];
+    for (let i = 0; i <= span; i++)
+        periods.push(periodOf(new Date(Date.UTC(start.getUTCFullYear(), start.getUTCMonth() + i, 1)).toISOString()));
+    return periods;
+}
+/** The caller's own domain, resolved from their binding — the report-side gate for a caller that
+ *  holds a {@link SurfaceBinding} but no live eve context (a slash command has no model turn, so
+ *  `resolveReportScope`'s `BindableContext` form does not reach it). Same policy, same refusal
+ *  reasons: it delegates to `skillDomainFor` rather than restating the rule. */
+export function reportDomainForBinding(binding, domains) {
+    // The two partition keys `skillDomainFor` reads, derived exactly as memory/partition.ts's
+    // `resolvePartition` derives them: the DOMAIN grain takes `domainSurface ?? surface`, so a
+    // Discord thread resolves through its parent channel (binding.ts's `domainSurface`).
+    const workspaceKey = `${binding.platform}/${binding.workspace}`;
+    return skillDomainFor(binding, { surfaceKey: `${workspaceKey}/${binding.surface}`, domainKey: `${workspaceKey}/${binding.domainSurface ?? binding.surface}` }, domains);
+}
+/**
+ * Sum ONE domain's `spend_ledger` rows over the calendar months a `days`-long window touches.
+ *
+ * 🔴 `org` IS THE STORE FILTER, not a filter over the answer (OPE-1446): it is passed to
+ * `spendRollup`, so a foreign tenant's rows never enter the process. The `l.org` conjunct below is
+ * the second belt, exactly as `spend_report`'s rollup keeps one.
+ *
+ * `domainName` is the caller's OWN domain from {@link reportDomainForBinding} — never a caller
+ * argument. Rows are attributed with {@link domainOfUsageRow}, the same hop the `spend_report`
+ * ledger rollup uses, with no `kind` — a ledger row carries its turn's CONVERSATION MODE
+ * (OPE-1862), never the turn-origin tag that hop reads.
+ */
+export async function domainSpendWindow(org, domainName, nowISO, days, deps = {}) {
+    const periods = periodsCoveringDays(nowISO, days);
+    const domains = deps.domains ?? getConfig().loadDomains();
+    // 🔴 THE PERIOD RANGE IS A STORE FILTER (OPE-1653), and on this path the cost is the point.
+    // This scan runs on the SLASH-COMMAND path, where a Discord interaction must answer inside 3
+    // seconds. Reading the org's whole ledger history to keep one or two months of it costs rows
+    // transferred, parsed and aggregated on every invocation, and that cost grows with the
+    // deployment's age. THE BOUND CAN NOW CUT THE ROWS THE ENGINE SCANS TOO (OPE-1677): both
+    // adapters declare a `(org_id, period)` index on `spend_ledger`. SQLite plans the range on it
+    // from the schema alone. Postgres plans it on the index once the ledger is large enough for the
+    // index to beat a sequential scan, and only where an OWNER-mode schema run has created it — a
+    // two-role deployment gets the index from the owner/migration role's schema step, never from
+    // the runtime role's boot (docs/extending/database.md). No measurement in this repo attributes
+    // a 3-second breach to this read — the deadline is why the read is worth bounding, never
+    // evidence that the bound alone meets it.
+    // `periodsCoveringDays` returns CONTIGUOUS
+    // calendar months oldest first, so the two ends bound exactly the set `periods` names — the
+    // range and the `periods.includes` belt below can never disagree.
+    const rows = await (deps.spendRollup ?? spendRollup)(org, { periodFrom: periods[0], periodTo: periods[periods.length - 1] });
+    const mine = rows.filter((l) => l.org === org && periods.includes(l.period) && domainOfUsageRow(l.surfaceKey, undefined, domains) === domainName);
+    return {
+        domain: domainName,
+        periods,
+        tokens: mine.reduce((sum, l) => sum + l.tokens, 0),
+        usd: mine.reduce((sum, l) => sum + l.usd, 0),
+        calls: mine.reduce((sum, l) => sum + l.calls, 0),
+    };
+}
+/**
+ * Resolve which model to price hook-written usage rows against (they carry no
+ * `model` field — see hooks/spend.ts). `explicit` (a caller-supplied assumption)
+ * always wins; otherwise falls back to spend/pricing.ts's soleConfiguredModel() —
+ * safe ONLY because there's exactly one priced model to assume. Never guesses among
+ * several candidates (that would be exactly the invented-number failure mode D5
+ * forbids) — a multi-model deployment must pass assumedModelId explicitly.
+ */
+export function resolveAssumedModel(explicit) {
+    const model = explicit ?? soleConfiguredModel();
+    if (!model) {
+        return {
+            note: "token $ omitted — hook-written usage rows carry no model id, and this deployment has no single default model to assume (pass assumedModelId, or ship exactly one entry in the built-in pricing table).",
+        };
+    }
+    const pricing = modelPricing(model);
+    if (!pricing) {
+        return { model, note: `token $ omitted — "${model}" has no configured pricing (checked the deployer pricing table and the built-in table).` };
+    }
+    return {
+        model,
+        pricing,
+        note: explicit
+            ? `token $ estimated at "${model}" rates (you supplied this model id — hook-written usage rows don't carry one).`
+            : `token $ estimated at "${model}" rates (this deployment's only priced model — hook-written usage rows carry no model id).`,
+    };
+}
+/**
+ * One row's USD cost: its OWN stamped model's rate when it has one AND this
+ * deployment has priced it (exact); otherwise the report's assumed-model fallback,
+ * ONLY for rows that carry no model at all. Undefined when neither prices it.
+ *
+ * 🔴 `shape` SAYS WHETHER THE ROW IS ONE CALL, and the caller must answer honestly, because "row"
+ * means two different things among this function's callers (OPE-2055). `session_cost` and the
+ * analytics executor walk RAW `usage_events` rows — one row, one model call, so a long-context tier
+ * applies. `spend_report` walks rows the store already grouped by (surfaceKey, principalId, kind,
+ * surfaceMode, model), each carrying its own `events` count — a sum with no prompt size in it, where
+ * the tier must never fire. See {@link UsageShape}. The default is `"aggregate"`, the
+ * non-surcharging answer, so a caller that says nothing cannot be over-billed.
+ */
+export function rowCostUsd(row, assumed, shape = "aggregate") {
+    if (row.model) {
+        const exact = modelPricing(row.model);
+        return exact ? estimateCostUsd(row, exact, shape) : undefined;
+    }
+    return assumed.pricing ? estimateCostUsd(row, assumed.pricing, shape) : undefined;
+}
+export function pricingMix(rows, assumed) {
+    let exact = 0;
+    let assumedCount = 0;
+    let unpriced = 0;
+    let unattributed = 0;
+    for (const r of rows) {
+        if (r.model) {
+            if (modelPricing(r.model))
+                exact++;
+            else
+                unpriced++;
+            if (r.model === UNKNOWN_MODEL)
+                unattributed++;
+        }
+        else if (assumed.pricing) {
+            assumedCount++;
+        }
+        else {
+            unpriced++;
+        }
+    }
+    return { exact, assumed: assumedCount, unpriced, unattributed };
+}
+/**
+ * Compose the honest $ note for a report given its pricing mix. Supersedes using
+ * `assumed.note` verbatim once ANY row carries a stamped model: that note describes
+ * only the assumed-model FALLBACK path ("hook-written rows carry no model id") and
+ * would misleadingly suggest $ is guessed/omitted even when most or all rows are now
+ * priced exactly by their own recorded model. Pre-item-17 behaviour (no stamped rows
+ * at all) reproduces `assumed.note` verbatim — no wording change for that case.
+ */
+export function pricingNote(mix, assumed) {
+    if (mix.exact === 0)
+        return assumed.note; // unchanged legacy wording — nothing stamped
+    const parts = [
+        mix.assumed === 0 && mix.unpriced === 0
+            ? "$ figures are exact — every priced row carries its own recorded model id."
+            : `${mix.exact} row(s) priced exactly by their own recorded model id.`,
+    ];
+    if (mix.assumed > 0)
+        parts.push(`${mix.assumed} row(s) with no recorded model: ${assumed.note}`);
+    // The unattributed rows are a SUBSET of `unpriced`, so they are subtracted out of that sentence
+    // rather than double-counted — and given their own, because "configure a rate" is the wrong
+    // remedy for them and would send a reader off to price a model id in agent/spend/model-pricing.ts that
+    // doesn't exist.
+    const unpricedButAttributed = mix.unpriced - mix.unattributed;
+    if (unpricedButAttributed > 0) {
+        parts.push(`${unpricedButAttributed} row(s) omitted — a recorded model this deployment hasn't configured a rate for (see agent/spend/model-pricing.ts), never priced at another model's rate.`);
+    }
+    if (mix.unattributed > 0) {
+        parts.push(`${mix.unattributed} row(s) omitted as "${UNKNOWN_MODEL}" — a real model call the host could not attribute to any model (the per-call model stamp was missing), so no rate was applied to it. ` +
+            `Its tokens are recorded in full, and where the gateway measured the call its exact $ is stored too; only the rate-derived $ is withheld. This is an instrumentation gap, not a pricing one.`);
+    }
+    return parts.join(" ");
+}
+/** Sum the attribution dimensions across rollup rows. Pure. */
+export function tokenAttribution(rows) {
+    const acc = { calls: 0, cacheReadTokens: 0, cacheWriteTokens: 0, reasoningTokens: 0, cacheReportedCalls: 0, reasoningReportedCalls: 0 };
+    for (const r of rows) {
+        acc.calls += r.events;
+        acc.cacheReadTokens += r.cacheReadTokens;
+        acc.cacheWriteTokens += r.cacheWriteTokens;
+        acc.reasoningTokens += r.reasoningTokens;
+        acc.cacheReportedCalls += r.cacheReportedCalls;
+        acc.reasoningReportedCalls += r.reasoningReportedCalls;
+    }
+    return acc;
+}
+/**
+ * The honest one-line attribution note that rides BESIDE a report's dollars.
+ *
+ * 🔴 IT NAMES NO DOLLARS, EVER, and that is the ruling it implements (Tommy, 2026-09-08): the
+ * gateway's measured `costUsd` is the billed truth, so "caching saved $X" derived from a token
+ * count nothing billed against would be a guess wearing a number. The note says how many tokens
+ * each dimension carried and — the part that makes it trustworthy — how much of that is known.
+ *
+ * 🔴 THE CACHE ARM KEYS ON THE TOKEN COUNT, NOT ON THE REPORTED-FIELD FLAG, and the distinction is
+ * the whole value of the line. The Vercel AI Gateway is recorded as billing the prompt-cache
+ * discount with `usage.cachedInputTokens` reading `0` rather than absent
+ * (docs/security/spend-and-cost.md, from the 2026-08-11 rate solve). A published zero sets
+ * `cacheTokensReported` true, so a note that trusted that flag would print "every call reported a
+ * split: 0 read, 0 write" — an affirmative "no caching" over calls the gateway discounted. A ZERO
+ * TOTAL therefore reads as UNATTRIBUTED here, whatever the flag says, and the field count rides
+ * along as the secondary fact rather than the verdict.
+ *
+ * 🔴 AND THE ZERO ARM SPLITS ON WHETHER ANY CALL PUBLISHED A FIELD, because the two silences have
+ * different causes and only one of them is the gateway's. With `cacheReportedCalls === 0` no source
+ * published the dimension at all, so the note claims nothing about caching and names no backend:
+ * blaming the gateway there would explain a provider-payload silence with someone else's billing
+ * behaviour. `ModelBackend` is swappable (docs/deploy/configuration-reference.md) — a self-host on
+ * OpenRouter or a direct provider SDK is supported — so the discount sentence is stated for the
+ * Vercel AI Gateway backend by name, never as a fact about every deployment. An operator who reads
+ * "the saving is already inside the cost" about a backend that does not behave that way stops
+ * looking for a real gap.
+ */
+export function tokenAttributionNote(a) {
+    if (a.calls === 0)
+        return "No model calls in scope — nothing to attribute.";
+    const parts = [];
+    const cacheTokens = a.cacheReadTokens + a.cacheWriteTokens;
+    parts.push(cacheTokens === 0
+        ? a.cacheReportedCalls === 0
+            ? `Cache: UNATTRIBUTED across all ${a.calls} call(s) — no call published a cache field at all, ` +
+                `so nothing here says whether caching happened.`
+            : `Cache: UNATTRIBUTED across all ${a.calls} call(s) — no cache tokens were reported at all ` +
+                `(${a.cacheReportedCalls} call(s) published a cache field, every one of them zero). A zero is NOT a measurement that caching did not happen: ` +
+                `on the Vercel AI Gateway backend a cached call is billed at the discount while the cached-token count reads 0 ` +
+                `(docs/security/spend-and-cost.md), so on that backend the saving shows in the cost and never in the split.`
+        : `Cache: ${a.cacheReadTokens} read / ${a.cacheWriteTokens} write token(s)` +
+            (a.cacheReportedCalls < a.calls
+                ? `; ${a.calls - a.cacheReportedCalls} of ${a.calls} call(s) published no cache field at all, so nothing is claimed about those.`
+                : ` across ${a.calls} call(s), all of which published a cache field.`));
+    parts.push(a.reasoningReportedCalls === 0
+        ? `Reasoning tokens: UNREPORTED on all ${a.calls} call(s).`
+        : `Reasoning: ${a.reasoningTokens} token(s) across ${a.reasoningReportedCalls} of ${a.calls} call(s) that reported the dimension.`);
+    // No "$" anywhere in this string, and the suite asserts that literally: the whole point of the
+    // line is that it answers WHERE the tokens went without answering what they saved.
+    parts.push("These are ATTRIBUTION counts only — no dollar figure is derived from them, and the billed cost above stands unchanged.");
+    return parts.join(" ");
+}
+/** Summarise measured-vs-derived divergence across already-scoped ledger rollup rows (pure). */
+export function summariseCostDrift(rows) {
+    let measuredUsd = 0;
+    let derivedUsd = 0;
+    let measuredCalls = 0;
+    let totalCalls = 0;
+    for (const r of rows) {
+        measuredUsd += r.usdMeasured;
+        derivedUsd += r.usdDerivedOnMeasured;
+        measuredCalls += r.measuredCalls;
+        totalCalls += r.calls;
+    }
+    const divergenceUsd = derivedUsd - measuredUsd;
+    return {
+        measuredUsd,
+        derivedUsd,
+        divergenceUsd,
+        ...(measuredCalls > 0 && measuredUsd > 0 ? { divergencePct: (divergenceUsd / measuredUsd) * 100 } : {}),
+        measuredCalls,
+        totalCalls,
+    };
+}
+/** The one-sentence reading of a {@link CostDrift}, for a report's note block. Always says what
+ *  the coverage was, because a divergence figure without its denominator is not interpretable. */
+export function costDriftNote(drift) {
+    if (drift.measuredCalls === 0) {
+        return `costDrift: no gateway-measured cost on any ledger row this period (${drift.totalCalls} call(s) in scope), so every $ above is rate-derived from this deployment's own price table. Measured cost is a GATEWAY feature — its absence is expected on a direct-provider deployment and is not a fault.`;
+    }
+    const pct = drift.divergencePct === undefined ? "n/a" : `${drift.divergencePct >= 0 ? "+" : ""}${drift.divergencePct.toFixed(1)}%`;
+    const direction = drift.divergenceUsd === 0 ? "agrees with" : drift.divergenceUsd > 0 ? "OVER-states" : "UNDER-states";
+    return (`costDrift: over the ${drift.measuredCalls} of ${drift.totalCalls} call(s) the gateway measured, it billed $${drift.measuredUsd.toFixed(4)} where this deployment's rate table derived $${drift.derivedUsd.toFixed(4)} ` +
+        `— the rate table ${direction} the bill by $${Math.abs(drift.divergenceUsd).toFixed(4)} (${pct}). The caps enforce the DERIVED figure, so a persistent divergence means the price table needs re-measuring (spend/pricing.ts), not that the caps are broken.`);
+}
+// --- routine cadence + cost prediction ----------------------------------------------
+// THE DISPATCHER FLOOR (OPE-146 / audit §S9). Whatever a trigger asks for, the dispatcher
+// evaluates the store once every DISPATCH_TICK_MINUTES and a routine is dispatched at most
+// ONCE per tick — so no routine can fire more than 1440/DISPATCH_TICK_MINUTES times a day.
+// The prediction used to read the trigger literally and over-count anything finer: an
+// `everyMinutes: 5` routine was projected at 288 fires/day against an actual ~144, i.e. a
+// 2× over-statement of its projected spend. Predictions are labelled estimates, but an
+// estimate that ignores a hard floor the same package enforces is just wrong.
+const MAX_FIRES_PER_DAY = 1440 / DISPATCH_TICK_MINUTES;
+function cronFiresPerDay(expr) {
+    try {
+        const parsed = parseCron(expr);
+        const start = new Date();
+        start.setUTCSeconds(0, 0);
+        // Count TICK WINDOWS containing at least one matching minute, not matching minutes: a
+        // `* * * * *` cron matches 1440 times but is dispatched once per tick. Windows are
+        // indexed off midnight so the count doesn't depend on when this happens to run.
+        const ticks = new Set();
+        for (let i = 0; i < 1440; i++) {
+            const t = new Date(start.getTime() + i * 60_000);
+            if (cronMatches(parsed, t))
+                ticks.add(Math.floor((t.getUTCHours() * 60 + t.getUTCMinutes()) / DISPATCH_TICK_MINUTES));
+        }
+        return ticks.size;
+    }
+    catch {
+        return undefined; // a malformed cron on a live routine — treat as unknowable, not a crash
+    }
+}
+/**
+ * Fires/day for a clock-scheduled trigger, or undefined when the cadence is
+ * unknowable for PREDICTION purposes. Per D6: `watch` re-evaluates on `everyMinutes`
+ * but posts only on a state DIFF, so how often it actually spends tokens isn't
+ * derivable from the schedule alone; `event` isn't clock-scheduled at all.
+ *
+ * Capped at the dispatcher's own tick floor (see {@link MAX_FIRES_PER_DAY}) — a cadence
+ * finer than the tick simply cannot be achieved, so predicting it would over-state spend.
+ */
+export function firesPerDay(trigger) {
+    switch (trigger.kind) {
+        case "interval":
+            return Math.min(MAX_FIRES_PER_DAY, 1440 / Math.max(1, trigger.everyMinutes));
+        case "cron":
+            return cronFiresPerDay(trigger.expr);
+        case "watch":
+        case "event":
+            return undefined;
+    }
+}
+const MIN_FIRES_FOR_PREDICTION = 3;
+/**
+ * Predict 7d/30d token (and $, if priced) spend per surface from routine-fired usage:
+ * avg tokens/fire (this window's historical average) × the surface's currently
+ * ACTIVE cron/interval cadence. ESTIMATES ONLY (label downstream) — skips a surface
+ * with fewer than MIN_FIRES_FOR_PREDICTION observed fires (not enough signal) or
+ * whose only routines are watch/event or inactive (cadence unknowable right now).
+ * `routineRows` should already be scoped (org/domain-filtered) usageSummary rows
+ * with kind === "routine".
+ */
+export async function buildRoutinePredictions(org, routineRows, pricing) {
+    const bySurface = new Map();
+    for (const r of routineRows) {
+        const acc = bySurface.get(r.surfaceKey) ?? { inputTokens: 0, outputTokens: 0, cacheReadTokens: 0, sessions: 0, rows: [] };
+        // Kept only to fold this surface's disclosure (OPE-1862) — see RoutinePredictionRow.
+        acc.rows.push(r);
+        acc.inputTokens += r.inputTokens;
+        acc.outputTokens += r.outputTokens;
+        acc.cacheReadTokens += r.cacheReadTokens;
+        // Routine fires rarely span multiple senders (routine.createdBy is audit-only,
+        // and the dispatched turn typically carries no per-turn human sender), so
+        // summing `sessions` across this surface's (principal,model) rows is a much
+        // safer approximation here than the general conversation-count problem
+        // approxConversationCount documents for live channel/dm traffic.
+        acc.sessions += r.sessions;
+        bySurface.set(r.surfaceKey, acc);
+    }
+    const store = getOperationalStore();
+    const out = [];
+    for (const [surfaceKey, acc] of bySurface) {
+        if (acc.sessions < MIN_FIRES_FOR_PREDICTION) {
+            out.push({
+                surfaceKey,
+                disclosure: foldDisclosure(acc.rows),
+                observedFires: acc.sessions,
+                avgTokensPerFire: acc.sessions > 0 ? (acc.inputTokens + acc.outputTokens) / acc.sessions : 0,
+                projected: null,
+                skippedReason: `fewer than ${MIN_FIRES_FOR_PREDICTION} observed fires in this window — not enough signal to predict`,
+            });
+            continue;
+        }
+        const avgTokensPerFire = (acc.inputTokens + acc.outputTokens) / acc.sessions;
+        const routines = await store.listRoutines(org, surfaceKey);
+        let cadence = 0;
+        let sawClockScheduled = false;
+        for (const routine of routines) {
+            if (routine.status !== "active")
+                continue;
+            const fpd = firesPerDay(routine.trigger);
+            if (fpd !== undefined) {
+                cadence += fpd;
+                sawClockScheduled = true;
+            }
+        }
+        if (!sawClockScheduled) {
+            out.push({
+                surfaceKey,
+                disclosure: foldDisclosure(acc.rows),
+                observedFires: acc.sessions,
+                avgTokensPerFire,
+                projected: null,
+                skippedReason: "no active cron/interval routine found for this surface — cadence unknowable (watch/event routines don't have a predictable fire rate)",
+            });
+            continue;
+        }
+        const avgInput = acc.inputTokens / acc.sessions;
+        const avgOutput = acc.outputTokens / acc.sessions;
+        const avgCacheRead = acc.cacheReadTokens / acc.sessions;
+        // 🔴 "aggregate", and the divisor is why. These are averages per FIRE — `acc.sessions` counts
+        // distinct sessions, not model calls — and one fire runs a whole session, which is many calls.
+        // So `avgInput` is a per-conversation total, not any prompt's size, and testing it against a
+        // per-call tier boundary would surcharge every routine whose FIRE totals 272,001 tokens across
+        // its turns (OPE-2055). A per-call average would have to divide by `events`, which this
+        // accumulator does not carry. The cost of withholding the tier here is an understated
+        // prediction for a routine that genuinely runs long prompts — stated, not silent.
+        const costPerFire = pricing ? estimateCostUsd({ inputTokens: avgInput, outputTokens: avgOutput, cacheReadTokens: avgCacheRead }, pricing, "aggregate") : undefined;
+        out.push({
+            surfaceKey,
+            disclosure: foldDisclosure(acc.rows),
+            observedFires: acc.sessions,
+            avgTokensPerFire,
+            cadencePerDay: cadence,
+            projected: {
+                tokens7d: avgTokensPerFire * cadence * 7,
+                tokens30d: avgTokensPerFire * cadence * 30,
+                ...(costPerFire !== undefined ? { costUsd7d: costPerFire * cadence * 7, costUsd30d: costPerFire * cadence * 30 } : {}),
+            },
+        });
+    }
+    return out;
+}
+/** The Slack member id embedded in a usage-row principal id, if any: a bare "U…"/"W…"
+ *  id, or the last segment of a composite "slack:T…:U…" / "slack:T…:bot:U…" principal. */
+export function slackUserIdIn(principalId) {
+    const candidate = principalId.includes(":") ? principalId.slice(principalId.lastIndexOf(":") + 1) : principalId;
+    return /^[UW][A-Z0-9]{5,}$/.test(candidate) ? candidate : undefined;
+}
+/** The Slack channel id in a fully-qualified surface key ("slack/T…/C…"), if any. */
+export function slackChannelIdIn(surfaceKey) {
+    const parts = surfaceKey.split("/");
+    if (parts[0] !== "slack" || parts.length < 3)
+        return undefined;
+    const id = parts[2];
+    return /^[CGD][A-Z0-9]{5,}$/.test(id) ? id : undefined;
+}
+/**
+ * Resolve display labels for a report's principal ids + surface keys in one pass,
+ * deduplicated, all lookups concurrent, every failure silently unlabelled. DMs ("D…"
+ * ids) get no conversations.info name — they stay unlabelled by design.
+ */
+export async function resolveSlackLabels(principalIds, surfaceKeys, deps) {
+    const users = new Map();
+    const channels = new Map();
+    const lookups = [];
+    for (const pid of new Set(principalIds)) {
+        const userId = slackUserIdIn(pid);
+        if (!userId)
+            continue;
+        lookups.push(deps
+            .userName(userId)
+            .then((name) => {
+            if (name)
+                users.set(pid, name);
+        })
+            .catch(() => { }));
+    }
+    for (const key of new Set(surfaceKeys)) {
+        const channelId = slackChannelIdIn(key);
+        if (!channelId || channelId.startsWith("D"))
+            continue;
+        lookups.push(deps
+            .channelName(channelId)
+            .then((name) => {
+            if (name)
+                channels.set(key, `#${name}`);
+        })
+            .catch(() => { }));
+    }
+    await Promise.all(lookups);
+    return { users, channels };
+}
+// --- usage_report aggregations -------------------------------------------------------
+/**
+ * "How many conversations happened" from grouped usageSummary rows. APPROXIMATE, not
+ * exact: usageSummary groups by (surfaceKey, principalId, kind, surfaceMode, model), and a single
+ * session's turns CAN carry different principalIds (per-turn caller identity is
+ * rewritten every turn — ground truth in the build plan), so summing `sessions`
+ * across a surface's principal-groups can double-count a session touched by more
+ * than one sender. There is no query that recovers the true distinct count from
+ * already-grouped data (it would need the raw per-event rows) — this is the
+ * documented, honestly-labelled approximation. kind==="sandbox" rows are excluded:
+ * they share a session_id with a real conversation-kind row and would double-count it
+ * on top of the principal-split issue.
+ */
+export function approxConversationCount(rows) {
+    let total = 0;
+    for (const r of rows) {
+        if (r.kind === "sandbox")
+            continue;
+        total += r.sessions;
+    }
+    return total;
+}
+/** Per-user activity (events + tokens), excluding sandbox rows and rows with no
+ *  resolved principal. Summing `events` (a plain row count) across groups is exact —
+ *  unlike `sessions` (a distinct count), it can't be double-counted by re-grouping. */
+export function aggregateByUser(rows) {
+    const byUser = new Map();
+    for (const r of rows) {
+        if (r.kind === "sandbox" || !r.principalId)
+            continue;
+        const acc = byUser.get(r.principalId) ?? { principalId: r.principalId, events: 0, inputTokens: 0, outputTokens: 0 };
+        byUser.set(r.principalId, {
+            principalId: r.principalId,
+            events: acc.events + r.events,
+            inputTokens: acc.inputTokens + r.inputTokens,
+            outputTokens: acc.outputTokens + r.outputTokens,
+        });
+    }
+    return [...byUser.values()].sort((a, b) => b.events - a.events);
+}
+/** Busiest-surfaces breakdown (events + tokens exact; sessions approximate — see
+ *  approxConversationCount), excluding sandbox rows. Sorted busiest-first. */
+export function aggregateBySurface(rows) {
+    const bySurface = new Map();
+    for (const r of rows) {
+        if (r.kind === "sandbox")
+            continue;
+        const acc = bySurface.get(r.surfaceKey) ?? { surfaceKey: r.surfaceKey, events: 0, sessions: 0, inputTokens: 0, outputTokens: 0 };
+        bySurface.set(r.surfaceKey, {
+            surfaceKey: r.surfaceKey,
+            events: acc.events + r.events,
+            sessions: acc.sessions + r.sessions,
+            inputTokens: acc.inputTokens + r.inputTokens,
+            outputTokens: acc.outputTokens + r.outputTokens,
+        });
+    }
+    return [...bySurface.values()].sort((a, b) => b.events - a.events);
+}
+//# sourceMappingURL=reporting.js.map