toolroll 0.9.91 → 0.9.92

package/dist/route-results.js

@@ -0,0 +1,340 @@
+/**
+ * Result records (docs/plans/results-routing.md, slice 1): what each finished task family shows about the model that
+ * built it, read only from Toolroll's own rows (runs, their cohort snapshots, checks, completions, merges, review
+ * findings and revision origins) — never worktree files, park payloads, agent reports or lead tool calls.
+ *
+ * A policy path (release-auto.ts EVAL_POLICY): the execution-class table, eligibility and the lifecycle decide what
+ * counts as a cheaper model's evidence, so a change here needs a person. The only writer is route-store.ts.
+ *
+ * Read-only in slice 1: nothing here suggests, routes or switches anything.
+ */
+import { protectedChanges } from "./approval-policy.js";
+import { assignmentChecksForRun } from "./assignment.js";
+import { INELIGIBLE_REASONS, REASON_WORDS, selectionSchema, } from "./contracts/route-results.js";
+import { changedFilesOf, COMPLETION_ACTION } from "./result-completion.js";
+import { runAccounting } from "./store.js";
+import { INFRASTRUCTURE_TERMINALS, saveResultRecord } from "./route-store.js";
+// The execution class and the cohort snapshot live with their writer (route-store.ts), which store.ts imports: kept
+// light so the store's module graph doesn't reach the evaluator's readers.
+export { cohortOf, EXEC_CLASS_OF_REASON, execClassOf } from "./route-store.js";
+// ---- the record ---------------------------------------------------------------------------------------------------
+/** How long an accepted result waits before it counts, and how long a result may wait for an answer. */
+export const MATURE_AFTER_MS = 14 * 24 * 60 * 60_000;
+export const UNANSWERED_AFTER_MS = 30 * 24 * 60 * 60_000;
+/** The explicit cutoff for a family's spending and counts: they keep accumulating through later revision and repair
+ * runs (a verdict, once final, never moves) until the family is quiet — every version ended and no run open — or
+ * this long after its first run, whichever is first. */
+export const ACCUMULATE_FOR_MS = 90 * 24 * 60 * 60_000;
+function cohortsFor(store, runs) {
+    const rows = store.handle.prepare("SELECT * FROM run_cohort WHERE run IN (SELECT value FROM json_each(?))").all(JSON.stringify(runs));
+    return new Map(rows.map(row => {
+        let selection = null;
+        try {
+            const read = selectionSchema.safeParse(JSON.parse(String(row["selection_json"])));
+            selection = read.success ? read.data : null;
+        }
+        catch {
+            selection = null;
+        }
+        const size = row["cohort_size"] === "small" || row["cohort_size"] === "medium" ? row["cohort_size"] : null;
+        return [Number(row["run"]), { run: Number(row["run"]), repo: row["repo"] == null ? null : String(row["repo"]), cohortSize: size,
+                ineligible: row["ineligible"] == null ? null : String(row["ineligible"]), model: row["model"] == null ? null : String(row["model"]),
+                provider: String(row["provider"]), selection, startedAt: String(row["started_at"]) }];
+    }));
+}
+/** A failed code-writing run's class: its kept class; otherwise a provider terminal or an interruption before the
+ * provider started is infrastructure; anything else (a missing write included) is the model's. */
+function classOfRun(run, kept) {
+    if (kept === "model" || kept === "infrastructure")
+        return kept;
+    if (run.terminalClass != null && INFRASTRUCTURE_TERMINALS.has(run.terminalClass))
+        return "infrastructure";
+    if ((run.outcome === "interrupted" || run.reason === "interrupted") && run.providerStartedAt === null)
+        return "infrastructure";
+    return "model";
+}
+const FAILED_OUTCOMES = new Set(["failed", "interrupted"]);
+/**
+ * A task family's record, evaluated now from its rows (null: no code-writing run, or a family whose lineage can't be
+ * proved). The order is the plan's: what can't be attributed to one model and one cohort first, then a live attempt
+ * (pending), then every rejection, then what isn't counted, then acceptance and maturity.
+ */
+export function evaluateFamily(store, rootTaskId, evidenceRoot, now) {
+    const family = store.taskFamilyOf(rootTaskId, null, true);
+    if (family === null || family.problem !== null || family.root.id !== rootTaskId)
+        return null;
+    const versionOf = new Map();
+    const runs = [];
+    for (const version of family.versions) {
+        for (const run of store.runsFor(version.refId)) {
+            if (run.role !== "builder" && run.role !== "repair")
+                continue;
+            runs.push(run);
+            versionOf.set(run.id, version.id);
+        }
+    }
+    if (runs.length === 0)
+        return null;
+    runs.sort((a, b) => a.id - b.id);
+    const ids = runs.map(run => run.id);
+    const cohorts = cohortsFor(store, ids);
+    const kept = new Map(store.handle.prepare("SELECT id, exec_class FROM run WHERE id IN (SELECT value FROM json_each(?))").all(JSON.stringify(ids))
+        .map(row => [Number(row["id"]), row["exec_class"] == null ? null : String(row["exec_class"])]));
+    // Spending, kept apart by kind and never added across kinds.
+    let apiMicrousd = 0, subscriptionRuns = 0, subscriptionTokens = 0, unknownRuns = 0, remediationRuns = 0;
+    for (const run of runs) {
+        if (run.role === "repair" || versionOf.get(run.id) !== family.root.id)
+            remediationRuns++;
+        if (run.providerStartedAt === null)
+            continue;
+        const accounting = runAccounting(store, run.id);
+        if (accounting === null || accounting.amount.kind === "unknown")
+            unknownRuns++;
+        else if (accounting.amount.kind === "api")
+            apiMicrousd += accounting.amount.microusd;
+        else {
+            subscriptionRuns++;
+            subscriptionTokens += (accounting.usage.in ?? 0) + (accounting.usage.out ?? 0);
+        }
+    }
+    let agentTurns = 0, turnsUnknownRuns = 0;
+    for (const run of runs) {
+        if (run.providerStartedAt === null)
+            continue;
+        if (run.agentTurns == null)
+            turnsUnknownRuns++;
+        else
+            agentTurns += run.agentTurns;
+    }
+    const firstBuilt = runs.find(run => run.outcome === "built");
+    const firstCheck = firstBuilt === undefined ? null : store.runCheckFor(firstBuilt.id)?.status ?? null;
+    const personRevisions = store.handle.prepare("SELECT COUNT(*) AS n FROM task_ref WHERE id IN (SELECT value FROM json_each(?)) AND revision_origin = 'person'")
+        .get(JSON.stringify(family.versions.filter(one => one.id !== family.root.id).map(one => one.refId)))?.["n"];
+    const quiet = family.versions.every(one => one.state === "done" || one.state === "cancelled" || one.state === "failed") && runs.every(run => run.outcome !== null);
+    let modelFailures = 0, infraFailures = 0;
+    for (const run of runs) {
+        const failedCheck = run.outcome === "built" && store.runCheckFor(run.id)?.status === "failed";
+        if (!FAILED_OUTCOMES.has(run.outcome ?? "") && !failedCheck)
+            continue;
+        if (failedCheck || classOfRun(run, kept.get(run.id) ?? null) === "model")
+            modelFailures++;
+        else
+            infraFailures++;
+    }
+    const first = cohorts.get(runs[0].id);
+    const attributed = runs.map(run => cohorts.get(run.id)).filter((one) => one !== undefined);
+    const value = {
+        taskRef: family.root.refId, task: family.root.id, repo: family.root.repo, cohortSize: first?.cohortSize ?? null,
+        provider: first?.provider ?? runs[0].provider, model: first?.model ?? runs[0].model, state: "pending", reason: null, resultRun: null,
+        firstStartedAt: first?.startedAt ?? runs[0].startedAt, acceptedAt: null, decidedAt: null, modelFailures, infraFailures,
+        apiMicrousd, subscriptionRuns, subscriptionTokens, unknownRuns, remediationRuns,
+        selections: attributed.map(one => one.selection).filter((one) => one !== null), settled: false,
+        personRevisions: Number(personRevisions ?? 0), firstCheckPassed: firstCheck === "passed" ? true : firstCheck === "failed" ? false : null,
+        agentTurns, turnsUnknownRuns,
+        accumulationEnded: quiet || now.getTime() >= Date.parse(first?.startedAt ?? runs[0].startedAt) + ACCUMULATE_FOR_MS,
+    };
+    const reject = (reason) => ({ ...value, state: "rejected", reason, decidedAt: now.toISOString(), settled: true });
+    const notCounted = (reason, settled) => ({ ...value, state: "not-counted", reason, decidedAt: settled ? now.toISOString() : null, settled });
+    // 1. One cohort and one model, or the record can't say anything about a model.
+    if (attributed.length !== runs.length)
+        return notCounted("before-records", true);
+    // A family whose runs disagree (a revision re-sized large, one run under strict) is mixed; one whose runs all agree
+    // on not being eligible is not eligible.
+    if (new Set(attributed.map(one => `${one.repo ?? ""}\u0000${one.cohortSize ?? "not-eligible"}`)).size > 1)
+        return notCounted("mixed-cohort", true);
+    if (attributed.some(one => one.cohortSize === null))
+        return notCounted("not-eligible", true);
+    if (new Set(attributed.map(one => `${one.provider}\u0000${one.model ?? ""}`)).size > 1)
+        return notCounted("mixed-models", true);
+    for (const run of runs) {
+        if (run.providerStartedAt === null || run.outcome === null)
+            continue;
+        if (run.modelReported == null)
+            return notCounted("model-not-reported", true);
+        if (run.modelReported !== cohorts.get(run.id).model)
+            return notCounted("mixed-models", true);
+    }
+    // 2. A person who asked for changes, or a HIGH finding, rejected a result already: that stands whatever the family
+    //    does next (its later runs still add to its spending).
+    if (value.personRevisions > 0)
+        return reject("person-revision");
+    if (highFinding(store, ids))
+        return reject("high-finding");
+    // 3. Still running: nothing to say yet.
+    if (runs.some(run => run.outcome === null))
+        return value;
+    const current = family.current;
+    const result = [...runs].reverse().find(run => versionOf.get(run.id) === current.id && run.role === "builder" && (run.outcome === "built" || run.outcome === "no-change"));
+    if (result === undefined) {
+        if (current.state === "failed")
+            return modelFailures === 0 && infraFailures > 0 ? notCounted("infrastructure-only", true) : reject("task-failed");
+        if (current.state === "cancelled")
+            return notCounted("cancelled-before-result", true);
+        return value;
+    }
+    value.resultRun = result.id;
+    // 4. Rejections, checked first among what a result can be.
+    if (modelFailures >= 2)
+        return reject("model-failures");
+    if (family.versions.some(one => one.state === "failed"))
+        return reject("task-failed");
+    if (current.state === "cancelled")
+        return reject("cancelled-after-result");
+    if (store.proofVerdictFor(result.id)?.verdict === "refuted")
+        return reject("proof-refuted");
+    const checks = evidenceRoot === undefined ? null : assignmentChecksForRun(store, evidenceRoot, result.id, now);
+    if (checks?.status === "failed")
+        return reject("check-failed");
+    // 5. Not counted.
+    const answerBy = Date.parse(result.finishedAt ?? result.startedAt) + UNANSWERED_AFTER_MS;
+    if (checks === null || checks.status === "unavailable")
+        return notCounted("check-unavailable", now.getTime() >= answerBy);
+    if (checks.status === "not-run")
+        return notCounted("no-check", now.getTime() >= answerBy);
+    const rules = value.repo === null ? null : store.approvalRules(value.repo);
+    // Post-build: each built run's own diff inventory; one that can't be read whole (or was never saved) is unknown.
+    for (const run of runs) {
+        if (run.outcome !== "built")
+            continue;
+        const changed = changedFilesOf(store, run.id, evidenceRoot);
+        if (changed === null)
+            return notCounted("changed-files-unknown", true);
+        if (rules !== null && protectedChanges(rules, changed).length > 0)
+            return notCounted("touched-protected", true);
+    }
+    // 6. Accepted by a person's completion of this result, or by its merge; then mature after 14 days.
+    const acceptedAt = acceptanceOf(store, family.root.id, current.id, result.id);
+    if (acceptedAt === null)
+        return now.getTime() >= answerBy ? notCounted("unanswered", true) : value;
+    const matureAt = Date.parse(acceptedAt) + MATURE_AFTER_MS;
+    if (now.getTime() < matureAt)
+        return { ...value, state: "provisional", acceptedAt };
+    return { ...value, state: "mature", acceptedAt, decidedAt: new Date(matureAt).toISOString(), settled: true };
+}
+/** Whether the automatic review graded any of these runs' results HIGH. */
+function highFinding(store, runs) {
+    const rows = store.handle.prepare("SELECT findings_json FROM build_review WHERE run IN (SELECT value FROM json_each(?)) AND findings_json IS NOT NULL").all(JSON.stringify(runs));
+    return rows.some(row => {
+        try {
+            const findings = JSON.parse(String(row["findings_json"])).findings;
+            return Array.isArray(findings) && findings.some(one => one?.severity === "HIGH");
+        }
+        catch {
+            return true; /* an unreadable review counts against, never for */
+        }
+    });
+}
+/** When a person accepted this result: the earliest person-proved completion of exactly this run (a machine's
+ * completion, a lead's, or Toolroll's own `system:landed` is not acceptance), or its merge. */
+function acceptanceOf(store, rootId, currentId, runId) {
+    const completed = store.handle.prepare(`SELECT MIN(at) AS at FROM action_ledger WHERE action = ? AND source = 'work' AND task_id IN (?, ?)
+    AND run_id = ? AND detail = 'proof person' AND actor LIKE 'operator:%'`).get(COMPLETION_ACTION, rootId, currentId, runId)?.["at"];
+    const merged = store.handle.prepare(`SELECT MIN(COALESCE(m.settled_at, m.created_at)) AS at FROM merge_intent m JOIN publication p ON p.id = m.publication
+    WHERE p.run = ? AND m.state = 'merged'`).get(runId)?.["at"];
+    const times = [completed, merged].filter((one) => typeof one === "string" && Number.isFinite(Date.parse(one)));
+    return times.length === 0 ? null : times.sort()[0];
+}
+// ---- reading and re-evaluating ------------------------------------------------------------------------------------
+/** The record in plain words, as the task page and `models results` say it. */
+export function recordWords(record) {
+    const model = record.model ?? "this model";
+    if (record.state === "pending")
+        return record.resultRun === null ? "Pending: no result yet" : "Pending: waiting for the result to be accepted";
+    if (record.state === "provisional")
+        return `Accepted: counts for ${model} 14 days after acceptance`;
+    if (record.state === "mature")
+        return `Counts for ${model}: accepted, checks passed`;
+    const words = record.reason === null ? "" : REASON_WORDS[record.reason];
+    return record.state === "rejected" ? `Counts against ${model}: ${words}` : `Not counted: ${words}`;
+}
+/** A record row as saved, in the shape `models results --json` and the task page read. */
+export function recordView(row, task) {
+    const n = (key) => Number(row[key] ?? 0);
+    const s = (key) => row[key] == null ? null : String(row[key]);
+    let selections = [];
+    try {
+        selections = JSON.parse(String(row["provenance_json"] ?? "[]")).flatMap(one => { const read = selectionSchema.safeParse(one); return read.success ? [read.data] : []; });
+    }
+    catch {
+        selections = [];
+    }
+    const state = String(row["state"]);
+    const reason = s("reason");
+    const view = {
+        task, repo: s("repo"), size: s("cohort_size"), provider: s("provider"), model: s("model"), state, reason,
+        resultRun: row["result_run"] == null ? null : n("result_run"), acceptedAt: s("accepted_at"), decidedAt: s("decided_at"),
+    };
+    return {
+        ...view, words: recordWords(view), failures: { model: n("model_failures"), infrastructure: n("infra_failures") },
+        spend: { apiMicrousd: n("api_microusd"), subscriptionRuns: n("subscription_runs"), subscriptionTokens: n("subscription_tokens"), unknownRuns: n("unknown_runs"), remediationRuns: n("remediation_runs") },
+        selections, personRevisions: n("person_revisions"),
+        firstCheckPassed: row["first_check_passed"] == null ? null : Number(row["first_check_passed"]) === 1,
+        turns: { known: n("agent_turns"), unknownRuns: n("turns_unknown_runs") }, closed: n("closed") === 1,
+    };
+}
+/** The value as a view, for a record evaluated now and not (yet) saved. */
+export function valueView(value) {
+    return recordView({ repo: value.repo, cohort_size: value.cohortSize, provider: value.provider, model: value.model, state: value.state, reason: value.reason,
+        result_run: value.resultRun, accepted_at: value.acceptedAt, decided_at: value.decidedAt, model_failures: value.modelFailures, infra_failures: value.infraFailures,
+        api_microusd: value.apiMicrousd, subscription_runs: value.subscriptionRuns, subscription_tokens: value.subscriptionTokens, unknown_runs: value.unknownRuns,
+        remediation_runs: value.remediationRuns, provenance_json: JSON.stringify(value.selections), person_revisions: value.personRevisions,
+        first_check_passed: value.firstCheckPassed === null ? null : value.firstCheckPassed ? 1 : 0, agent_turns: value.agentTurns,
+        turns_unknown_runs: value.turnsUnknownRuns, closed: value.settled && value.accumulationEnded ? 1 : 0 }, value.task);
+}
+/** The saved records of these projects, newest first (by their family's first run). */
+export function resultRecords(store, repos, limit = 200) {
+    return store.handle.prepare(`SELECT r.*, t.external_id AS task FROM route_record r JOIN task_ref t ON t.id = r.task_ref
+    WHERE r.repo IN (SELECT value FROM json_each(?)) ORDER BY r.first_started_at DESC, t.external_id DESC LIMIT ?`).all(JSON.stringify(repos), limit)
+        .map(row => recordView(row, String(row["task"])));
+}
+/** A task's record: its family root's saved record, or, before the first pass saves one, the record evaluated now. */
+export function resultRecordOf(store, taskId, evidenceRoot, now) {
+    const family = store.taskFamilyOf(taskId, null, true);
+    if (family === null || family.problem !== null)
+        return null;
+    const row = store.handle.prepare("SELECT * FROM route_record WHERE task_ref = ?").get(family.root.refId);
+    if (row !== undefined)
+        return recordView(row, family.root.id);
+    const value = evaluateFamily(store, family.root.id, evidenceRoot, now);
+    return value === null ? null : valueView(value);
+}
+/** The task page's "Result record" line: the record's words, or null when the task has none (or it can't be read:
+ * a record never fails the page). */
+export function resultRecordWordsOf(store, taskId, evidenceRoot, now) {
+    try {
+        return resultRecordOf(store, taskId, evidenceRoot, now)?.words ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+/** The families the re-evaluation pass looks at: a root task with a code-writing run that has a cohort snapshot, whose
+ * record is missing or not closed (a final verdict still gathers its family's later spending until it closes); the
+ * least recently evaluated first. */
+export function familiesToEvaluate(store, repo, limit) {
+    return store.handle.prepare(`SELECT root.external_id AS task FROM run_cohort c JOIN task_ref root ON root.id = c.root_ref
+    LEFT JOIN route_record rec ON rec.task_ref = c.root_ref
+    WHERE c.repo = ? AND (rec.task_ref IS NULL OR rec.closed = 0)
+    GROUP BY c.root_ref ORDER BY COALESCE(MIN(rec.evaluated_at), ''), c.root_ref LIMIT ?`).all(repo, limit).map(row => String(row["task"]));
+}
+export { INELIGIBLE_REASONS };
+/** The re-evaluation pass (the reconcile pass of each project, operate.ts): every family with a cohort snapshot whose
+ * record is missing or not closed is evaluated again from its rows, oldest evaluation first, at most `limit` a pass,
+ * and saved through route-store.ts. Each family is its own transaction, so one unreadable family never holds the others
+ * back. */
+export function reevaluateResultRecords(store, repo, evidenceRoot, now, limit = 100) {
+    let saved = 0;
+    for (const task of familiesToEvaluate(store, repo, limit)) {
+        try {
+            store.transact(() => {
+                const value = evaluateFamily(store, task, evidenceRoot, now);
+                if (value !== null) {
+                    saveResultRecord(store, value, now);
+                    saved++;
+                }
+            });
+        }
+        catch { /* the next pass tries again */ }
+    }
+    return saved;
+}

package/dist/route-rules.d.ts

@@ -0,0 +1,324 @@
+import { type NotCountedReason } from "./contracts/route-results.js";
+import { type PhaseRoute } from "./phase-routing.js";
+import { type RuleDoor, type RuleRefusalReason } from "./route-store.js";
+import { type Store } from "./store.js";
+/** The policy version a grant is sealed under: a grant sealed under another version pauses its rule. */
+export declare const ROUTING_POLICY_VERSION = 1;
+/** When to suggest (Suggest and trigger terms): records of the last 90 days, the newest 20 decided. */
+export declare const SUGGEST_TERMS: Readonly<{
+    windowDays: 90;
+    newest: 20;
+    minDecided: 10;
+    minMature: 0.9;
+    lastClean: 3;
+    configuredGap: 0.05;
+    maxNotCounted: number;
+}>;
+/** How long a grant lasts, how long Not now keeps a suggestion quiet, and when Needs you says a grant ends soon. */
+export declare const GRANT_DAYS = 90;
+export declare const NOT_NOW_DAYS = 30;
+export declare const EXPIRY_WARNING_DAYS = 7;
+/** A rule's switch-back terms, sealed at acceptance (route_rule.grant_json) and read only from there. */
+export type Grant = {
+    policyVersion: number;
+    cutoff: string;
+    expires: string;
+    /** Switch off when more than `max` of the latest `window` decided records are rejected. */
+    reject: {
+        window: number;
+        max: number;
+    };
+    /** Once `window` decided records exist: switch off when fewer than `min` of the latest `window` are mature. */
+    mature: {
+        window: number;
+        min: number;
+    };
+    /** Switch off when more than `max` of the latest `window` closed exposures were approved with another model. */
+    declined: {
+        window: number;
+        max: number;
+    };
+};
+export declare function grantFor(now: Date): Grant;
+/** The switch-back terms in words, as the review shows them before acceptance and Settings after. */
+export declare function grantWords(grant: Grant): string[];
+export type RuleState = "active" | "trialling" | "paused" | "switched-off" | "turned-off" | "expired" | "dropped" | "finished";
+export type RuleRow = {
+    id: number;
+    repo: string;
+    cohortSize: "small" | "medium";
+    kind: "rule" | "trial";
+    provider: string;
+    model: string;
+    configured: {
+        provider: string;
+        model: string | null;
+    };
+    state: RuleState;
+    generation: number;
+    grant: Grant | null;
+    prices: Prices | null;
+    depends: Record<string, number> | null;
+    acceptedBy: string;
+    acceptedAt: string;
+    endedAt: string | null;
+    endedBy: string | null;
+    endReason: string | null;
+    /** A trial's number of places (slice 3); null for a rule. */
+    limit: number | null;
+};
+/** Listed prices, in dollars per million tokens, as snapshotted. */
+export type Prices = {
+    model: {
+        in: number;
+        out: number;
+    };
+    configured: {
+        in: number;
+        out: number;
+    };
+};
+export declare function ruleById(store: Store, id: number): RuleRow | null;
+/** 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 declare function rulesOf(store: Store, repo: string, now: Date): RuleRow[];
+/** Whether a project offers suggestions (its "Suggest cheaper models" switch; a project not saved here reads on). */
+export declare function suggestModelsOn(store: Store, repo: string): boolean;
+/** The configuration generations a rule for this project depends on: the installation's and the project's build and
+ * repair rows. */
+export declare function dependsOf(store: Store, repo: string): Record<string, number>;
+export type Evidence = {
+    /** The newest decided records counted (at most SUGGEST_TERMS.newest), how many of them were accepted and checked. */
+    decided: number;
+    mature: number;
+    rejected: number;
+    /** Records in the window not counted, and their reasons with how many each. */
+    notCounted: number;
+    notCountedReasons: {
+        reason: NotCountedReason;
+        count: number;
+    }[];
+    total: number;
+    /** The newest decided tasks, by id, newest first. */
+    tasks: string[];
+    /** Observed median API dollars a task, over mature records priced in dollars; null below 5 such records. */
+    medianMicrousd: number | null;
+};
+/** The model's own name when the catalog knows it ("Claude Haiku 5.5"), else its id. */
+export declare function modelName(store: Store, model: string): string;
+export type Suggestion = {
+    /** `<size>:<model>:<offer>` — what the person reviews, and what accept and Not now name. */
+    id: string;
+    repo: string;
+    cohortSize: "small" | "medium";
+    provider: "claude";
+    model: string;
+    name: string;
+    configured: {
+        provider: string;
+        model: string;
+        name: string;
+    };
+    evidence: Evidence;
+    configuredEvidence: Evidence;
+    prices: Prices;
+    depends: Record<string, number>;
+    /** Three digests the offer binds: the evidence, the prices, and the configuration generations. */
+    offer: {
+        evidence: string;
+        prices: string;
+        depends: string;
+    };
+    grant: Grant;
+};
+/** 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 declare function offerNow(store: Store, repo: string, size: "small" | "medium", model: string, now: Date): {
+    suggestion: Suggestion | null;
+    why: string | null;
+    parts: Suggestion["offer"] | null;
+};
+/** A suggestion id read back: its cohort, model and the three digest prefixes it was offered under. */
+export declare function readSuggestionId(id: string): {
+    size: "small" | "medium";
+    model: string;
+    evidence: string;
+    prices: string;
+    depends: string;
+} | null;
+/**
+ * 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 declare function suggestionsFor(store: Store, repo: string, now: Date): Suggestion[];
+/** A suggestion in plain words, the evidence first. */
+export declare function suggestionWords(suggestion: Suggestion): string;
+export type RuleRefusal = {
+    ok: false;
+    reason: RuleRefusalReason | "stale-suggestion" | "price-changed" | "config-changed" | "invalid" | "taken" | "not-found" | "unknown-project";
+    problem: string;
+};
+/**
+ * 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 declare function acceptSuggestion(store: Store, input: {
+    repo: string;
+    id: string;
+}, door: RuleDoor, now: Date): {
+    ok: true;
+    rule: number;
+    suggestion: Suggestion;
+} | RuleRefusal;
+/** Turn a live rule off, or drop a paused one. Tasks already approved keep the model they were approved with. */
+export declare function turnOffRule(store: Store, ruleId: number, door: RuleDoor, now: Date): {
+    ok: true;
+    rule: RuleRow;
+} | RuleRefusal;
+/** Keep a paused rule: live again on the configuration as it stands, if that configuration can run it. */
+export declare function keepRule(store: Store, ruleId: number, door: RuleDoor, now: Date): {
+    ok: true;
+    rule: RuleRow;
+} | RuleRefusal;
+/** Not now: the suggestion stays quiet for 30 days. */
+export declare function dismissSuggestion(store: Store, input: {
+    repo: string;
+    id: string;
+}, door: RuleDoor, now: Date): {
+    ok: true;
+} | RuleRefusal;
+/** A project's "Suggest cheaper models" switch: on takes a person's step-up, off also the local owner. */
+export declare function setSuggestModels(store: Store, repo: string, on: boolean, door: RuleDoor): {
+    ok: true;
+} | RuleRefusal;
+export type TripResult = {
+    trips: false;
+} | {
+    trips: true;
+    why: string;
+};
+/** 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 declare function tripOf(grant: Grant, decided: readonly ("mature" | "rejected")[], exposures: readonly boolean[]): TripResult;
+export type SwitchOffOutcome = "kept" | "switched-off" | "paused" | "expired" | "moved";
+/**
+ * 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 declare function switchOffIfTripped(store: Store, ruleId: number, now: Date): {
+    outcome: SwitchOffOutcome;
+    why: string | null;
+};
+/** 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 declare function holdRuleOff(store: Store, taskRef: number, taskId: string, model: string, now: Date): void;
+/**
+ * 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 declare function routeRulesPass(store: Store, repo: string, now: Date): {
+    switchedOff: number;
+    paused: number;
+    held: number;
+    refiled: number;
+};
+/**
+ * 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 declare function selectionEvidenceWords(store: Store, route: PhaseRoute | null, now: Date): string | null;
+/** The evidence line for a task's proposed (or, once approved, sealed) route. */
+export declare function taskEvidenceWords(store: Store, taskId: string, now: Date): string | null;
+/** A rule in words for Settings and the command line. */
+export declare function ruleWords(store: Store, rule: RuleRow): string;
+/** 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 declare const TRIAL_TERMS: Readonly<{
+    places: 10;
+    configuredMinDecided: 10;
+    configuredMinMature: 0.9;
+    days: 90;
+}>;
+export type TrialOffer = {
+    /** `trial:<size>:<model>:<offer>` — what the person starts, and what Not now names. */
+    id: string;
+    repo: string;
+    cohortSize: "small" | "medium";
+    provider: "claude";
+    model: string;
+    name: string;
+    configured: {
+        provider: string;
+        model: string;
+        name: string;
+    };
+    evidence: Evidence;
+    configuredEvidence: Evidence;
+    prices: Prices;
+    depends: Record<string, number>;
+    places: number;
+    offer: {
+        evidence: string;
+        prices: string;
+        depends: string;
+    };
+};
+/** A trial offer's id read back: its cohort, model and the three digest prefixes it was offered under. */
+export declare function readTrialOfferId(id: string): {
+    size: "small" | "medium";
+    model: string;
+    evidence: string;
+    prices: string;
+    depends: string;
+} | 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 declare function trialOfferNow(store: Store, repo: string, size: "small" | "medium", model: string, now: Date): {
+    offer: TrialOffer | null;
+    why: string | null;
+    parts: TrialOffer["offer"] | null;
+};
+/**
+ * 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 declare function trialOffersFor(store: Store, repo: string, now: Date): TrialOffer[];
+/** A trial offer in plain words, the evidence first. */
+export declare function trialOfferWords(offer: TrialOffer): string;
+/** A project's trials a person sees: live (trialling, paused) and, for 30 days, the ones that ended. */
+export declare function trialsOf(store: Store, repo: string, now: Date): RuleRow[];
+/**
+ * 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 declare function startTrial(store: Store, input: {
+    repo: string;
+    id: string;
+}, door: RuleDoor, now: Date): {
+    ok: true;
+    trial: number;
+    offer: TrialOffer;
+} | RuleRefusal;
+/** 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 declare function stopTrial(store: Store, trialId: number, door: RuleDoor, now: Date): {
+    ok: true;
+    trial: RuleRow;
+} | RuleRefusal;
+/** A trial's progress in words, as Settings, the command line and chat say it. */
+export declare function trialWords(store: Store, trial: RuleRow): string;
+/** The project's live trial for a size, as Settings reads it (null when none). */
+export declare function liveTrialOf(store: Store, repo: string, size: "small" | "medium"): RuleRow | null;