@quickchatai/quickreview 0.0.0-stage → 1.1.0

package/dist/src/memory/selection.js

@@ -0,0 +1,690 @@
+// Lesson selection: which curated lessons and which past finding cases a
+// round would carry — pure, deterministic, no I/O.
+//
+// The round's prefetch (src/lessonselect.ts) asks OpenViking two
+// `/search/find`s under a hard budget (a find per plan row does not answer
+// inside it): one inside `memories/experiences/` with a round-level query and
+// a `limit` sized to cover the whole lesson corpus (`lessonFindLimit`, from the store's
+// own count, bounded), and ONE for the main session inside
+// `memories/finding-cases/`. Every row, the validator and every lens the
+// session may add then filter that ONE answer for themselves. What comes back
+// is a ranked list of hits by the ENGINE's score — semantic similarity, which
+// knows nothing of lenses, paths or retirements; with the limit covering the
+// corpus the score decides nothing at all. This module turns those hits into
+// a selection with rules a person can read:
+//
+//   FILTER (on the typed header — src/memory/lessons.ts `parseLesson`, the
+//   header only, so quoted prose in a body can never make a lesson eligible):
+//     * the hit is a file inside the area that was searched (never a folder
+//       blurb, never another area's entry the server let through);
+//     * never `#retired`, never a move's `#moved` stub, never a URI on the
+//       store's retired list, never a URI the operator SUPPRESSED (the kill
+//       switch, `commands/operator/` → state.db — src/lessonledger.ts);
+//     * a lesson (a typed header, or one of the legacy shapes the tolerant
+//       reader knows) whose polarity is known — a lesson nobody can tell is
+//       a "look for" or a "don't raise" is delivered to nobody;
+//     * the row's lens is in its `lens=` (a lesson naming no lens — the
+//       legacy conventions — is for every lens);
+//     * one of its `paths=` globs matches one of the row's files, when it
+//       names any;
+//     * created strictly before `as_of`, when a replay sets one (a temporal
+//       hold-out: a lesson the replayed PR's own outcome produced must not
+//       grade that PR). A lesson whose creation date cannot be read is not
+//       provably older, so it is out.
+//   RANK (deterministic — the engine's score only decided which hits came
+//   back, never their order here): pinned > a `paths=` glob hit > a `lens=`
+//   hit > evidence count > recency > URI.
+//   CAP per role (`SELECTION_CAPS`): items and an estimated token budget,
+//   greedy in rank order; EVERY lesson cut is listed with why.
+//
+// A CASE (src/cases.ts) is filtered on its own header: `#case kind=case`, not
+// withdrawn, about a file this PR changes, from ANOTHER PR (the session has
+// this PR's own history in its ledger), posted before `as_of`. Ranked by a
+// shared lens > the replies it drew > recency > URI.
+//
+// Under `[memory] delivery = "shadow"` (the shipped value) the selection is
+// only what the shadow ledger records; under `on` it is also what is
+// delivered (src/memory/delivery.ts renders it) — the lenses a session may ADD
+// included (one shared find, filtered per lens), and, for the recheck and the
+// ping-pong wake, the repo facts for the paths they touch
+// (`selectRepoFacts`).
+import { globMatcherOrNothing } from "@quickchatai/pi-quickreview/src/glob.js";
+import { canonicalLensIds } from "@quickchatai/pi-quickreview/src/lensids.js";
+import { roundContextQuery } from "./context.js";
+import { parseEventTags, parseHashTags } from "./eventtags.js";
+import { CASES_AREA, EXPERIENCES_AREA, PINNED_AREA, isRetired } from "./layout.js";
+import { parseLesson } from "./lessons.js";
+import { VALIDATOR_LENS } from "@quickchatai/pi-quickreview/src/memoryport.js";
+/** The validator's lens id — it has no task file and judges every finding
+ * (the delivery's, packages/pi-plugin/src/memoryport.ts). */
+export { VALIDATOR_LENS };
+/** What each role may carry: items and an ESTIMATED token budget. */
+export const SELECTION_CAPS = Object.freeze({
+    /** One lens row's task file. */
+    row: Object.freeze({ items: 6, tokens: 1200 }),
+    /** The main session's "past reviews of these files". */
+    cases: Object.freeze({ items: 8, tokens: 2000 }),
+    /** The validator's lesson addendum. */
+    validator: Object.freeze({ items: 20, tokens: 2500 }),
+});
+/** How many hits the main session's cases find asks for. The finding-case
+ * area is large (a case per answered finding) and the query names the PR's
+ * paths; the filter keeps only cases about those paths. */
+export const FIND_LIMITS = Object.freeze({ cases: 40 });
+/**
+ * The bounds of a lesson find's `limit`. One find inside `experiences/`
+ * serves every role of a round (and the recheck's repo facts), so it asks for
+ * the whole lesson corpus: the filters, the ranking and the caps all run
+ * here, and none of them reads the engine's score. `min` keeps a small
+ * corpus's find at the size a shared find has always asked for; `max`
+ * bounds the answer's size for a corpus that outgrows it — past it the
+ * round-level query's similarity decides which entries come back, recorded
+ * on the `lesson_selection` event (`corpus` > `limit`).
+ */
+export const LESSON_FIND_LIMIT = Object.freeze({ min: 40, max: 200 });
+/**
+ * The lesson find's `limit` for a corpus of `corpus` files in `experiences/`
+ * (the store's last sweep — `LessonEngine.corpusSize`): twice the count plus
+ * eight, within `LESSON_FIND_LIMIT`. The headroom is for what the engine
+ * returns that is not one lesson file each — the area's own directory record,
+ * an engine blurb, a file indexed more than once — all dropped by the
+ * filter, but each takes a place in the top K.
+ * An unknown corpus (no sweep yet) asks for the ceiling: coverage first, and
+ * the limit only sizes the answer — the query is embedded once either way.
+ */
+export function lessonFindLimit(corpus) {
+    if (corpus === null || corpus === undefined || !Number.isFinite(corpus) || corpus < 0)
+        return LESSON_FIND_LIMIT.max;
+    return Math.max(LESSON_FIND_LIMIT.min, Math.min(LESSON_FIND_LIMIT.max, 2 * Math.ceil(corpus) + 8));
+}
+/** Characters per token for the caps' estimate — the usual English ratio. */
+export const CHARS_PER_TOKEN = 4;
+export function estimateTokens(text) {
+    return Math.max(1, Math.ceil(text.trim().length / CHARS_PER_TOKEN));
+}
+/** `20260824T153000-…` / `20260824-eod-…` → `2026-08-24[T15:30:00]`; null when
+ * the file name carries no date. */
+export function createdOfUri(uri) {
+    const name = uri.slice(uri.lastIndexOf("/") + 1);
+    const m = /^(\d{4})(\d{2})(\d{2})(?:T(\d{2})(\d{2})(\d{2}))?/.exec(name);
+    if (!m)
+        return null;
+    const day = `${m[1]}-${m[2]}-${m[3]}`;
+    return m[4] !== undefined ? `${day}T${m[4]}:${m[5]}:${m[6]}` : day;
+}
+/** Is `uri` a FILE directly addressable under `<root>/<area>/` (never a
+ * folder, never the engine's `.abstract.md`/`.overview.md` blurbs)? */
+export function inArea(uri, root, area) {
+    const prefix = `${root.replace(/\/+$/, "")}/${area}/`;
+    if (!uri.startsWith(prefix))
+        return false;
+    const rest = uri.slice(prefix.length);
+    const base = rest.slice(rest.lastIndexOf("/") + 1);
+    // `experiences/` holds files directly; a deeper path is another area
+    // (`preferences/pinned/` under `preferences/`) or something we never write.
+    if (rest.includes("/"))
+        return false;
+    return base.endsWith(".md") && !base.startsWith(".");
+}
+/** A hit's engine score, or 0 when it is missing or not finite. */
+function finiteScore(score) {
+    return typeof score === "number" && Number.isFinite(score) ? score : 0;
+}
+/** The score as the ledger records it: three decimals. */
+function recordedScore(score) {
+    return Math.round(score * 1000) / 1000;
+}
+function cmp(a, b) {
+    return a < b ? -1 : a > b ? 1 : 0;
+}
+/** Sort by URI and keep one hit per URI (the highest score), so the order the
+ * engine returned them in can never change what is selected. */
+function dedupeHits(hits) {
+    const best = new Map();
+    let duplicates = 0;
+    for (const h of hits) {
+        if (typeof h?.uri !== "string" || h.uri === "")
+            continue;
+        const prev = best.get(h.uri);
+        if (prev) {
+            duplicates += 1;
+            if ((h.score ?? 0) > (prev.score ?? 0))
+                best.set(h.uri, h);
+        }
+        else
+            best.set(h.uri, h);
+    }
+    return { hits: [...best.values()].sort((a, b) => cmp(a.uri, b.uri)), duplicates };
+}
+function bump(d, reason, n = 1) {
+    d[reason] = (d[reason] ?? 0) + n;
+}
+/** Retired or moved, by the store's list or by the entry's own header. */
+function retiredState(uri, text, retired) {
+    const hash = parseHashTags(text.trim());
+    if (hash.includes("moved"))
+        return "moved";
+    if (hash.includes("retired") || retired.has(uri))
+        return "retired";
+    return null;
+}
+function beforeAsOf(created, asOf) {
+    if (!asOf)
+        return true;
+    if (created === null)
+        return false;
+    return created.slice(0, 10) < asOf.slice(0, 10);
+}
+/**
+ * The hits that may be selected for one lens, and how many were dropped for
+ * each reason. Pure; the order of `hits` does not matter.
+ */
+export function filterLessonHits(hits, ctx) {
+    const dropped = {};
+    const { hits: unique, duplicates } = dedupeHits(hits);
+    if (duplicates > 0)
+        bump(dropped, "duplicate", duplicates);
+    const eligible = [];
+    for (const h of unique) {
+        const text = typeof h.text === "string" ? h.text : "";
+        if (!inArea(h.uri, ctx.root, EXPERIENCES_AREA)) {
+            bump(dropped, "out_of_area");
+            continue;
+        }
+        const gone = retiredState(h.uri, text, ctx.retired);
+        if (gone) {
+            bump(dropped, gone);
+            continue;
+        }
+        if (ctx.suppressed.has(h.uri)) {
+            bump(dropped, "suppressed");
+            continue;
+        }
+        const lesson = parseLesson(text);
+        if (!lesson) {
+            bump(dropped, "not_lesson");
+            continue;
+        }
+        if (lesson.kind === null) {
+            bump(dropped, "kind_unknown");
+            continue;
+        }
+        if (ctx.lens !== null && lesson.lens.length > 0 && !lesson.lens.includes(ctx.lens)) {
+            bump(dropped, "lens");
+            continue;
+        }
+        const pathHit = pathHitOn(lesson, ctx.files);
+        if (lesson.paths.length > 0 && !pathHit) {
+            bump(dropped, "paths");
+            continue;
+        }
+        const created = createdOfUri(h.uri);
+        if (!beforeAsOf(created, ctx.asOf)) {
+            bump(dropped, "as_of");
+            continue;
+        }
+        eligible.push({
+            uri: h.uri,
+            text: text.trim(),
+            score: finiteScore(h.score),
+            created,
+            lesson: lesson,
+            tokens: estimateTokens(text),
+            pinned: h.uri.includes(`/memories/${PINNED_AREA}/`),
+            pathHit,
+        });
+    }
+    return { eligible, dropped };
+}
+/** Does the lesson's `paths=` precondition match any of `files`? A lesson
+ * with no paths is no hit; a glob list the compiler refuses matches nothing. */
+function pathHitOn(lesson, files) {
+    return lesson.paths.length > 0 && files.some(globMatcherOrNothing(lesson.paths));
+}
+/** Ranking keys, most significant first; every key is "higher first" except
+ * the URI, the final tie-break. */
+function lessonKey(c, lens) {
+    return [
+        c.pinned ? 1 : 0,
+        c.pathHit ? 1 : 0,
+        c.lesson.lens.includes(lens) ? 1 : 0,
+        c.lesson.evidence.length,
+        c.created ?? "",
+    ];
+}
+function compareKeys(a, b) {
+    for (let i = 0; i < a.length; i++) {
+        const x = a[i];
+        const y = b[i];
+        if (x === y)
+            continue;
+        return x > y ? -1 : 1;
+    }
+    return 0;
+}
+/** Deterministic order: pinned > path-glob hit > lens hit > evidence count >
+ * recency > URI. The engine's score is not a key. */
+export function rankLessons(cands, lens) {
+    return [...cands].sort((a, b) => compareKeys(lessonKey(a, lens), lessonKey(b, lens)) || cmp(a.uri, b.uri));
+}
+/** Greedy in rank order: an item past the item cap, or one that would take
+ * the role over its token budget, is CUT (and listed); a smaller one after
+ * it may still fit. */
+export function capSelection(ranked, cap) {
+    const selected = [];
+    const cuts = [];
+    let used = 0;
+    for (const c of ranked) {
+        if (selected.length >= cap.items) {
+            cuts.push({ uri: c.uri, reason: "items" });
+            continue;
+        }
+        if (used + c.tokens > cap.tokens) {
+            cuts.push({ uri: c.uri, reason: "tokens" });
+            continue;
+        }
+        selected.push(c);
+        used += c.tokens;
+    }
+    return { selected, cuts };
+}
+/** A case header value, decoded (src/cases.ts `tagValue` encodes `%`, the
+ * whitespace and control bytes as `%XX`, or wide code units as `%uXXXX`). */
+function decodeTagValue(v) {
+    return v.replace(/%u([0-9A-Fa-f]{4})|%([0-9A-Fa-f]{2})/g, (_m, wide, byte) => String.fromCharCode(parseInt(wide ?? byte, 16)));
+}
+/** A finding case's header, or null when the text is not a live case (no
+ * `#case kind=case` header, or withdrawn/retired). Header only. */
+export function parseCaseHeader(text) {
+    const t = text.trim();
+    const hash = parseHashTags(t);
+    if (!hash.includes("case") || hash.includes("retired") || hash.includes("moved"))
+        return null;
+    const tags = parseEventTags(t);
+    if (tags["kind"] !== "case")
+        return null;
+    const pr = tags["pr"] !== undefined && /^\d{1,9}$/.test(tags["pr"]) ? Number(tags["pr"]) : null;
+    const replies = tags["replies"] !== undefined && /^\d{1,6}$/.test(tags["replies"]) ? Number(tags["replies"]) : 0;
+    return {
+        pr,
+        path: tags["path"] !== undefined ? decodeTagValue(tags["path"]) : null,
+        lens: canonicalLensIds(tags["lens"] ?? ""),
+        fate: tags["fate"] ?? null,
+        posted: tags["posted"] ?? null,
+        replies,
+    };
+}
+export function filterCaseHits(hits, ctx) {
+    const dropped = {};
+    const { hits: unique, duplicates } = dedupeHits(hits);
+    if (duplicates > 0)
+        bump(dropped, "duplicate", duplicates);
+    const files = new Set(ctx.files);
+    const eligible = [];
+    for (const h of unique) {
+        const text = typeof h.text === "string" ? h.text : "";
+        if (!inArea(h.uri, ctx.root, CASES_AREA)) {
+            bump(dropped, "out_of_area");
+            continue;
+        }
+        if (ctx.retired.has(h.uri) || isRetired(text.trim())) {
+            bump(dropped, "retired");
+            continue;
+        }
+        if (ctx.suppressed.has(h.uri)) {
+            bump(dropped, "suppressed");
+            continue;
+        }
+        const header = parseCaseHeader(text);
+        if (!header) {
+            bump(dropped, "not_case");
+            continue;
+        }
+        if (header.pr === ctx.pr) {
+            bump(dropped, "same_pr");
+            continue;
+        }
+        if (header.path === null || !files.has(header.path)) {
+            bump(dropped, "paths");
+            continue;
+        }
+        if (!beforeAsOf(header.posted, ctx.asOf)) {
+            bump(dropped, "as_of");
+            continue;
+        }
+        eligible.push({
+            uri: h.uri,
+            text: text.trim(),
+            score: finiteScore(h.score),
+            header,
+            tokens: estimateTokens(text),
+            lensHit: header.lens.some((l) => ctx.lenses.includes(l)),
+        });
+    }
+    return { eligible, dropped };
+}
+/** Deterministic: a shared lens > replies drawn > recency > URI. */
+export function rankCases(cands) {
+    return [...cands].sort((a, b) => compareKeys([a.lensHit ? 1 : 0, a.header.replies, a.header.posted ?? ""], [b.lensHit ? 1 : 0, b.header.replies, b.header.posted ?? ""]) || cmp(a.uri, b.uri));
+}
+const QUERY_MAX_CHARS = 600;
+/** A lens id as a query word: `pass-data-safety` → `data-safety`. */
+function lensWord(lens) {
+    return lens.replace(/^pass-/, "");
+}
+/**
+ * The query of the round's one lesson find: the PR title and the
+ * shape of its changed files (the round context query's own builder — the
+ * changed areas and extensions, a function of the file SET), then the
+ * planned lenses, sorted. With the find's limit covering the corpus the query
+ * only matters once the corpus outgrows `LESSON_FIND_LIMIT.max`.
+ */
+export function roundLessonQuery(input) {
+    const base = roundContextQuery({ title: input.title, files: input.files.map((filename) => ({ filename })) });
+    const lenses = [...new Set(input.lenses.map(lensWord).filter((w) => w !== ""))].sort().join(" ");
+    return [base, lenses].filter((p) => p !== "").join(" — ").slice(0, QUERY_MAX_CHARS);
+}
+/** The main session's cases query: the title and the changed paths, sorted
+ * (a function of the file SET). */
+export function casesQuery(input) {
+    const title = input.title.replace(/\s+/g, " ").trim();
+    const paths = [...new Set(input.files)].sort().slice(0, 12).join(" ");
+    return [title, paths].filter((p) => p !== "").join(" — ").slice(0, QUERY_MAX_CHARS);
+}
+function findKey(area, query) {
+    return `${area}\u0000${query}`;
+}
+/**
+ * The round's finds — at most two: the main session's cases find
+ * (when the PR changes a file), then ONE lesson find inside `experiences/`
+ * that every discovery row, the validator and every lens the session may add
+ * share, its `limit` sized to cover the lesson corpus (`lessonFindLimit` of
+ * `corpus`, the store's count; the ceiling when unknown). Every per-row
+ * decision — lens, `paths=` globs, polarity, `as_of`, suppressed, retired,
+ * moved, caps, ranking — is `selectRound`'s, on that one answer: over an
+ * answer that holds the whole corpus, one shared find gives the same
+ * selection as a find per row (tests/lesson-selection.test.ts).
+ */
+export function planFinds(input) {
+    const finds = [];
+    let casesKey = null;
+    if (input.prFiles.length > 0) {
+        const query = casesQuery({ title: input.title, files: input.prFiles });
+        casesKey = findKey(CASES_AREA, query);
+        finds.push({ key: casesKey, area: CASES_AREA, query, limit: FIND_LIMITS.cases });
+    }
+    const addable = input.addable ?? [];
+    let lessonsKey = null;
+    if (input.rows.length > 0 || addable.length > 0) {
+        const query = roundLessonQuery({
+            title: input.title,
+            files: input.prFiles,
+            lenses: input.rows.map((r) => r.lens),
+        });
+        lessonsKey = findKey(EXPERIENCES_AREA, query);
+        finds.push({
+            key: lessonsKey,
+            area: EXPERIENCES_AREA,
+            query,
+            limit: lessonFindLimit(input.corpus),
+        });
+    }
+    const rowKey = new Map();
+    if (lessonsKey !== null)
+        for (const r of input.rows)
+            rowKey.set(r.row, lessonsKey);
+    return {
+        finds,
+        rowKey,
+        casesKey,
+        addableKey: addable.length > 0 ? lessonsKey : null,
+        lessonsKey,
+    };
+}
+function asSelected(c) {
+    return {
+        uri: c.uri,
+        kind: c.lesson.kind,
+        class: c.lesson.class,
+        lens: [...c.lesson.lens],
+        paths: [...c.lesson.paths],
+        evidence: c.lesson.evidence.length,
+        format: c.lesson.format,
+        tokens: c.tokens,
+        score: recordedScore(c.score),
+        created: c.created,
+    };
+}
+function caseSelected(c) {
+    return {
+        uri: c.uri,
+        pr: c.header.pr,
+        path: c.header.path,
+        lens: [...c.header.lens],
+        fate: c.header.fate,
+        replies: c.header.replies,
+        tokens: c.tokens,
+        score: recordedScore(c.score),
+    };
+}
+/**
+ * The round's selection, one record per role: every discovery row's lessons,
+ * the validator's (the dont-raise lessons any discovery row found eligible,
+ * and every lesson naming `pass-validate` its row's find returned), every
+ * lens the session may add (filtered per lens like a row over the PR's
+ * files), and the main session's cases. Under `planFinds` the rows, the
+ * validator and the addable lenses all read the round's one lesson find; the
+ * function itself takes any plan (each row's answer by its `rowKey`). Pure
+ * and deterministic: the same outcomes in any order give the same records.
+ */
+export function selectRound(input) {
+    const caps = input.caps ?? SELECTION_CAPS;
+    const out = [];
+    const keepText = (c) => {
+        input.texts?.set(c.uri, c.text);
+    };
+    const query = (key) => key ? (input.plan.finds.find((f) => f.key === key)?.query ?? null) : null;
+    const base = { retired: input.retired, suppressed: input.suppressed, asOf: input.asOf ?? null, root: input.root };
+    // Every dont-raise lesson some planned discovery row found eligible — the
+    // validator's candidates beside its own find's. An addable lens's do not
+    // join: an added lens may never run.
+    const dontRaise = new Map();
+    let validatorRow = null;
+    /** A discovery role's selection from its find's hits — planned rows and
+     * addable lenses alike: filtered for its lens and files, ranked, capped. A
+     * planned row's dont-raise lessons also feed the validator's pool. */
+    const selectDiscovery = (rec, hits, files) => {
+        const { eligible, dropped } = filterLessonHits(hits, { ...base, lens: rec.lens, files });
+        rec.dropped = dropped;
+        if (rec.role === "row")
+            for (const c of eligible)
+                if (c.lesson.kind === "dont-raise" && !dontRaise.has(c.uri))
+                    dontRaise.set(c.uri, c);
+        const { selected, cuts } = capSelection(rankLessons(eligible, rec.lens), caps.row);
+        rec.lessons = selected.map(asSelected);
+        selected.forEach(keepText);
+        rec.cuts = cuts;
+    };
+    for (const r of input.rows) {
+        if (r.lens === VALIDATOR_LENS) {
+            validatorRow ??= r;
+            continue;
+        }
+        const key = input.plan.rowKey.get(r.row);
+        const rec = {
+            role: "row",
+            row: r.row,
+            lens: r.lens,
+            agent: r.agent,
+            query: query(key),
+            status: "ok",
+            lessons: [],
+            cases: [],
+            cuts: [],
+            dropped: {},
+        };
+        out.push(rec);
+        if (!key) {
+            rec.status = "find_cap";
+            continue;
+        }
+        const o = input.outcomes.get(key) ?? { status: "timeout" };
+        if (o.status !== "ok") {
+            rec.status = o.status;
+            if (o.status === "unreadable")
+                rec.reason = o.reason;
+            continue;
+        }
+        selectDiscovery(rec, o.hits, r.focus && r.focus.length > 0 ? r.focus : input.prFiles);
+    }
+    if (validatorRow) {
+        const key = input.plan.rowKey.get(validatorRow.row);
+        const rec = {
+            role: "validator",
+            row: validatorRow.row,
+            lens: VALIDATOR_LENS,
+            agent: validatorRow.agent,
+            query: query(key),
+            status: "ok",
+            lessons: [],
+            cases: [],
+            cuts: [],
+            dropped: {},
+        };
+        const pool = new Map(dontRaise);
+        if (!key)
+            rec.status = "find_cap";
+        else {
+            const o = input.outcomes.get(key) ?? { status: "timeout" };
+            if (o.status !== "ok") {
+                // Its own find did not answer; the discovery rows' dont-raise lessons
+                // are still its candidates.
+                rec.status = o.status;
+                if (o.status === "unreadable")
+                    rec.reason = o.reason;
+            }
+            else {
+                const { eligible, dropped } = filterLessonHits(o.hits, {
+                    ...base,
+                    lens: VALIDATOR_LENS,
+                    files: input.prFiles,
+                });
+                rec.dropped = dropped;
+                for (const c of eligible)
+                    if (c.lesson.lens.includes(VALIDATOR_LENS) || c.lesson.kind === "dont-raise")
+                        if (!pool.has(c.uri))
+                            pool.set(c.uri, c);
+            }
+        }
+        // Ranked against the whole PR: a path hit is a hit on any changed file.
+        const ranked = rankLessons([...pool.values()].map((c) => ({
+            ...c,
+            pathHit: pathHitOn(c.lesson, input.prFiles),
+        })), VALIDATOR_LENS);
+        const { selected, cuts } = capSelection(ranked, caps.validator);
+        rec.lessons = selected.map(asSelected);
+        selected.forEach(keepText);
+        rec.cuts = cuts;
+        out.push(rec);
+    }
+    // The lenses the session may add: each filtered over the PR's files
+    // from the one shared find, ranked and capped like a row.
+    const addable = [...new Set(input.addable ?? [])];
+    if (addable.length > 0) {
+        const key = input.plan.addableKey ?? null;
+        const o = key ? (input.outcomes.get(key) ?? { status: "timeout" }) : null;
+        addable.forEach((lens, i) => {
+            const rec = {
+                role: "addable",
+                row: i,
+                lens,
+                agent: null,
+                query: query(key),
+                status: "ok",
+                lessons: [],
+                cases: [],
+                cuts: [],
+                dropped: {},
+            };
+            out.push(rec);
+            if (!o) {
+                rec.status = "find_cap";
+                return;
+            }
+            if (o.status !== "ok") {
+                rec.status = o.status;
+                if (o.status === "unreadable")
+                    rec.reason = o.reason;
+                return;
+            }
+            selectDiscovery(rec, o.hits, input.prFiles);
+        });
+    }
+    const casesKey = input.plan.casesKey;
+    const casesRec = {
+        role: "cases",
+        row: -1,
+        lens: "",
+        agent: null,
+        query: query(casesKey),
+        status: "ok",
+        lessons: [],
+        cases: [],
+        cuts: [],
+        dropped: {},
+    };
+    if (casesKey) {
+        const o = input.outcomes.get(casesKey) ?? { status: "timeout" };
+        if (o.status !== "ok") {
+            casesRec.status = o.status;
+            if (o.status === "unreadable")
+                casesRec.reason = o.reason;
+        }
+        else {
+            const { eligible, dropped } = filterCaseHits(o.hits, {
+                ...base,
+                pr: input.pr,
+                files: input.prFiles,
+                lenses: input.rows.map((r) => r.lens),
+            });
+            casesRec.dropped = dropped;
+            const { selected, cuts } = capSelection(rankCases(eligible), caps.cases);
+            casesRec.cases = selected.map(caseSelected);
+            selected.forEach(keepText);
+            casesRec.cuts = cuts;
+        }
+    }
+    out.push(casesRec);
+    return out;
+}
+// ---- repo facts for the recheck and the ping-pong wake ----------------------
+/** The query of a repo-fact find: the PR's title and the touched paths,
+ * sorted (a function of the path SET). */
+export function repoFactsQuery(input) {
+    return casesQuery({ title: input.title, files: input.paths });
+}
+/**
+ * The repo-fact lessons for the paths a recheck's delta or an author's reply
+ * touches: the same header filters as a row's (never retired,
+ * moved, suppressed, of unknown polarity, or created on/after `as_of`), no
+ * lens precondition (the main session reads them), and then only
+ * `kind=repo-fact` lessons whose `paths=` glob matches a TOUCHED path — a
+ * lesson naming no paths is for no path in particular, so it is not "for the
+ * touched paths" and is left out (`no_paths`). Ranked and capped like a row.
+ * Pure.
+ */
+export function selectRepoFacts(hits, ctx, cap = SELECTION_CAPS.row) {
+    const { eligible, dropped } = filterLessonHits(hits, { ...ctx, lens: null });
+    const facts = [];
+    for (const c of eligible) {
+        if (c.lesson.kind !== "repo-fact")
+            bump(dropped, "kind");
+        else if (!c.pathHit)
+            bump(dropped, "no_paths");
+        else
+            facts.push(c);
+    }
+    const { selected, cuts } = capSelection(rankLessons(facts, ""), cap);
+    return { selected, cuts, dropped };
+}
+//# sourceMappingURL=selection.js.map