@quickchatai/quickreview 0.0.0-stage → 1.1.0

package/dist/src/setup/stage2.js

@@ -0,0 +1,617 @@
+import { globMatcher } from "@quickchatai/pi-quickreview/src/glob.js";
+import { isSweepSkipped, isTestFile } from "@quickchatai/pi-quickreview/src/heuristics.js";
+import { lensEnabled, flooredTier, } from "@quickchatai/pi-quickreview/src/lenstuning.js";
+import { PASS_TIER_ORDER, tiersAtOrAbove, } from "@quickchatai/pi-quickreview/src/types.js";
+import { caseEstimate, coverKey, cutRanges, focusLine, planKey, rangeNote, TREE_PATHS_NOTE, rangesCover, SCAN_DEEP_LENSES, stage1Exclusion, SCAN_PASS, } from "./scan.js";
+import { depthOf, measuredRate, rateWhere } from "./ledger.js";
+import { assign, splitUnit } from "./unitcut.js";
+/** At most this many rows the companion asks for in one proposal (the deep
+ * floor is not counted: it is bounded by the tree). */
+export const MAX_STAGE2_ROWS = 100;
+/** At most this many tests paired with one code file (the nearest win). */
+export const MAX_PAIRED_PER_FILE = 3;
+/** A row's reason is one line. */
+export const ROW_REASON_MAX = 300;
+/** The unit a file no unit of the cut owns is filed under. */
+export const NO_UNIT = "(no unit)";
+/** Better bases first: what `priceStage2Row` prefers at the row's own depth. */
+const BASIS_RANK = {
+    measured: 0,
+    borrowed: 1,
+    learned: 2,
+    extrapolated: 3,
+};
+/** Stage 1 measured at BOTH validator settings at one tier and effort —
+ * `[scan]`'s own when it has both, else the first other pair (sorted) that
+ * does — or null: the skeptic's share is then unmeasured. */
+function stage1Pair(entries, cfg, validator) {
+    const at = (tier, effort) => {
+        const row = measuredRate(entries, { lens: SCAN_PASS, tier, effort, validator });
+        const other = measuredRate(entries, { lens: SCAN_PASS, tier, effort, validator: !validator });
+        return row && other ? { row, other } : null;
+    };
+    const own = at(cfg.tier, cfg.effort);
+    if (own)
+        return own;
+    const keys = [
+        ...new Set(entries.filter((e) => e.lens === SCAN_PASS).map((e) => `${e.tier}\0${e.effort}`)),
+    ].sort();
+    for (const k of keys) {
+        const [tier, effort] = k.split("\0");
+        const p = at(tier, effort);
+        if (p)
+            return p;
+    }
+    return null;
+}
+/**
+ * A stage-2 row's price at `lens`/`tier`/`effort` from the ledger (header
+ * "PRICED FROM THE LEDGER"), or null when stage 1 has measured nothing. With
+ * a `depth`, the price stands on readings at that depth when they price the
+ * row at least as well as every reading does; otherwise it is the price over
+ * every reading, marked `across_depth`.
+ */
+export function priceStage2Row(entries, cfg, lens, tier, effort, depth) {
+    const any = priceFrom(entries, cfg, lens, tier, effort);
+    if (depth === undefined || any === null)
+        return any;
+    const same = priceFrom(entries.filter((e) => depthOf(e) === depth), cfg, lens, tier, effort);
+    if (same !== null && BASIS_RANK[same.basis] <= BASIS_RANK[any.basis])
+        return same;
+    return { ...any, across_depth: true };
+}
+function priceFrom(entries, cfg, lens, tier, effort) {
+    const validator = cfg.validator;
+    const own = measuredRate(entries, { lens, tier, effort, validator });
+    if (own)
+        return { rate: own, basis: "measured", from: lens };
+    // Borrowed only from another DEEP lens: pass-scan is the cheap wide pass,
+    // and its rate at a matching tier/effort (a profile giving a deep lens
+    // `effort = "low"` at `[scan] tier`) would price a deep row at stage 1's
+    // cost unscaled — stage 1's rate reaches a row only through a factor.
+    const deepAt = (v, same) => (e) => (same ? e.lens === lens : e.lens !== lens && e.lens !== SCAN_PASS) &&
+        e.tier === tier &&
+        e.effort === effort &&
+        e.validator === v;
+    const lensesOf = (keep) => [...new Set(entries.filter((e) => keep(e) && e.cost_usd !== null).map((e) => e.lens))]
+        .sort()
+        .join(", ");
+    const borrowed = rateWhere(entries, deepAt(validator, false));
+    if (borrowed)
+        return { rate: borrowed, basis: "borrowed", from: lensesOf(deepAt(validator, false)) };
+    // Stage 1 at a validator setting: at `[scan]`'s tier and effort, else at
+    // any (the extrapolation's fallback too).
+    const stage1At = (v) => measuredRate(entries, { lens: SCAN_PASS, tier: cfg.tier, effort: cfg.effort, validator: v }) ??
+        rateWhere(entries, (e) => e.lens === SCAN_PASS && e.validator === v);
+    // Learned: a stage-2 measurement at the same tier and effort with the
+    // validator the other way, carried across by the skeptic's measured share —
+    // stage 1's rate at the row's setting over its rate at the other. Both
+    // stage-1 rates must come from ONE tier and effort (`[scan]`'s first, else
+    // the first other pair measured both ways): a ratio across tiers would be
+    // the tier's price, not the skeptic's. The share is bounded by direction —
+    // the skeptic adds work, so it can raise a price learned from a skeptic-off
+    // measurement and lower one learned from a skeptic-on one, never the
+    // reverse (two noisy stage-1 samples must not price a validated row UNDER
+    // what the unvalidated lens was measured at).
+    const other = !validator;
+    const s1Row = stage1At(validator);
+    const pair = stage1Pair(entries, cfg, validator);
+    if (pair && pair.other.usd_per_kline > 0) {
+        const raw = pair.row.usd_per_kline / pair.other.usd_per_kline;
+        const skeptic = validator ? Math.max(raw, 1) : Math.min(raw, 1);
+        for (const same of [true, false]) {
+            const s2 = rateWhere(entries, deepAt(other, same));
+            if (!s2)
+                continue;
+            return {
+                rate: { ...s2, usd_per_kline: s2.usd_per_kline * skeptic },
+                basis: "learned",
+                from: lensesOf(deepAt(other, same)),
+                learned: { validator: other, factor: s2.usd_per_kline / pair.other.usd_per_kline, skeptic },
+            };
+        }
+    }
+    const stage1 = s1Row ?? rateWhere(entries, (e) => e.lens === SCAN_PASS);
+    if (!stage1)
+        return null;
+    return {
+        rate: { ...stage1, usd_per_kline: stage1.usd_per_kline * cfg.unmeasured_rate_factor },
+        basis: "extrapolated",
+        from: SCAN_PASS,
+        factor: cfg.unmeasured_rate_factor,
+    };
+}
+/** A row's effort as the ledger keys it: the lens's profile `effort`, or
+ * `tier` (the tier's own reasoning level). */
+export function lensEffort(lenses, lens) {
+    return lenses?.[lens]?.effort ?? "tier";
+}
+/** A risk pass runs at `sol-high` alone; any other lens, null. */
+function riskTier(riskPasses, lens) {
+    return riskPasses.includes(lens) ? "sol-high" : null;
+}
+/** The tiers `lens` may run at in a scan: the ones its build variants exist
+ * at, at or above its profile floor. */
+export function lensTiers(lenses, lens, riskPasses) {
+    const risk = riskTier(riskPasses, lens);
+    if (risk !== null)
+        return [risk];
+    const floor = flooredTier(lenses, lens, PASS_TIER_ORDER[0]);
+    return tiersAtOrAbove(floor);
+}
+/** The deep lenses stage 2 may run on this repo: stage 1's suggestible set,
+ * less every lens the profile switched off. */
+export function stage2Lenses(lenses) {
+    return SCAN_DEEP_LENSES.filter((l) => lensEnabled(lenses, l, true));
+}
+// ---- pairing tests -------------------------------------------------------------
+const TEST_DIRS = new Set(["test", "tests", "__tests__", "spec", "specs", "testing", "main"]);
+const FAMILY = {
+    ts: "js",
+    tsx: "js",
+    js: "js",
+    jsx: "js",
+    mjs: "js",
+    cjs: "js",
+    mts: "js",
+    cts: "js",
+};
+function ext(path) {
+    const base = path.slice(path.lastIndexOf("/") + 1);
+    const i = base.lastIndexOf(".");
+    return i <= 0 ? "" : base.slice(i + 1).toLowerCase();
+}
+function family(path) {
+    const e = ext(path);
+    return FAMILY[e] ?? e;
+}
+function dirSegs(path) {
+    const i = path.lastIndexOf("/");
+    return i < 0 ? [] : path.slice(0, i).split("/");
+}
+/** A code file's subject: its basename without the extension. */
+function codeStem(path) {
+    const base = path.slice(path.lastIndexOf("/") + 1);
+    const i = base.lastIndexOf(".");
+    return (i <= 0 ? base : base.slice(0, i)).toLowerCase();
+}
+/** A test file's subject: its basename with the extension and every test
+ * marker (`test_`, `_test`, `.test`, `.spec`, `Test`, …) stripped. */
+function testStem(path) {
+    let s = path.slice(path.lastIndexOf("/") + 1);
+    const i = s.lastIndexOf(".");
+    if (i > 0)
+        s = s.slice(0, i);
+    s = s
+        .replace(/[._-](test|spec)s?$/i, "")
+        .replace(/(?<=[a-z0-9])Tests?$/, "")
+        .replace(/^tests?[_-]/i, "");
+    return s.toLowerCase();
+}
+const endsWithSegs = (a, b) => b.length <= a.length && b.every((s, i) => a[a.length - b.length + i] === s);
+/**
+ * The tests in `tree` that pair with `code`: same subject, same language
+ * family, and a directory that mirrors the code's once the test directories
+ * (`tests/`, `__tests__/`, `src/test` vs `src/main`, …) are set aside — the
+ * code's own directory, a `tests/` beside or under it, or a top-level tests
+ * tree mirroring its package. The nearest (most shared leading directories)
+ * win, at most `MAX_PAIRED_PER_FILE` of those `eligible` says a lens may read
+ * — so a test it may not never takes a nearer one's place. A heuristic,
+ * deliberately: a pair is reading context for the lens, never a claim about
+ * coverage.
+ */
+export function pairTests(code, tree, eligible = () => true) {
+    const stem = codeStem(code);
+    if (stem === "" || isTestFile(code))
+        return [];
+    const fam = family(code);
+    const cDir = dirSegs(code);
+    const cNorm = cDir.filter((s) => !TEST_DIRS.has(s.toLowerCase()));
+    const scored = [];
+    for (const t of tree) {
+        if (t === code || !isTestFile(t) || family(t) !== fam || testStem(t) !== stem)
+            continue;
+        if (!eligible(t))
+            continue;
+        const tDir = dirSegs(t);
+        const tNorm = tDir.filter((s) => !TEST_DIRS.has(s.toLowerCase()));
+        if (!(endsWithSegs(cNorm, tNorm) || endsWithSegs(tNorm, cNorm)))
+            continue;
+        let shared = 0;
+        while (shared < cDir.length && shared < tDir.length && cDir[shared] === tDir[shared])
+            shared++;
+        scored.push({ path: t, score: shared * 10 - Math.abs(tNorm.length - cNorm.length) });
+    }
+    scored.sort((a, b) => b.score - a.score || (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
+    return scored.slice(0, MAX_PAIRED_PER_FILE).map((s) => s.path);
+}
+// ---- the plan ------------------------------------------------------------------
+const cleanPath = (p) => p
+    .trim()
+    .replace(/^`+|`+$/g, "")
+    .replace(/^\.?\/+/, "");
+/** A row's tier when none is named: the lens's floor over `[scan] tier`
+ * (`sol-high` for a risk pass). */
+function defaultRowTier(input, lens) {
+    return riskTier(input.riskPasses, lens) ?? flooredTier(input.lenses, lens, input.defaultTier);
+}
+/**
+ * Plan a proposal: every row checked (all-or-nothing — one bad row refuses
+ * the proposal, each problem named), tests paired, units found, each row
+ * priced, covered rows marked; then, for a deep proposal, the floor rows
+ * after them; then the runnable rows fitted to the budget in that order.
+ * Deterministic.
+ */
+export function planStage2(input) {
+    const errors = [];
+    if (input.rows.length === 0 && input.floor === undefined)
+        return { ok: false, errors: ["a stage 2 proposal needs at least one row"] };
+    if (input.rows.length > MAX_STAGE2_ROWS) {
+        return {
+            ok: false,
+            errors: [`${input.rows.length} rows — at most ${MAX_STAGE2_ROWS} in one proposal`],
+        };
+    }
+    const excluded = globMatcher(input.exclude);
+    const blobs = new Map(input.files.map((f) => [f.path, f.blob]));
+    const treePaths = [...blobs.keys()].sort();
+    const unitOf = unitOwner(input.cut, treePaths);
+    const allowed = stage2Lenses(input.lenses);
+    const seen = new Set();
+    const rows = [];
+    /** One file too big for one case alone: read in line ranges. */
+    const oversized = (sorted, lines) => sorted.length === 1 && lines.get(sorted[0]) > input.budget.maxLines;
+    /** One row over `sorted` (checked files; `lines` holds their counts), its
+     * tests paired when `pair` — or why it cannot be priced. */
+    const build = (spec) => {
+        const { lens, sorted, lines } = spec;
+        let rowLines = sorted.reduce((n, p) => n + lines.get(p), 0);
+        const oversize = oversized(sorted, lines);
+        // Pair the tests, nearest first, while the case budget holds. A ranged
+        // row's tests ride in EVERY range case, so they get at most half a case.
+        const testFiles = !spec.pair
+            ? 0
+            : oversize
+                ? input.budget.maxFiles - 1
+                : input.budget.maxFiles - sorted.length;
+        const testLines = oversize
+            ? Math.floor(input.budget.maxLines / 2)
+            : input.budget.maxLines - rowLines;
+        let pairedLines = 0;
+        const tests = [];
+        const unpaired = [];
+        const taken = new Set(sorted);
+        // A paired test obeys the named files' rules: never an unreadable kind
+        // (generated, vendored, a lockfile), never excluded, readable as text.
+        const pairable = (t) => !isSweepSkipped(t) && !excluded(t) && input.linesOf(t) !== null;
+        for (const code of spec.pair ? sorted : []) {
+            for (const t of pairTests(code, treePaths, pairable)) {
+                if (taken.has(t))
+                    continue;
+                taken.add(t);
+                const n = input.linesOf(t);
+                if (tests.length + 1 > testFiles || pairedLines + n > testLines) {
+                    unpaired.push(t);
+                    continue;
+                }
+                tests.push({ path: t, blob: blobs.get(t), lines: n });
+                pairedLines += n;
+            }
+        }
+        let ranges;
+        if (oversize) {
+            const p = sorted[0];
+            const done = input.partial?.(lens).get(coverKey(p, blobs.get(p))) ?? [];
+            ranges = cutRanges(lines.get(p), input.budget.maxLines - pairedLines, input.textOf?.(p) ?? null).filter((r) => !rangesCover(done, r.start, r.end));
+            rowLines = ranges.reduce((n, r) => n + rangeCaseLines(r, pairedLines), 0);
+        }
+        else {
+            rowLines += pairedLines;
+        }
+        const effort = lensEffort(input.lenses, lens);
+        const price = input.price(lens, spec.tier, effort);
+        if (price === null) {
+            return `no measured price for any scan lens yet — run stage 1 (its calibration run prices the scan) before proposing stage 2`;
+        }
+        const files = sorted.map((p) => ({ path: p, blob: blobs.get(p), lines: lines.get(p) }));
+        const cover = input.covered(lens);
+        const all = [...files, ...tests];
+        const isCovered = all.every((f) => cover.has(coverKey(f.path, f.blob))) ||
+            (ranges !== undefined && ranges.length === 0);
+        return {
+            id: spec.id,
+            lens,
+            tier: spec.tier,
+            effort,
+            reason: spec.reason,
+            units: [...new Set(all.map((f) => unitOf(f.path)))].sort(),
+            files,
+            tests,
+            unpaired,
+            ...(ranges !== undefined ? { ranges } : {}),
+            lines: rowLines,
+            estimate_usd: isCovered
+                ? 0
+                : ranges !== undefined
+                    ? ranges.reduce((n, r) => n + caseEstimate(rangeCaseLines(r, pairedLines), price.rate), 0)
+                    : caseEstimate(rowLines, price.rate),
+            price,
+            status: isCovered ? "covered" : "run",
+            ...(spec.floor ? { floor: true } : {}),
+        };
+    };
+    input.rows.forEach((req, i) => {
+        const id = `row-${i + 1}`;
+        const bad = (why) => void errors.push(`${id}: ${why}`);
+        const lens = typeof req?.lens === "string" ? req.lens.trim() : "";
+        if (lens === SCAN_PASS)
+            return bad(`${SCAN_PASS} is stage 1's lens — a stage 2 row names a deep lens`);
+        if (!allowed.includes(lens)) {
+            return bad(SCAN_DEEP_LENSES.includes(lens)
+                ? `${JSON.stringify(lens)} is switched off by this repo's profile`
+                : `${JSON.stringify(lens)} is not a deep lens a scan can run (one of: ${allowed.join(", ")})`);
+        }
+        const reason = typeof req.reason === "string" ? req.reason.trim().replace(/\s+/g, " ") : "";
+        if (reason === "")
+            return bad("no reason — say in one line what the lens should chase");
+        if (reason.length > ROW_REASON_MAX)
+            return bad(`the reason is ${reason.length} characters — one line, at most ${ROW_REASON_MAX}`);
+        const tiers = lensTiers(input.lenses, lens, input.riskPasses);
+        let tier;
+        if (req.tier === undefined || req.tier === null || req.tier === "") {
+            tier = defaultRowTier(input, lens);
+        }
+        else if (tiers.includes(req.tier)) {
+            tier = req.tier;
+        }
+        else {
+            return bad(`${lens} cannot run at ${JSON.stringify(req.tier)} here — one of: ${tiers.join(", ")}`);
+        }
+        const named = [
+            ...new Set((Array.isArray(req.files) ? req.files : [])
+                .filter((p) => typeof p === "string")
+                .map(cleanPath)),
+        ].filter((p) => p !== "");
+        if (named.length === 0)
+            return bad("no files");
+        const problems = [];
+        const lines = new Map();
+        for (const p of named) {
+            if (!blobs.has(p))
+                problems.push(`${p} is not in the tree at the scan sha`);
+            else if (isTestFile(p))
+                problems.push(`${p} is a test — tests enter stage 2 only paired with the code they test; name that code`);
+            else if (isSweepSkipped(p))
+                problems.push(`${p} is not code a lens reads (lockfile, generated, binary or prose)`);
+            else if (excluded(p))
+                problems.push(`${p} is excluded from scans by [scan] exclude`);
+            else {
+                const n = input.linesOf(p);
+                if (n === null) {
+                    const why = input.whyUnreadable?.(p) ?? null;
+                    problems.push(`${p} cannot be read as text${why === "binary" ? " (skipped: binary)" : why === "too-big" ? " (skipped: over the size cap)" : ""}`);
+                }
+                else
+                    lines.set(p, n);
+            }
+        }
+        if (problems.length > 0)
+            return bad(problems.join("; "));
+        const sorted = [...named].sort();
+        const dedupe = `${lens}\0${sorted.join("\0")}`;
+        if (seen.has(dedupe))
+            return bad(`the same ${lens} row as an earlier one`);
+        seen.add(dedupe);
+        const rowLines = sorted.reduce((n, p) => n + lines.get(p), 0);
+        // One file too big for one case is cut into line ranges; anywhere else a
+        // row over one case is refused.
+        const oversize = oversized(sorted, lines);
+        if (!oversize && (sorted.length > input.budget.maxFiles || rowLines > input.budget.maxLines)) {
+            const big = sorted.filter((p) => lines.get(p) > input.budget.maxLines);
+            return bad(`${sorted.length} files, ${rowLines} lines — over one case (${input.budget.maxFiles} files, ${input.budget.maxLines} lines); split it into narrower rows` +
+                (big.length > 0
+                    ? ` (${big.join(", ")} ${big.length === 1 ? "is" : "are"} over one case alone — name ${big.length === 1 ? "it" : "each"} alone in a row and it is cut into line ranges)`
+                    : ""));
+        }
+        const row = build({ id, lens, tier, reason, sorted, lines, pair: true, floor: false });
+        if (typeof row === "string")
+            return bad(row);
+        rows.push(row);
+    });
+    if (errors.length > 0)
+        return { ok: false, errors };
+    let floor = null;
+    if (input.floor !== undefined) {
+        floor = {
+            lenses: input.floor.filter((l) => allowed.includes(l)),
+            skipped: input.floor.filter((l) => !allowed.includes(l)),
+            covered: 0,
+            named: 0,
+        };
+        // Stage 1's files: readable, not a test, a migration, an excluded glob
+        // or an unreadable kind — and owned by a unit of the cut.
+        const lines = new Map();
+        for (const p of treePaths) {
+            if (stage1Exclusion(p, excluded) !== null)
+                continue;
+            const n = input.linesOf(p);
+            if (n !== null)
+                lines.set(p, n);
+        }
+        const owned = assign(input.cut, [...lines.keys()]).byUnit;
+        let n = 0;
+        for (const lens of floor.lenses) {
+            const named = new Set(rows.filter((r) => !r.floor && r.lens === lens).flatMap((r) => r.files.map((f) => f.path)));
+            const cover = input.covered(lens);
+            const tier = defaultRowTier(input, lens);
+            for (const u of input.cut.units) {
+                const files = [];
+                for (const p of owned.get(u.name) ?? []) {
+                    if (named.has(p))
+                        floor.named++;
+                    else if (cover.has(coverKey(p, blobs.get(p))))
+                        floor.covered++;
+                    else
+                        files.push(p);
+                }
+                if (files.length === 0)
+                    continue;
+                for (const chunk of splitUnit(u.name, files, (p) => lines.get(p), input.budget)) {
+                    const row = build({
+                        id: `floor-${++n}`,
+                        lens,
+                        tier,
+                        reason: `deep floor: ${lens} over ${u.name}`,
+                        sorted: [...chunk.files].sort(),
+                        lines,
+                        pair: false,
+                        floor: true,
+                    });
+                    if (typeof row === "string")
+                        return { ok: false, errors: [`floor-${n}: ${row}`] };
+                    rows.push(row);
+                }
+            }
+        }
+        if (rows.length === 0) {
+            return {
+                ok: false,
+                errors: [
+                    floor.lenses.length === 0
+                        ? `no row and no floor: every [scan] deep_lenses lens (${input.floor.join(", ")}) is switched off by this repo's profile`
+                        : floor.covered > 0
+                            ? "nothing left for the floor: the ledger already holds a deep reading of every file by every floor lens at this content"
+                            : "no row and no floor: stage 1 reads no file a unit of the cut owns",
+                ],
+            };
+        }
+    }
+    let total = 0;
+    let over = 0;
+    for (const r of rows) {
+        if (r.status !== "run")
+            continue;
+        if (input.budgetUsd !== null && total + r.estimate_usd > input.budgetUsd + 1e-9) {
+            r.status = "over-budget";
+            over += r.estimate_usd;
+            continue;
+        }
+        total += r.estimate_usd;
+    }
+    const runnable = rows.filter((r) => r.status === "run").length;
+    return { ok: true, rows, runnable, total_usd: total, over_budget_usd: over, floor };
+}
+/** The unit owning each tree path under `cut` (NO_UNIT for none). */
+export function unitOwner(cut, paths) {
+    const owner = new Map();
+    for (const [unit, ps] of assign(cut, paths).byUnit)
+        for (const p of ps)
+            owner.set(p, unit);
+    return (p) => owner.get(p) ?? NO_UNIT;
+}
+// ---- the prompt ----------------------------------------------------------------
+/** The cases one row runs as: the row itself, or — a row over a file too
+ * big for one case — one per range, `<row>#<i>`, each the ranged file plus
+ * the paired tests. */
+export function stage2Cases(row) {
+    if (row.ranges === undefined)
+        return [
+            { id: row.id, part: 1, parts: 1, files: [...row.files, ...row.tests], lines: row.lines },
+        ];
+    const code = row.files[0];
+    const tests = row.tests.reduce((n, t) => n + t.lines, 0);
+    return row.ranges.map((r, i) => ({
+        id: `${row.id}#${i + 1}`,
+        part: i + 1,
+        parts: row.ranges.length,
+        files: [{ ...code, lines: rangeCaseLines(r, 0), range: r }, ...row.tests],
+        lines: rangeCaseLines(r, tests),
+    }));
+}
+/** Stage-1 leads a stage-2 case carries at most. */
+export const STAGE2_MAX_LEADS = 8;
+/** A lead's reason is cut to this many characters. */
+const LEAD_MAX_CHARS = 300;
+/**
+ * The stage-1 suggestions a stage-2 row's cases carry: those naming the
+ * row's lens and at least one of its code files, newest first (by `at`), one
+ * per reason, at most `STAGE2_MAX_LEADS`. Each keeps only the row's files it
+ * names; its reason is flattened to one line and capped. The companion's row reason is one line; what stage 1 saw in these
+ * files is otherwise never in front of the lens. Pure.
+ */
+export function stage2Leads(row, suggestions) {
+    const mine = new Set(row.files.map((f) => f.path));
+    const seen = new Set();
+    const out = [];
+    const newest = [...suggestions].sort((a, b) => (b.at ?? "").localeCompare(a.at ?? ""));
+    for (const s of newest) {
+        if (s.lens !== row.lens)
+            continue;
+        const files = s.files.filter((f) => mine.has(f));
+        // Model-written: one line, capped, so a lead can never pass for a
+        // header or a findings block in the task string.
+        const flat = s.reason.replace(/\s+/g, " ").trim();
+        const reason = flat.length > LEAD_MAX_CHARS ? `${flat.slice(0, LEAD_MAX_CHARS - 1)}…` : flat;
+        if (files.length === 0 || reason === "" || seen.has(reason))
+            continue;
+        seen.add(reason);
+        out.push({ files, reason });
+        if (out.length >= STAGE2_MAX_LEADS)
+            break;
+    }
+    return out;
+}
+/** The stage-2 task string for one row — or, for a ranged row, for the one
+ * case whose `files` (from `stage2Cases`) are given. `leads` are what stage 1
+ * pointed this lens at in the row's files (`stage2Leads`). */
+export function stage2CasePrompt(row, ctx, caseFiles, leads = []) {
+    const list = (fs) => fs.map((f) => focusLine(f, ctx.root)).join("\n");
+    const code = caseFiles ? caseFiles.slice(0, row.files.length) : row.files;
+    return [
+        `SCAN CASE ${ctx.caseId} — stage 2, ${row.id}: ${row.lens}${row.units.length > 1 ? ` across units ${row.units.join(", ")}` : ` in unit ${row.units[0]}`}.`,
+        `Scan sha: ${ctx.sha}`,
+        `Tree root (the repository at the scan sha, read-only): ${ctx.root}`,
+        TREE_PATHS_NOTE,
+        "",
+        `Why this case: ${row.reason}`,
+        ...(row.floor
+            ? [
+                leads.length > 0
+                    ? "This row is the deep scan's floor: every file is read with this lens whether or not a first look pointed here."
+                    : "This row is the deep scan's floor: every file is read with this lens whether or not a first look pointed here, so nobody names a shape for you — find it in the focus files yourself.",
+            ]
+            : []),
+        ...(leads.length > 0
+            ? [
+                "",
+                `What the first look pointed this lens at in these files (${leads.length} — leads to check first, not findings, and not the limit of your reading):`,
+                ...leads.map((l) => `- ${l.files.map((f) => `\`${f}\``).join(", ")}: ${l.reason}`),
+            ]
+            : []),
+        "",
+        `Focus files (${code.length} — read each in full; they are one case because the problem may live between them):`,
+        list(code),
+        ...rangeNote(code),
+        ...(row.tests.length > 0
+            ? [
+                "",
+                `Their tests (${row.tests.length} — read them for the contract the code is held to; a missing test is not a finding):`,
+                list(row.tests),
+            ]
+            : []),
+        "",
+        `Answer with the findings block headed \`FINDINGS ${row.lens} SCAN ${ctx.caseId} @${ctx.sha}\` (or NONE).`,
+    ].join("\n");
+}
+/** The lines one range case reads: the range, and the paired tests that
+ * ride in every range case — the row's total, its price and its cases all
+ * count it this one way. */
+function rangeCaseLines(r, pairedLines) {
+    return r.end - r.start + 1 + pairedLines;
+}
+/** The key a stage-2 start must quote: the runnable rows, the sha, the
+ * validator setting and the cap. */
+export function stage2Key(parts) {
+    return planKey({ stage: 2, parts });
+}
+//# sourceMappingURL=stage2.js.map