tickmarkr 1.30.0

package/dist/plan/prompt.js

@@ -0,0 +1,31 @@
+export function scopePrompt(intent, repair) {
+    return `DROVR-JUDGE
+You are drafting a drovr native spec from an answered intent. Return only the Markdown spec, with no commentary or code fence.
+
+The draft must:
+- start with <!-- drovr:spec -->
+- include a Requirements section whose ids are sequential REQ-01, REQ-02, ...
+- include an Assumptions section that makes every residual uncertainty explicit
+- include a Traceability section mapping every REQ-nn to at least one Tn task
+- use native "## Tn: Title" tasks and only command:, test:, or judge: acceptance entries
+- keep scope guesses advisory in prose; runtime files scope remains authoritative
+
+Intent:
+<intent>
+${intent.trim()}
+</intent>
+${repair ? `
+The previous draft failed validation. Repair it without dropping valid detail.
+
+Validation errors:
+<errors>
+${repair.error}
+</errors>
+
+Previous draft:
+<draft>
+${repair.draft}
+</draft>
+` : ""}
+`;
+}

package/dist/plan/scope.d.ts

@@ -0,0 +1,17 @@
+import type { WorkerAdapter } from "../adapters/types.js";
+import type { DrovrConfig } from "../config/config.js";
+import type { ExecutorDriver } from "../drivers/types.js";
+export declare function clarificationGate(intent: string): string[];
+export interface ScopeOptions {
+    cfg: DrovrConfig;
+    adapters: WorkerAdapter[];
+    driver?: ExecutorDriver;
+    force?: boolean;
+}
+export interface ScopeResult {
+    specFile: string;
+    tasks: number;
+    attempts: number;
+}
+export declare function specPathForIntent(intentFile: string): string;
+export declare function scopeIntent(intentFile: string, repoRoot: string, options: ScopeOptions): Promise<ScopeResult>;

package/dist/plan/scope.js

@@ -0,0 +1,141 @@
+import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { basename, dirname, extname, join } from "node:path";
+import { discoverChannels, getAdapter, probeAll } from "../adapters/registry.js";
+import { compileNative } from "../compile/native.js";
+import { pickDriver } from "../drivers/index.js";
+import { extractJson, runLlm } from "../gates/llm.js";
+import { TaskSchema } from "../graph/schema.js";
+import { route } from "../route/router.js";
+import { scopePrompt } from "./prompt.js";
+const HEADING_RE = /^#{1,6}\s+(.+?)\s*$/;
+const ITEM_RE = /^\s*(?:[-*+]\s+|\d+[.)]\s+)(?:\[[ xX]\]\s*)?(?:[QA]\d*:\s*)?(.+?)\s*$/;
+function sectionItems(source, heading) {
+    const items = [];
+    let active = false;
+    for (const line of source.split("\n")) {
+        const h = line.match(HEADING_RE);
+        if (h) {
+            active = heading.test(h[1]);
+            continue;
+        }
+        if (!active)
+            continue;
+        const item = line.match(ITEM_RE)?.[1].trim();
+        if (item)
+            items.push(item);
+    }
+    return items;
+}
+export function clarificationGate(intent) {
+    const questions = sectionItems(intent, /^blocking questions?$/i);
+    if (questions.length > 3)
+        throw new Error(`intent has ${questions.length} blocking questions; at most 3 blocking questions are allowed`);
+    const answers = sectionItems(intent, /^(?:blocking )?answers?$/i);
+    return questions.filter((_, i) => !answers[i] || /^(?:tbd|todo|unanswered|\?)$/i.test(answers[i]));
+}
+export function specPathForIntent(intentFile) {
+    const ext = extname(intentFile);
+    const stem = basename(intentFile, ext).replace(/\.intent$/i, "");
+    return join(dirname(intentFile), `${stem}.spec.md`);
+}
+function section(source, name) {
+    const lines = source.split("\n");
+    const start = lines.findIndex((line) => new RegExp(`^#{1,6}\\s+${name}\\s*$`, "i").test(line));
+    if (start === -1)
+        return "";
+    const end = lines.findIndex((line, i) => i > start && HEADING_RE.test(line));
+    return lines.slice(start + 1, end === -1 ? undefined : end).join("\n");
+}
+function extractDraft(raw) {
+    const clean = raw.replace(/\nDROVR_EXIT:\d[\s\S]*$/, "").trim();
+    try {
+        const value = JSON.parse(clean);
+        if (typeof value === "string")
+            return value;
+    }
+    catch {
+        // normal adapters return Markdown, not JSON strings
+    }
+    const json = extractJson(clean);
+    const value = json?.spec ?? json?.draft;
+    if (typeof value === "string")
+        return value;
+    const fenced = [...clean.matchAll(/```(?:markdown|md)?\s*\n([\s\S]*?)```/gi)].at(-1)?.[1];
+    if (fenced)
+        return fenced;
+    const marker = clean.indexOf("<!-- drovr:spec");
+    return (marker === -1 ? clean : clean.slice(marker)).trimEnd() + "\n";
+}
+function validateDraft(draft) {
+    if (!/^<!--\s*drovr:spec(?:\s+v1)?\s*-->/m.test(draft))
+        throw new Error("draft is missing the drovr native marker");
+    if (!section(draft, "Assumptions").trim())
+        throw new Error("draft is missing explicit assumptions");
+    const requirements = [...new Set(section(draft, "Requirements").match(/\bREQ-\d{2}\b/g) ?? [])];
+    if (!requirements.length)
+        throw new Error("draft has no REQ-nn requirements");
+    const dir = mkdtempSync(join(tmpdir(), "drovr-scope-compile-"));
+    const file = join(dir, "draft.spec.md");
+    try {
+        writeFileSync(file, draft);
+        const graph = compileNative(file);
+        const trace = section(draft, "Traceability");
+        for (const req of requirements) {
+            const mapped = trace.split("\n").some((line) => line.includes(req) && graph.tasks.some((task) => new RegExp(`\\b${task.id}\\b`).test(line)));
+            if (!mapped)
+                throw new Error(`${req} is not mapped to a task in Traceability`);
+        }
+        const plain = graph.tasks.flatMap((task) => task.acceptance).filter((item) => typeof item === "string");
+        if (plain.length)
+            throw new Error(`draft has ${plain.length} untyped acceptance item${plain.length === 1 ? "" : "s"}`);
+        return graph.tasks.length;
+    }
+    finally {
+        rmSync(dir, { recursive: true, force: true });
+    }
+}
+export async function scopeIntent(intentFile, repoRoot, options) {
+    if (!existsSync(intentFile))
+        throw new Error(`no such intent file: ${intentFile}`);
+    const intent = readFileSync(intentFile, "utf8");
+    const unanswered = clarificationGate(intent);
+    if (unanswered.length) {
+        throw new Error(`unanswered blocking questions (${unanswered.length}):\n${unanswered.map((q, i) => `${i + 1}. ${q}`).join("\n")}`);
+    }
+    const specFile = specPathForIntent(intentFile);
+    if (existsSync(specFile) && !options.force)
+        throw new Error(`${specFile} already exists; pass --force to overwrite it`);
+    const health = await probeAll(options.adapters);
+    const channels = discoverChannels(options.cfg, options.adapters, health);
+    const planningTask = TaskSchema.parse({
+        id: "SCOPE", title: "Draft native spec", goal: "Draft a compiled native spec", shape: "spec", complexity: 7,
+        acceptance: [{ oracle: "judge", text: "Every requirement maps to a task with typed acceptance oracles" }],
+    });
+    const assignment = route(planningTask, options.cfg, channels).assignment;
+    const adapter = getAdapter(assignment.adapter, options.adapters);
+    const driver = options.cfg.visibility.llm === "pane" ? options.driver ?? pickDriver(options.cfg) : undefined;
+    const name = basename(specFile, ".spec.md");
+    let prompt = scopePrompt(intent);
+    for (let attempts = 1; attempts <= 3; attempts++) {
+        const via = driver ? {
+            driver, name: `scope-${name}-${attempts}-${adapter.id}`, label: "SCOPE",
+            keep: options.cfg.visibility.keepPanes === "forever",
+        } : undefined;
+        const draft = extractDraft(await runLlm(adapter, assignment.model, prompt, repoRoot, via));
+        let tasks;
+        try {
+            tasks = validateDraft(draft);
+        }
+        catch (error) {
+            const message = error.message;
+            if (attempts === 3)
+                throw new Error(`scope draft failed after 2 repair retries:\n${message}`);
+            prompt = scopePrompt(intent, { draft, error: message });
+            continue;
+        }
+        writeFileSync(specFile, draft, options.force ? undefined : { flag: "wx" });
+        return { specFile, tasks, attempts };
+    }
+    throw new Error("unreachable");
+}

package/dist/report/cost.d.ts

@@ -0,0 +1,24 @@
+import { type TokenUsage } from "../adapters/types.js";
+import type { ModelPricing, SubPricing } from "../config/config.js";
+import type { TelemetryRow } from "../run/journal.js";
+export interface CostConfig {
+    models?: Record<string, ModelPricing>;
+    subs?: Record<string, SubPricing>;
+}
+export interface ChannelCost {
+    adapter: string;
+    model: string;
+    channel: string;
+    attempts: number;
+    tasks: number;
+    tokens?: TokenUsage;
+    partialMetering: boolean;
+    apiUsd?: number;
+    amortizedUsd?: [number, number];
+    counterfactualUsd?: number;
+    rate?: ModelPricing;
+    subPlan?: SubPricing;
+    measurable: boolean;
+    reason?: string;
+}
+export declare function estimateCosts(rows: TelemetryRow[], cost?: CostConfig): ChannelCost[];

package/dist/report/cost.js

@@ -0,0 +1,89 @@
+// v1.20 REC-02: pure cost estimation. Turns telemetry usage rows + an operator-maintained price table
+// into per-channel cost estimates with full basis (tokens counted, rate used, rate date) — justification
+// is data, not prose. ABSENT pricing degrades to "not measurable", never a crash or a fake $0. No network
+// anywhere in the path; the price table is operator config copied from LiteLLM's price JSON (spec cost model).
+import { addUsage } from "../adapters/types.js";
+const round6 = (n) => Math.round(n * 1e6) / 1e6; // kill float dust without faking cents precision
+// tokens × per-Mtok rate. Only dimensions with a configured rate are priced; cacheWrite/reasoning carry no
+// rate field (REC-02) so they stay counted-in-basis but unpriced — honest, not silently inflated.
+function apiCost(t, r) {
+    const perMtok = (tokens, rate) => (tokens / 1_000_000) * rate;
+    let usd = perMtok(t.input, r.inPerMtok) + perMtok(t.output, r.outPerMtok);
+    if (t.cacheRead !== undefined && r.cacheReadPerMtok !== undefined)
+        usd += perMtok(t.cacheRead, r.cacheReadPerMtok);
+    return round6(usd);
+}
+function estimateGroup(gr, cost) {
+    const { adapter, model, channel } = gr[0];
+    const attempts = gr.reduce((s, r) => s + (r.attempts ?? 0), 0);
+    // fold only rows that metered tokens; absent stays absent (the one sanctioned addUsage coalesce)
+    let tokens;
+    let metered = 0;
+    for (const r of gr)
+        if (r.tokens) {
+            metered++;
+            tokens = addUsage(tokens, r.tokens);
+        }
+    const partialMetering = metered > 0 && metered < gr.length;
+    const rate = cost.models?.[model];
+    const subPlan = cost.subs?.[adapter];
+    const c = {
+        adapter,
+        model,
+        channel,
+        attempts,
+        tasks: gr.length,
+        partialMetering,
+        measurable: false,
+        ...(tokens ? { tokens } : {}),
+    };
+    if (channel === "api") {
+        if (tokens && rate) {
+            c.apiUsd = apiCost(tokens, rate);
+            c.rate = rate;
+        }
+        else {
+            // fail closed: known rate but no tokens ⇒ unmetered; tokens but no rate ⇒ price unknown
+            c.reason = !tokens ? "unmetered — no token usage recorded" : `no API rate configured for model "${model}"`;
+        }
+    }
+    else {
+        // sub channel: amortized range from the plan (a RANGE — time-varying quotas); counterfactual from
+        // metered tokens × the model's API rate. Each is independent; either may be absent.
+        if (subPlan) {
+            // more windows ⇒ cheaper per window ⇒ low uses High and high uses Low
+            const perWindowLow = subPlan.planMonthly / subPlan.windowsPerMonthHigh;
+            const perWindowHigh = subPlan.planMonthly / subPlan.windowsPerMonthLow;
+            c.amortizedUsd = [round6(attempts * perWindowLow), round6(attempts * perWindowHigh)];
+            c.subPlan = subPlan;
+        }
+        if (tokens && rate) {
+            c.counterfactualUsd = apiCost(tokens, rate);
+            c.rate = rate;
+        }
+        if (c.amortizedUsd === undefined && c.counterfactualUsd === undefined) {
+            // here subPlan is necessarily undefined (else amortized would be set); counterfactual needs tokens+rate
+            c.reason = tokens
+                ? `no sub plan for adapter "${adapter}" and no API rate for model "${model}"`
+                : `no sub plan for adapter "${adapter}" and unmetered`;
+        }
+    }
+    c.measurable = c.apiUsd !== undefined || c.amortizedUsd !== undefined || c.counterfactualUsd !== undefined;
+    return c;
+}
+// Pure: (telemetry rows, price table) → per-channel estimates. Groups by adapter:model (matches the
+// report's existing grouping). Deterministic order: sorted by adapter:model. No I/O, no network.
+export function estimateCosts(rows, cost = {}) {
+    const groups = new Map();
+    for (const r of rows) {
+        const key = `${r.adapter}:${r.model}`;
+        const arr = groups.get(key);
+        if (arr)
+            arr.push(r);
+        else
+            groups.set(key, [r]);
+    }
+    return [...groups.entries()]
+        .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+        .map(([, gr]) => estimateGroup(gr, cost));
+}

package/dist/route/preference.d.ts

@@ -0,0 +1,27 @@
+import { type AuthHealth } from "../adapters/types.js";
+import type { DrovrConfig } from "../config/config.js";
+export interface Disallowed {
+    by: "deny" | "allow";
+    entry: string;
+}
+export declare function excludedChannels(cfg: DrovrConfig, adapters: {
+    id: string;
+}[] | string[], health: Record<string, AuthHealth>): {
+    key: string;
+    d: Disallowed;
+}[];
+export declare function exclusionLine(excluded: {
+    key: string;
+    d: Disallowed;
+}[]): string;
+export declare function preferRanks(c: {
+    adapter: string;
+    model: string;
+}, cfg: DrovrConfig): {
+    shape: string;
+    rank: number;
+}[];
+export declare function disallowedBy(c: {
+    adapter: string;
+    model: string;
+}, routing: DrovrConfig["routing"]): Disallowed | null;

package/dist/route/preference.js

@@ -0,0 +1,49 @@
+import { channelKey, channelsFromConfig } from "../adapters/types.js";
+const adapterIds = (adapters) => typeof adapters[0] === "string" ? adapters : adapters.map((a) => a.id);
+export function excludedChannels(cfg, adapters, health) {
+    const { allow, deny } = cfg.routing;
+    if (!allow && !deny)
+        return [];
+    const out = [];
+    for (const id of adapterIds(adapters)) {
+        if (!health[id]?.installed || !health[id]?.authed)
+            continue;
+        for (const c of channelsFromConfig(id, cfg)) {
+            const d = disallowedBy(c, cfg.routing);
+            if (d)
+                out.push({ key: channelKey(c), d });
+        }
+    }
+    return out;
+}
+export function exclusionLine(excluded) {
+    const parts = excluded.map(({ key, d }) => `${key} (${d.by}: ${d.entry})`);
+    return `routing preference active: ${excluded.length} channel(s) excluded — ${parts.join(", ")}`;
+}
+// T4: the prefer rank a channel holds across the routing map — every shape whose prefer list ranks
+// it, with its 0-based index in that list. Empty ⇒ the channel isn't a prefer target (routes only via
+// tier/floor/cost). Mirrors preferIndex's match grammar (adapter id | channel key) — the authoritative
+// routing comparator in router.ts — never the looser disallowedBy grammar that also bare-matches models.
+export function preferRanks(c, cfg) {
+    const out = [];
+    for (const [shape, entry] of Object.entries(cfg.routing.map)) {
+        const i = (entry.prefer ?? []).findIndex((p) => p === c.adapter || p === channelKey(c));
+        if (i !== -1)
+            out.push({ shape, rank: i });
+    }
+    return out;
+}
+// entries in either list accept adapter id, model id, or adapter:model (grammar A1)
+export function disallowedBy(c, routing) {
+    const { allow, deny } = routing;
+    const matches = (e) => e === c.adapter || e === c.model || e === channelKey(c);
+    const d = [...(deny?.adapters ?? []), ...(deny?.models ?? [])].find(matches);
+    if (d)
+        return { by: "deny", entry: d };
+    if (allow) {
+        const entries = [...(allow.adapters ?? []), ...(allow.models ?? [])];
+        if (!entries.some(matches))
+            return { by: "allow", entry: entries.join(", ") || "(empty allowlist)" };
+    }
+    return null;
+}

package/dist/route/profile.d.ts

@@ -0,0 +1,65 @@
+export interface ProfileRow {
+    shape: string;
+    adapter: string;
+    model: string;
+    channel: string;
+    attempts: number;
+    outcome: "done" | "failed" | "human";
+    durationMs: number;
+    firstAttemptOk?: boolean;
+    gateFails?: number;
+    consults?: number;
+    parkKind?: string;
+    runId?: string;
+    quotaFailover?: true;
+    overrun?: true;
+}
+export interface ProfileCell {
+    n: number;
+    qSum: number;
+    dispatches: number;
+    doneCount: number;
+    quotaHits: number;
+    doneMedianMs?: number;
+    nRaw?: number;
+    overruns?: number;
+}
+export interface RoutingProfile {
+    cells: Map<string, ProfileCell>;
+}
+export declare const NEUTRAL = 0;
+export declare const MIN_SAMPLES = 5;
+export declare const PRIOR_K = 3;
+export declare const PERF_WEIGHT = 0.05;
+export declare const AVAIL_WEIGHT = 0.05;
+export declare const OVERRUN_WEIGHT = 0.05;
+export declare const REF_MS = 600000;
+export declare const EXPLORE_CAP = 5;
+export declare const HALF_LIFE_RUNS = 5;
+export declare const DECAY_CAP = 30;
+export declare function decayWeight(age: number, halfLife?: number): number;
+export declare function explorationBonus(cell: ProfileCell | undefined): number;
+export declare function classify(r: ProfileRow): 1 | 0.5 | 0 | null;
+export declare function buildProfile(rows: ProfileRow[], opts?: {
+    halfLifeRuns?: number;
+}): RoutingProfile;
+export declare function cellOf(profile: RoutingProfile | undefined, shape: string, chKey: string, channel: string): ProfileCell | undefined;
+export declare function cellsOf(profile: RoutingProfile): Generator<{
+    shape: string;
+    chKey: string;
+    channel: string;
+    cell: ProfileCell;
+}>;
+export interface CellSummary {
+    nRaw: number;
+    nEff: number;
+    dispatches: number;
+    quality?: number;
+    quotaHits: number;
+    cold: boolean;
+    exploreRemaining: number;
+}
+export declare function cellSummary(cell: ProfileCell): CellSummary;
+export declare function learnedScore(profile: RoutingProfile | undefined, shape: string, chKey: string, channel: string, opts?: {
+    availWeight?: number;
+}): number;

package/dist/route/profile.js

@@ -0,0 +1,197 @@
+// v1.6 self-learning routing — Phase 12: pure profile derivation + total scoring.
+// pure: no I/O, no clock, no RNG (grep-pinned by tests/route/profile.test.ts); structural
+// mirror of TelemetryRow & { runId } — route/ must NOT import run/ (layer DAG: run → route).
+// Phase 13 wires learnedScore in as the 4th (last) router sort key; this file only produces it.
+import { channelKey } from "../adapters/types.js";
+// A1 tuning knobs (module constants; promotion to routing.learned.* config is Phase 13's call).
+// Every value preserves totality and exact-neutrality — each is a one-line edit.
+export const NEUTRAL = 0;
+export const MIN_SAMPLES = 5; // n below this ⇒ score exactly 0 ⇒ static sort keys decide (ROUTE-07)
+export const PRIOR_K = 3; // α=β=3 pseudo-count; denom = n + 2·PRIOR_K ≥ 6 > 0 always
+export const PERF_WEIGHT = 0.05; // perf term ∈ (−0.025, +0.025] — strictly below one quality quantum
+export const AVAIL_WEIGHT = 0.05; // conservative default, NOT data-derived; penalty-only — avail ∈ [−AVAIL_WEIGHT, 0],
+// ≤ one quality quantum; a quotaHits=0 cell contributes exactly 0 (pre-ROUTE-12
+// byte-identity for no-throttle profiles)
+export const OVERRUN_WEIGHT = 0.05; // ROUTE-18 (OBS-04): conservative default, NOT data-derived; penalty-only —
+// overrunPen ∈ [−OVERRUN_WEIGHT, 0], ≤ one quality quantum (twin of AVAIL_WEIGHT);
+// an overruns=0 cell contributes exactly 0 (byte-identity for overrun-free profiles).
+export const REF_MS = 600_000; // 10 min; REF_MS/(REF_MS+m) is a total monotone map into (0,1]
+export const EXPLORE_CAP = MIN_SAMPLES; // Phase 14 probe budget in dispatches per (shape × channel); A1 knob (2*MIN_SAMPLES = one edit)
+// ROUTE-11 evidence decay (v1.8). Quality evidence loses influence by run-recency RANK, so a
+// warm-but-bad channel whose luck changed no longer waits the whole RUNS_WINDOW to roll.
+export const HALF_LIFE_RUNS = 5; // conservative default, NOT data-derived (real journal: 18 pre-v1.6 rows — cannot tune)
+// conservative default, NOT data-derived. TWO-part exactness argument:
+//  (granularity) caps weights at ≥ 2^-30 — every weight is an exact dyadic, no underflow;
+//  (magnitude)  weights are multiples of 2^-31 ⇒ qSum stays bit-exact while row-count ≪ 2^21
+//               (= 2^(51-DECAY_CAP)); raising DECAY_CAP past ~40 would need a canonical fold order.
+export const DECAY_CAP = 30;
+// w = 2 ** -min(floor(age/halfLife), DECAY_CAP). age/Infinity = 0 ⇒ weight 1 ⇒ decay-off degenerates
+// to v1.7 exactly. Dyadic power-of-two weights are the load-bearing exactness property: w·q (q dyadic)
+// and every partial sum stay exact in IEEE-754, so the fold is order-insensitive by construction.
+export function decayWeight(age, halfLife = HALF_LIFE_RUNS) {
+    return 2 ** -Math.min(Math.floor(age / halfLife), DECAY_CAP);
+}
+// Phase 14 exploration bonus: an under-observed channel keeps gathering evidence so early bad luck can't
+// starve it permanently (EXP-01). Total by construction — dispatches is a finite non-negative integer counter,
+// the denominator is a compile-time positive constant; no ln/sqrt/data-dependent divide, so none of the
+// NaN/Infinity hazards that killed UCB and inverse-dispatch. No cell ⇒ 0: an UNKNOWN channel is not
+// "under-observed", it is UNOBSERVED — bonusing it would be a discovery-order fairness scheduler (D2 forbids
+// it) and would flip learned.test.ts Row 7. Fund from dispatches, not n: a channel that dispatched but
+// yielded no quality obs (quota parks) has spent its budget — stop probing it, don't probe it forever.
+// ponytail: rank-decay ships in v1.8 (buildProfile below); remaining ceiling = doneMedianMs staleness
+// (perf term is undecayed) and per-cell EWMA as the finer upgrade path.
+export function explorationBonus(cell) {
+    if (!cell)
+        return 0;
+    return Math.max(0, 1 - cell.dispatches / EXPLORE_CAP); // ∈ [0,1]; exactly 0 once dispatches ≥ cap
+}
+const QUALITY_FAIL_PARKS = new Set(["ladder-exhausted", "attempt-cap", "gate-fail"]);
+// Quality observation per row: 1 clean, 0.5 degraded, 0 verified failure, null excluded/unobserved.
+// Uses gateFails/consults, NOT firstAttemptOk/attempts: firstAttemptOk is `attempt===0` at the global
+// loop counter (daemon.ts:347), which quota failovers bump — it would blame the final channel for
+// another channel's quota. gateFails/consults are the quota-immune "merged clean" signals. A future
+// session must NOT "fix" this back to firstAttemptOk.
+// v1.5 rows: optional fields undefined = UNOBSERVED, never 0/false (journal.ts:21-22 — the poisoning bug).
+export function classify(r) {
+    if (r.outcome === "done") {
+        if (r.gateFails === undefined)
+            return r.attempts === 1 ? 1 : null; // v1.5: >1 attempt = quota-vs-retry ambiguous
+        // consults ?? 0 is the ONE deliberate coalesce — safe ONLY behind gateFails !== undefined, because
+        // both fields ship together from the same v1.6 write sites (daemon.ts:120,347). Not the banned pattern.
+        return r.gateFails === 0 && (r.consults ?? 0) === 0 ? 1 : 0.5;
+    }
+    if (r.outcome === "human")
+        return r.parkKind !== undefined && QUALITY_FAIL_PARKS.has(r.parkKind) ? 0 : null;
+    return null; // "failed" exception rows carry channel "-" — structurally excluded below anyway
+}
+// PROF-04/05a: SYMMETRIC channel-class split — `channel` is a REQUIRED param (no default, no api
+// special-casing) so a forgotten arg is a tsc compile error, not a silent "sub". Ceiling: splitting
+// doubles cells per model reachable on both classes; per-cell EXPLORE_CAP/MIN_SAMPLES then means a
+// warm model's evidence can dilute below MIN_SAMPLES per class once api channels warm and fall back to
+// the exactly-neutral score — that is the correct separated-evidence behavior, not a regression.
+const cellKey = (shape, chKey, channel) => `${shape}|${chKey}|${channel}`;
+// ROUTE-15 PARAM-SHAPE: optional trailing opts (not PROF-05 required-param) — default is PROVABLY the module
+// constant and oracle (a) Object.is byte-identity drill guards a wrong default; zero churn on callers.
+export function buildProfile(rows, opts = {}) {
+    const halfLife = opts.halfLifeRuns ?? HALF_LIFE_RUNS;
+    const cells = new Map();
+    const durs = new Map();
+    // ROUTE-11 pre-pass: rank the DISTINCT defined runIds present. String sort of run-YYYYMMDD-HHMMSS
+    // IS chronological — runId content is NEVER parsed. age = numDistinct-1-ascIndex (newest = 0);
+    // runId undefined ⇒ age = numDistinct (strictly oldest, least influence — ROUTE-11a, fail toward
+    // least influence). numDistinct = 0 (no row carries a runId) ⇒ every age = 0 ⇒ every weight = 1 ⇒
+    // byte-identical v1.7 for runId-free inputs. Ranks are relative to the rows present at build time;
+    // a profile is built once per route call from readAllTelemetry, so ages cannot drift within one
+    // in-memory profile object.
+    const sorted = [...new Set(rows.map((r) => r.runId).filter((id) => id !== undefined))].sort();
+    const numDistinct = sorted.length;
+    const ascIndex = new Map(sorted.map((id, i) => [id, i]));
+    const ageOf = (runId) => runId === undefined ? numDistinct : numDistinct - 1 - ascIndex.get(runId);
+    for (const r of rows) {
+        if (r.adapter === "-")
+            continue; // exception row (daemon.ts:387): no real channel, skip entirely
+        const key = cellKey(r.shape, channelKey(r), r.channel);
+        let c = cells.get(key);
+        if (!c) {
+            c = { n: 0, qSum: 0, dispatches: 0, doneCount: 0, quotaHits: 0, nRaw: 0, overruns: 0 };
+            cells.set(key, c);
+            durs.set(key, []);
+        }
+        c.dispatches++; // utilization axis: every real-channel row, regardless of classification (UNDECAYED — EXP-04)
+        if (r.quotaFailover === true || r.parkKind === "quota")
+            c.quotaHits++; // availability fact, never a quality input (ROUTE-12); || not +: a both-marked row counts once
+        if (r.overrun === true)
+            c.overruns = (c.overruns ?? 0) + 1; // ROUTE-18 no-trailer fact (OBS-04), never a quality input; === true only — absent = unobserved (48-03's write side feeds this)
+        const q = classify(r);
+        // w is a power of two and q dyadic ({0, 0.5, 1}) ⇒ every product q·w and every partial sum is EXACT
+        // in IEEE-754 ⇒ the fold stays order-insensitive (v1.7's invariant EXTENDED, not abandoned). Magnitude
+        // headroom: weights are multiples of 2^-31, so exactness holds while row-count ≪ 2^21. nRaw is the
+        // integer undecayed observation count (Phase 28) — never enters the score arithmetic.
+        if (q !== null) {
+            const w = decayWeight(ageOf(r.runId), halfLife);
+            c.n += w;
+            c.qSum += q * w;
+            c.nRaw = (c.nRaw ?? 0) + 1;
+        }
+        if (r.outcome === "done" && Number.isFinite(r.durationMs) && r.durationMs >= 0) {
+            c.doneCount++;
+            durs.get(key).push(r.durationMs);
+        }
+    }
+    for (const [key, list] of durs) {
+        if (list.length === 0)
+            continue;
+        const s = list.slice().sort((a, b) => a - b); // median from a sorted copy ⇒ order-insensitive
+        const mid = s.length >> 1;
+        cells.get(key).doneMedianMs = s.length % 2 ? s[mid] : (s[mid - 1] + s[mid]) / 2;
+    }
+    return { cells };
+}
+// The one keyed lookup helper — Phase 13's provenance never hand-builds Map keys.
+export function cellOf(profile, shape, chKey, channel) {
+    return profile?.cells.get(cellKey(shape, chKey, channel));
+}
+// Phase 28/VIS-05: the ONLY place besides cellKey that knows the key format. report.ts iterates cells
+// via this and NEVER hand-splits a raw key. PROF-04: chKey is `${adapter}:${model}` (contains ":",
+// never "|"); parse channel from the RIGHT (lastIndexOf "|"), shape from the left.
+export function* cellsOf(profile) {
+    for (const key of [...profile.cells.keys()].sort()) {
+        const ci = key.lastIndexOf("|");
+        const channel = key.slice(ci + 1);
+        const rest = key.slice(0, ci);
+        const si = rest.indexOf("|");
+        yield { shape: rest.slice(0, si), chKey: rest.slice(si + 1), channel, cell: profile.cells.get(key) };
+    }
+}
+// Phase 28/VIS-05: the single arithmetic source for the report — report.ts renders, never derives.
+// nRaw ?? 0 coalesces HERE (report.ts bans `?? 0`); cold/exploreRemaining reuse the router thresholds.
+export function cellSummary(cell) {
+    return {
+        nRaw: cell.nRaw ?? 0,
+        nEff: cell.n,
+        dispatches: cell.dispatches,
+        quality: cell.n > 0 ? cell.qSum / cell.n : undefined,
+        quotaHits: cell.quotaHits,
+        cold: cell.n < MIN_SAMPLES,
+        exploreRemaining: Math.max(0, EXPLORE_CAP - cell.dispatches),
+    };
+}
+// Total by construction: every miss returns the explicit NEUTRAL constant; every denominator is a
+// compile-time-positive constant sum; no Record indexing by row strings (the TIER_RANK[typo] scar).
+// Score 0 defers to the static sort keys, which already encode the benchmark-dated tier seeds — a
+// per-channel numeric prior would give differing n=0 scores and break ROUTE-07's byte-identical cold
+// start. Shrinking toward 0 IS shrinking toward the static prior.
+export function learnedScore(profile, shape, chKey, channel, opts = {}) {
+    const availWeight = opts.availWeight ?? AVAIL_WEIGHT;
+    const cell = cellOf(profile, shape, chKey, channel);
+    if (!cell)
+        return NEUTRAL; // unknown channel ⇒ exactly neutral (empty-profile / cold-start leg, ROUTE-07)
+    // Cold-start proof (ROUTE-07): n ≤ nRaw ≤ dispatches and doneCount ≤ dispatches by construction, so a
+    // thin-dispatch cell (dispatches < MIN_SAMPLES) gates ALL THREE terms to literal +0 ⇒ exactly NEUTRAL.
+    // Each term is gated INDEPENDENTLY (no early-exit) so a dispatch-warm/quality-cold HIGH-throttle cell can
+    // still reach the negative avail term the old `n < MIN ⇒ NEUTRAL` exit suppressed.
+    const quality = cell.n < MIN_SAMPLES ? 0 : (cell.qSum + PRIOR_K) / (cell.n + 2 * PRIOR_K) - 0.5; // denom ≥ 2·PRIOR_K > 0
+    // REF_MS/(REF_MS+m), NOT range-normalization (x−min)/(max−min): the latter is 0/0 when all durations
+    // are identical. median ≥ 0 by the build-time filter ⇒ denom ≥ REF_MS > 0. The leading `cell.n < MIN_SAMPLES ||`
+    // is LOAD-BEARING: a null-classified done row bumps doneCount but NOT n (the `n<MIN ⇏ doneCount<MIN` lemma), so
+    // without it a {quotaHits=0, n<MIN, doneCount≥MIN} cell would score a nonzero perf where the old early-exit scored
+    // 0 — a silent ROUTE-07 break. With it, every quotaHits=0 cell is byte-identical to pre-ROUTE-12.
+    const perf = cell.n < MIN_SAMPLES || cell.doneMedianMs === undefined || cell.doneCount < MIN_SAMPLES
+        ? 0
+        : PERF_WEIGHT * (REF_MS / (REF_MS + cell.doneMedianMs) - 0.5);
+    // PENALTY-ONLY availability (ROUTE-12): a throttling channel is less available — deprioritize it without ever
+    // treating quota as a quality signal, ejecting it, or predicting quota. quotaHits=0 ⇒ avail 0 (no-throttle
+    // byte-identity). Gated on dispatches (≥ MIN_SAMPLES > 0 ⇒ positive denominator, no divide-by-zero) INDEPENDENTLY
+    // of n, so the perf n-gate never suppresses the throttle penalty. NOT the symmetric (0.5 − ratio) form.
+    // ROUTE-16: penalty-only CONFIRMED v1.9 (see .overseer/DECISIONS.md 2026-07-11) — Option B (symmetric
+    // 0.5−ratio availability) NOT adopted: no evidence of over-penalization in the real dogfood;
+    // PREFER-STARVATION is an orthogonal hint/exploration finding, not an availability defect.
+    const avail = cell.dispatches < MIN_SAMPLES ? 0 : -availWeight * (cell.quotaHits / cell.dispatches); // ∈ [−availWeight, 0]
+    // PENALTY-ONLY no-trailer overrun (ROUTE-18, OBS-04): a channel that repeatedly burns a whole dispatch
+    // window without ever emitting a trailer is less reliable — deprioritize it without ever treating the overrun
+    // fact as a quality signal, ejecting it, or predicting it. overruns=0 ⇒ overrunPen 0 (overrun-free byte-identity).
+    // Gated on dispatches (≥ MIN_SAMPLES > 0 ⇒ positive denominator, no divide-by-zero) INDEPENDENTLY of n, mirroring
+    // the ROUTE-12 avail term exactly. NOT the symmetric (0.5 − ratio) form (the v1.9 ROUTE-16 penalty-only precedent).
+    const overrunPen = cell.dispatches < MIN_SAMPLES ? 0 : -OVERRUN_WEIGHT * ((cell.overruns ?? 0) / cell.dispatches); // ∈ [−OVERRUN_WEIGHT, 0]
+    return quality + perf + avail + overrunPen; // score ∈ (−0.625, +0.525), finite for every input
+}