toolroll 0.9.104 → 0.9.105

package/dist/route-rules.js

@@ -1,17 +1,3 @@
-/**
- * Earned rules (docs/plans/results-routing.md, slice 2): suggesting a cheaper model from a project's own result
- * records, accepting it as a rule with a bounded switch-back grant, and the rule switching itself off when its sealed
- * terms trip. A rule is a separate layer: it never edits the owner's Models rows, and it routes only through the one
- * precedence order (phase-routing.ts selectBuildLeg). Every task is still approved, and its route stays sealed.
- *
- * Doors (Authority): accepting, keeping a paused rule and switching suggestions on take a person with a step-up;
- * turning a rule off, dropping a paused one, Not now and switching suggestions off also take this computer's local
- * owner inside exactly that act. A lead token or a remote API token is refused. The writer (route-store.ts) re-proves
- * the door inside the write's transaction.
- *
- * A policy path (release-auto.ts EVAL_POLICY): the thresholds, the grant's terms and the trigger decide when a model
- * routes and when it stops, so a change here needs a person.
- */
 import { createHash } from "node:crypto";
 import { INSTALLATION_SCOPE } from "./agentconfig.js";
 import { canonicalJson } from "./canonical-json.js";
@@ -21,13 +7,9 @@ import { seenModel, seenModels } from "./model-catalog.js";
 import { exactModelId, legOf, routeFromJson } from "./phase-routing.js";
 import { endRuleByDoor, endRuleByPlane, endTrialByDoor, insertEarnedRule, insertTrial, keepPausedRule, liveEarnedRules, liveTrialFor, modelsGenerationOf, proveRuleDoor, recordNotNow, ruleHoldOf, trialOrdinalOf, trialPlaceLive, trialPlacesOf, writeSuggestModels, } from "./route-store.js";
 import { BUILT_IN } from "./store.js";
-// ---- the terms ----------------------------------------------------------------------------------------------------
-/** The policy version a grant is sealed under: a grant sealed under another version pauses its rule. */
 export const ROUTING_POLICY_VERSION = 1;
 const DAY = 24 * 60 * 60_000;
-/** When to suggest (Suggest and trigger terms): records of the last 90 days, the newest 20 decided. */
 export const SUGGEST_TERMS = Object.freeze({ windowDays: 90, newest: 20, minDecided: 10, minMature: 0.9, lastClean: 3, configuredGap: 0.05, maxNotCounted: 1 / 3 });
-/** How long a grant lasts, how long Not now keeps a suggestion quiet, and when Needs you says a grant ends soon. */
 export const GRANT_DAYS = 90;
 export const NOT_NOW_DAYS = 30;
 export const EXPIRY_WARNING_DAYS = 7;
@@ -49,7 +31,6 @@ function readGrant(json) {
         return null;
     }
 }
-/** The switch-back terms in words, as the review shows them before acceptance and Settings after. */
 export function grantWords(grant) {
     return [
         `It switches itself off if ${grant.reject.max + 1} of the latest ${grant.reject.window} decided tasks are rejected,`,
@@ -81,20 +62,15 @@ export function ruleById(store, id) {
     const row = store.handle.prepare("SELECT * FROM route_rule WHERE id = ?").get(id);
     return row === undefined ? null : readRule(row);
 }
-/** A project's rules a person sees: the live ones (active, paused) and, for 30 days, the ones that ended (a Not now
- * offer is not a rule and is left out). */
 export function rulesOf(store, repo, now) {
     return store.handle.prepare(`SELECT * FROM route_rule WHERE repo = ? AND kind = 'rule' AND COALESCE(end_reason, '') != 'not-now'
       AND (state IN ('active','trialling','paused') OR ended_at >= ?) ORDER BY cohort_size, id DESC`)
         .all(repo, new Date(now.getTime() - NOT_NOW_DAYS * DAY).toISOString()).map(readRule);
 }
-/** Whether a project offers suggestions (its "Suggest cheaper models" switch; a project not saved here reads on). */
 export function suggestModelsOn(store, repo) {
     const row = store.handle.prepare("SELECT suggest_models FROM project WHERE path = ?").get(repo);
     return row === undefined || Number(row["suggest_models"]) === 1;
 }
-/** The configuration generations a rule for this project depends on: the installation's and the project's build and
- * repair rows. */
 export function dependsOf(store, repo) {
     const out = {};
     for (const scope of [INSTALLATION_SCOPE, repo])
@@ -102,7 +78,6 @@ export function dependsOf(store, repo) {
             out[`${scope}|${phase}`] = modelsGenerationOf(store, scope, phase);
     return out;
 }
-/** A cohort's records of one model, newest first (by their family's first code-writing run, then task id). */
 function cohortRecords(store, repo, size, provider, model, since) {
     return store.handle.prepare(`SELECT t.external_id AS task, r.state, r.reason, r.first_started_at, r.api_microusd, r.unknown_runs, r.subscription_runs
       FROM route_record r JOIN task_ref t ON t.id = r.task_ref
@@ -133,13 +108,11 @@ function pricesOf(store, provider, model) {
     const seen = seenModel(store, "claude", model);
     return seen === null || seen.inputUsd === null || seen.outputUsd === null ? null : { in: seen.inputUsd, out: seen.outputUsd };
 }
-/** The model's own name when the catalog knows it ("Claude Haiku 5.5"), else its id. */
 export function modelName(store, model) {
     return seenModel(store, "claude", model)?.name ?? model;
 }
 const short = (value) => createHash("sha256").update(canonicalJson(value)).digest("hex").slice(0, 12);
 const sizeWord = (size) => size === "small" ? "small" : "routine";
-/** One cohort's configured builder now (the configured rows alone, never a rule), or null when it can't be read. */
 function configuredBuilder(store, repo, size) {
     const routes = effectiveRoutes(store, repo, { rules: false });
     if (!routes.ok)
@@ -148,8 +121,6 @@ function configuredBuilder(store, repo, size) {
     const leg = route === undefined ? null : legOf(route, "build");
     return leg === null ? null : { provider: leg.provider, model: leg.model };
 }
-/** What an offer for this cohort and model would say now, whether or not it qualifies: the parts its digests bind,
- * and why it doesn't qualify (null: it does). */
 export function offerNow(store, repo, size, model, now) {
     const configured = configuredBuilder(store, repo, size);
     if (configured === null)
@@ -188,22 +159,16 @@ export function offerNow(store, repo, size, model, now) {
         why: null, parts,
     };
 }
-/** A suggestion id read back: its cohort, model and the three digest prefixes it was offered under. */
 export function readSuggestionId(id) {
     const match = /^(small|medium):([A-Za-z0-9][A-Za-z0-9._/-]{0,127}):([0-9a-f]{12})$/.exec(id);
     if (match === null)
         return null;
     return { size: match[1], model: match[2], evidence: match[3].slice(0, 4), prices: match[3].slice(4, 8), depends: match[3].slice(8, 12) };
 }
-/** Whether a Not now on this cohort and model is still within its 30 days. */
 function notNowStands(store, repo, size, model, now) {
     return store.handle.prepare(`SELECT 1 FROM route_rule WHERE repo = ? AND cohort_size = ? AND model = ? AND state = 'dropped' AND end_reason = 'not-now' AND ended_at > ? LIMIT 1`)
         .get(repo, size, model, new Date(now.getTime() - NOT_NOW_DAYS * DAY).toISOString()) !== undefined;
 }
-/**
- * The suggestions a project offers now: per size (small, routine), the cheapest Claude model whose records here earn
- * it, unless a rule for that size is live, the project's switch is off, or a person said Not now within 30 days.
- */
 export function suggestionsFor(store, repo, now) {
     if (!suggestModelsOn(store, repo))
         return [];
@@ -221,7 +186,6 @@ export function suggestionsFor(store, repo, now) {
     }
     return out;
 }
-/** A suggestion in plain words, the evidence first. */
 export function suggestionWords(suggestion) {
     const e = suggestion.evidence;
     return `${suggestion.name} for ${sizeWord(suggestion.cohortSize)} tasks instead of ${suggestion.configured.name}: ${e.mature} of the last ${e.decided} decided similar tasks were accepted with checks passing${notCountedWords(e)}.`;
@@ -252,7 +216,6 @@ class Refused extends Error {
         this.refusal = refusal;
     }
 }
-/** One door act in one transaction, with a savepoint so a refusal rolls back its writes even inside a caller's. */
 function act(store, body) {
     try {
         return store.transact(() => {
@@ -282,12 +245,6 @@ function prove(store, door, which, repo) {
     return proved.door;
 }
 const known = (store, repo) => store.knownRepos().includes(repo) || store.handle.prepare("SELECT 1 FROM project WHERE path = ?").get(repo) !== undefined;
-/**
- * Accept a suggestion as a rule, in one transaction: the person re-proved; the offer still earned, at the same
- * prices and on the same configuration generations it was offered under; the configuration valid with the rule
- * added (checkScope); and the size's one winner free. A refusal names which: `stale-suggestion`, `price-changed`,
- * `config-changed`, `invalid` or `taken`.
- */
 export function acceptSuggestion(store, input, door, now) {
     return act(store, () => {
         if (!known(store, input.repo))
@@ -319,7 +276,6 @@ export function acceptSuggestion(store, input, door, now) {
         return { ok: true, rule, suggestion };
     });
 }
-/** Turn a live rule off, or drop a paused one. Tasks already approved keep the model they were approved with. */
 export function turnOffRule(store, ruleId, door, now) {
     return act(store, () => {
         const rule = ruleById(store, ruleId);
@@ -334,7 +290,6 @@ export function turnOffRule(store, ruleId, door, now) {
         return { ok: true, rule: ruleById(store, rule.id) };
     });
 }
-/** Keep a paused rule: live again on the configuration as it stands, if that configuration can run it. */
 export function keepRule(store, ruleId, door, now) {
     return act(store, () => {
         const rule = ruleById(store, ruleId);
@@ -359,7 +314,6 @@ export function keepRule(store, ruleId, door, now) {
         return { ok: true, rule: ruleById(store, rule.id) };
     });
 }
-/** Not now: the suggestion stays quiet for 30 days. */
 export function dismissSuggestion(store, input, door, now) {
     return act(store, () => {
         if (!known(store, input.repo))
@@ -374,7 +328,6 @@ export function dismissSuggestion(store, input, door, now) {
         return { ok: true };
     });
 }
-/** A project's "Suggest cheaper models" switch: on takes a person's step-up, off also the local owner. */
 export function setSuggestModels(store, repo, on, door) {
     return act(store, () => {
         const proved = prove(store, door, on ? "suggest-on" : "suggest-off", repo);
@@ -383,8 +336,6 @@ export function setSuggestModels(store, repo, on, door) {
         return { ok: true };
     });
 }
-/** Whether a grant's sealed terms trip on these decided records (newest first) and closed exposures (newest first,
- * true = approved with another model). Pure. Pending and provisional records are never passed in. */
 export function tripOf(grant, decided, exposures) {
     const rejected = decided.slice(0, grant.reject.window).filter(one => one === "rejected").length;
     if (rejected > grant.reject.max)
@@ -400,8 +351,6 @@ export function tripOf(grant, decided, exposures) {
         return { trips: true, why: `${declined} of the latest ${Math.min(grant.declined.window, exposures.length)} approvals picked another model` };
     return { trips: false };
 }
-/** The evidence a rule's trigger reads: its model's decided records in its cohort since the grant's cutoff, and its
- * closed exposures, both newest first and in a fixed order. */
 function triggerInputs(store, rule, grant) {
     const decided = decidedOf(cohortRecords(store, rule.repo, rule.cohortSize, rule.provider, rule.model, grant.cutoff)).map(one => one.state);
     const exposures = store.handle.prepare(`SELECT e.id, (SELECT kind FROM route_exposure_event c WHERE c.exposure = e.id AND c.kind IN ('approved-as-proposed','approved-with-other','cancelled') ORDER BY c.id LIMIT 1) AS closer,
@@ -410,13 +359,6 @@ function triggerInputs(store, rule, grant) {
         .map(row => row["closer"] === "approved-with-other");
     return { decided, exposures };
 }
-/**
- * One rule's check, as ONE transaction: re-read the rule and its generation; any configuration generation it depends
- * on that moved pauses it (never a switch-off on terms it no longer has); an ended grant ends it, a grant sealed under
- * another policy or by an account that's gone pauses it; then the trigger, recomputed from records with the sealed
- * terms, switches it off by compare-and-swap on its generation — and the configuration is checked without it, or the
- * switch-off rolls back and the rule pauses instead.
- */
 export function switchOffIfTripped(store, ruleId, now) {
     return store.transact(() => {
         const rule = ruleById(store, ruleId);
@@ -458,8 +400,6 @@ export function switchOffIfTripped(store, ruleId, now) {
         return { outcome: "switched-off", why: trip.why };
     });
 }
-// ---- the pass, held tasks, Needs you -------------------------------------------------------------------------------
-/** The selection a stored route's build leg carries (route v3), or undefined. */
 function selectionOf(json) {
     const route = typeof json === "string" ? routeFromJson(json) : null;
     return route === null ? undefined : legOf(route, "build").selection;
@@ -472,19 +412,10 @@ function resolveRuleNotices(store, ruleId, now) {
     store.handle.prepare("UPDATE notification SET resolved_at = ? WHERE kind = 'routing' AND resolved_at IS NULL AND (dedupe_key LIKE ? OR dedupe_key LIKE ?)")
         .run(now.toISOString(), `route-rule-paused:${ruleId}:%`, `route-rule-expiring:${ruleId}`);
 }
-/** Hold a task approved under a rule that switched itself off: nothing starts on it (no strike: nothing ran) until a
- * person approves it again — the hold goes with that yes (store.ts sealScopeApproval). */
 export function holdRuleOff(store, taskRef, taskId, model, now) {
     const name = modelName(store, model);
     store.holdOwned({ taskRef, ownerKind: "backoff", ownerId: `rule-off:${taskRef}`, reason: `Results for ${name} dropped after you approved this. Approve it again or re-file it.`, until: null }, now);
 }
-/**
- * The reconcile pass's routing step (operate.ts, after the records are evaluated again): each live rule checked
- * against its sealed terms; Needs you told about a rule that switched off, paused or ends soon; tasks approved under a
- * switched-off rule held, with their plans re-filed on the configured builder so a person can approve them again; and
- * plans still waiting for approval under a rule that is no longer live re-filed the same way. Each task is its own
- * transaction; one that can't be re-filed now (a live claim) is tried again next pass.
- */
 export function routeRulesPass(store, repo, now) {
     const counts = { switchedOff: 0, paused: 0, held: 0, refiled: 0 };
     for (const rule of rulesOf(store, repo, now).filter(one => one.state === "active")) {
@@ -506,13 +437,11 @@ export function routeRulesPass(store, repo, now) {
         if (rule.state === "expired")
             notify(store, repo, `route-rule-expired:${rule.id}`, `${name} for ${sizeWord(rule.cohortSize)} tasks ended`, "Its 90 days are over. These tasks build on the configured model again; tasks already approved keep their model.", now);
     }
-    // Trials (slice 3): one past its days ends; tasks already approved on it keep their place and model.
     for (const trial of trialsOf(store, repo, now).filter(one => one.state === "trialling" || one.state === "paused")) {
         const expires = trialExpiry(store, trial);
         if (expires === null || expires <= now.getTime())
             endRuleByPlane(store, trial.id, trial.generation, "expired", "trial-ended", now);
     }
-    // Tasks under a rule that is no longer live, and plans waiting on a trial place that no longer stands.
     const live = new Set(liveEarnedRules(store, repo).map(one => one.id));
     const rows = store.handle.prepare(`SELECT ts.task_id, tr.id AS ref, ts.proposed_route_json, ts.approved_route_json, ts.approved_digest, ts.digest
       FROM task_scope ts JOIN task_ref tr ON tr.backend = ? AND tr.external_id = ts.task_id JOIN task t ON t.id = ts.task_id
@@ -539,16 +468,10 @@ export function routeRulesPass(store, repo, now) {
                     counts.refiled++;
             });
         }
-        catch { /* the next pass tries again */ }
+        catch { }
     }
     return counts;
 }
-// ---- what the person sees ------------------------------------------------------------------------------------------
-/**
- * The evidence line beside a route whose build leg an earned rule selected (approval sheet, approval step, chat side
- * panel, text card), or null for any other route. The selection is sealed; the counts read "so far", from the
- * records as they stand.
- */
 export function selectionEvidenceWords(store, route, now) {
     if (route === null)
         return null;
@@ -570,7 +493,6 @@ export function selectionEvidenceWords(store, route, now) {
     const state = rule.state === "active" ? "" : rule.state === "switched-off" ? ` This rule switched itself off since: approve again after re-filing, or change the builder.` : ` This rule is ${rule.state === "paused" ? "paused" : "off"} now; approving keeps ${name}.`;
     return `Why this model: ${name} builds ${sizeWord(rule.cohortSize)} tasks in this project. ${counts}${cost}${state}`;
 }
-/** The evidence line for a task's proposed (or, once approved, sealed) route. */
 export function taskEvidenceWords(store, taskId, now) {
     try {
         const row = store.handle.prepare("SELECT proposed_route_json, approved_route_json, approved_digest, digest FROM task_scope WHERE task_id = ?").get(taskId);
@@ -583,7 +505,6 @@ export function taskEvidenceWords(store, taskId, now) {
         return null;
     }
 }
-/** A rule in words for Settings and the command line. */
 export function ruleWords(store, rule) {
     const name = modelName(store, rule.model);
     const what = `${name} builds ${sizeWord(rule.cohortSize)} tasks instead of ${rule.configured.model === null ? "the configured model" : modelName(store, rule.configured.model)}`;
@@ -597,17 +518,10 @@ export function ruleWords(store, rule) {
         return `${what}: ended on ${rule.endedAt?.slice(0, 10) ?? "?"}.`;
     return `${what}: turned off${rule.endedBy === null ? "" : ` by ${rule.endedBy}`} on ${rule.endedAt?.slice(0, 10) ?? "?"}.`;
 }
-// ---- trials (slice 3) ------------------------------------------------------------------------------------------------
-/** When to offer a trial (docs/plans/results-routing.md, "Trials"): the configured Claude builder of a cohort has at
- * least 10 decided records here at ≥ 90% accepted with checks passing, and a cheaper Claude model has too few results
- * here to be suggested on its own. A trial tries it on the next 10 eligible tasks, each approved by a person. */
 export const TRIAL_TERMS = Object.freeze({ places: 10, configuredMinDecided: 10, configuredMinMature: 0.9, days: 90 });
-/** A trial offer's id read back: its cohort, model and the three digest prefixes it was offered under. */
 export function readTrialOfferId(id) {
     return id.startsWith("trial:") ? readSuggestionId(id.slice("trial:".length)) : null;
 }
-/** What a trial offer for this cohort and model would say now, whether or not it qualifies: the parts its digests
- * bind, and why it doesn't qualify (null: it does). */
 export function trialOfferNow(store, repo, size, model, now) {
     const configured = configuredBuilder(store, repo, size);
     if (configured === null)
@@ -646,11 +560,6 @@ export function trialOfferNow(store, repo, size, model, now) {
         why: null, parts,
     };
 }
-/**
- * The trials a project offers now: per size, where nothing is suggested (a suggestion has enough evidence to stand on
- * its own) and no rule or trial is live, the closest cheaper Claude model the catalog lists now (the dearest of those
- * cheaper on both prices, then the newest), unless the project's switch is off or a person said Not now to it.
- */
 export function trialOffersFor(store, repo, now) {
     if (!suggestModelsOn(store, repo))
         return [];
@@ -669,18 +578,15 @@ export function trialOffersFor(store, repo, now) {
     }
     return out;
 }
-/** A trial offer in plain words, the evidence first. */
 export function trialOfferWords(offer) {
     const c = offer.configuredEvidence, e = offer.evidence;
     const own = e.decided === 0 ? `${offer.name} has no decided tasks here yet` : `${offer.name} has ${e.decided} decided task${e.decided === 1 ? "" : "s"} here so far; ${SUGGEST_TERMS.minDecided} are needed to suggest it`;
     return `${offer.configured.name} does well on ${sizeWord(offer.cohortSize)} tasks here (${c.mature} of the last ${c.decided} accepted with checks passing). ${own}. Try it on the next ${offer.places}; a person approves each one.`;
 }
-/** A project's trials a person sees: live (trialling, paused) and, for 30 days, the ones that ended. */
 export function trialsOf(store, repo, now) {
     return store.handle.prepare(`SELECT * FROM route_rule WHERE repo = ? AND kind = 'trial' AND (state IN ('trialling','paused') OR ended_at >= ?) ORDER BY cohort_size, id DESC`)
         .all(repo, new Date(now.getTime() - NOT_NOW_DAYS * DAY).toISOString()).map(readRule);
 }
-/** When a trial's days end, from its sealed grant; null when that can't be read (it then ends: fail closed). */
 function trialExpiry(store, trial) {
     try {
         const grant = JSON.parse(String(store.handle.prepare("SELECT grant_json FROM route_rule WHERE id = ?").get(trial.id)?.["grant_json"]));
@@ -691,12 +597,6 @@ function trialExpiry(store, trial) {
         return null;
     }
 }
-/**
- * Start a trial, in one transaction: the person re-proved (a step-up); the offer still standing, at the same prices
- * and on the same configuration generations it was offered under, with its eligibility re-checked now (a stale
- * offer refuses); the configuration valid with the trial's builder added (checkScope: repairs resume its session);
- * and the size's one winner free (concurrent starts: one wins). A refusal names which.
- */
 export function startTrial(store, input, door, now) {
     return act(store, () => {
         if (!known(store, input.repo))
@@ -730,8 +630,6 @@ export function startTrial(store, input, door, now) {
         return { ok: true, trial, offer };
     });
 }
-/** Stop a live or paused trial. Plans waiting on it are re-filed on the configured builder; tasks a person already
- * approved on it keep that model. */
 export function stopTrial(store, trialId, door, now) {
     return act(store, () => {
         const trial = ruleById(store, trialId);
@@ -746,7 +644,6 @@ export function stopTrial(store, trialId, door, now) {
         return { ok: true, trial: ruleById(store, trial.id) };
     });
 }
-/** A trial's progress in words, as Settings, the command line and chat say it. */
 export function trialWords(store, trial) {
     const name = modelName(store, trial.model);
     const places = trialPlacesOf(store, trial.id);
@@ -763,7 +660,6 @@ export function trialWords(store, trial) {
         return `Trying ${name} on ${sizeWord(trial.cohortSize)} tasks ended on ${trial.endedAt?.slice(0, 10) ?? "?"} after ${places.consumed} of ${places.limit}.`;
     return `Trying ${name} on ${sizeWord(trial.cohortSize)} tasks: stopped${trial.endedBy === null ? "" : ` by ${trial.endedBy}`} on ${trial.endedAt?.slice(0, 10) ?? "?"} after ${places.consumed} of ${places.limit}.`;
 }
-/** The evidence line for a build leg a trial selected: which model, and which trial task this is ("trial 3 of 10"). */
 function trialEvidenceWords(store, selection) {
     const trial = ruleById(store, selection.rule);
     if (trial === null || trial.kind !== "trial")
@@ -774,7 +670,6 @@ function trialEvidenceWords(store, selection) {
     const state = trial.state === "trialling" || trial.state === "finished" ? "" : ` The trial is ${trial.state === "paused" ? "paused" : "over"} now; approving keeps ${name}.`;
     return `Trying a cheaper model: ${name}, ${which}. A person approves each trial task; you can pick another model before approving.${state}`;
 }
-/** The project's live trial for a size, as Settings reads it (null when none). */
 export function liveTrialOf(store, repo, size) {
     const live = liveTrialFor(store, repo, size);
     return live === null ? null : ruleById(store, live.id);

package/dist/route-savings.js

@@ -1,32 +1,10 @@
-/**
- * What earned rules and trials observed (docs/plans/results-routing.md, slice 4): the Spend page's "Suggestions and
- * rules" block and the matching lines of `toolroll spend [--json]`. Read-only: it reads saved result records and rules,
- * and never suggests, accepts, routes or switches anything.
- *
- * For each project and size, each live or recently ended rule or trial (and each standing suggestion) compares two
- * sides over matched 90-day windows:
- * - a rule or trial: the configured model's results in the 90 days before it was accepted, against the results built
- *   under that rule or trial (their sealed selection names it) in the 90 days from acceptance, to its end or now;
- * - a suggestion: the configured model's results and the cheaper model's, over the same last 90 days.
- *
- * Cost rules (item 10): API dollars, plan usage and unknown cost are kept apart and never added together. The median is
- * of API dollars a task over results priced wholly in API dollars, with "API-priced N of M" beside it; it is hidden
- * (null, shown "—") unless each side has at least 5 such results. A result's spending includes its revision and repair
- * runs (remediation). Prices are the snapshot sealed at acceptance (a suggestion's are the listed prices now). Unknown
- * is never $0. The label is "observed, not a promise".
- */
 import { modelName, rulesOf, suggestionsFor, trialsOf } from "./route-rules.js";
 import { selectionSchema } from "./contracts/route-results.js";
 const DAY = 24 * 60 * 60_000;
-/** The window on each side, the priced results each side needs before a median shows, and when an open result's
- * last evaluation reads as stale. */
 export const SAVINGS_TERMS = Object.freeze({ windowDays: 90, minPriced: 5, staleAfterHours: 24 });
 export const SAVINGS_LABEL = "observed, not a promise";
-// ---- the figures (pure) --------------------------------------------------------------------------------------------
 const ANSWERED = new Set(["provisional", "mature", "rejected"]);
-/** Whether a result was priced wholly in API dollars: no plan run, no unknown run, and a recorded charge. */
 export const apiPriced = (one) => one.unknownRuns === 0 && one.subscriptionRuns === 0 && one.apiMicrousd > 0;
-/** The median of whole micro-dollars, rounded; null for none. */
 export function medianOf(values) {
     if (values.length === 0)
         return null;
@@ -34,7 +12,6 @@ export function medianOf(values) {
     const mid = Math.floor(sorted.length / 2);
     return sorted.length % 2 === 1 ? sorted[mid] : Math.round((sorted[mid - 1] + sorted[mid]) / 2);
 }
-/** One side's figures from its records. The median is computed here, and hidden by `compare` when either side is short. */
 export function sideOf(who, window, records) {
     const answered = records.filter(one => ANSWERED.has(one.state));
     const priced = answered.filter(apiPriced);
@@ -50,19 +27,15 @@ export function sideOf(who, window, records) {
         remediationRuns: answered.reduce((sum, one) => sum + one.remediationRuns, 0),
     };
 }
-/** Two sides compared: both medians show only when each side has enough API-priced results; otherwise neither does. */
 export function compare(configured, cheaper) {
     const enough = configured.apiPriced >= SAVINGS_TERMS.minPriced && cheaper.apiPriced >= SAVINGS_TERMS.minPriced;
     return enough ? { configured, cheaper, enough } : { configured: { ...configured, medianApiMicrousd: null }, cheaper: { ...cheaper, medianApiMicrousd: null }, enough };
 }
-// ---- words -----------------------------------------------------------------------------------------------------------
-/** Dollars a task: under a cent reads "<$0.01", never a false $0. */
 export const dollars = (microusd) => microusd > 0 && microusd < 10_000 ? "<$0.01" : `$${(microusd / 1_000_000).toFixed(2)}`;
 const each = (n, one, many = `${one}s`) => `${n} ${n === 1 ? one : many}`;
 const sizeWord = (size) => size === "small" ? "small" : "routine";
 const day = (iso) => iso.slice(0, 10);
 const perMillion = (n) => `$${Number.isInteger(n) ? n : n.toFixed(2)}`;
-/** A side's figures in words: the median (or —), then API-priced, plan usage and unknown cost, each apart. */
 export function sideWords(side) {
     return {
         median: side.medianApiMicrousd === null ? "—" : dollars(side.medianApiMicrousd),
@@ -74,14 +47,12 @@ export function sideWords(side) {
         ],
     };
 }
-/** The listed prices in words, per million tokens. */
 export function pricesWords(row) {
     if (row.prices === null)
         return "Listed prices: not recorded.";
     const p = row.prices;
     return `${row.pricesFrom === "accepted" ? "Listed prices when accepted" : "Listed prices now"}, per million tokens in / out: ${row.cheaper.name} ${perMillion(p.model.in)} / ${perMillion(p.model.out)}, ${row.configured.name} ${perMillion(p.configured.in)} / ${perMillion(p.configured.out)}.`;
 }
-/** What not having enough priced results means, in words. */
 export function notEnoughWords(row) {
     return `Not enough priced results yet: ${row.cheaper.apiPriced} and ${row.configured.apiPriced}; ${SAVINGS_TERMS.minPriced} on each side are needed before a median shows.`;
 }
@@ -90,7 +61,6 @@ const STATUS_WORDS = {
     expired: "Ended", dropped: "Dropped", finished: "Trial finished", suggested: "Suggested",
 };
 export const statusWords = (state) => STATUS_WORDS[state] ?? state;
-/** The row's own lines, as the command line prints them. */
 export function rowLines(row) {
     const sideLine = (label, side) => {
         const words = sideWords(side);
@@ -105,7 +75,6 @@ export function rowLines(row) {
         `    ${pricesWords(row)}`,
     ];
 }
-/** The spend report's lines for this block: a heading and each row, or one line when there is nothing yet. */
 export function savingsLines(report) {
     if ("error" in report)
         return ["  Suggestions and rules can't be read right now."];
@@ -139,7 +108,6 @@ function recordsOf(store, repo, size, from, to) {
 const underRuleOrTrial = (one) => one.selections.some(s => s.kind === "rule" || s.kind === "trial");
 const projectName = (repo) => repo.split("/").filter(Boolean).pop() ?? repo;
 const iso = (ms) => new Date(ms).toISOString();
-/** A rule's or trial's two sides: the configured model before acceptance, and its own results after. */
 function ruleRow(store, rule, now, seen) {
     const accepted = Date.parse(rule.acceptedAt);
     const window = SAVINGS_TERMS.windowDays * DAY;
@@ -148,7 +116,6 @@ function ruleRow(store, rule, now, seen) {
     const afterWindow = { from: iso(accepted), to: iso(Math.max(accepted, end)) };
     const before = recordsOf(store, rule.repo, rule.cohortSize, beforeWindow.from, beforeWindow.to)
         .filter(one => one.provider === rule.configured.provider && one.model === rule.configured.model && !underRuleOrTrial(one));
-    // The results built under this rule or trial: their sealed selection names it.
     const after = recordsOf(store, rule.repo, rule.cohortSize, afterWindow.from, afterWindow.to)
         .filter(one => one.selections.some(s => (s.kind === "rule" || s.kind === "trial") && s.rule === rule.id));
     seen.push(...before, ...after);
@@ -158,7 +125,6 @@ function ruleRow(store, rule, now, seen) {
         ...compared, prices: rule.prices, pricesFrom: "accepted", words: [] };
     return { ...row, words: rowLines(row) };
 }
-/** A project's rows: its rules and trials (live, and those that ended in the last 30 days), then what it suggests now. */
 function projectRows(store, repo, now, seen) {
     const rows = [...rulesOf(store, repo, now), ...trialsOf(store, repo, now)].map(rule => ruleRow(store, rule, now, seen));
     const window = { from: iso(now.getTime() - SAVINGS_TERMS.windowDays * DAY), to: now.toISOString() };
@@ -174,7 +140,6 @@ function projectRows(store, repo, now, seen) {
     const order = (one) => (one.kind === "suggestion" ? 2 : ["active", "trialling", "paused"].includes(one.state) ? 0 : 1);
     return rows.sort((a, b) => (a.size === b.size ? 0 : a.size === "small" ? -1 : 1) || order(a) - order(b) || Number(b.id) - Number(a.id));
 }
-/** The block for these projects, by project then size. */
 export function savingsReport(store, repos, now) {
     const seen = [];
     const rows = [...new Set(repos)].sort((a, b) => projectName(a).localeCompare(projectName(b)) || a.localeCompare(b)).flatMap(repo => projectRows(store, repo, now, seen));
@@ -182,7 +147,6 @@ export function savingsReport(store, repos, now) {
     const stale = seen.filter(one => !one.closed && Date.parse(one.evaluatedAt) < staleBefore).map(one => one.evaluatedAt).sort();
     return { label: SAVINGS_LABEL, windowDays: SAVINGS_TERMS.windowDays, minPriced: SAVINGS_TERMS.minPriced, rows, staleSince: stale[0] ?? null };
 }
-/** The block, or that it can't be read: an unreadable block never fails the Spend page or `toolroll spend`. */
 export function savingsReportOrError(store, repos, now) {
     try {
         return savingsReport(store, repos, now);