tewip-ai 0.19.0 → 0.21.0

package/dist/cli/help.js

@@ -100,6 +100,17 @@ Usage:
                                     same way more than once, which rule decided it, and the failures
                                     it came from. Says "not yet" rather than inventing a pattern
                                     from two cases. No model, no cost.
+  tewip recall "<an error, or a question>" [--test "<id>"] [--limit 5]
+                                    What this project already concluded: earlier failures that look
+                                    like this one, what was decided, by which rule or which person,
+                                    and the run each came from. Searches the history Tewip keeps -
+                                    no model, no network, nothing to set up.
+  tewip incident <sentry.json | otel.json | stack.txt> [--framework <id>] [--out incident.md]
+                                    Turn a production incident into a test that proves it: reads
+                                    Sentry, OpenTelemetry or a pasted stack trace, writes a test
+                                    against the code the trace names, runs it, and keeps it ONLY if
+                                    it fails for the incident's own reason. A test that passes, or
+                                    fails its own way, is reported and thrown away.
   tewip attest [--run <id>] [--out attestation.md] [--json bundle.json]
                                     What Tewip checked for a build, as one artifact: the claims with
                                     their evidence and which layer decided each, what it refused to

package/dist/cli/tewip.js

@@ -177,6 +177,25 @@ async function main() {
             runLearn({ root: process.cwd(), name: flag(args, 'name'), labels: flag(args, 'labels'), out: flag(args, 'out') });
             return;
         }
+        case 'recall': {
+            const question = args.filter((a, i) => !a.startsWith('--') && !['--test', '--limit', '--name', '--out'].includes(args[i - 1] ?? '')).join(' ').trim();
+            if (!question)
+                throw new Error('usage: tewip recall "<an error, or a question>" [--test "<test id>"] [--limit 5]');
+            const { runRecall } = await import('../engine/recall/recall-command.js');
+            runRecall({ root: process.cwd(), question, testId: flag(args, 'test'), limit: Number(flag(args, 'limit')) || undefined, name: flag(args, 'name'), out: flag(args, 'out') });
+            return;
+        }
+        case 'incident': {
+            const file = args.find((a, i) => !a.startsWith('--') && !['--framework', '--out'].includes(args[i - 1] ?? ''));
+            if (!file)
+                throw new Error('usage: tewip incident <sentry.json | otel.json | stack.txt> [--framework pytest] [--keep] [--out incident.md]');
+            const { runIncident } = await import('../engine/incident/incident-command.js');
+            const result = await runIncident({ root: process.cwd(), file, framework: flag(args, 'framework'), keep: args.includes('--keep'), out: flag(args, 'out') });
+            // A reproduction that was not reproduced is not a success, and a script should be able to tell.
+            if (!result.kept)
+                process.exitCode = 1;
+            return;
+        }
         case 'attest': {
             const { runAttest } = await import('../engine/attest/attest-command.js');
             runAttest({ root: process.cwd(), name: flag(args, 'name'), runId: flag(args, 'run'), out: flag(args, 'out'), json: flag(args, 'json') });

package/dist/engine/incident/incident-command.js

@@ -0,0 +1,111 @@
+// `tewip incident <file>`: turn what happened in production into a test that proves it.
+//
+// The loop, and the reason each step is there:
+//   read the incident      - deterministic, from Sentry, OpenTelemetry or a pasted stack trace
+//   find the code it names - the project's own frames, so the test aims at real functions
+//   write a failing test   - the model's only job, and the smallest one
+//   run it                 - because a test nobody ran proves nothing
+//   judge it               - red is not proof: it has to be red for the incident's reason
+//
+// Nothing is kept unless the judgement is "reproduced". A test that passes, fails its own way, or
+// never ran is reported as exactly that and the file is removed, because a test wrongly labelled
+// "reproduces the outage" is worse than no test: the next person will trust it.
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { noModelHelp } from '../llm/providers.js';
+import { writerFromEnv } from '../quality/model.js';
+import { usageLine } from '../llm/usage.js';
+import { chooseFramework, detectFrameworks } from '../quality/frameworks.js';
+import { draftTest } from '../quality/write.js';
+import { runTest } from '../quality/write-verify.js';
+import { ourFrames, readIncident } from './incident.js';
+import { judgeReproduction, nextStep } from './reproduced.js';
+/** The code the incident points at, so the test is written against real functions, not guesses. */
+function codeFromFrames(root, incident) {
+    const seen = new Set();
+    const out = [];
+    for (const frame of ourFrames(incident)) {
+        // A production path (/app/src/pay.ts) rarely matches a checkout, so the tail is tried too.
+        const candidates = [frame.file, ...frame.file.split('/').map((_, i, all) => all.slice(i).join('/'))];
+        for (const candidate of candidates) {
+            const path = resolve(root, candidate);
+            if (seen.has(path) || !existsSync(path) || !path.startsWith(resolve(root)))
+                continue;
+            seen.add(path);
+            out.push({ file: candidate, content: readFileSync(path, 'utf8').slice(0, 8000) });
+            break;
+        }
+        if (out.length >= 3)
+            break;
+    }
+    return out;
+}
+/** The incident as a scenario the writer already knows how to take. */
+function asScenario(incident) {
+    const where = ourFrames(incident)[0];
+    return {
+        id: 'INCIDENT-1',
+        title: `reproduce: ${incident.title}`.slice(0, 120),
+        preconditions: [incident.operation ? `the system is doing: ${incident.operation}` : 'the code path below is exercised'],
+        steps: [
+            where ? `call the code in ${where.file}${where.fn ? ` (${where.fn})` : ''}${where.line ? ` around line ${where.line}` : ''} the way production did` : 'exercise the failing path',
+            'do not guard against the failure; the test must hit it',
+        ],
+        expected: `it fails with ${[incident.errorType, incident.errorMessage].filter(Boolean).join(': ') || incident.title}. Write the test asserting the behaviour that SHOULD happen, so it is red now and green once the bug is fixed.`,
+    };
+}
+export async function runIncident(cmd) {
+    const incident = readIncident(readFileSync(resolve(cmd.file), 'utf8'));
+    const framework = chooseFramework(detectFrameworks(cmd.root), cmd.framework, false);
+    if (!framework)
+        throw new Error('no test framework was found here, so there is nothing to write a test in. Run this inside the project.');
+    const model = writerFromEnv(cmd.root);
+    if (!model)
+        throw new Error(`reproducing an incident needs a model to write the test.\n${noModelHelp()}`);
+    const code = codeFromFrames(cmd.root, incident);
+    console.error(`Read a ${incident.source} incident: ${incident.title.slice(0, 90)}`);
+    console.error(code.length > 0 ? `It points at ${code.map((c) => c.file).join(', ')}.` : 'It names no file inside this project, so the test is written from the error alone.');
+    // The framework names the file, so its runner picks it up and its imports resolve.
+    const fileName = framework.fileFor(`incident-${Date.now().toString(36)}`);
+    const testFile = join(framework.testDir, fileName);
+    mkdirSync(dirname(testFile), { recursive: true });
+    const draft = await draftTest(model, { framework, fileName, pages: [], feature: `A production incident: ${incident.title}`, code }, asScenario(incident));
+    writeFileSync(testFile, draft.code, 'utf8');
+    console.error('Wrote the test; running it now, because a test nobody ran proves nothing…');
+    const run = runTest(framework, testFile);
+    const judgement = judgeReproduction(incident, { passed: run.passed, output: run.output });
+    const kept = judgement.verdict === 'reproduced';
+    if (!kept)
+        rmSync(testFile, { force: true });
+    const report = renderIncident(incident, judgement, kept ? testFile : '', draft.code);
+    console.log(report);
+    console.error(`\n${usageLine()}`);
+    if (cmd.out) {
+        mkdirSync(dirname(resolve(cmd.out)), { recursive: true });
+        writeFileSync(resolve(cmd.out), `${report}\n`, 'utf8');
+    }
+    return { incident, judgement, testFile: kept ? testFile : '', kept };
+}
+export function renderIncident(incident, judgement, testFile, code) {
+    const where = ourFrames(incident)[0];
+    const lines = [
+        `# ${judgement.verdict === 'reproduced' ? 'Reproduced' : 'Not reproduced'}: ${incident.title.slice(0, 100)}`,
+        '',
+        `Read from ${incident.source}.${incident.operation ? ` During: ${incident.operation}.` : ''}`,
+        `Production reported: ${[incident.errorType, incident.errorMessage].filter(Boolean).join(': ') || '(no error text)'}`,
+        where ? `Your code in the trace: ${where.file}${where.line ? `:${where.line}` : ''}${where.fn ? ` (${where.fn})` : ''}` : 'No file of yours appears in the trace.',
+        '',
+        `## ${judgement.verdict === 'reproduced' ? 'The test is red for the right reason' : 'Nothing is kept'}`,
+        '',
+        judgement.why,
+        '',
+        `**Do:** ${nextStep[judgement.verdict]}`,
+        '',
+    ];
+    if (testFile)
+        lines.push(`The test is at \`${testFile}\`. It should stay red until the bug is fixed, and turning it green is the proof that it was.`, '');
+    else
+        lines.push('The test Tewip wrote is below, unkept, so you can see what was tried:', '', '```', code.slice(0, 2000), '```', '');
+    lines.push('Tewip never keeps a test that has not been run, and never calls a red test a reproduction unless it is red for the reason production was.');
+    return lines.join('\n');
+}

package/dist/engine/incident/incident.js

@@ -0,0 +1,116 @@
+const LIBRARY = /[\\/](?:node_modules|site-packages|dist-packages|vendor|\.venv|venv|target[\\/]dependency|gems)[\\/]/;
+const RUNTIME = /^(?:node:|internal[\\/]|java\.|javax\.|sun\.|System\.|Microsoft\.)/;
+const ours = (file) => Boolean(file) && !LIBRARY.test(file) && !RUNTIME.test(file);
+const frame = (file, line, fn) => ({
+    file: String(file ?? '').replace(/\\/g, '/'),
+    line: Number(line) || 0,
+    fn: String(fn ?? ''),
+    ours: ours(String(file ?? '')),
+});
+/** A stack trace as every language prints it, which is the fallback when there is no tool. */
+export function framesFromStack(stack) {
+    const out = [];
+    for (const line of stack.split('\n')) {
+        // JavaScript: "at handler (/app/src/pay.ts:42:9)" or "at /app/src/pay.ts:42:9"
+        const js = /^\s*at\s+(?:(?<fn>[^(]+?)\s+\()?(?<file>[^():]+?):(?<line>\d+):\d+\)?\s*$/.exec(line);
+        if (js?.groups) {
+            out.push(frame(js.groups.file, js.groups.line, (js.groups.fn ?? '').trim()));
+            continue;
+        }
+        // Python: '  File "/app/pay.py", line 42, in charge'
+        const py = /^\s*File\s+"(?<file>[^"]+)",\s+line\s+(?<line>\d+)(?:,\s+in\s+(?<fn>\S+))?/.exec(line);
+        if (py?.groups) {
+            out.push(frame(py.groups.file, py.groups.line, py.groups.fn ?? ''));
+            continue;
+        }
+        // Java and C#: "at com.shop.Pay.charge(Pay.java:42)"
+        const jvm = /^\s*at\s+(?<fn>[\w.$<>]+)\((?<file>[^):]+):(?<line>\d+)\)/.exec(line);
+        if (jvm?.groups)
+            out.push(frame(jvm.groups.file, jvm.groups.line, jvm.groups.fn));
+    }
+    return out;
+}
+/** Sentry's event JSON, as its API and its "download JSON" button produce it. */
+function fromSentry(event) {
+    const thrown = event.exception?.values?.at?.(-1) ?? event.exception?.values?.[0];
+    if (!thrown && !event.title && !event.message)
+        return null;
+    const frames = (thrown?.stacktrace?.frames ?? [])
+        .map((f) => frame(f.abs_path ?? f.filename ?? '', f.lineno, f.function ?? ''))
+        // Sentry lists the oldest frame first; a person reads the newest first, and so does a fix.
+        .reverse();
+    const request = event.request ?? {};
+    return {
+        title: String(event.title ?? thrown?.value ?? event.message ?? 'an incident'),
+        errorType: String(thrown?.type ?? ''),
+        errorMessage: String(thrown?.value ?? event.message ?? ''),
+        frames,
+        operation: [request.method, request.url].filter(Boolean).join(' ') || String(event.culprit ?? ''),
+        when: String(event.datetime ?? event.timestamp ?? ''),
+        source: 'sentry',
+    };
+}
+/** An OpenTelemetry span that failed, carrying the standard `exception` event. */
+function fromOtel(span) {
+    const events = span.events ?? span.Events ?? [];
+    const thrown = events.find?.((e) => (e.name ?? '') === 'exception');
+    const status = span.status?.code ?? span.status?.Code ?? '';
+    if (!thrown && !/ERROR|STATUS_CODE_ERROR|2/.test(String(status)))
+        return null;
+    const attrs = {};
+    // OTLP writes attributes either as a map or as a list of {key,value}; both are seen in exports.
+    const raw = thrown?.attributes ?? {};
+    if (Array.isArray(raw))
+        for (const a of raw)
+            attrs[a.key] = a.value?.stringValue ?? a.value?.string_value ?? a.value;
+    else
+        Object.assign(attrs, raw);
+    const stack = String(attrs['exception.stacktrace'] ?? '');
+    return {
+        title: String(span.name ?? attrs['exception.type'] ?? 'a failed operation'),
+        errorType: String(attrs['exception.type'] ?? ''),
+        errorMessage: String(attrs['exception.message'] ?? span.status?.message ?? ''),
+        frames: framesFromStack(stack),
+        operation: String(span.name ?? ''),
+        when: String(span.startTime ?? span.startTimeUnixNano ?? ''),
+        source: 'opentelemetry',
+    };
+}
+/** Whatever was pasted: the first line is the error, the rest is the stack. */
+function fromText(text) {
+    const lines = text.split('\n');
+    const head = lines.find((l) => l.trim()) ?? '';
+    const typed = /^\s*(?<type>[\w.]*(?:Error|Exception|Fault))\b:?\s*(?<message>.*)$/.exec(head);
+    return {
+        title: head.trim().slice(0, 160) || 'an incident',
+        errorType: typed?.groups?.type ?? '',
+        errorMessage: (typed?.groups?.message ?? head).trim(),
+        frames: framesFromStack(text),
+        operation: '',
+        when: '',
+        source: 'stack trace',
+    };
+}
+/** Reads an incident from a file's contents, whichever of the three shapes it is in. */
+export function readIncident(contents) {
+    const text = contents.trim();
+    if (text.startsWith('{') || text.startsWith('[')) {
+        try {
+            const parsed = JSON.parse(text);
+            const one = Array.isArray(parsed) ? parsed[0] : parsed;
+            // A Sentry event and an OTel span are both objects; each is recognised by what it carries.
+            const sentry = one?.exception || one?.culprit || one?.event_id ? fromSentry(one) : null;
+            if (sentry)
+                return sentry;
+            const otel = fromOtel(one?.resourceSpans?.[0]?.scopeSpans?.[0]?.spans?.[0] ?? one?.span ?? one);
+            if (otel)
+                return otel;
+        }
+        catch {
+            // Not JSON after all: fall through and read it as a pasted stack trace.
+        }
+    }
+    return fromText(text);
+}
+/** The frames in the project's own code, newest first: where a reproduction has to aim. */
+export const ourFrames = (incident) => incident.frames.filter((f) => f.ours);

package/dist/engine/incident/reproduced.js

@@ -0,0 +1,87 @@
+// Did that test actually reproduce the incident?
+//
+// This is the whole of Phase 16 in one question, and getting it wrong is how a tool like this
+// becomes worthless. A test that fails is not a reproduction. A test with a typo fails. A test
+// against a missing fixture fails. A test that asserts the opposite of the truth fails. Each of
+// those would let Tewip announce "reproduced your incident" and hand over something that proves
+// nothing, and then the fix that makes it pass would fix nothing.
+//
+// So a reproduction has to fail **for the incident's reason**, and that is checkable without a
+// model: the error the test produced and the error production reported have to be the same error.
+// Everything else - a pass, a failure of a different kind, a crash before the test ran - is
+// refused and said out loud.
+import { errorShape } from '../signature.js';
+/** Words that mean the test never got as far as exercising anything. */
+const NEVER_RAN = /\b(?:cannot find module|ModuleNotFoundError|No module named|SyntaxError|IndentationError|fixture '[^']+' not found|ERR_MODULE_NOT_FOUND|NoClassDefFoundError|ClassNotFoundException|command not found|no tests? (?:found|ran)|collection failure)\b/i;
+const typeOf = (text) => /\b([\w.]*(?:Error|Exception|Fault))\b/.exec(text)?.[1]?.split('.').pop() ?? '';
+/** The words of an error, without the parts that differ every run. */
+const wordsOf = (text) => new Set(errorShape(text)
+    .toLowerCase()
+    .match(/[a-z][a-z-]{2,}/g)
+    ?.filter((w) => !['error', 'exception', 'the', 'and', 'for', 'with', 'from', 'test', 'failed', 'assert'].includes(w)) ?? []);
+/**
+ * Judges one test run against the incident it was written for.
+ *
+ * `passed` is not a near miss. It means the test does not exercise the broken path at all, and the
+ * honest thing is to say the reproduction failed, not to weaken the test until it goes red.
+ */
+export function judgeReproduction(incident, run) {
+    if (NEVER_RAN.test(run.output)) {
+        return {
+            verdict: 'never-ran',
+            why: 'the test never ran - something was missing or would not compile - so it shows nothing about the incident',
+            match: 'none',
+        };
+    }
+    if (run.passed) {
+        return {
+            verdict: 'passed',
+            why: 'the test passes against the code that is broken in production, so it does not exercise what broke. It is not a reproduction, and weakening it until it fails would prove nothing',
+            match: 'none',
+        };
+    }
+    const wanted = `${incident.errorType} ${incident.errorMessage}`.trim();
+    const sameType = Boolean(incident.errorType) && typeOf(run.output) === typeOf(wanted);
+    const theirs = wordsOf(wanted);
+    const ours = wordsOf(run.output);
+    const shared = [...theirs].filter((w) => ours.has(w));
+    // Most of the incident's own words, not most of the test output's: a long stack trace should not
+    // earn a match by sheer length.
+    const overlap = theirs.size > 0 ? shared.length / theirs.size : 0;
+    if (sameType && overlap >= 0.5) {
+        return { verdict: 'reproduced', why: `the test fails with the same error production reported (${typeOf(wanted)}), and most of the same words`, match: 'same type and message' };
+    }
+    if (sameType) {
+        return { verdict: 'reproduced', why: `the test fails with ${typeOf(wanted)}, the same error type production reported, though the message differs`, match: 'same type' };
+    }
+    if (overlap >= 0.7 && theirs.size >= 3) {
+        return { verdict: 'reproduced', why: 'the test fails with the same message production reported, although neither names an error type', match: 'same message' };
+    }
+    return {
+        verdict: 'failed-differently',
+        why: `the test fails, but not with the incident's error: production reported ${wanted.slice(0, 80) || 'its own error'}, and the test reported ${errorLine(run.output)}`,
+        match: 'none',
+    };
+}
+/**
+ * The line of a runner's output that is actually the error. Quoting the first non-empty line put
+ * "RUN v5.0.2 C:/Users/..." into a real report as though it were what the test said - a banner, not
+ * a finding, and exactly the loose evidence this project refuses everywhere else.
+ */
+function errorLine(output) {
+    // Two passes, because a runner prints its own status lines too: " FAIL tests/a.test.js" says
+    // which file failed, not what went wrong. A named error always wins over a status line.
+    const named = /\b(?:\w*Error|\w*Exception|expected|Expected|assert)\b/;
+    const anyFailure = /\b(?:FAIL|failed|failure)\b/i;
+    const noise = /^\s*(?:RUN|DEV|WATCH)\b/;
+    const lines = output.split('\n').filter((l) => l.trim() && !noise.test(l));
+    const found = lines.find((l) => named.test(l)) ?? lines.find((l) => anyFailure.test(l)) ?? lines[0];
+    return (found ?? '').trim().slice(0, 100);
+}
+/** What to do about each verdict, for the report. */
+export const nextStep = {
+    reproduced: 'keep this test: it is red for the reason production was, so a fix that turns it green has fixed the incident',
+    passed: 'do not keep this test. Either the incident depends on data or state the test does not create, or it is not in this code at all',
+    'failed-differently': 'do not keep this test: it is broken in its own way, which would be mistaken for the incident later',
+    'never-ran': 'fix the setup and try again; nothing has been shown either way',
+};

package/dist/engine/recall/recall-command.js

@@ -0,0 +1,39 @@
+// `tewip recall "<an error, or a question>"`: what this project already concluded.
+import { existsSync, mkdirSync, readdirSync, writeFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { datasetFiles, readTriageRecords } from '../../reporters/store.js';
+import { loadCorrections } from '../corrections.js';
+import { memories, recall, renderRecall } from './recall.js';
+/** Everything kept for this project: its failures, and the times a person overruled Tewip. */
+function kept(root, only) {
+    const dir = join(root, '.tewip', 'history');
+    if (!existsSync(dir))
+        return { records: [], corrections: [] };
+    const records = [];
+    const corrections = [];
+    for (const project of only ? [only] : readdirSync(dir)) {
+        const where = join(dir, project);
+        if (!existsSync(where))
+            continue;
+        records.push(...readTriageRecords(datasetFiles(where).triage));
+        corrections.push(...loadCorrections(where));
+    }
+    return { records, corrections };
+}
+export function runRecall(cmd) {
+    const { records, corrections } = kept(cmd.root, cmd.name);
+    if (records.length === 0) {
+        const empty = 'Nothing has been kept here yet, so there is no history to search. Run `tewip explain <report>` first.';
+        console.log(empty);
+        return empty;
+    }
+    const found = recall(cmd.question, memories(records, corrections), { testId: cmd.testId, limit: cmd.limit ?? 5 });
+    const report = renderRecall(cmd.question, found);
+    console.log(report);
+    console.error(`\nSearched ${records.length} kept failure(s) and ${corrections.length} correction(s). No model was called.`);
+    if (cmd.out) {
+        mkdirSync(dirname(resolve(cmd.out)), { recursive: true });
+        writeFileSync(resolve(cmd.out), `${report}\n`, 'utf8');
+    }
+    return report;
+}

package/dist/engine/recall/recall.js

@@ -0,0 +1,109 @@
+import { errorShape } from '../signature.js';
+/** Words worth matching on: rare, specific, not the furniture of every stack trace. */
+const COMMON = new Set([
+    'error', 'failed', 'failure', 'test', 'expected', 'received', 'actual', 'value', 'object', 'null', 'undefined', 'true', 'false', 'none', 'with', 'from', 'this', 'that', 'have', 'been', 'were', 'when', 'then', 'there', 'which', 'while', 'after', 'before', 'timeout', 'waiting', 'call', 'log', 'line', 'file', 'at', 'in', 'on', 'of', 'to', 'for', 'and', 'the', 'a', 'an', 'is', 'it', 'was', 'not', 'no', 'yes',
+]);
+const words = (text) => (errorShape(text).toLowerCase().match(/[a-z][a-z0-9_-]{2,}/g) ?? []).filter((w) => !COMMON.has(w));
+/** How rare each word is across the history: a word in every failure tells you nothing. */
+function rarity(all) {
+    const seen = new Map();
+    for (const doc of all)
+        for (const w of new Set(doc))
+            seen.set(w, (seen.get(w) ?? 0) + 1);
+    const total = Math.max(all.length, 1);
+    const out = new Map();
+    for (const [w, n] of seen)
+        out.set(w, Math.log(total / n) + 1);
+    return out;
+}
+/** Everything Tewip has kept about this project, as memories that can be cited. */
+export function memories(records, corrections = []) {
+    const byShape = new Map();
+    for (const c of corrections)
+        byShape.set(`${c.testId}::${c.errorShape}`, c);
+    const out = [];
+    for (const record of records) {
+        const diagnosis = record.diagnosis;
+        if (!diagnosis?.category)
+            continue;
+        const correction = byShape.get(`${record.testId}::${errorShape(record.errorMessage)}`);
+        out.push({
+            testId: record.testId,
+            category: correction?.category ?? diagnosis.category,
+            decidedBy: correction ? `${correction.by} (a person)` : String(diagnosis.source ?? 'unknown'),
+            when: record.timestamp,
+            runId: record.runId,
+            error: (record.errorMessage ?? '').replace(/\s+/g, ' ').slice(0, 220),
+            full: (record.errorMessage ?? '').replace(/\s+/g, ' ').slice(0, 4000),
+            ...(correction ? { correctedBy: correction.by, correctionReason: correction.reason } : {}),
+        });
+    }
+    return out;
+}
+/**
+ * The memories that answer a question, most useful first.
+ *
+ * Three things decide the order, and each is stated in `why` so a person can disagree with it: the
+ * same error shape is the strongest signal there is, the same test is next, and shared rare words
+ * carry the rest. A memory a person corrected is lifted above one only Tewip decided, because what
+ * the team concluded outranks what the tool concluded.
+ */
+export function recall(question, all, { testId, limit = 5 } = {}) {
+    if (all.length === 0)
+        return [];
+    const docs = all.map((m) => words(`${m.testId} ${m.full ?? m.error}`));
+    const weight = rarity(docs);
+    const asked = new Set(words(question));
+    const askedShape = errorShape(question);
+    const scored = all.map((memory, i) => {
+        const shared = docs[i].filter((w) => asked.has(w));
+        const mass = [...new Set(shared)].reduce((sum, w) => sum + (weight.get(w) ?? 1), 0);
+        const possible = [...asked].reduce((sum, w) => sum + (weight.get(w) ?? 1), 0) || 1;
+        let score = Math.min(mass / possible, 1);
+        const reasons = [];
+        if (askedShape && errorShape(memory.full ?? memory.error) === askedShape) {
+            score = Math.max(score, 0.95);
+            reasons.push('the same error, word for word once the changing parts are removed');
+        }
+        else if (shared.length > 0) {
+            reasons.push(`shares ${[...new Set(shared)].slice(0, 4).join(', ')}`);
+        }
+        if (testId && memory.testId === testId) {
+            score = Math.min(score + 0.25, 1);
+            reasons.push('the same test');
+        }
+        if (memory.correctedBy) {
+            score = Math.min(score + 0.1, 1);
+            reasons.push(`${memory.correctedBy} corrected this one`);
+        }
+        return { ...memory, score, sameTest: Boolean(testId && memory.testId === testId), why: reasons.join('; ') || 'nothing in common but the project' };
+    });
+    // Two memories can both reach the ceiling - an identical error recorded twice does - so the
+    // ordering needs a tie-break of its own. When the question is about one test, that test's own
+    // history comes first; otherwise the most recent, because the project changes underneath you.
+    return scored
+        .filter((m) => m.score > 0.15)
+        .sort((a, b) => b.score - a.score || Number(b.sameTest) - Number(a.sameTest) || (b.when > a.when ? 1 : -1))
+        .map(({ sameTest, ...rest }) => rest)
+        .slice(0, limit);
+}
+/** What a person reads. Every line names the run it came from, so nothing has to be believed. */
+export function renderRecall(question, found) {
+    const lines = [`# What this project already knows`, '', `Asked: ${question.replace(/\s+/g, ' ').slice(0, 160)}`, ''];
+    if (found.length === 0) {
+        lines.push('Nothing in this project\'s history resembles it. That is an answer, not a failure: it means', 'this is new here, and there is no earlier decision to follow.');
+        return lines.join('\n');
+    }
+    const corrected = found.filter((f) => f.correctedBy);
+    lines.push(`${found.length} earlier failure(s) look like this one.${corrected.length > 0 ? ` ${corrected.length} of them a person judged themselves.` : ''}`, '');
+    for (const memory of found) {
+        lines.push(`- **${memory.category}** — ${memory.testId}`);
+        lines.push(`  - Decided by ${memory.decidedBy}${memory.when ? ` on ${memory.when.slice(0, 10)}` : ''}, run \`${memory.runId}\``);
+        if (memory.correctionReason)
+            lines.push(`  - They said: ${memory.correctionReason}`);
+        lines.push(`  - Why it matched: ${memory.why}`);
+        lines.push(`  - The error then: ${memory.error.slice(0, 140)}`);
+    }
+    lines.push('', 'No model was called to answer this, and nothing above is a guess: each line is a record kept from a real run of this project.');
+    return lines.join('\n');
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tewip-ai",
-  "version": "0.19.0",
+  "version": "0.21.0",
   "description": "Tewip finds why each failing test failed - real bug, flaky test, environment, test data or changed selector - for any stack, from the command line, CI, or your editor.",
   "keywords": [
     "test-failures",