@davesheffer/hunch 1.36.0 → 1.37.1

package/dist/core/taskRankEval.js

@@ -0,0 +1,195 @@
+/** Offline evaluation of task-record ranking (dec_66925aa0ee, PR B).
+ *
+ * Leave-one-out over finished task records: for each task T, rank the tasks
+ * that finished before it with a query built from T's own record, and ask
+ * whether the records T evidently needed appear in the five slots. Compared
+ * against the previous behaviour ("latest 3 on the file") with a paired
+ * bootstrap confidence interval. Deterministic: seeded resampling, no clock.
+ *
+ * Ground truth is what the record itself proves T used: an older task that
+ * received or saved a record T applied, that ran the same check T ran on an
+ * overlapping file, or whose violated rule T received. This is a proxy, not a
+ * label; the metric is pre-registered so the ranker cannot be tuned to it and
+ * then evaluated on the same window. */
+import { DEFAULT_WEIGHTS, normalizePath, rankTaskRecords, recordIdsOf, selectTaskSlots } from "./taskRanking.js";
+export const TASK_RANK_EVAL_SCHEMA = "hunch.task-rank-eval/1";
+const GENERIC_TITLES = new Set(["Assistant task", "Claude task"]);
+function tokens(text) {
+    return new Set(text.toLowerCase().split(/[^a-z0-9_]+/).filter((t) => t.length > 2));
+}
+/** What T evidently used from older tasks. */
+export function groundTruth(task, older) {
+    const applied = new Set(task.applied.map((a) => a.record_id));
+    const received = new Set(task.lessons.map((l) => l.record_id));
+    const labels = new Set(task.checks.map((c) => c.label));
+    const files = new Set(task.files.map(normalizePath));
+    const truth = new Set();
+    for (const o of older) {
+        const ids = recordIdsOf(o);
+        const overlap = o.files.some((f) => files.has(normalizePath(f)));
+        if ([...applied].some((id) => ids.has(id))) {
+            truth.add(o.id);
+            continue;
+        }
+        if (overlap && o.checks.some((c) => labels.has(c.label))) {
+            truth.add(o.id);
+            continue;
+        }
+        if (o.conformance.some((c) => c.outcome === "violated" && received.has(c.record_id))) {
+            truth.add(o.id);
+            continue;
+        }
+    }
+    return truth;
+}
+/** T's own record as the query it would have had before editing. */
+export function evalQuery(task) {
+    const files = new Set(task.files.map(normalizePath));
+    return {
+        target: normalizePath(task.files[0] ?? task.title),
+        files,
+        recordIds: new Set(task.lessons.map((l) => l.record_id)),
+        phrase: GENERIC_TITLES.has(task.title) ? null : task.title,
+        now: Date.parse(task.finished_at) || 0,
+    };
+}
+/** A store-free context: IDF over the older set, lexical by token overlap. */
+export function pureContext(older, query) {
+    const df = new Map();
+    for (const r of older)
+        for (const id of recordIdsOf(r))
+            df.set(id, (df.get(id) ?? 0) + 1);
+    const n = Math.max(1, older.length);
+    const lexical = new Map();
+    if (query.phrase) {
+        const q = tokens(query.phrase);
+        let best = 0;
+        const raw = new Map();
+        for (const r of older) {
+            const doc = tokens(`${r.title} ${r.lessons.map((l) => l.title).join(" ")}`);
+            let inter = 0;
+            for (const t of q)
+                if (doc.has(t))
+                    inter++;
+            const score = q.size ? inter / q.size : 0;
+            if (score > 0) {
+                raw.set(r.id, score);
+                best = Math.max(best, score);
+            }
+        }
+        for (const [id, s] of raw)
+            lexical.set(id, s / best);
+    }
+    return {
+        dependents: new Set(), cochange: new Map(), lexical, anchorsAlive: () => 1,
+        ruleStats: (id) => { const d = df.get(id) ?? 0; return { df: d, idf: Math.log((n + 1) / (d + 1)) + 1e-6 }; },
+    };
+}
+export function buildCases(records) {
+    const sorted = [...records].filter((r) => r.state === "completed").sort((a, b) => a.finished_at.localeCompare(b.finished_at) || a.id.localeCompare(b.id));
+    const cases = [];
+    for (let i = 0; i < sorted.length; i++) {
+        const task = sorted[i];
+        if (!task.files.length)
+            continue;
+        const older = sorted.slice(0, i);
+        if (!older.length)
+            continue;
+        const truth = groundTruth(task, older);
+        if (!truth.size)
+            continue;
+        cases.push({ task, file: normalizePath(task.files[0]), older, truth });
+    }
+    return cases;
+}
+export function rankedRanker(weights = DEFAULT_WEIGHTS) {
+    return (c) => {
+        const q = evalQuery(c.task);
+        const ranked = rankTaskRecords(c.older, q, pureContext(c.older, q), weights);
+        return selectTaskSlots(ranked).picks.map((p) => p.ranked.record.id);
+    };
+}
+export const latest3Ranker = (c) => c.older.filter((r) => r.files.map(normalizePath).includes(c.file))
+    .sort((a, b) => b.finished_at.localeCompare(a.finished_at) || a.id.localeCompare(b.id))
+    .slice(0, 3).map((r) => r.id);
+export function scoreRanker(name, ranker, cases) {
+    const hits = [];
+    let rr = 0;
+    for (const c of cases) {
+        const picks = ranker(c).slice(0, 5);
+        const rank = picks.findIndex((id) => c.truth.has(id));
+        hits.push(rank >= 0 ? 1 : 0);
+        if (rank >= 0)
+            rr += 1 / (rank + 1);
+    }
+    const n = cases.length || 1;
+    return { name, hit5: hits.reduce((s, h) => s + h, 0) / n, mrr: rr / n, hits };
+}
+/** xorshift32: deterministic resampling so two runs agree byte for byte. */
+function prng(seed) {
+    let x = seed >>> 0 || 0x9e3779b9;
+    return () => { x ^= x << 13; x >>>= 0; x ^= x >>> 17; x ^= x << 5; x >>>= 0; return x / 0x1_0000_0000; };
+}
+export function pairedBootstrap(a, b, resamples = 1000, seed = 42) {
+    const n = a.length;
+    if (!n)
+        return { mean: 0, ci95: [0, 0] };
+    const diffs = a.map((x, i) => x - (b[i] ?? 0));
+    const mean = diffs.reduce((s, d) => s + d, 0) / n;
+    const rnd = prng(seed);
+    const means = [];
+    for (let r = 0; r < resamples; r++) {
+        let s = 0;
+        for (let i = 0; i < n; i++)
+            s += diffs[Math.floor(rnd() * n)];
+        means.push(s / n);
+    }
+    means.sort((x, y) => x - y);
+    const at = (p) => means[Math.min(means.length - 1, Math.max(0, Math.floor(p * (means.length - 1))))];
+    return { mean, ci95: [at(0.025), at(0.975)] };
+}
+export function evaluateTaskRanking(records, options = {}) {
+    const split = options.split ?? 0.3;
+    const minEvaluated = options.minEvaluated ?? 5;
+    const all = buildCases(records);
+    let cases = all.slice(Math.floor(all.length * (1 - split)));
+    let note = null;
+    if (cases.length < minEvaluated) {
+        cases = all;
+        note = `fewer than ${minEvaluated} cases in the newest ${Math.round(split * 100)}%; evaluated every case`;
+    }
+    const weights = { ...(options.weights ?? DEFAULT_WEIGHTS) };
+    const ranked = scoreRanker("ranked", rankedRanker(weights), cases);
+    const baseline = scoreRanker("latest3", latest3Ranker, cases);
+    const resamples = options.resamples ?? 1000;
+    const delta = pairedBootstrap(ranked.hits, baseline.hits, resamples);
+    let verdict = "inconclusive";
+    if (cases.length < minEvaluated)
+        verdict = "insufficient-data";
+    else if (delta.ci95[0] > 0)
+        verdict = "ranked-better";
+    else if (delta.ci95[1] < 0)
+        verdict = "baseline-better";
+    return {
+        schema: TASK_RANK_EVAL_SCHEMA,
+        tasks: records.length,
+        evaluable: all.length,
+        split: { fraction: split, evaluated: cases.length, note },
+        rankers: [ranked, baseline].map(({ hits: _h, ...rest }) => rest),
+        delta_hit5: { ...delta, resamples },
+        verdict,
+        weights,
+    };
+}
+export function renderRankEval(report) {
+    const pct = (x) => `${(x * 100).toFixed(0)}%`;
+    const lines = [
+        `Task ranking evaluation — ${report.evaluable} evaluable of ${report.tasks} task record(s); evaluated ${report.split.evaluated}${report.split.note ? ` (${report.split.note})` : ` (newest ${Math.round(report.split.fraction * 100)}%)`}`,
+    ];
+    for (const r of report.rankers)
+        lines.push(`  ${r.name.padEnd(8)} Hit@5 ${pct(r.hit5).padStart(4)}  MRR ${r.mrr.toFixed(2)}`);
+    lines.push(`  Δ Hit@5 ranked − latest3: ${(report.delta_hit5.mean * 100).toFixed(0)} pts, 95% CI [${(report.delta_hit5.ci95[0] * 100).toFixed(0)}, ${(report.delta_hit5.ci95[1] * 100).toFixed(0)}] (${report.delta_hit5.resamples} resamples)`);
+    lines.push(`  verdict: ${report.verdict}${report.verdict === "insufficient-data" ? " — keep collecting; the kill rule needs a CI that excludes zero" : ""}`);
+    return lines.join("\n");
+}
+//# sourceMappingURL=taskRankEval.js.map

package/dist/core/taskRanking.d.ts

@@ -0,0 +1,118 @@
+/** Ranking of task records for pre-edit delivery (dec_66925aa0ee).
+ *
+ * Pure functions over plain data: no I/O, no clock, no model. The store gathers
+ * candidates and computes the corpus-level inputs (dependents, co-change, IDF,
+ * lexical scores, anchor liveness); this module gates, scores, slots and
+ * explains. Same inputs always give the same picks, so a selection is
+ * replayable and every line carries the reasons that produced it.
+ *
+ * Design, from the research synthesis: gate before rank (unfiltered injection
+ * is what lost in every negative result), structure over similarity, verified
+ * outcome as the importance proxy, recency as a decayed term with a floor and
+ * never a cutoff, convex weighted sum (not RRF, which degenerates on short
+ * lists), IDF-weighted overlap instead of Jaccard on tiny id sets, slots plus
+ * MMR instead of a flat top-k, one factual reason per pick. */
+import type { TaskRecord } from "./types.js";
+export interface RankingQuery {
+    /** File (posix path) or phrase the agent is working on. */
+    target: string;
+    /** Files this task has already touched (from its ledger). */
+    files: ReadonlySet<string>;
+    /** Record ids delivered, applied or saved in this task so far. */
+    recordIds: ReadonlySet<string>;
+    /** Task title (opt-in) or the hunch_context phrase; null when unknown. */
+    phrase: string | null;
+    /** Milliseconds since epoch; passed in so ranking is replayable. */
+    now: number;
+}
+export interface CochangeStrength {
+    /** Commits in which the file and the target changed together. */
+    count: number;
+    /** count / max(commits touching either), in [0, 1]. */
+    strength: number;
+}
+export interface RankingContext {
+    /** Files that depend on the target or share its component (posix paths). */
+    dependents: ReadonlySet<string>;
+    /** Co-change strength per file, for files that changed with the target. */
+    cochange: ReadonlyMap<string, CochangeStrength>;
+    /** Corpus statistics for a record id across all task records. */
+    ruleStats: (recordId: string) => {
+        idf: number;
+        df: number;
+    };
+    /** bm25 of the query phrase over task title + lesson titles, normalized to the top hit. */
+    lexical: ReadonlyMap<string, number>;
+    /** Fraction of a record's files that still exist; 1 when it names no files. */
+    anchorsAlive: (record: TaskRecord) => number;
+    /** Task ids some later record supersedes; never delivered. */
+    superseded?: ReadonlySet<string>;
+    /** Last time a task line was delivered (ms since epoch), when receipts know. */
+    lastDelivered?: (taskId: string) => number | null;
+}
+export interface RankingWeights {
+    file: number;
+    rules: number;
+    outcome: number;
+    lexical: number;
+    recency: number;
+    workingSet: number;
+}
+/** A prior, not a measurement. Changed only through `hunch task rank-eval`. */
+export declare const DEFAULT_WEIGHTS: Readonly<RankingWeights>;
+export declare const RECENCY_HALF_LIFE_DAYS = 30;
+export declare const RECENCY_FLOOR = 0.1;
+export declare const COCHANGE_MIN_COUNT = 2;
+/** A shared record admits a candidate only when it is informative: present in
+ * at most half of all task records (idf ≥ ln 2). A rule every task receives
+ * says nothing about relatedness; it still contributes to the score, weakly. */
+export declare const RULE_GATE_MIN_IDF: number;
+export type RankingTerm = keyof RankingWeights;
+export interface RankedTask {
+    record: TaskRecord;
+    score: number;
+    terms: Record<RankingTerm, number>;
+    /** Factual reasons, strongest first (weighted term contribution). */
+    reasons: string[];
+    anchorsAlive: number;
+    /** True when the record names the exact target file. */
+    exactFile: boolean;
+    /** True when a delivered rule was violated or a check failed in the record. */
+    problem: boolean;
+}
+export type SlotName = "latest" | "violation" | "relevant";
+export interface SlotPick {
+    slot: SlotName;
+    ranked: RankedTask;
+}
+export interface TaskSelection {
+    picks: SlotPick[];
+    /** Ranked candidates not shown. */
+    more: number;
+    candidates: number;
+    /** How the picks were chosen: the ranker, or the "latest 3" fallback the kill rule imposes. */
+    mode?: "ranked" | "latest";
+}
+/** The pre-ranking behaviour, kept as the baseline and the fallback: the three
+ * most recent records on the exact file, no scoring. */
+export declare function selectLatestTasks(records: readonly TaskRecord[], query: RankingQuery, ctx: RankingContext, limit?: number): TaskSelection;
+export interface SlotOptions {
+    limit?: number;
+    relevant?: number;
+    lambda?: number;
+}
+export declare function normalizePath(path: string): string;
+/** Every record id a task record references: lessons received, applications, saves. */
+export declare function recordIdsOf(record: TaskRecord): Set<string>;
+export declare function recencyTerm(record: TaskRecord, now: number, lastDelivered?: number | null): number;
+export declare function outcomeTerm(record: TaskRecord): {
+    value: number;
+    reason: string | null;
+};
+/** Gate, score and explain one record. Null when the gate rejects it. */
+export declare function rankTaskRecord(record: TaskRecord, query: RankingQuery, ctx: RankingContext, weights?: Readonly<RankingWeights>): RankedTask | null;
+export declare function rankTaskRecords(records: readonly TaskRecord[], query: RankingQuery, ctx: RankingContext, weights?: Readonly<RankingWeights>): RankedTask[];
+/** Jaccard over files ∪ record ids: the similarity MMR penalizes. */
+export declare function taskSimilarity(a: TaskRecord, b: TaskRecord): number;
+/** Slots: latest on the exact file, most recent problem, then relevant by MMR. */
+export declare function selectTaskSlots(ranked: readonly RankedTask[], options?: SlotOptions): TaskSelection;

package/dist/core/taskRanking.js

@@ -0,0 +1,214 @@
+/** A prior, not a measurement. Changed only through `hunch task rank-eval`. */
+export const DEFAULT_WEIGHTS = Object.freeze({
+    file: 0.30, rules: 0.25, outcome: 0.15, lexical: 0.10, recency: 0.10, workingSet: 0.10,
+});
+export const RECENCY_HALF_LIFE_DAYS = 30;
+export const RECENCY_FLOOR = 0.1;
+export const COCHANGE_MIN_COUNT = 2;
+/** A shared record admits a candidate only when it is informative: present in
+ * at most half of all task records (idf ≥ ln 2). A rule every task receives
+ * says nothing about relatedness; it still contributes to the score, weakly. */
+export const RULE_GATE_MIN_IDF = Math.log(2);
+/** The pre-ranking behaviour, kept as the baseline and the fallback: the three
+ * most recent records on the exact file, no scoring. */
+export function selectLatestTasks(records, query, ctx, limit = 3) {
+    const target = normalizePath(query.target);
+    const ranked = records
+        .filter((r) => !ctx.superseded?.has(r.id) && recordFiles(r).includes(target))
+        .map((r) => rankTaskRecord(r, query, ctx))
+        .filter((r) => r !== null)
+        .sort(newestFirst);
+    const picks = ranked.slice(0, Math.max(1, limit)).map((r) => ({ slot: "latest", ranked: r }));
+    return { picks, more: ranked.length - picks.length, candidates: ranked.length, mode: "latest" };
+}
+const DAY_MS = 86_400_000;
+export function normalizePath(path) {
+    return path.trim().replace(/\\/g, "/").replace(/^\.\//, "");
+}
+/** Every record id a task record references: lessons received, applications, saves. */
+export function recordIdsOf(record) {
+    const ids = new Set();
+    for (const l of record.lessons)
+        ids.add(l.record_id);
+    for (const a of record.applied)
+        ids.add(a.record_id);
+    for (const s of record.saved)
+        ids.add(s.record_id);
+    return ids;
+}
+function recordFiles(record) {
+    return record.files.map(normalizePath);
+}
+/** Age from the later of finishing and the last delivery: a record that keeps
+ * being delivered stays warm (access-based decay, as in Generative Agents). */
+function ageDays(record, now, lastDelivered = null) {
+    const finished = Date.parse(record.finished_at);
+    const anchor = Math.max(Number.isFinite(finished) ? finished : Number.NEGATIVE_INFINITY, lastDelivered ?? Number.NEGATIVE_INFINITY);
+    if (!Number.isFinite(anchor))
+        return Number.POSITIVE_INFINITY;
+    return Math.max(0, (now - anchor) / DAY_MS);
+}
+export function recencyTerm(record, now, lastDelivered = null) {
+    const days = ageDays(record, now, lastDelivered);
+    if (!Number.isFinite(days))
+        return RECENCY_FLOOR;
+    return Math.max(RECENCY_FLOOR, Math.pow(0.5, days / RECENCY_HALF_LIFE_DAYS));
+}
+export function outcomeTerm(record) {
+    if (record.conformance.some((c) => c.outcome === "violated"))
+        return { value: 1, reason: "RULE VIOLATED" };
+    if (record.checks.some((c) => c.state === "failed" || c.state === "timed out"))
+        return { value: 0.8, reason: "check failed" };
+    if (record.saved.length)
+        return { value: 0.6, reason: `saved ${record.saved[0].record_id}${record.saved.length > 1 ? ` +${record.saved.length - 1}` : ""}` };
+    if (record.applied.some((a) => a.supported_by))
+        return { value: 0.5, reason: "applied a rule (rule-supported)" };
+    if (record.checks.some((c) => c.state === "passed"))
+        return { value: 0.3, reason: "check passed" };
+    return { value: 0, reason: null };
+}
+function humanAge(days) {
+    if (!Number.isFinite(days))
+        return "undated";
+    if (days < 1)
+        return "today";
+    if (days < 2)
+        return "yesterday";
+    return `${Math.floor(days)} days ago`;
+}
+function clip(text, max) {
+    return text.length <= max ? text : `${text.slice(0, max - 1).trimEnd()}…`;
+}
+/** Gate, score and explain one record. Null when the gate rejects it. */
+export function rankTaskRecord(record, query, ctx, weights = DEFAULT_WEIGHTS) {
+    const target = normalizePath(query.target);
+    if (ctx.superseded?.has(record.id))
+        return null; // a later task verified over it
+    const files = recordFiles(record);
+    const alive = files.length ? ctx.anchorsAlive(record) : 1;
+    if (files.length && alive === 0)
+        return null; // nothing it names still exists
+    // --- file: same file 1, dependent / same component 0.5, co-change 0.3 × strength-ish
+    const exactFile = files.includes(target);
+    const dependent = !exactFile && files.some((f) => ctx.dependents.has(f));
+    let cochangeHit = null;
+    if (!exactFile && !dependent) {
+        for (const f of files) {
+            const c = ctx.cochange.get(f);
+            if (c && c.count >= COCHANGE_MIN_COUNT && (!cochangeHit || c.count > cochangeHit.count))
+                cochangeHit = { file: f, count: c.count };
+        }
+    }
+    const fileValue = exactFile ? 1 : dependent ? 0.5 : cochangeHit ? 0.3 : 0;
+    // --- rules: IDF-weighted intersection over the current task's own ids
+    const ids = recordIdsOf(record);
+    const shared = [];
+    let queryMass = 0;
+    for (const id of query.recordIds) {
+        const s = ctx.ruleStats(id);
+        queryMass += s.idf;
+        if (ids.has(id))
+            shared.push({ id, ...s });
+    }
+    const rulesValue = queryMass > 0 ? Math.min(1, shared.reduce((sum, s) => sum + s.idf, 0) / queryMass) : 0;
+    // --- gate: structure or an informative shared rule; lexical/recency/outcome alone never admit
+    const informative = shared.some((s) => s.idf >= RULE_GATE_MIN_IDF);
+    if (fileValue === 0 && !informative)
+        return null;
+    const outcome = outcomeTerm(record);
+    const lexicalValue = Math.max(0, Math.min(1, ctx.lexical.get(record.id) ?? 0));
+    const lastDelivered = ctx.lastDelivered?.(record.id) ?? null;
+    const recencyValue = recencyTerm(record, query.now, lastDelivered);
+    const touched = files.filter((f) => query.files.has(f));
+    const workingSetValue = query.files.size ? Math.min(1, touched.length / query.files.size) : 0;
+    const terms = {
+        file: fileValue, rules: rulesValue, outcome: outcome.value, lexical: lexicalValue, recency: recencyValue, workingSet: workingSetValue,
+    };
+    const score = Object.keys(terms).reduce((sum, k) => sum + weights[k] * terms[k], 0);
+    // --- reasons, ordered by weighted contribution
+    const reasons = [];
+    if (exactFile)
+        reasons.push({ weight: weights.file * 1, text: "same file" });
+    else if (dependent)
+        reasons.push({ weight: weights.file * 0.5, text: `dependent of ${target}` });
+    else if (cochangeHit)
+        reasons.push({ weight: weights.file * 0.3, text: `co-changed with ${target} in ${cochangeHit.count} commits` });
+    if (shared.length) {
+        const top = [...shared].sort((a, b) => b.idf - a.idf)[0];
+        reasons.push({ weight: weights.rules * rulesValue, text: `shares ${top.id}${top.df ? ` (${top.df === 1 ? "only here" : `${top.df} tasks`})` : ""}${shared.length > 1 ? ` +${shared.length - 1}` : ""}` });
+    }
+    if (outcome.reason)
+        reasons.push({ weight: weights.outcome * outcome.value, text: outcome.reason });
+    if (lexicalValue > 0 && query.phrase)
+        reasons.push({ weight: weights.lexical * lexicalValue, text: `matches "${clip(query.phrase, 40)}"` });
+    if (touched.length)
+        reasons.push({ weight: weights.workingSet * workingSetValue, text: `also touched ${touched[0]} this task` });
+    const finishedAge = ageDays(record, query.now);
+    const effectiveAge = ageDays(record, query.now, lastDelivered);
+    reasons.push({ weight: weights.recency * recencyValue, text: effectiveAge < finishedAge ? `delivered ${humanAge(effectiveAge)}` : humanAge(finishedAge) });
+    if (alive < 1)
+        reasons.push({ weight: 0, text: "files since changed" });
+    reasons.sort((a, b) => b.weight - a.weight);
+    return {
+        record, score, terms, reasons: reasons.map((r) => r.text), anchorsAlive: alive, exactFile,
+        problem: outcome.value >= 0.8,
+    };
+}
+/** Newest first, then id — the tie order the research insists on. */
+function newestFirst(a, b) {
+    return b.record.finished_at.localeCompare(a.record.finished_at) || a.record.id.localeCompare(b.record.id);
+}
+export function rankTaskRecords(records, query, ctx, weights = DEFAULT_WEIGHTS) {
+    const ranked = [];
+    for (const record of records) {
+        const r = rankTaskRecord(record, query, ctx, weights);
+        if (r)
+            ranked.push(r);
+    }
+    return ranked.sort((a, b) => (b.score - a.score) || newestFirst(a, b));
+}
+/** Jaccard over files ∪ record ids: the similarity MMR penalizes. */
+export function taskSimilarity(a, b) {
+    const sa = new Set([...recordFiles(a), ...recordIdsOf(a)]);
+    const sb = new Set([...recordFiles(b), ...recordIdsOf(b)]);
+    if (!sa.size && !sb.size)
+        return 0;
+    let inter = 0;
+    for (const x of sa)
+        if (sb.has(x))
+            inter++;
+    return inter / (sa.size + sb.size - inter);
+}
+/** Slots: latest on the exact file, most recent problem, then relevant by MMR. */
+export function selectTaskSlots(ranked, options = {}) {
+    const limit = Math.max(1, options.limit ?? 5);
+    const relevantMax = Math.max(0, options.relevant ?? 3);
+    const lambda = options.lambda ?? 0.7;
+    const picks = [];
+    const taken = new Set();
+    const take = (slot, r) => { picks.push({ slot, ranked: r }); taken.add(r.record.id); };
+    const latest = [...ranked].filter((r) => r.exactFile).sort(newestFirst)[0];
+    if (latest)
+        take("latest", latest);
+    const violation = [...ranked].filter((r) => r.problem && !taken.has(r.record.id)).sort(newestFirst)[0];
+    if (violation && picks.length < limit)
+        take("violation", violation);
+    let remaining = ranked.filter((r) => !taken.has(r.record.id));
+    while (picks.length < limit && picks.length - (latest ? 1 : 0) - (violation ? 1 : 0) < relevantMax && remaining.length) {
+        let best = null, bestValue = -Infinity;
+        for (const r of remaining) {
+            const redundancy = picks.length ? Math.max(...picks.map((p) => taskSimilarity(p.ranked.record, r.record))) : 0;
+            const value = lambda * r.score - (1 - lambda) * redundancy;
+            if (value > bestValue || (value === bestValue && best && newestFirst(r, best) < 0)) {
+                best = r;
+                bestValue = value;
+            }
+        }
+        if (!best)
+            break;
+        take("relevant", best);
+        remaining = remaining.filter((r) => r !== best);
+    }
+    return { picks, more: ranked.length - picks.length, candidates: ranked.length, mode: "ranked" };
+}
+//# sourceMappingURL=taskRanking.js.map

package/dist/core/taskRankingMode.d.ts

@@ -0,0 +1,36 @@
+import type { HunchStore } from "../store/hunchStore.js";
+import { type RankEvalReport } from "./taskRankEval.js";
+export declare const RANK_EVAL_CACHE_SCHEMA: "hunch.task-rank-eval-cache/1";
+/** The decision's threshold: the kill rule needs at least this many task records. */
+export declare const KILL_MIN_TASKS = 200;
+export type TaskRankingMode = "ranked" | "latest";
+export interface RankEvalCache {
+    schema: typeof RANK_EVAL_CACHE_SCHEMA;
+    computed_at: string;
+    /** Task-record count the report was computed over; a different count triggers a recompute. */
+    records: number;
+    /** Content hash of the record ids + report hashes, so an edit without a count change also refreshes. */
+    corpus_hash: string;
+    report: RankEvalReport;
+}
+export declare function readRankEvalCache(root: string): RankEvalCache | null;
+/** Recompute when the corpus changed; otherwise return the cached report. Never throws. */
+export declare function refreshRankEval(root: string, store: HunchStore, options?: {
+    force?: boolean;
+    now?: () => string;
+}): RankEvalCache | null;
+/** The rule from the decision, applied to a report. */
+export declare function modeFromReport(report: RankEvalReport | null | undefined): {
+    mode: TaskRankingMode;
+    reason: string;
+};
+export interface ResolvedRankingMode {
+    mode: TaskRankingMode;
+    reason: string;
+    source: "override" | "auto";
+    cache: RankEvalCache | null;
+}
+/** What delivery should do right now for this repository. */
+export declare function resolveTaskRankingMode(root: string, store: HunchStore): ResolvedRankingMode;
+/** One line for `hunch now` and the task stats. */
+export declare function rankingStatusLine(resolved: ResolvedRankingMode): string;