toolroll 0.9.90 → 0.9.92

package/dist/route-savings.d.ts

@@ -0,0 +1,136 @@
+/**
+ * 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 { type Prices } from "./route-rules.js";
+import type { Store } from "./store.js";
+/** 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 declare const SAVINGS_TERMS: Readonly<{
+    windowDays: 90;
+    minPriced: 5;
+    staleAfterHours: 24;
+}>;
+export declare const SAVINGS_LABEL = "observed, not a promise";
+/** One result record as this view reads it. */
+export type SavingsRecord = {
+    state: string;
+    firstStartedAt: string;
+    apiMicrousd: number;
+    subscriptionRuns: number;
+    subscriptionTokens: number;
+    unknownRuns: number;
+    remediationRuns: number;
+    closed: boolean;
+    evaluatedAt: string;
+};
+/** One side of a comparison. Every amount kind is counted on its own. */
+export type SavingsSide = {
+    provider: string;
+    model: string | null;
+    name: string;
+    /** The window, [from, to). */
+    from: string;
+    to: string;
+    /** Results with an answer (accepted and waiting, counted, counted against); pending and not counted ones apart. */
+    results: number;
+    mature: number;
+    rejected: number;
+    provisional: number;
+    pending: number;
+    notCounted: number;
+    /** Results whose every run was priced in API dollars, and their median API dollars a task (null: hidden). */
+    apiPriced: number;
+    medianApiMicrousd: number | null;
+    /** Results with work on a plan (usage, not billed), with their runs and tokens. */
+    planResults: number;
+    planRuns: number;
+    planTokens: number;
+    /** Results with a run whose cost is unknown, and how many runs. Never $0. */
+    unknownResults: number;
+    unknownRuns: number;
+    /** Revision and repair runs, whose spending is included in their results'. */
+    remediationRuns: number;
+};
+export type SavingsKind = "rule" | "trial" | "suggestion";
+export type SavingsRow = {
+    kind: SavingsKind;
+    id: string;
+    repo: string;
+    project: string;
+    size: "small" | "medium";
+    state: string;
+    status: string;
+    /** The configured model's side (before, for a rule or trial) and the cheaper model's (after). */
+    configured: SavingsSide;
+    cheaper: SavingsSide;
+    /** Both sides have at least SAVINGS_TERMS.minPriced API-priced results, so the medians show. */
+    enough: boolean;
+    prices: Prices | null;
+    pricesFrom: "accepted" | "listed-now";
+    words: string[];
+};
+export type SavingsReport = {
+    label: typeof SAVINGS_LABEL;
+    windowDays: number;
+    minPriced: number;
+    rows: SavingsRow[];
+    /** The oldest last evaluation of an open result shown, when it is older than SAVINGS_TERMS.staleAfterHours. */
+    staleSince: string | null;
+};
+/** Whether a result was priced wholly in API dollars: no plan run, no unknown run, and a recorded charge. */
+export declare const apiPriced: (one: Pick<SavingsRecord, "apiMicrousd" | "subscriptionRuns" | "unknownRuns">) => boolean;
+/** The median of whole micro-dollars, rounded; null for none. */
+export declare function medianOf(values: readonly number[]): number | null;
+/** One side's figures from its records. The median is computed here, and hidden by `compare` when either side is short. */
+export declare function sideOf(who: {
+    provider: string;
+    model: string | null;
+    name: string;
+}, window: {
+    from: string;
+    to: string;
+}, records: readonly SavingsRecord[]): SavingsSide;
+/** Two sides compared: both medians show only when each side has enough API-priced results; otherwise neither does. */
+export declare function compare(configured: SavingsSide, cheaper: SavingsSide): {
+    configured: SavingsSide;
+    cheaper: SavingsSide;
+    enough: boolean;
+};
+/** Dollars a task: under a cent reads "<$0.01", never a false $0. */
+export declare const dollars: (microusd: number) => string;
+/** A side's figures in words: the median (or —), then API-priced, plan usage and unknown cost, each apart. */
+export declare function sideWords(side: SavingsSide): {
+    median: string;
+    parts: string[];
+};
+/** The listed prices in words, per million tokens. */
+export declare function pricesWords(row: Pick<SavingsRow, "prices" | "pricesFrom" | "configured" | "cheaper">): string;
+/** What not having enough priced results means, in words. */
+export declare function notEnoughWords(row: Pick<SavingsRow, "configured" | "cheaper">): string;
+export declare const statusWords: (state: string) => string;
+/** The row's own lines, as the command line prints them. */
+export declare function rowLines(row: SavingsRow): string[];
+/** The spend report's lines for this block: a heading and each row, or one line when there is nothing yet. */
+export declare function savingsLines(report: SavingsReport | {
+    error: string;
+}): string[];
+/** The block for these projects, by project then size. */
+export declare function savingsReport(store: Store, repos: readonly string[], now: Date): SavingsReport;
+/** The block, or that it can't be read: an unreadable block never fails the Spend page or `toolroll spend`. */
+export declare function savingsReportOrError(store: Store, repos: readonly string[], now: Date): SavingsReport | {
+    error: string;
+};

package/dist/route-savings.js

@@ -0,0 +1,193 @@
+/**
+ * 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;
+    const sorted = [...values].sort((a, b) => a - b);
+    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);
+    const plan = answered.filter(one => one.subscriptionRuns > 0);
+    const unknown = answered.filter(one => one.unknownRuns > 0);
+    const count = (state) => records.filter(one => one.state === state).length;
+    return {
+        ...who, ...window,
+        results: answered.length, mature: count("mature"), rejected: count("rejected"), provisional: count("provisional"), pending: count("pending"), notCounted: count("not-counted"),
+        apiPriced: priced.length, medianApiMicrousd: medianOf(priced.map(one => one.apiMicrousd)),
+        planResults: plan.length, planRuns: plan.reduce((sum, one) => sum + one.subscriptionRuns, 0), planTokens: plan.reduce((sum, one) => sum + one.subscriptionTokens, 0),
+        unknownResults: unknown.length, unknownRuns: unknown.reduce((sum, one) => sum + one.unknownRuns, 0),
+        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),
+        parts: [
+            `API-priced ${side.apiPriced} of ${side.results}`,
+            side.planResults === 0 ? "plan usage —" : `plan usage ${each(side.planResults, "result")} (${each(side.planRuns, "run")})`,
+            side.unknownResults === 0 ? "unknown cost —" : `unknown cost ${each(side.unknownResults, "result")} (${each(side.unknownRuns, "run")})`,
+            `${each(side.remediationRuns, "revision or repair run")} included`,
+        ],
+    };
+}
+/** 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.`;
+}
+const STATUS_WORDS = {
+    active: "In use", trialling: "Trial running", paused: "Paused", "switched-off": "Switched itself off", "turned-off": "Turned off",
+    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);
+        return `    ${label.padEnd(10)} ${side.name}, ${day(side.from)} to ${day(side.to)}: median ${words.median} a task · ${words.parts.join(" · ")}`;
+    };
+    const before = row.kind === "suggestion" ? "configured" : "before";
+    const after = row.kind === "suggestion" ? "suggested" : "after";
+    return [
+        `  ${row.project} · ${sizeWord(row.size)} tasks · ${row.cheaper.name} instead of ${row.configured.name} · ${row.status}`,
+        sideLine(before, row.configured), sideLine(after, row.cheaper),
+        ...(row.enough ? [] : [`    ${notEnoughWords(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."];
+    if (report.rows.length === 0)
+        return [`  ${"suggestions and rules".padEnd(24)} none yet`];
+    return [
+        `Suggestions and rules (${report.label}; ${report.windowDays} days a side; a median shows from ${report.minPriced} API-priced results a side)`,
+        ...(report.staleSince === null ? [] : [`  Some results were last checked on ${day(report.staleSince)}; they update while Toolroll runs.`]),
+        ...report.rows.flatMap(rowLines),
+    ];
+}
+function recordsOf(store, repo, size, from, to) {
+    return store.handle.prepare(`SELECT state, first_started_at, api_microusd, subscription_runs, subscription_tokens, unknown_runs, remediation_runs, closed, evaluated_at,
+      provider, model, provenance_json FROM route_record WHERE repo = ? AND cohort_size = ? AND first_started_at >= ? AND first_started_at < ?`).all(repo, size, from, to)
+        .map(row => {
+        let selections = [];
+        try {
+            selections = JSON.parse(String(row["provenance_json"] ?? "[]")).flatMap(one => { const read = selectionSchema.safeParse(one); return read.success ? [read.data] : []; });
+        }
+        catch {
+            selections = [];
+        }
+        return {
+            state: String(row["state"]), firstStartedAt: String(row["first_started_at"]), apiMicrousd: Number(row["api_microusd"] ?? 0),
+            subscriptionRuns: Number(row["subscription_runs"] ?? 0), subscriptionTokens: Number(row["subscription_tokens"] ?? 0), unknownRuns: Number(row["unknown_runs"] ?? 0),
+            remediationRuns: Number(row["remediation_runs"] ?? 0), closed: Number(row["closed"]) === 1, evaluatedAt: String(row["evaluated_at"]),
+            provider: String(row["provider"] ?? ""), model: row["model"] == null ? null : String(row["model"]), selections,
+        };
+    });
+}
+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;
+    const beforeWindow = { from: iso(accepted - window), to: iso(accepted) };
+    const end = Math.min(rule.endedAt === null ? now.getTime() : Date.parse(rule.endedAt), accepted + window, now.getTime());
+    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);
+    const configuredName = rule.configured.model === null ? "the configured model" : modelName(store, rule.configured.model);
+    const compared = compare(sideOf({ provider: rule.configured.provider, model: rule.configured.model, name: configuredName }, beforeWindow, before), sideOf({ provider: rule.provider, model: rule.model, name: modelName(store, rule.model) }, afterWindow, after));
+    const row = { kind: rule.kind, id: String(rule.id), repo: rule.repo, project: projectName(rule.repo), size: rule.cohortSize, state: rule.state, status: statusWords(rule.state),
+        ...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() };
+    for (const suggestion of suggestionsFor(store, repo, now)) {
+        const all = recordsOf(store, repo, suggestion.cohortSize, window.from, window.to).filter(one => one.provider === "claude");
+        const mine = all.filter(one => one.model === suggestion.model), standing = all.filter(one => one.model === suggestion.configured.model);
+        seen.push(...mine, ...standing);
+        const compared = compare(sideOf({ ...suggestion.configured }, window, standing), sideOf({ provider: suggestion.provider, model: suggestion.model, name: suggestion.name }, window, mine));
+        const row = { kind: "suggestion", id: suggestion.id, repo, project: projectName(repo), size: suggestion.cohortSize, state: "suggested", status: statusWords("suggested"),
+            ...compared, prices: suggestion.prices, pricesFrom: "listed-now", words: [] };
+        rows.push({ ...row, words: rowLines(row) });
+    }
+    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));
+    const staleBefore = now.getTime() - SAVINGS_TERMS.staleAfterHours * 60 * 60_000;
+    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);
+    }
+    catch {
+        return { error: "unreadable" };
+    }
+}

package/dist/route-store.d.ts

@@ -0,0 +1,300 @@
+import { type ExecClass, type IneligibleReason, type RevisionOrigin, type Selection } from "./contracts/route-results.js";
+import type { RecordValue } from "./route-results.js";
+import type { EarnedRule, EarnedTrial } from "./phase-routing.js";
+import { type Store } from "./store.js";
+/** A failed run's raw reason, by whose account it failed. Anything not listed counts as the model's (conservative: a
+ * missing or unknown class counts against the cheaper model, never for it). */
+export declare const EXEC_CLASS_OF_REASON: Readonly<Record<string, ExecClass>>;
+/** The gateway's terminal classes that say the provider, not the model, ended the attempt. */
+export declare const INFRASTRUCTURE_TERMINALS: ReadonlySet<string>;
+/** The class a failed run's raw reason (before the tick's normalization) and its terminal class give. */
+export declare function execClassOf(reason: string, terminalClass: string | null): ExecClass;
+export type CohortRow = {
+    run: number;
+    taskRef: number;
+    rootRef: number;
+    repo: string | null;
+    role: "builder" | "repair";
+    size: "small" | "medium" | "large" | null;
+    risky: boolean | null;
+    qualityMode: "default" | "strict";
+    evidenceDemands: boolean;
+    publication: "none" | "notify" | "automerge";
+    release: boolean;
+    protected: boolean;
+    selection: Selection;
+    routeDigest: string;
+    provider: string;
+    model: string | null;
+    cohortSize: "small" | "medium" | null;
+    ineligible: IneligibleReason | null;
+    startedAt: string;
+};
+export type CohortInput = {
+    run: number;
+    taskRef: number;
+    role: "builder" | "repair";
+    routeDigest: string;
+    provider: string;
+    model: string | null;
+    qualityMode: "default" | "strict";
+    startedAt: string;
+};
+/** The sealed facts a code-writing run's eligibility is decided from, conservatively: anything unreadable or not
+ * sealed is not eligible. Pure reads of the store, in the admission transaction. */
+export declare function cohortOf(store: Store, input: CohortInput): CohortRow;
+/** Keep a failed run's execution class from its raw reason, before the tick normalizes it (dispose.ts). First write
+ * wins: a later ending of the same run never rewrites the class it was kept with. */
+export declare function recordExecClass(store: Store, runId: number, reason: string): void;
+/** Who a revision came from, written once with the revision's seal; never on a task that revises nothing. */
+export declare function recordRevisionOrigin(store: Store, taskId: string, origin: RevisionOrigin): void;
+/**
+ * A code-writing run's cohort snapshot, in its admission transaction (store.ts admitRun), written once and never
+ * updated. A snapshot that can't be computed is never a refused admission: the run is recorded as not eligible, and a
+ * write that fails leaves no row (its record then reads "started before results were recorded"), so a cheaper model
+ * never gains from either.
+ */
+export declare function writeRunCohort(store: Store, input: CohortInput): void;
+/** Save a family's record as evaluated now. A decision time is kept while the state stays the same. Once a verdict
+ * is final (settled) it never moves — state, reason, result run, acceptance and decision time stay as decided — but
+ * the family's spending and counts keep being updated from later revision and repair runs until the record closes
+ * (route-results.ts ACCUMULATE_FOR_MS); a closed record is never written again. */
+export declare function saveResultRecord(store: Store, value: RecordValue, now: Date): void;
+/** The generation of one (scope, phase) Models row set: 0 before anything changed it. */
+export declare function modelsGenerationOf(store: Store, scope: string, phase: string): number;
+/**
+ * Move a (scope, phase) generation: called by every Models row writer (store.ts), inside the writer's own
+ * transaction, whenever a row actually changed. Rules that depend on a generation that moved are paused in the same
+ * transaction (pauseDependentRules), so a configuration change can never leave a rule running on terms it no longer
+ * has.
+ */
+export declare function bumpModelsGeneration(store: Store, scope: string, phase: string, now: Date): number;
+/** Pause every running rule or trial whose recorded dependency generations no longer match: a compare-and-swap on
+ * the rule's own generation, so a rule another writer already moved is left to that writer. An unreadable
+ * dependency list pauses too. */
+export declare function pauseDependentRules(store: Store, now: Date): number;
+/** A deleted project's results-routing rows (project-delete.ts, through store.ts forgetProjectModels): its rules,
+ * their exposures and trial places, its records and its runs' cohort snapshots. How many rows went. */
+export declare function forgetProjectRoutes(store: Store, repo: string): number;
+/** A person who proved themselves for this act (model-choices.ts ModelAuthority's shape): the account, the credential
+ * generation the proof was checked against, how they proved it, and whether the session or login still stands. */
+export type RulePerson = {
+    actor: string;
+    generation: number;
+    method: string;
+    live: () => boolean;
+};
+/** Who asks a rule act: a person, or this computer's local owner (local mode) inside the one act it may do. */
+export type RuleDoor = {
+    kind: "person";
+    person: RulePerson;
+} | {
+    kind: "local-owner";
+    actor: string;
+};
+/** The acts and the door each takes (docs/plans/results-routing.md, Authority). Raising acts take a person with a
+ * step-up; lowering acts take a person, or a local owner whose in-flight act is exactly the one named here. */
+export declare const RULE_ACTS: Readonly<{
+    readonly accept: {
+        readonly raising: true;
+        readonly localAct: null;
+    };
+    readonly keep: {
+        readonly raising: true;
+        readonly localAct: null;
+    };
+    readonly "suggest-on": {
+        readonly raising: true;
+        readonly localAct: null;
+    };
+    readonly "turn-off": {
+        readonly raising: false;
+        readonly localAct: "routing-turn-off";
+    };
+    readonly dismiss: {
+        readonly raising: false;
+        readonly localAct: "dismiss-suggestion";
+    };
+    readonly "suggest-off": {
+        readonly raising: false;
+        readonly localAct: "dismiss-suggestion";
+    };
+    readonly "trial-start": {
+        readonly raising: true;
+        readonly localAct: null;
+    };
+    readonly "trial-stop": {
+        readonly raising: false;
+        readonly localAct: "trial-stop";
+    };
+}>;
+export type RuleAct = keyof typeof RULE_ACTS;
+export type RuleRefusalReason = "lead-refused" | "authority";
+/** A door proved inside the write's own transaction: minted only by proveRuleDoor, and spent only there. */
+export type ProvedRuleDoor = {
+    readonly actor: string;
+    readonly act: RuleAct;
+    readonly via: "person" | "local-owner";
+};
+/**
+ * The rule doors' one proof, run inside the write's transaction: a lead token or a remote API token never acts
+ * (`lead-refused`); a person is re-proved — the same account, still active, still an instance operator who can open
+ * the project, at the credential generation the proof was made under, by a proof that still stands (model-choices.ts
+ * applyModelChoices' re-proof); a local owner only for a lowering act, only while it still stands, and only when its
+ * in-flight act is exactly that act's.
+ */
+export declare function proveRuleDoor(store: Store, door: RuleDoor, act: RuleAct, repo: string): {
+    ok: true;
+    door: ProvedRuleDoor;
+} | {
+    ok: false;
+    reason: RuleRefusalReason;
+};
+export type RuleInsert = {
+    repo: string;
+    cohortSize: "small" | "medium";
+    provider: string;
+    model: string;
+    configuredProvider: string;
+    configuredModel: string | null;
+    grant: unknown;
+    prices: unknown;
+    depends: Readonly<Record<string, number>>;
+};
+/** Insert an accepted earned rule, live. The winner index makes a second live rule for the same project and size
+ * refuse (null); nothing else is written. */
+export declare function insertEarnedRule(store: Store, door: ProvedRuleDoor, rule: RuleInsert, now: Date): number | null;
+/** A person's or local owner's end of a live rule — turned off, or a paused one dropped — by compare-and-swap on its
+ * generation. False when the rule moved since (or isn't live). */
+export declare function endRuleByDoor(store: Store, door: ProvedRuleDoor, ruleId: number, generation: number, now: Date): boolean;
+/** Keep a paused rule: live again, on the configuration generations it depends on now. Its sealed grant (terms,
+ * cutoff, expiry) never changes. */
+export declare function keepPausedRule(store: Store, door: ProvedRuleDoor, ruleId: number, generation: number, depends: Readonly<Record<string, number>>): boolean;
+/** "Not now" on one suggestion: kept as an ended offer (state dropped, reason not-now) so the same suggestion stays
+ * quiet for its 30 days; it never blocks a rule. */
+export declare function recordNotNow(store: Store, door: ProvedRuleDoor, offer: {
+    repo: string;
+    cohortSize: "small" | "medium";
+    provider: string;
+    model: string;
+    configuredProvider: string;
+    configuredModel: string | null;
+    prices: unknown;
+}, now: Date): void;
+/** A project's "Suggest cheaper models" switch. False when the project isn't saved here. */
+export declare function writeSuggestModels(store: Store, door: ProvedRuleDoor, repo: string, on: boolean): boolean;
+/** The plane's own end of a rule (no person): switched off by its sealed trigger, paused (a configuration or grant
+ * change), or expired. A compare-and-swap on the rule's generation and a live state: false when it moved since. */
+export declare function endRuleByPlane(store: Store, ruleId: number, generation: number, to: "switched-off" | "paused" | "expired", reason: string, now: Date): boolean;
+/** The exposure rows a filing writes (store.ts saveScope): a build leg sealed under a rule opens the task's exposure
+ * to it (`proposed`) or, filed again, adds `refiled`; a filing that no longer selects a rule the task was exposed to
+ * adds `refiled` to that open exposure, which its approval then closes as approved with another model. Re-filing
+ * never adds a row. */
+export declare function noteExposureFiled(store: Store, taskRef: number, selection: Selection | undefined, now: Date): void;
+/** An approval closes the task's open exposures: as proposed when it sealed that very rule, otherwise approved with
+ * the model it sealed. */
+export declare function noteExposureSealed(store: Store, taskRef: number, sealed: {
+    selection: Selection | undefined;
+    model: string;
+}, now: Date): void;
+/** A cancel closes the task's open exposures. */
+export declare function noteExposureCancelled(store: Store, taskRef: number, now: Date): void;
+/** A project's live earned rules, as routing reads them (phase-routing.ts EarnedRule): kind rule, state active, a
+ * Claude model. A row that doesn't read is left out (it can only ever not apply). */
+export declare function liveEarnedRules(store: Store, repo: string | null): EarnedRule[];
+/** Why a build of this task must not start under the rule its route sealed, or null: the rule switched itself off
+ * after the approval and the task hasn't started (docs/plans/results-routing.md, "When a rule ends"). A rule turned off
+ * by a person, or expired, keeps the sealed model; a started task's later attempts finish under it. */
+export declare function ruleHoldOf(store: Store, taskId: string): {
+    rule: number;
+    model: string;
+} | null;
+export type TrialInsert = {
+    repo: string;
+    cohortSize: "small" | "medium";
+    model: string;
+    configuredProvider: string;
+    configuredModel: string | null;
+    limit: number;
+    grant: unknown;
+    prices: unknown;
+    depends: Readonly<Record<string, number>>;
+};
+/** Start a trial, live (state trialling) with its number of places. The winner index makes a second live rule or
+ * trial for the same project and size refuse (null); nothing else is written. */
+export declare function insertTrial(store: Store, door: ProvedRuleDoor, trial: TrialInsert, now: Date): number | null;
+/**
+ * A person's or local owner's stop of a live or paused trial, by compare-and-swap on its generation, in the same
+ * transaction as releasing the places of tasks not approved on them (those plans are re-filed by the rule pass). A
+ * place a task was approved on stays reserved: that task keeps the model a person approved (as a rule turned off
+ * does). False when the trial moved since.
+ */
+export declare function endTrialByDoor(store: Store, door: ProvedRuleDoor, trialId: number, generation: number, now: Date): boolean;
+/** A project's live trial for one size, as routing reads it (without this filing's place): state trialling, a Claude
+ * model. Null when none, or when its row doesn't read (it can only ever not apply). */
+export declare function liveTrialFor(store: Store, repo: string | null, size: string | null | undefined): Omit<EarnedTrial, "reservation"> | null;
+/**
+ * This task's place in a trial, in the filing's own write transaction (store.ts saveScope, serialized by
+ * beginWriteWithin): a place it already holds (reserved, or consumed by its own earlier attempt) is reused, so
+ * repeated saves never take a second one; a place it gave up is never taken back; otherwise a new one only while
+ * reserved + consumed is under the trial's limit and the trial is live. Its digest is bound by settleTrialPlaces in
+ * the same transaction. Null: no place.
+ */
+export declare function reserveTrialPlace(store: Store, trialId: number, taskRef: number, now: Date): number | null;
+/**
+ * After a filing, in its transaction: the place its route seals (if any) is bound to the scope digest it was filed
+ * under (a compare-and-swap on `reserved`; a place this task's own attempt already consumed stays as it is), and every
+ * other place this task holds unconsumed is released. A selection that names a place this task doesn't hold throws:
+ * nothing files on it.
+ */
+export declare function settleTrialPlaces(store: Store, taskRef: number, selection: Selection | undefined, digest: string, now: Date): void;
+/** A cancel gives up every place the task holds unconsumed (store.ts applyCancellationLocked). A consumed place is
+ * never released. How many went. */
+export declare function releaseTrialPlaces(store: Store, taskRef: number, now: Date): number;
+/**
+ * Why a seal of this route must not stand, or null (store.ts sealScopeApproval): a trial task is approved only by a
+ * person — their own ceremony (no basis; not a machine acting, not an AI approver's name) or their paired-chat tap —
+ * never a mode, a grant, a schedule, a carry, an automatic seal or the lead; and only while its place stands.
+ */
+export declare function trialSealProblem(store: Store, input: {
+    taskRef: number | null;
+    selection: Selection | undefined;
+    digest: string;
+    basis: string | null;
+    by: string;
+    machine: boolean;
+}): string | null;
+/**
+ * A code-writing run's trial check, in its admission transaction after the run row exists (store.ts admitRun): for a
+ * route sealed on a trial, the approval must be a person's own (approval-authority.ts trialSealStandsSql), and the
+ * sealed place is consumed exactly once — a compare-and-swap on `reserved` and the sealed scope digest. A retry or
+ * repair of the same task whose place that task already consumed is admitted without consuming again. The words, or
+ * null to admit; the caller refuses (rolling the row back) on words.
+ */
+export declare function admitTrialRun(store: Store, input: {
+    taskId: string;
+    taskRef: number;
+    role: string;
+    run: number;
+    now: Date;
+}): string | null;
+/** Consume one reserved place for this run: only with the sealed scope digest it was bound to. */
+export declare function consumeTrialPlace(store: Store, reservation: number, sealedDigest: string, run: number, now: Date): boolean;
+/** A trial's places: its limit, how many are reserved (waiting) and consumed (started). */
+export declare function trialPlacesOf(store: Store, trialId: number): {
+    limit: number;
+    reserved: number;
+    consumed: number;
+};
+/** Which place in its trial this one is (1-based, counting places held or used, in order), or null. */
+export declare function trialOrdinalOf(store: Store, reservation: number): {
+    trial: number;
+    ordinal: number;
+    state: string;
+} | null;
+/** Whether a proposal's trial place still stands for re-use by its next approval: the trial is live and the place is
+ * held reserved by that task (the rule pass re-files a proposal whose place doesn't). */
+export declare function trialPlaceLive(store: Store, selection: {
+    rule: number;
+    reservation: number;
+}, taskRef: number): boolean;