@unblocklabs/unblock-memory 0.3.29 → 0.4.0

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 ?? [] };
 }

package/dist/src/training-runtime.js

@@ -66,7 +66,7 @@ export function registerMemoryTraining(api, config) {
                 process.exitCode = 1;
         });
         for (const command of ["generate", "evaluate"]) {
-            const stage = root.command(command).description(command === "generate" ? "Generate ten exact queries with isolated gpt-6-luna" : "Rank queries using existing historical QMD results")
+            const stage = root.command(command).description(command === "generate" ? "Generate five candidates per lex/vec lane with isolated gpt-6-luna" : "Grade, revise once per lane and select independent lex/vec winners")
                 .option("--agent <id>", "Agent id", "main")
                 .option("--threshold <p>", "Minimum completed recall probability", String(TRAINING_GATE_THRESHOLD))
                 .option("--max-examples <n>", "Optional maximum uncached examples")
@@ -75,18 +75,18 @@ export function registerMemoryTraining(api, config) {
                 stage.option("--max-input-bytes <n>", "Teacher input byte budget", "3000000")
                     .option("--concurrency <n>", "Concurrent isolated teacher completions", "8");
             else
-                stage.option("--max-calls <n>", "Maximum new retrieval operations plus uncached passage judgments")
-                    .option("--exclude-judgment <hash...>", "Explicitly exclude exact judgment hashes; persist exclusions, never score as zero")
+                stage.option("--max-calls <n>", "Maximum new teacher completions, retrieval operations and passage judgments")
+                    .option("--max-input-bytes <n>", "Revision teacher input byte budget", "3000000")
                     .option("--concurrency <n>", "Concurrent historical inputs; remote passage judgments run concurrently", String(TRAINING_EVALUATION_CONCURRENCY));
             stage.action(async (opts) => {
                 const options = { maxExamples: opts.maxExamples === undefined ? undefined : Number(opts.maxExamples),
                     dryRun: opts.dryRun, threshold: thresholdOption(opts.threshold) };
                 const result = await withStore(opts.agent, {}, async (store, source) => command === "generate"
                     ? await generateTrainingQueries(source, store, api.runtime, { ...options, maxInputBytes: Number(opts.maxInputBytes), concurrency: Number(opts.concurrency) })
-                    : await evaluateTrainingQueries(source, store, config, { ...options, maxCalls: opts.maxCalls === undefined ? undefined : Number(opts.maxCalls),
-                        concurrency: Number(opts.concurrency), excludeJudgments: opts.excludeJudgment }));
+                    : await evaluateTrainingQueries(source, store, config, api.runtime, { ...options, maxCalls: opts.maxCalls === undefined ? undefined : Number(opts.maxCalls),
+                        concurrency: Number(opts.concurrency), maxInputBytes: Number(opts.maxInputBytes) }));
                 console.log(JSON.stringify(result, null, 2));
-                if (result.failed || result.ambiguous || result.blocked)
+                if (result.failed || result.ambiguous || result.blocked || result.flagged)
                     process.exitCode = 1;
             });
         }
@@ -97,9 +97,10 @@ export function registerMemoryTraining(api, config) {
             console.log(JSON.stringify(await withStore(opts.agent, { readOnly: true }, store => store.status(threshold)), null, 2));
         });
         root.command("retry-failed").option("--agent <id>", "Agent id", "main")
+            .requiredOption("--id <hash...>", "Exact reviewed recall-gate or query-step hashes from status")
             .option("--include-ambiguous", "Explicitly permit retrying requests that may already have been billed")
             .action(async (opts) => {
-            const reset = await withStore(opts.agent, {}, store => store.retry(opts.includeAmbiguous === true));
+            const reset = await withStore(opts.agent, {}, store => store.retry(opts.includeAmbiguous === true, opts.id));
             console.log(JSON.stringify({ reset, calls: 0 }));
         });
         root.command("export").option("--agent <id>", "Agent id", "main")

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

@@ -1,8 +1,9 @@
 import { type TrainingExample, type TrainingInput } from "./training-input.js";
 import { type judgeTrainingInput } from "./training-gate.js";
-import type { TeacherResult } from "./training-models.js";
+import { type TeacherResult, type TrainingRound } from "./training-models.js";
 import type { TrainingHit } from "./training-retrieval.js";
-import type { parseContextJudgment } from "./training-judge.js";
+import type { judgeTrainingPassage } from "./training-judge.js";
+import type { QueryLane, QueryPair } from "./query-contract.js";
 type GateResult = Awaited<ReturnType<typeof judgeTrainingInput>>;
 type Job = {
     id: string;
@@ -18,19 +19,19 @@ export type TrainingSourceExample = {
 };
 export type QueryEvaluation = {
     query: string;
+    lane: QueryLane;
+    round: TrainingRound;
     retrievalId: string;
     score: number;
-    judgments?: {
-        id: string;
-        excluded: boolean;
-    }[];
+    maxProbability: number;
+    judgments: string[];
 };
 type TrainingEvaluation = {
     sourceId: string;
     inputHash: string;
     timestamp: number;
     corpusHash: string;
-    teacherId: string;
+    teacherIds: string[];
     corpusReport: {
         sessions: number;
         chunks: number;
@@ -39,23 +40,31 @@ type TrainingEvaluation = {
         excludedChunks: number;
     };
     queries: QueryEvaluation[];
-    selected: string[];
+    selected: QueryPair | null;
+    review: string[];
 };
 export type TrainingStepResults = {
     generate: TeacherResult;
     retrieve: {
         query: string;
+        lane: QueryLane;
         maxDate: string;
         corpusHash: string;
         hits: TrainingHit[];
     };
-    judge: ReturnType<typeof parseContextJudgment> | {
-        excluded: true;
-        reason: "operator-exclusion";
-    };
+    judge: Awaited<ReturnType<typeof judgeTrainingPassage>>;
+    score: QueryEvaluation;
     evaluate: TrainingEvaluation;
 };
 type StepStatus = "pending" | "attempted" | "complete" | "failed" | "ambiguous";
+type ReviewDetails = {
+    steps: string[];
+} | {
+    lanes: string[];
+    evaluationId: string;
+} | {
+    timestamp: number;
+};
 export declare class TrainingStore {
     #private;
     constructor(path: string, agentId: string);
@@ -75,7 +84,7 @@ export declare class TrainingStore {
         status: "failed" | "ambiguous";
         error: string;
     }): void;
-    retry(includeAmbiguous: boolean): number;
+    retry(includeAmbiguous: boolean, ids: readonly string[]): number;
     activeExamples(): TrainingSourceExample[];
     queryExamples(threshold?: number): {
         recallProbability: number;
@@ -85,14 +94,24 @@ export declare class TrainingStore {
         sessionId: string;
         timestamp: number;
     }[];
-    step<S extends keyof TrainingStepResults>(stage: S, request: unknown): {
+    step<S extends keyof TrainingStepResults>(stage: S, parameters: Record<string, unknown>): {
         id: string;
         stage: S;
-        request: unknown;
+        request: {
+            recipe: string;
+        };
         status: StepStatus;
         result: TrainingStepResults[S] | undefined;
     };
-    judgmentExcluded(identity: string): boolean;
+    flagReview(example: TrainingSourceExample, reason: string, details: ReviewDetails): void;
+    clearReview(sourceId: string): void;
+    reviews(): {
+        sourceId: string;
+        inputHash: string;
+        reason: string;
+        details: ReviewDetails;
+        updatedAt: number;
+    }[];
     startStep(stage: keyof TrainingStepResults, id: string, request: unknown): number;
     finishStep<S extends keyof TrainingStepResults>(stage: S, id: string, attempt: number, outcome: {
         result: TrainingStepResults[S];
@@ -103,6 +122,7 @@ export declare class TrainingStore {
     completedEvaluations(versions?: {
         selection: string;
         retrieval: string;
+        judge: string;
     }): TrainingEvaluation[];
     sourceDetails(id: string): {
         nodeId: string;
@@ -116,6 +136,7 @@ export declare class TrainingStore {
         result: unknown;
         completedAt: import("node:sqlite").SQLOutputValue;
     };
+    stepRecordStatus(id: string): StepStatus | undefined;
     status(threshold: number): {
         nodeId: string;
         agentId: string;
@@ -132,6 +153,15 @@ export declare class TrainingStore {
         inputTokens: number;
         outputTokens: number;
         negative: number;
+        recipe: string;
+        reviews: {
+            sourceId: string;
+            inputHash: string;
+            reason: string;
+            details: ReviewDetails;
+            updatedAt: number;
+        }[];
+        retryable: Record<string, import("node:sqlite").SQLOutputValue>[];
         queryStages: Record<string, import("node:sqlite").SQLOutputValue>[];
         queryAttempts: Record<string, import("node:sqlite").SQLOutputValue>[];
         attempts: Record<string, import("node:sqlite").SQLOutputValue>[];

package/dist/src/training-store.js

@@ -2,6 +2,7 @@ import { randomUUID } from "node:crypto";
 import { openMemoryDatabase } from "./memory-database.js";
 import { trainingHash, TRAINING_PREPARATION } from "./training-input.js";
 import { TRAINING_GATE_MODEL, TRAINING_GATE_THRESHOLD, TRAINING_GATE_VERSION } from "./training-gate.js";
+import { TRAINING_RECIPE_VERSION } from "./training-models.js";
 const LEASE_MS = 120_000;
 export class TrainingStore {
     #db;
@@ -43,8 +44,10 @@ export class TrainingStore {
           status TEXT NOT NULL CHECK(status IN ('pending','attempted','complete','failed','ambiguous')),
           result_json TEXT, error TEXT, completed_at INTEGER
         ) STRICT;
-        CREATE INDEX IF NOT EXISTS training_judgment_exclusions ON training_steps(json_extract(request_json,'$.identity'))
-          WHERE stage='judge' AND status='complete' AND json_extract(result_json,'$.excluded')=1;
+        CREATE TABLE IF NOT EXISTS training_reviews (
+          source_id TEXT PRIMARY KEY REFERENCES training_examples(id), input_hash TEXT NOT NULL,
+          recipe TEXT NOT NULL, reason TEXT NOT NULL, details_json TEXT NOT NULL, updated_at INTEGER NOT NULL
+        ) STRICT;
         CREATE TABLE IF NOT EXISTS training_step_attempts (
           id INTEGER PRIMARY KEY, step_id TEXT NOT NULL REFERENCES training_steps(id), started_at INTEGER NOT NULL,
           finished_at INTEGER, status TEXT NOT NULL, error TEXT, result_json TEXT
@@ -87,10 +90,17 @@ export class TrainingStore {
             if (!lock.changes)
                 throw new Error("Another memory-training command is running");
             // A request may have been billed before a crashed process saved the response.
-            this.#db.exec(`UPDATE training_gates SET status='ambiguous',error='interrupted' WHERE status='attempted';
-        UPDATE training_attempts SET status='ambiguous',error='interrupted' WHERE status='attempted';
-        UPDATE training_steps SET status='ambiguous',error='interrupted' WHERE status='attempted';
-        UPDATE training_step_attempts SET status='ambiguous',error='interrupted' WHERE status='attempted';`);
+            this.#db.prepare(`UPDATE training_gates SET status='ambiguous',error='interrupted' WHERE status='attempted'
+        AND prompt_version=? AND requested_model=? AND input_hash IN (SELECT hash FROM training_inputs WHERE preparation=?)`)
+                .run(TRAINING_GATE_VERSION, TRAINING_GATE_MODEL, TRAINING_PREPARATION);
+            this.#db.prepare(`UPDATE training_attempts SET status='ambiguous',error='interrupted' WHERE status='attempted'
+        AND gate_id IN (SELECT g.id FROM training_gates g JOIN training_inputs i ON i.hash=g.input_hash
+          WHERE g.prompt_version=? AND g.requested_model=? AND i.preparation=?)`)
+                .run(TRAINING_GATE_VERSION, TRAINING_GATE_MODEL, TRAINING_PREPARATION);
+            this.#db.prepare(`UPDATE training_steps SET status='ambiguous',error='interrupted' WHERE status='attempted'
+        AND json_extract(request_json,'$.recipe')=?`).run(TRAINING_RECIPE_VERSION);
+            this.#db.prepare(`UPDATE training_step_attempts SET status='ambiguous',error='interrupted' WHERE status='attempted'
+        AND step_id IN (SELECT id FROM training_steps WHERE json_extract(request_json,'$.recipe')=?)`).run(TRAINING_RECIPE_VERSION);
         });
         let leaseError;
         const heartbeat = setInterval(() => { try {
@@ -156,13 +166,14 @@ export class TrainingStore {
         this.#db.prepare("UPDATE training_examples SET active=-1 WHERE session_id=? AND active=1").run(sessionId);
     }
     #scope = `g.prompt_version=? AND g.requested_model=? AND EXISTS
-    (SELECT 1 FROM training_examples e WHERE e.input_hash=g.input_hash AND e.active=1)`;
+    (SELECT 1 FROM training_examples e JOIN training_inputs i ON i.hash=e.input_hash
+      WHERE e.input_hash=g.input_hash AND e.active=1 AND i.preparation=?)`;
     pending(limit) {
         return this.#db.prepare(`SELECT g.id,g.input_hash inputHash,i.input_json inputJson
       FROM training_gates g JOIN training_inputs i ON i.hash=g.input_hash
       WHERE ${this.#scope} AND g.status='pending' ORDER BY
       (SELECT MAX(timestamp) FROM training_examples WHERE input_hash=g.input_hash AND active=1) DESC,g.id LIMIT ?`)
-            .all(TRAINING_GATE_VERSION, TRAINING_GATE_MODEL, limit ?? -1);
+            .all(TRAINING_GATE_VERSION, TRAINING_GATE_MODEL, TRAINING_PREPARATION, limit ?? -1);
     }
     start(id) {
         return this.#transaction(() => {
@@ -185,35 +196,61 @@ export class TrainingStore {
                 .run(status, Date.now(), error, ok ? JSON.stringify(result) : null, attempt, id);
         });
     }
-    retry(includeAmbiguous) {
+    retry(includeAmbiguous, ids) {
+        if (!ids.length || ids.some(id => !/^[a-f0-9]{64}$/u.test(id)))
+            throw new Error("Specify exact training gate or step hashes to retry");
         this.#checkLease();
-        return this.#transaction(() => ["training_gates", "training_steps"].reduce((n, table) => n + Number(this.#db.prepare(`UPDATE ${table} SET status='pending',error=NULL WHERE status='failed' ${includeAmbiguous ? "OR status='ambiguous'" : ""}`).run().changes), 0));
+        return this.#transaction(() => ids.reduce((count, id) => {
+            const statuses = includeAmbiguous ? "('failed','ambiguous')" : "('failed')";
+            const gates = this.#db.prepare(`UPDATE training_gates SET status='pending',error=NULL WHERE id=?
+        AND prompt_version=? AND requested_model=? AND status IN ${statuses}
+        AND input_hash IN (SELECT hash FROM training_inputs WHERE preparation=?)`)
+                .run(id, TRAINING_GATE_VERSION, TRAINING_GATE_MODEL, TRAINING_PREPARATION);
+            const steps = this.#db.prepare(`UPDATE training_steps SET status='pending',error=NULL WHERE id=?
+        AND json_extract(request_json,'$.recipe')=? AND status IN ${statuses}`).run(id, TRAINING_RECIPE_VERSION);
+            return count + Number(gates.changes) + Number(steps.changes);
+        }, 0));
     }
     activeExamples() {
         return this.#db.prepare(`SELECT e.id,e.input_hash inputHash,i.input_json inputJson,e.session_id sessionId,e.timestamp
       FROM training_examples e JOIN training_inputs i ON i.hash=e.input_hash
-      WHERE e.active=1 ORDER BY e.timestamp DESC,e.id`).all();
+      WHERE e.active=1 AND i.preparation=? ORDER BY e.timestamp DESC,e.id`).all(TRAINING_PREPARATION);
     }
     queryExamples(threshold = TRAINING_GATE_THRESHOLD) {
         if (!Number.isFinite(threshold) || threshold < 0 || threshold > 1)
             throw new Error("Threshold must be between 0 and 1");
         const probabilities = new Map(this.#db.prepare(`SELECT g.input_hash,g.probability FROM training_gates g
       WHERE ${this.#scope} AND g.status='complete' AND g.probability>=?`)
-            .all(TRAINING_GATE_VERSION, TRAINING_GATE_MODEL, threshold).map(row => [String(row.input_hash), Number(row.probability)]));
+            .all(TRAINING_GATE_VERSION, TRAINING_GATE_MODEL, TRAINING_PREPARATION, threshold).map(row => [String(row.input_hash), Number(row.probability)]));
         return this.activeExamples().flatMap(example => {
             const recallProbability = probabilities.get(example.inputHash);
             return recallProbability === undefined ? [] : [{ ...example, recallProbability }];
         });
     }
-    step(stage, request) {
+    step(stage, parameters) {
+        const request = { ...parameters, recipe: TRAINING_RECIPE_VERSION };
         const id = trainingHash([stage, request]);
         const row = this.#db.prepare("SELECT status,result_json FROM training_steps WHERE id=? AND stage=?").get(id, stage);
         return { id, stage, request, status: (row?.status ?? "pending"),
             result: row?.status === "complete" ? JSON.parse(String(row.result_json)) : undefined };
     }
-    judgmentExcluded(identity) {
-        return !!this.#db.prepare(`SELECT 1 FROM training_steps WHERE stage='judge' AND status='complete'
-      AND json_extract(request_json,'$.identity')=? AND json_extract(result_json,'$.excluded')=1 LIMIT 1`).get(identity);
+    flagReview(example, reason, details) {
+        this.#checkLease();
+        this.#db.prepare(`INSERT INTO training_reviews VALUES (?,?,?,?,?,?) ON CONFLICT(source_id) DO UPDATE SET
+      input_hash=excluded.input_hash,recipe=excluded.recipe,reason=excluded.reason,
+      details_json=excluded.details_json,updated_at=excluded.updated_at`)
+            .run(example.id, example.inputHash, TRAINING_RECIPE_VERSION, reason, JSON.stringify(details), Date.now());
+    }
+    clearReview(sourceId) {
+        this.#checkLease();
+        this.#db.prepare("DELETE FROM training_reviews WHERE source_id=? AND recipe=?").run(sourceId, TRAINING_RECIPE_VERSION);
+    }
+    reviews() {
+        return this.#db.prepare(`SELECT r.source_id sourceId,r.input_hash inputHash,r.reason,r.details_json details,r.updated_at updatedAt
+      FROM training_reviews r JOIN training_examples e ON e.id=r.source_id
+      WHERE r.recipe=? AND e.active=1 AND e.input_hash=r.input_hash ORDER BY r.updated_at DESC,r.source_id`)
+            .all(TRAINING_RECIPE_VERSION).map(row => ({ sourceId: String(row.sourceId), inputHash: String(row.inputHash),
+            reason: String(row.reason), details: JSON.parse(String(row.details)), updatedAt: Number(row.updatedAt) }));
     }
     startStep(stage, id, request) {
         return this.#transaction(() => {
@@ -242,8 +279,10 @@ export class TrainingStore {
     }
     completedEvaluations(versions) {
         return this.#db.prepare(`SELECT result_json FROM training_steps WHERE stage='evaluate' AND status='complete'
-      AND (? IS NULL OR (json_extract(request_json,'$.version')=? AND json_extract(request_json,'$.retrievalVersion')=?)) ORDER BY completed_at DESC,id`)
-            .all(versions?.selection ?? null, versions?.selection ?? null, versions?.retrieval ?? null)
+      AND json_extract(request_json,'$.recipe')=?
+      AND (? IS NULL OR (json_extract(request_json,'$.version')=? AND json_extract(request_json,'$.retrievalVersion')=?
+        AND json_extract(request_json,'$.judgeVersion')=?)) ORDER BY completed_at DESC,id`)
+            .all(TRAINING_RECIPE_VERSION, versions?.selection ?? null, versions?.selection ?? null, versions?.retrieval ?? null, versions?.judge ?? null)
             .map(row => JSON.parse(String(row.result_json)));
     }
     sourceDetails(id) {
@@ -260,34 +299,49 @@ export class TrainingStore {
         return { id, stage: row.stage, request: JSON.parse(String(row.request_json)),
             result: JSON.parse(String(row.result_json)), completedAt: row.completed_at };
     }
+    stepRecordStatus(id) {
+        return this.#db.prepare("SELECT status FROM training_steps WHERE id=? AND json_extract(request_json,'$.recipe')=?")
+            .get(id, TRAINING_RECIPE_VERSION)?.status;
+    }
     status(threshold) {
         const stages = this.#db.prepare(`SELECT g.status,COUNT(*) count FROM training_gates g WHERE ${this.#scope} GROUP BY g.status`)
-            .all(TRAINING_GATE_VERSION, TRAINING_GATE_MODEL);
+            .all(TRAINING_GATE_VERSION, TRAINING_GATE_MODEL, TRAINING_PREPARATION);
         const labels = this.#db.prepare(`SELECT COUNT(*) complete,COALESCE(SUM(g.probability>=?),0) positive,
       COALESCE(SUM(g.input_tokens),0) inputTokens,COALESCE(SUM(g.output_tokens),0) outputTokens
-      FROM training_gates g WHERE ${this.#scope} AND g.status='complete'`).get(threshold, TRAINING_GATE_VERSION, TRAINING_GATE_MODEL);
+      FROM training_gates g WHERE ${this.#scope} AND g.status='complete'`).get(threshold, TRAINING_GATE_VERSION, TRAINING_GATE_MODEL, TRAINING_PREPARATION);
         return { nodeId: this.#nodeId, agentId: this.#agentId, preparation: TRAINING_PREPARATION,
             promptVersion: TRAINING_GATE_VERSION, requestedModel: TRAINING_GATE_MODEL, threshold,
-            examples: this.#db.prepare("SELECT active,COUNT(*) count FROM training_examples GROUP BY active").all(),
-            collectedInputs: Number(this.#db.prepare("SELECT COUNT(DISTINCT input_hash) count FROM training_examples WHERE active=1").get().count),
+            examples: this.#db.prepare(`SELECT e.active,COUNT(*) count FROM training_examples e
+        JOIN training_inputs i ON i.hash=e.input_hash WHERE i.preparation=? GROUP BY e.active`).all(TRAINING_PREPARATION),
+            collectedInputs: Number(this.#db.prepare(`SELECT COUNT(DISTINCT e.input_hash) count FROM training_examples e
+        JOIN training_inputs i ON i.hash=e.input_hash WHERE e.active=1 AND i.preparation=?`).get(TRAINING_PREPARATION).count),
             queryInputs: Number(labels.positive),
             stages, complete: Number(labels.complete), positive: Number(labels.positive),
             inputTokens: Number(labels.inputTokens), outputTokens: Number(labels.outputTokens),
             negative: Number(labels.complete) - Number(labels.positive),
-            queryStages: this.#db.prepare("SELECT stage,status,COUNT(*) count FROM training_steps GROUP BY stage,status ORDER BY stage,status").all(),
+            recipe: TRAINING_RECIPE_VERSION, reviews: this.reviews(),
+            retryable: this.#db.prepare(`SELECT id,stage,status,error FROM training_steps
+        WHERE json_extract(request_json,'$.recipe')=? AND status IN ('failed','ambiguous')
+        UNION ALL SELECT g.id,'recall',g.status,g.error FROM training_gates g WHERE ${this.#scope}
+        AND g.status IN ('failed','ambiguous') ORDER BY stage,id`)
+                .all(TRAINING_RECIPE_VERSION, TRAINING_GATE_VERSION, TRAINING_GATE_MODEL, TRAINING_PREPARATION),
+            queryStages: this.#db.prepare(`SELECT stage,status,COUNT(*) count FROM training_steps
+        WHERE json_extract(request_json,'$.recipe')=? GROUP BY stage,status ORDER BY stage,status`).all(TRAINING_RECIPE_VERSION),
             queryAttempts: this.#db.prepare(`SELECT s.stage,a.status,COUNT(*) count,
         COUNT(json_extract(a.result_json,'$.usage.input_tokens')) usageReported,
         SUM(json_extract(a.result_json,'$.usage.input_tokens')) inputTokens,
         SUM(json_extract(a.result_json,'$.usage.output_tokens')) outputTokens
-        FROM training_step_attempts a JOIN training_steps s ON s.id=a.step_id GROUP BY s.stage,a.status`).all(),
-            attempts: this.#db.prepare(`SELECT status,COUNT(*) count,
-        COALESCE(SUM(json_extract(result_json,'$.usage.input_tokens')),0) inputTokens,
-        COALESCE(SUM(json_extract(result_json,'$.usage.output_tokens')),0) outputTokens
-        FROM training_attempts GROUP BY status`).all() };
+        FROM training_step_attempts a JOIN training_steps s ON s.id=a.step_id
+        WHERE json_extract(s.request_json,'$.recipe')=? GROUP BY s.stage,a.status`).all(TRAINING_RECIPE_VERSION),
+            attempts: this.#db.prepare(`SELECT a.status,COUNT(*) count,
+        COALESCE(SUM(json_extract(a.result_json,'$.usage.input_tokens')),0) inputTokens,
+        COALESCE(SUM(json_extract(a.result_json,'$.usage.output_tokens')),0) outputTokens
+        FROM training_attempts a JOIN training_gates g ON g.id=a.gate_id WHERE ${this.#scope} GROUP BY a.status`)
+                .all(TRAINING_GATE_VERSION, TRAINING_GATE_MODEL, TRAINING_PREPARATION) };
     }
     *exportRows(threshold) {
         const rows = this.#db.prepare(`SELECT g.*,i.input_json FROM training_gates g JOIN training_inputs i ON i.hash=g.input_hash
-      WHERE ${this.#scope} AND g.status='complete' ORDER BY g.id`).iterate(TRAINING_GATE_VERSION, TRAINING_GATE_MODEL);
+      WHERE ${this.#scope} AND g.status='complete' ORDER BY g.id`).iterate(TRAINING_GATE_VERSION, TRAINING_GATE_MODEL, TRAINING_PREPARATION);
         for (const row of rows) {
             yield { stage: "recall-gate", inputHash: row.input_hash, preparation: TRAINING_PREPARATION,
                 input: JSON.parse(String(row.input_json)), recallProbability: row.probability,

package/dist/src/training.d.ts

@@ -22,6 +22,11 @@ export declare function collectTraining(source: Source, store?: TrainingStore, o
     changed: number;
     unchanged: number;
     retired: number;
+    review: {
+        sessionId: string;
+        seq: number;
+        reason: string;
+    }[];
 };
 /** Parallel, bounded paid work. Negative results are just as cacheable as positives. */
 export declare function runTraining(source: Source, store: TrainingStore, config: UnblockMemoryConfig, options: {
@@ -43,6 +48,11 @@ export declare function runTraining(source: Source, store: TrainingStore, config
         changed: number;
         unchanged: number;
         retired: number;
+        review: {
+            sessionId: string;
+            seq: number;
+            reason: string;
+        }[];
     };
     pendingSelected: number;
     calls: number;

package/dist/src/training.js

@@ -6,12 +6,13 @@ export function collectTraining(source, store, options = {}) {
     const since = options.since ?? 0, until = options.until ?? Number.MAX_SAFE_INTEGER;
     const reader = new TrainingTranscriptReader(source.databasePath, source.agentId);
     const result = { sessions: 0, excludedSessions: 0, oversizedSessions: 0, eligible: 0,
-        users: 0, filtered: 0, oversized: 0, unanswered: 0, added: 0, changed: 0, unchanged: 0, retired: 0 };
+        users: 0, filtered: 0, oversized: 0, unanswered: 0, added: 0, changed: 0, unchanged: 0, retired: 0,
+        review: [] };
     try {
         const sessions = new Set(options.existingOnly ? store?.sessions() : [...reader.sessions(), ...store?.sessions() ?? []]);
         for (const id of sessions) {
             store?.renew();
-            const extracted = reader.read(id);
+            const extracted = reader.read(id, () => store?.renew());
             result.sessions++;
             if (extracted && "oversized" in extracted) {
                 result.oversizedSessions++;
@@ -21,6 +22,7 @@ export function collectTraining(source, store, options = {}) {
             if (!extracted)
                 result.excludedSessions++;
             else {
+                result.review.push(...extracted.review.map(item => ({ sessionId: id, ...item })));
                 for (const key of ["users", "filtered", "oversized", "unanswered"])
                     result[key] += extracted.coverage[key];
                 result.eligible += extracted.examples.filter(e => e.timestamp >= since && e.timestamp < until).length;
@@ -54,7 +56,7 @@ export async function runTraining(source, store, config, options) {
         throw new Error("TypeSafe is disabled or its credential is unavailable");
     let next = 0, stopped = false;
     const workers = await Promise.allSettled(Array.from({ length: Math.min(concurrency, jobs.length) }, async () => {
-        while (!stopped && !result.budgetLimited && !result.failed && !result.ambiguous) {
+        while (!stopped && !result.budgetLimited) {
             const job = jobs[next++];
             if (!job)
                 return;
@@ -83,8 +85,8 @@ export async function runTraining(source, store, config, options) {
                     store.finish(job.id, attempt, { status, error: error instanceof TypeSafeRequestError && error.code === "http_error" ?
                             `http_${error.status}` : "request_or_response_uncertain" });
                     result[status]++;
-                    // Stop on the first failure rather than spending the rest of the budget during an outage.
-                    return;
+                    // Flag this input for operator review; do not stall untouched inputs or retry it.
+                    continue;
                 }
                 // Storage failures must not be misclassified as provider failures/retried.
                 store.finish(job.id, attempt, judgment);

package/dist/src/typesafe.d.ts

@@ -1,4 +1,4 @@
-import type { memoryConversation } from "./whisperer-context.js";
+import type { QueryConversation } from "./query-contract.js";
 /** Select from trusted candidates; never accept a provider-generated path or skill name. */
 export declare function selectTypeSafeSkill(params: {
     apiKey: string;
@@ -29,15 +29,65 @@ export declare function judgeTypeSafeQuality(params: {
         sourceKind: "files" | "sessions";
     }[];
 }): Promise<QualityJudgment[]>;
-/** One HTTP request per candidate, all launched together; result order matches input order. */
+export declare const MEMORY_JUDGE_VERSION = "jev-1.13.0:memory-usefulness-v2";
+export type MemoryPassage = {
+    excerpt: string;
+    corpus: string;
+    sourcePath: string;
+    dates: readonly string[];
+};
+/** The sole versioned passage prompt/state builder for both training and runtime. */
+export declare function memoryUsefulnessRequest(conversation: QueryConversation, candidate: MemoryPassage, asOf: string): {
+    model: string;
+    state: {
+        conversation: {
+            history: {
+                role: "user" | "assistant";
+                content: string;
+            }[];
+            currentRequest: string;
+        };
+        asOf: string;
+        candidates: {
+            excerpt: string;
+            corpus: string;
+            sourcePath: string;
+            dates: readonly string[];
+        }[];
+    };
+    questions: {
+        memory_0: {
+            type: string;
+            instructions: string;
+            criteria: {
+                true: string;
+                false: string;
+            };
+        };
+    };
+};
+export declare function judgeMemoryPassage(request: ReturnType<typeof memoryUsefulnessRequest>, params: {
+    apiKey: string;
+    timeoutMs: number;
+    signal?: AbortSignal;
+}): Promise<{
+    probability: number;
+    answer: {
+        type: "noul";
+        noul: number;
+    };
+    model: "jev-1.13.0";
+    usage: {
+        input_tokens: number;
+        output_tokens: number;
+    } | null;
+}>;
+/** One HTTP request per candidate; result order matches input order. */
 export declare function judgeTypeSafeMemories(params: {
     apiKey: string;
     timeoutMs: number;
     signal: AbortSignal;
-    conversation: ReturnType<typeof memoryConversation>;
-    candidates: readonly {
-        excerpt: string;
-        corpus: string;
-        messageTimestamp?: string;
-    }[];
+    conversation: QueryConversation;
+    asOf: string;
+    candidates: readonly MemoryPassage[];
 }): Promise<number[]>;