@unblocklabs/unblock-memory 0.3.30 → 0.5.0

package/dist/src/training-queries.js

@@ -2,10 +2,12 @@ import { collectTraining } from "./training.js";
 import { trainingHash } from "./training-input.js";
 import { TRAINING_GATE_THRESHOLD } from "./training-gate.js";
 import { resolveTypeSafeApiKey, TypeSafeRequestError } from "./typesafe-client.js";
-import { trainingTeacher, trainingTeacherMessage, TRAINING_TEACHER_MODEL, TRAINING_TEACHER_PROMPT, TRAINING_TEACHER_VERSION } from "./training-models.js";
-import { historicalTrainingSearch, TRAINING_RETRIEVAL_VERSION, TRAINING_SEARCH_OPTIONS } from "./training-retrieval.js";
+import { trainingTeacher, trainingTeacherMessage, trainingTeacherPrompt, TRAINING_TEACHER_MODEL, TRAINING_TEACHER_VERSION } from "./training-models.js";
+import { historicalTrainingSearch, HistoricalCorpusUnavailableError, TRAINING_RETRIEVAL_VERSION, TRAINING_SEARCH_OPTIONS } from "./training-retrieval.js";
 import { contextJudgeRequest, judgeTrainingPassage, CONTEXT_JUDGE_VERSION } from "./training-judge.js";
-const SELECTION_VERSION = "conversation-utility-top5-sum-v2";
+const LANES = ["lex", "vec"];
+const SELECTION_VERSION = "independent-lanes-top3-mean-v2";
+const TARGET_POLICY = "best-per-lane-no-minimum-v1";
 export const TRAINING_EVALUATION_CONCURRENCY = 4;
 function bounds(options) {
     for (const value of [options.maxExamples, options.maxCalls, options.maxInputBytes, options.concurrency]) {
@@ -13,13 +15,14 @@ function bounds(options) {
             throw new Error("Training bounds must be positive integers");
     }
 }
-function teacherRequest(example) {
+function teacherRequest(example, lane, feedback) {
     return { version: TRAINING_TEACHER_VERSION, model: TRAINING_TEACHER_MODEL, inputHash: example.inputHash,
-        input: JSON.parse(example.inputJson) };
+        input: JSON.parse(example.inputJson), lane, round: feedback ? 2 : 1,
+        ...(feedback ? { feedback: feedback.map(({ query, score }) => ({ query, score })) } : {}) };
 }
 const summary = () => ({ examples: 0, calls: 0, completed: 0, cached: 0, failed: 0, ambiguous: 0,
-    blocked: 0, inputBytes: 0, budgetLimited: false });
-/** One fenced checkpoint per paid operation, with no hidden transport retries. */
+    blocked: 0, flagged: 0, inputBytes: 0, budgetLimited: false });
+/** One fenced checkpoint per operation. Storage failures are fatal; provider failures are local. */
 async function checkpoint(store, step, result, operation) {
     if (step.result !== undefined) {
         result.cached++;
@@ -37,14 +40,19 @@ async function checkpoint(store, step, result, operation) {
         value = await operation();
     }
     catch (error) {
+        // Historical retrieval is local code. Only an explicitly unavailable corpus
+        // is a reviewable data case; do not swallow SQLite, I/O or snapshot-integrity errors.
+        if (step.stage === "retrieve" && !(error instanceof HistoricalCorpusUnavailableError))
+            throw error;
         const hostCode = error && typeof error === "object" && "code" in error && typeof error.code === "string" &&
             /^LLM_[A-Z_]+$/u.test(error.code) ? error.code : undefined;
-        const status = hostCode === "LLM_COMPLETION_NOT_AUTHORIZED" ||
+        const status = error instanceof HistoricalCorpusUnavailableError || hostCode === "LLM_COMPLETION_NOT_AUTHORIZED" ||
             (error instanceof TypeSafeRequestError && error.code === "http_error" &&
                 error.status !== undefined && error.status >= 400 && error.status < 500) ? "failed" : "ambiguous";
         store.finishStep(step.stage, step.id, attempt, { status,
             error: error instanceof TypeSafeRequestError && error.code === "http_error" ?
-                `http_${error.status}` : hostCode ?? "request_or_response_uncertain" });
+                `http_${error.status}` : error instanceof HistoricalCorpusUnavailableError ? "historical_corpus_unavailable" :
+                hostCode ?? "request_or_response_uncertain" });
         result[status]++;
         return;
     }
@@ -52,6 +60,18 @@ async function checkpoint(store, step, result, operation) {
     result.completed++;
     return value;
 }
+function save(store, step, value) {
+    const attempt = store.startStep(step.stage, step.id, step.request);
+    store.finishStep(step.stage, step.id, attempt, { result: value });
+    return value;
+}
+async function drain(tasks) {
+    const settled = await Promise.allSettled(tasks);
+    const failure = settled.find(item => item.status === "rejected");
+    if (failure)
+        throw failure.reason;
+    return settled.flatMap(item => item.status === "fulfilled" ? [item.value] : []);
+}
 export async function generateTrainingQueries(source, store, runtime, options) {
     bounds(options);
     const refreshed = collectTraining(source, store, { existingOnly: true }), result = summary();
@@ -59,8 +79,8 @@ export async function generateTrainingQueries(source, store, runtime, options) {
     let teacher;
     const examples = store.queryExamples(options.threshold);
     let next = 0, stopped = false;
-    const workers = await Promise.allSettled(Array.from({ length: Math.min(options.concurrency ?? 8, examples.length) }, async () => {
-        while (!stopped && !result.budgetLimited && !result.failed && !result.ambiguous) {
+    await drain(Array.from({ length: Math.min(options.concurrency ?? 8, examples.length) }, async () => {
+        while (!stopped && !result.budgetLimited) {
             const example = examples[next++];
             if (!example)
                 return;
@@ -68,29 +88,49 @@ export async function generateTrainingQueries(source, store, runtime, options) {
                 if (seen.has(example.inputHash))
                     continue;
                 seen.add(example.inputHash);
-                const request = teacherRequest(example), step = store.step("generate", request);
-                if (step.result) {
-                    result.cached++;
+                const steps = LANES.map(lane => ({ lane, step: store.step("generate", teacherRequest(example, lane)) }));
+                if (steps.every(({ step }) => step.result)) {
+                    result.cached += steps.length;
                     continue;
                 }
-                if (step.status !== "pending") {
-                    result.blocked++;
+                if (steps.every(({ step }) => step.result || step.status !== "pending")) {
+                    const problems = steps.filter(({ step }) => !step.result).map(({ step }) => step.id);
+                    result.blocked += problems.length;
+                    result.flagged++;
+                    store.flagReview(example, "generation-unresolved", { steps: problems });
                     continue;
                 }
                 if (options.maxExamples !== undefined && result.examples >= options.maxExamples)
                     return;
-                const bytes = Buffer.byteLength(trainingTeacherMessage(request.input)) + Buffer.byteLength(TRAINING_TEACHER_PROMPT);
-                if (result.inputBytes + bytes > options.maxInputBytes) {
-                    result.budgetLimited = true;
-                    return;
-                }
                 result.examples++;
-                result.inputBytes += bytes;
-                if (options.dryRun)
-                    continue;
-                teacher ??= trainingTeacher(runtime, source.agentId); // Capability check BEFORE committing a paid attempt.
-                if (!await checkpoint(store, step, result, () => teacher(request.input)))
-                    return;
+                const problems = [];
+                for (const { lane, step } of steps) {
+                    if (step.result) {
+                        result.cached++;
+                        continue;
+                    }
+                    if (step.status !== "pending") {
+                        result.blocked++;
+                        problems.push(step.id);
+                        continue;
+                    }
+                    const input = JSON.parse(example.inputJson);
+                    const bytes = Buffer.byteLength(trainingTeacherMessage(input, lane)) + Buffer.byteLength(trainingTeacherPrompt(lane));
+                    if (result.inputBytes + bytes > options.maxInputBytes) {
+                        result.budgetLimited = true;
+                        break;
+                    }
+                    result.inputBytes += bytes;
+                    if (options.dryRun)
+                        continue;
+                    teacher ??= trainingTeacher(runtime, source.agentId);
+                    if (!await checkpoint(store, step, result, () => teacher(input, lane)))
+                        problems.push(step.id);
+                }
+                if (problems.length) {
+                    store.flagReview(example, "generation-unresolved", { steps: problems });
+                    result.flagged++;
+                }
             }
             catch (error) {
                 stopped = true;
@@ -98,142 +138,237 @@ export async function generateTrainingQueries(source, store, runtime, options) {
             }
         }
     }));
-    const failure = workers.find(item => item.status === "rejected");
-    if (failure)
-        throw failure.reason;
     return { refreshed, ...result, threshold: options.threshold ?? TRAINING_GATE_THRESHOLD, model: TRAINING_TEACHER_MODEL };
 }
+/** Raw top-three average, including values below runtime's injection threshold. */
+export function trainingQueryScore(probabilities) {
+    const top = probabilities.toSorted((a, b) => b - a).slice(0, 3);
+    return top.length ? top.reduce((sum, value) => sum + value, 0) / top.length : 0;
+}
 export function selectTrainingQueries(queries) {
-    // Stable ties preserve teacher order; neither low scores nor overlapping hits reject a query.
-    return queries.toSorted((a, b) => b.score - a.score).slice(0, 3).map(q => q.query);
+    const winner = (lane) => {
+        const ranked = queries.filter(query => query.lane === lane).toSorted((a, b) => b.score - a.score);
+        if (!ranked[0])
+            throw new Error(`No resolved ${lane} candidates`);
+        return ranked[0].query; // Stable ties preserve round and teacher order.
+    };
+    return { lex: winner("lex"), vec: winner("vec") };
 }
-export async function evaluateTrainingQueries(source, store, config, options, createSearch = historicalTrainingSearch) {
+export async function evaluateTrainingQueries(source, store, config, runtime, options, createSearch = historicalTrainingSearch) {
     bounds(options);
-    if (options.excludeJudgments?.some(id => !/^[a-f0-9]{64}$/u.test(id)))
-        throw new Error("Invalid excluded judgment hash");
     const corpus = config.corpora.find(c => c.kind === "sessions");
     if (!corpus)
         throw new Error("Training retrieval requires a configured sessions corpus");
     const refreshed = collectTraining(source, store, { existingOnly: true });
     const result = { ...summary(), retrievals: 0, evaluated: 0, awaitingTeacher: 0 };
     const concurrency = options.concurrency ?? TRAINING_EVALUATION_CONCURRENCY;
-    let key;
+    let key, teacher;
     const apiKey = () => key ??= resolveTypeSafeApiKey(config.typesafe).then(value => {
         if (!value)
             throw new Error("TypeSafe is disabled or its credential is unavailable");
         return value;
     });
     let stopped = false;
-    const shouldStop = () => stopped || result.budgetLimited || result.failed > 0 || result.ambiguous > 0 || result.blocked > 0;
+    const shouldStop = () => stopped || result.budgetLimited;
+    const room = () => {
+        if (shouldStop())
+            return false;
+        if (options.maxCalls !== undefined && result.calls >= options.maxCalls) {
+            result.budgetLimited = true;
+            return false;
+        }
+        return true;
+    };
     const judgments = new Map();
+    const revisions = new Map();
+    const reviews = new Map(store.reviews().map(review => [review.sourceId, review]));
     const evaluate = async (example) => {
-        const teacher = store.step("generate", teacherRequest(example));
-        if (!teacher.result) {
-            result.awaitingTeacher++;
+        const previousReview = reviews.get(example.id);
+        if (previousReview && "steps" in previousReview.details) {
+            const blocked = previousReview.details.steps.filter(id => {
+                const status = store.stepRecordStatus(id);
+                return status !== undefined && status !== "pending" && status !== "complete";
+            });
+            // A known failed example cannot resolve before manual retry. Do not scan its
+            // historical corpus or consume the example budget on every invocation.
+            if (blocked.length) {
+                result.blocked += blocked.length;
+                result.flagged++;
+                return;
+            }
+        }
+        const initial = LANES.map(lane => ({ lane, step: store.step("generate", teacherRequest(example, lane)) }));
+        if (initial.some(({ step }) => !step.result)) {
+            const blocked = initial.filter(({ step }) => !step.result && step.status !== "pending");
+            if (blocked.length) {
+                result.blocked += blocked.length;
+                result.flagged++;
+                store.flagReview(example, "generation-unresolved", { steps: blocked.map(({ step }) => step.id) });
+            }
+            else
+                result.awaitingTeacher++;
             return;
         }
         if (options.maxExamples !== undefined && result.examples >= options.maxExamples)
             return;
         store.renew();
-        const snapshot = await createSearch(source.stateDir, corpus.chatTypes, example.timestamp);
+        let snapshot;
+        try {
+            snapshot = await createSearch(source.stateDir, corpus.chatTypes, example.timestamp);
+        }
+        catch (error) {
+            if (!(error instanceof HistoricalCorpusUnavailableError))
+                throw error;
+            store.flagReview(example, "historical-snapshot-unavailable", { timestamp: example.timestamp });
+            result.flagged++;
+            return;
+        }
         try {
             const evaluation = store.step("evaluate", { version: SELECTION_VERSION, sourceId: example.id, inputHash: example.inputHash,
-                timestamp: example.timestamp, teacherId: teacher.id, corpusHash: snapshot.corpusHash,
+                timestamp: example.timestamp, teacherIds: initial.map(({ step }) => step.id), corpusHash: snapshot.corpusHash,
                 retrievalVersion: TRAINING_RETRIEVAL_VERSION, judgeVersion: CONTEXT_JUDGE_VERSION,
-                exclusions: options.excludeJudgments?.toSorted() ?? [], options: TRAINING_SEARCH_OPTIONS });
+                options: TRAINING_SEARCH_OPTIONS });
             if (evaluation.result) {
                 result.cached++;
+                store.clearReview(example.id);
                 return;
             }
             if (evaluation.status !== "pending") {
                 result.blocked++;
+                result.flagged++;
+                store.flagReview(example, "evaluation-unresolved", { steps: [evaluation.id] });
                 return;
             }
-            // Snapshot creation is async: reserve the shared example budget only after it settles.
             if (shouldStop() || (options.maxExamples !== undefined && result.examples >= options.maxExamples))
                 return;
             result.examples++;
             if (options.dryRun)
                 return;
             const input = JSON.parse(example.inputJson);
+            const problems = new Set();
             const judge = (hit) => {
                 const request = contextJudgeRequest(input, snapshot.maxDate, hit);
-                // Same identity as the experiment: duplicate query memberships share one judgment.
-                const identity = trainingHash([CONTEXT_JUDGE_VERSION, example.inputHash, hit.position, request]);
+                const identity = trainingHash([CONTEXT_JUDGE_VERSION, request]);
                 let pending = judgments.get(identity);
                 if (!pending) {
                     pending = (async () => {
-                        const excluded = options.excludeJudgments?.includes(identity) || store.judgmentExcluded(identity);
-                        const step = store.step("judge", { identity, request, excluded });
+                        const step = store.step("judge", { identity, request });
                         if (step.result) {
                             result.cached++;
                             return { id: step.id, result: step.result };
                         }
-                        if (excluded) {
-                            const attempt = store.startStep("judge", step.id, step.request);
-                            const value = { excluded: true, reason: "operator-exclusion" };
-                            store.finishStep("judge", step.id, attempt, { result: value });
-                            return { id: step.id, result: value };
+                        if (step.status !== "pending") {
+                            result.blocked++;
+                            return { id: step.id, result: undefined };
                         }
                         const credential = await apiKey();
-                        if (shouldStop())
+                        if (!room())
                             return { id: step.id, result: undefined };
-                        if (options.maxCalls !== undefined && result.calls >= options.maxCalls) {
-                            result.budgetLimited = true;
-                            return { id: step.id, result: undefined };
-                        }
                         return { id: step.id, result: await checkpoint(store, step, result, () => judgeTrainingPassage(request, credential)) };
                     })();
                     judgments.set(identity, pending);
                 }
                 return pending;
             };
-            // Keep teacher order, and drain every in-flight operation before closing its snapshot.
-            const settled = await Promise.allSettled(teacher.result.queries.map(async (query) => {
+            const scoreQueries = async (lane, round, generation, generationId) => await drain(generation.queries.map(async (query) => {
                 try {
-                    if (shouldStop())
+                    const score = store.step("score", { version: SELECTION_VERSION, lane, round, generationId, query,
+                        sourceId: example.id, corpusHash: snapshot.corpusHash, judgeVersion: CONTEXT_JUDGE_VERSION,
+                        retrievalVersion: TRAINING_RETRIEVAL_VERSION });
+                    if (score.result) {
+                        result.cached++;
+                        return score.result;
+                    }
+                    if (score.status !== "pending") {
+                        problems.add(score.id);
+                        result.blocked++;
                         return;
-                    const retrieval = store.step("retrieve", { version: TRAINING_RETRIEVAL_VERSION, query,
+                    }
+                    const retrieval = store.step("retrieve", { version: TRAINING_RETRIEVAL_VERSION, query, lane,
                         sourceId: example.id, maxDate: snapshot.maxDate, corpusHash: snapshot.corpusHash, options: TRAINING_SEARCH_OPTIONS });
-                    if (shouldStop())
+                    if (!retrieval.result && retrieval.status === "pending" && !room())
                         return;
-                    // No await between this check and checkpoint's synchronous reservation of result.calls.
-                    if (!retrieval.result && options.maxCalls !== undefined && result.calls >= options.maxCalls) {
-                        result.budgetLimited = true;
+                    const retrieved = await checkpoint(store, retrieval, result, async () => ({ query, lane, maxDate: snapshot.maxDate,
+                        corpusHash: snapshot.corpusHash, hits: await snapshot.search(query, lane) }));
+                    if (!retrieved) {
+                        problems.add(retrieval.id);
                         return;
                     }
-                    const retrieved = await checkpoint(store, retrieval, result, async () => ({ query, maxDate: snapshot.maxDate,
-                        corpusHash: snapshot.corpusHash, hits: await snapshot.search(query) }));
-                    if (!retrieved)
-                        return;
                     if (!retrieval.result)
                         result.retrievals++;
-                    const settledHits = await Promise.allSettled(retrieved.hits.map(judge));
-                    const failure = settledHits.find(item => item.status === "rejected");
-                    if (failure)
-                        throw failure.reason;
-                    const scored = settledHits.flatMap(item => item.status === "fulfilled" ? [item.value] : []);
-                    if (scored.some(item => !item.result))
+                    const scored = await drain(retrieved.hits.map(judge));
+                    const missing = scored.filter(item => !item.result);
+                    if (missing.length) {
+                        for (const item of missing) {
+                            const record = store.stepRecordStatus(item.id);
+                            if (record && record !== "pending")
+                                problems.add(item.id);
+                        }
+                        return;
+                    }
+                    const probabilities = scored.map(item => item.result.probability);
+                    return save(store, score, { query, lane, round, retrievalId: retrieval.id,
+                        score: trainingQueryScore(probabilities), maxProbability: Math.max(0, ...probabilities), judgments: scored.map(item => item.id) });
+                }
+                catch (error) {
+                    stopped = true;
+                    throw error;
+                }
+            }));
+            const lanes = await drain(initial.map(async ({ lane, step }) => {
+                try {
+                    const first = await scoreQueries(lane, 1, step.result, step.id);
+                    if (first.some(item => !item) || shouldStop())
+                        return;
+                    const feedback = first.map(item => ({ query: item.query, score: item.score }));
+                    // The only feedback sent to Luna is this lane's exact earlier queries and scores.
+                    const revision = store.step("generate", teacherRequest(example, lane, feedback));
+                    let pending = revisions.get(revision.id);
+                    if (!pending) {
+                        pending = (async () => {
+                            if (!revision.result && revision.status === "pending") {
+                                const bytes = Buffer.byteLength(trainingTeacherMessage(input, lane, feedback)) + Buffer.byteLength(trainingTeacherPrompt(lane));
+                                if (!room())
+                                    return;
+                                if (result.inputBytes + bytes > (options.maxInputBytes ?? 3_000_000)) {
+                                    result.budgetLimited = true;
+                                    return;
+                                }
+                                result.inputBytes += bytes;
+                                teacher ??= trainingTeacher(runtime, source.agentId);
+                            }
+                            return checkpoint(store, revision, result, () => teacher(input, lane, feedback));
+                        })();
+                        revisions.set(revision.id, pending);
+                    }
+                    const revised = await pending;
+                    if (!revised) {
+                        if (store.stepRecordStatus(revision.id))
+                            problems.add(revision.id);
+                        return;
+                    }
+                    const second = await scoreQueries(lane, 2, revised, revision.id);
+                    if (second.some(item => !item))
                         return;
-                    const scores = scored.flatMap(item => item.result && "score" in item.result ? [item.result.score] : []);
-                    return { query, retrievalId: retrieval.id, score: scores.sort((a, b) => b - a).slice(0, 5).reduce((a, b) => a + b, 0),
-                        judgments: scored.map(item => ({ id: item.id, excluded: !!item.result && "excluded" in item.result })) };
+                    return { teacherIds: [step.id, revision.id], queries: [...first, ...second].filter((item) => !!item) };
                 }
                 catch (error) {
                     stopped = true;
                     throw error;
                 }
             }));
-            const failure = settled.find(item => item.status === "rejected");
-            if (failure)
-                throw failure.reason;
-            const queries = settled.flatMap(item => item.status === "fulfilled" && item.value ? [item.value] : []);
-            if (queries.length !== 10)
-                return; // Resume only unfinished queries; never repeat completed calls.
+            if (problems.size) {
+                result.flagged++;
+                store.flagReview(example, "evaluation-unresolved", { steps: [...problems] });
+                return;
+            }
+            if (lanes.some(lane => !lane))
+                return; // Budget pause: completed operations remain reusable.
+            const queries = lanes.flatMap(lane => lane.queries);
             const selected = selectTrainingQueries(queries);
-            const attempt = store.startStep("evaluate", evaluation.id, evaluation.request);
-            store.finishStep("evaluate", evaluation.id, attempt, { result: { sourceId: example.id, inputHash: example.inputHash,
-                    timestamp: example.timestamp, corpusHash: snapshot.corpusHash, corpusReport: snapshot.report, teacherId: teacher.id, queries, selected } });
+            save(store, evaluation, { sourceId: example.id, inputHash: example.inputHash, timestamp: example.timestamp,
+                corpusHash: snapshot.corpusHash, corpusReport: snapshot.report, teacherIds: lanes.flatMap(lane => lane.teacherIds), queries, selected, review: [] });
+            store.clearReview(example.id);
             result.evaluated++;
         }
         finally {
@@ -242,7 +377,7 @@ export async function evaluateTrainingQueries(source, store, config, options, cr
     };
     const examples = store.queryExamples(options.threshold);
     let next = 0;
-    const workers = await Promise.allSettled(Array.from({ length: Math.min(concurrency, examples.length) }, async () => {
+    await drain(Array.from({ length: Math.min(concurrency, examples.length) }, async () => {
         while (!shouldStop() && (options.maxExamples === undefined || result.examples < options.maxExamples)) {
             const example = examples[next++];
             if (!example)
@@ -256,27 +391,28 @@ export async function evaluateTrainingQueries(source, store, config, options, cr
             }
         }
     }));
-    const failure = workers.find(item => item.status === "rejected");
-    if (failure)
-        throw failure.reason; // All workers/snapshots have drained, including on storage failures.
     return { refreshed, ...result, concurrency, threshold: options.threshold ?? TRAINING_GATE_THRESHOLD,
-        retrievalMethod: "vector10-bm25-10", callUnit: "retrieval operation or uncached passage judgment" };
+        retrievalMethod: "independent-lex10-vec10", callUnit: "teacher completion, retrieval operation or uncached passage judgment" };
 }
 export function* exportQueryTraining(store, threshold = TRAINING_GATE_THRESHOLD) {
     const active = new Map(store.queryExamples(threshold).map(e => [e.id, e]));
-    const exported = new Set();
-    for (const evaluation of store.completedEvaluations({ selection: SELECTION_VERSION, retrieval: TRAINING_RETRIEVAL_VERSION })) {
+    const unresolved = new Set(store.reviews().map(review => review.sourceId)), exported = new Set();
+    for (const evaluation of store.completedEvaluations({ selection: SELECTION_VERSION, retrieval: TRAINING_RETRIEVAL_VERSION, judge: CONTEXT_JUDGE_VERSION })) {
         const source = active.get(evaluation.sourceId);
         if (!source || source.inputHash !== evaluation.inputHash || source.timestamp !== evaluation.timestamp || exported.has(source.id))
             continue;
-        if (store.step("generate", teacherRequest(source)).id !== evaluation.teacherId)
+        exported.add(source.id); // Never fall back to an older accepted corpus after a newer flagged result.
+        if (unresolved.has(source.id))
+            continue;
+        if (!LANES.every(lane => evaluation.teacherIds.includes(store.step("generate", teacherRequest(source, lane)).id)))
             continue;
-        exported.add(source.id); // Only the newest corpus evaluation per source.
-        const provenance = [evaluation.teacherId, ...evaluation.queries.flatMap(q => [q.retrievalId, ...q.judgments?.map(j => j.id) ?? []])];
+        // Selection is a local policy over completed scores, not another paid step.
+        // This also recovers v2 checkpoints whose old usefulness policy saved null.
+        const selected = selectTrainingQueries(evaluation.queries);
+        const provenance = [...evaluation.teacherIds, ...evaluation.queries.flatMap(q => [q.retrievalId, ...q.judgments])];
         yield { stage: "query-training", input: JSON.parse(source.inputJson), inputHash: source.inputHash,
-            recallProbability: source.recallProbability, threshold,
-            target: evaluation.selected, source: store.sourceDetails(source.id), evaluation,
-            splitGroup: trainingHash(source.sessionId), // Also keep identical inputHash groups together across sessions/nodes.
+            recallProbability: source.recallProbability, threshold, target: selected, targetPolicy: TARGET_POLICY,
+            source: store.sourceDetails(source.id), evaluation: { ...evaluation, selected, review: [] }, splitGroup: trainingHash(source.sessionId),
             provenance: [...new Set(provenance)].map(id => store.stepRecord(id)) };
     }
 }

package/dist/src/training-retrieval.d.ts

@@ -1,6 +1,7 @@
 import type { ChatType } from "./config.js";
 import type { SessionMessageSpan } from "./session-projector.js";
-export declare const TRAINING_RETRIEVAL_VERSION = "qmd-2.10.1-historical-prefix-depth10-v2";
+import type { QueryLane } from "./query-contract.js";
+export declare const TRAINING_RETRIEVAL_VERSION = "qmd-2.10.2-historical-lanes-depth10-v3:complete-excerpt-1200-v1";
 export declare const TRAINING_SEARCH_OPTIONS: {
     readonly vector: 10;
     readonly bm25: 10;
@@ -9,12 +10,18 @@ export declare const TRAINING_SEARCH_OPTIONS: {
 };
 export type TrainingHit = {
     path: string;
+    corpus: string;
     text: string;
     dates: string[];
     position: number;
+    startLine: number;
+    endLine: number;
     score: number;
     methods: string[];
 };
+/** Missing historical evidence is reviewable; unexpected SQLite/I/O failures remain fatal. */
+export declare class HistoricalCorpusUnavailableError extends Error {
+}
 /** Never infer dates by parsing message bodies: headings can be quoted or forged. */
 export declare function historicalPrefix(body: string, spans: readonly SessionMessageSpan[] | undefined, cutoff: number): {
     body: string;
@@ -32,6 +39,6 @@ export declare function historicalTrainingSearch(stateDir: string, chatTypes: re
         excludedChunks: number;
     };
     maxDate: string;
-    search: (query: string) => Promise<TrainingHit[]>;
+    search: (query: string, lane: QueryLane) => Promise<TrainingHit[]>;
     close: () => Promise<void>;
 }>;

package/dist/src/training-retrieval.js

@@ -1,13 +1,17 @@
 import { createHash } from "node:crypto";
-import { existsSync } from "node:fs";
+import { statSync } from "node:fs";
 import { join } from "node:path";
 import { createRequire } from "node:module";
 import { setImmediate as yieldToEventLoop } from "node:timers/promises";
 import { readSessionManifest } from "./session-sync.js";
 import { resolveSessionSource } from "./sources.js";
 import { trainingCandidates } from "./training-candidates.js";
-export const TRAINING_RETRIEVAL_VERSION = "qmd-2.10.1-historical-prefix-depth10-v2";
+import { MEMORY_PASSAGE_VERSION, renderMemoryPassage, duplicateMemoryPassage } from "./memory-passage.js";
+export const TRAINING_RETRIEVAL_VERSION = `qmd-2.10.2-historical-lanes-depth10-v3:${MEMORY_PASSAGE_VERSION}`;
 export const TRAINING_SEARCH_OPTIONS = { vector: 10, bm25: 10, mergedLimit: null, rerank: false };
+/** Missing historical evidence is reviewable; unexpected SQLite/I/O failures remain fatal. */
+export class HistoricalCorpusUnavailableError extends Error {
+}
 /** Never infer dates by parsing message bodies: headings can be quoted or forged. */
 export function historicalPrefix(body, spans, cutoff) {
     if (!spans?.length || !body.startsWith("# Transcript\n\n") || !Number.isFinite(cutoff))
@@ -47,8 +51,15 @@ export function historicalPrefix(body, spans, cutoff) {
  * No filesystem projection, live-index mutation, model re-embedding or dependency patch. */
 export async function historicalTrainingSearch(stateDir, chatTypes, cutoff, openStore) {
     const indexPath = join(stateDir, "index.sqlite");
-    if (!existsSync(indexPath))
-        throw new Error("No QMD index; sync sessions before evaluating training queries");
+    try {
+        statSync(indexPath);
+    }
+    catch (error) {
+        if (error && typeof error === "object" && "code" in error && error.code === "ENOENT") {
+            throw new HistoricalCorpusUnavailableError("No QMD index; sync sessions before evaluating training queries");
+        }
+        throw error;
+    }
     const manifest = await readSessionManifest(join(stateDir, "sessions-manifest.json"));
     const source = resolveSessionSource(join(stateDir, "sessions"), chatTypes);
     const createStore = openStore ?? (await import("@unblocklabs/qmd")).createStore;
@@ -189,16 +200,21 @@ export async function historicalTrainingSearch(stateDir, chatTypes, cutoff, open
             }
         };
         return { corpusHash, report, maxDate,
-            search: async (query) => {
+            search: async (query, lane) => {
                 if (closed)
                     throw new Error("Historical snapshot is closed");
                 if (!report.sessions)
                     return [];
-                if (!report.chunks)
-                    throw new Error("Historical snapshot has no vectors; refusing a BM25-only evaluation");
+                if (lane === "vec" && !report.chunks)
+                    throw new HistoricalCorpusUnavailableError("Historical snapshot has no vectors; refusing an unresolved vector evaluation");
                 const qmd = await (indexed ??= materialize());
-                const hits = await trainingCandidates(qmd, query, source.collection, `Historical request made at ${maxDate}. Current, now and latest refer to that timestamp.`);
-                return hits.map(hit => trainingHit(hit, metadata, cutoff));
+                const hits = await trainingCandidates(qmd, query, source.collection, lane);
+                const rendered = await Promise.all(hits.map(hit => trainingHit(hit, metadata, cutoff)));
+                const distinct = [];
+                for (const hit of rendered)
+                    if (hit && !duplicateMemoryPassage(hit, distinct))
+                        distinct.push(hit);
+                return distinct;
             }, close: async () => {
                 if (closed)
                     return;
@@ -221,12 +237,20 @@ function historicalChunk(chunk, length) {
     return Number.isSafeInteger(chunk.pos) && Number.isSafeInteger(chunk.chunk_len) && chunk.pos >= 0 && chunk.chunk_len > 0 &&
         chunk.pos + chunk.chunk_len <= length;
 }
-function trainingHit(hit, metadata, cutoff) {
-    const spans = metadata.get(hit.file)?.filter(s => s.start < hit.bestChunkPos + hit.bestChunk.length && s.end > hit.bestChunkPos);
+async function trainingHit(hit, metadata, cutoff) {
+    const messages = metadata.get(hit.file);
+    const selected = await renderMemoryPassage({ body: hit.body, bestChunk: hit.bestChunk,
+        chunkPos: hit.bestChunkPos, chunkLen: hit.bestChunk.length }, messages);
+    if (!selected)
+        return;
+    const spans = messages?.filter(s => s.start < selected.position + (selected.sourceText ?? selected.text).length && s.end > selected.position);
     if (!spans?.length || spans.some(s => !(Date.parse(s.timestamp) < Math.floor(cutoff / 1000) * 1000)) ||
         hit.body.slice(hit.bestChunkPos, hit.bestChunkPos + hit.bestChunk.length) !== hit.bestChunk) {
         throw new Error("QMD returned evidence outside the historical snapshot");
     }
-    return { path: hit.file, position: hit.bestChunkPos, text: hit.bestChunk, dates: [...new Set(spans.map(s => s.timestamp))],
+    const startLine = hit.body.slice(0, selected.position).split("\n").length;
+    const endLine = startLine + (selected.sourceText ?? selected.text).split("\n").length - 1;
+    return { path: hit.file, corpus: "sessions", position: selected.position, text: selected.text, startLine, endLine,
+        dates: [...new Set(spans.map(s => s.timestamp))],
         score: hit.score, methods: hit.explain?.methods ?? [] };
 }