@gamaze/hicortex 0.20.7 → 0.20.10

package/dist/eval/decay-eval.js

@@ -89,12 +89,12 @@ function runDomainBacklogAudit(db, stateDir) {
 /**
  * Run the actual `stageDecayPrune` (imported from consolidate.ts, `dryRun:
  * true`) against the snapshot. Configures the decay clock to the given
- * half-life first (bedrock has no `decayHalfLifeDays` override, so the
- * caller should pass the shipped default — see run-eval.ts) so the eval and
- * production score with the same clock.
+ * half-life first via the eval seam (#408: the half-life is a calibration
+ * constant — the caller should pass the shipped default, see run-eval.ts) so
+ * the eval and production score with the same clock.
  */
 function runPruneDryRun(db, decayHalfLifeDays = retrieval_js_1.DEFAULT_DECAY_HALF_LIFE_DAYS) {
-    (0, retrieval_js_1.configureDecay)({ halfLifeDays: decayHalfLifeDays });
+    (0, retrieval_js_1.configureDecay)(decayHalfLifeDays);
     const result = (0, consolidate_js_1.stageDecayPrune)(db, true);
     return { ...result, decayHalfLifeDaysUsed: decayHalfLifeDays };
 }

package/dist/eval/importance-eval.d.ts

@@ -0,0 +1,85 @@
+#!/usr/bin/env node
+/**
+ * Importance-scorer distribution eval (#425) — the AC4 measurement.
+ *
+ *   npm run eval:importance -- <snapshot.db> [--sample N] [--seed S]
+ *        [--llm-base-url U --llm-model M --llm-api-key K]
+ *
+ * Samples real memories from a READONLY snapshot (openSnapshot — never
+ * initDb), sends them through the PRODUCTION scoring path — the real
+ * `LlmClient` and the CURRENT `importanceScoring` prompt, batched 10 per
+ * call exactly like the nightly's stageImportance — and reports the score
+ * distribution: histogram (0.1 buckets), min/p25/median/p75/p90/max, count
+ * at exactly 1.0, and the owner-approved target band (D2, 2026-09-13:
+ * median 0.30-0.40, p90 <= 0.75, zero at 1.0).
+ *
+ * This is the before/after photo for the scorer recalibration: run it on
+ * the OLD prompt (the inflated-distribution red photo), then on the
+ * re-anchored prompt (AC4 gate).
+ *
+ * Determinism: the sample is stratified across created_at deciles and
+ * drawn with a SEEDED PRNG (mulberry32) — same snapshot + same seed =
+ * same sample + same batches + same prompts. Calls are SERIAL (one
+ * in-flight request, like the nightly).
+ *
+ * Honesty rules: no stub LLM, no fallback distribution, measured scores
+ * only; a mid-run endpoint error aborts with the partial histogram
+ * printed (never silently padded). The gateway endpoint is passed at RUN
+ * TIME via flags — nothing about any specific endpoint lives in this file.
+ */
+import { LlmClient } from "../llm.js";
+export interface SampleRow {
+    id: string;
+    content: string;
+    created_at: string;
+}
+/**
+ * Deterministic decile-stratified sample: rows sorted by created_at, split
+ * into 10 equal deciles, `ceil(n/10)` drawn from each via the seeded PRNG
+ * (each decile shuffled by its own PRNG stream — index-independent). Same
+ * (rows, n, seed) always yields the same ordered selection.
+ */
+export declare function stratifiedSample(rows: SampleRow[], n: number, seed: number): SampleRow[];
+export interface ScoreSummary {
+    n: number;
+    min: number;
+    p25: number;
+    median: number;
+    p75: number;
+    p90: number;
+    max: number;
+    atExactly1: number;
+    histogram: Record<string, number>;
+}
+export declare function summarizeScores(scores: number[]): ScoreSummary;
+export interface ImportanceEvalOptions {
+    snapshotPath: string;
+    sample?: number;
+    seed?: number;
+    llm: LlmClient;
+    /** Where to write the report (default data/importance-eval-report.md). */
+    reportPath?: string;
+}
+export interface ImportanceEvalResult {
+    summary: ScoreSummary;
+    /** Per-batch measured scores, in call order (audit trail). */
+    batches: Array<{
+        sent: number;
+        scores: number[];
+    }>;
+    aborted: boolean;
+    error?: string;
+}
+/**
+ * Run the importance distribution measurement. Throws only on setup errors;
+ * an LLM/endpoint failure mid-run sets `aborted` (partial results returned —
+ * the caller decides exit code, always loudly).
+ */
+export declare function runImportanceEval(opts: ImportanceEvalOptions): Promise<ImportanceEvalResult>;
+export declare function renderImportanceReport(args: {
+    snapshotPath: string;
+    summary: ScoreSummary;
+    aborted: boolean;
+    error?: string;
+    model: string;
+}): string;

package/dist/eval/importance-eval.js

@@ -0,0 +1,286 @@
+#!/usr/bin/env node
+"use strict";
+/**
+ * Importance-scorer distribution eval (#425) — the AC4 measurement.
+ *
+ *   npm run eval:importance -- <snapshot.db> [--sample N] [--seed S]
+ *        [--llm-base-url U --llm-model M --llm-api-key K]
+ *
+ * Samples real memories from a READONLY snapshot (openSnapshot — never
+ * initDb), sends them through the PRODUCTION scoring path — the real
+ * `LlmClient` and the CURRENT `importanceScoring` prompt, batched 10 per
+ * call exactly like the nightly's stageImportance — and reports the score
+ * distribution: histogram (0.1 buckets), min/p25/median/p75/p90/max, count
+ * at exactly 1.0, and the owner-approved target band (D2, 2026-09-13:
+ * median 0.30-0.40, p90 <= 0.75, zero at 1.0).
+ *
+ * This is the before/after photo for the scorer recalibration: run it on
+ * the OLD prompt (the inflated-distribution red photo), then on the
+ * re-anchored prompt (AC4 gate).
+ *
+ * Determinism: the sample is stratified across created_at deciles and
+ * drawn with a SEEDED PRNG (mulberry32) — same snapshot + same seed =
+ * same sample + same batches + same prompts. Calls are SERIAL (one
+ * in-flight request, like the nightly).
+ *
+ * Honesty rules: no stub LLM, no fallback distribution, measured scores
+ * only; a mid-run endpoint error aborts with the partial histogram
+ * printed (never silently padded). The gateway endpoint is passed at RUN
+ * TIME via flags — nothing about any specific endpoint lives in this file.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.stratifiedSample = stratifiedSample;
+exports.summarizeScores = summarizeScores;
+exports.runImportanceEval = runImportanceEval;
+exports.renderImportanceReport = renderImportanceReport;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const eval_db_js_1 = require("./eval-db.js");
+const llm_js_1 = require("../llm.js");
+const consolidate_js_1 = require("../consolidate.js");
+const prompts_js_1 = require("../prompts.js");
+const DEFAULT_SAMPLE = 200;
+const DEFAULT_SEED = 1;
+/** The nightly's stageImportance batch size — matched exactly. */
+const BATCH_SIZE = 10;
+// ---------------------------------------------------------------------------
+// Deterministic stratified sampler
+// ---------------------------------------------------------------------------
+/** mulberry32 — small, seedable, deterministic across Node versions. */
+function mulberry32(seed) {
+    let a = seed >>> 0;
+    return () => {
+        a |= 0;
+        a = (a + 0x6d2b79f5) | 0;
+        let t = Math.imul(a ^ (a >>> 15), 1 | a);
+        t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
+        return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+    };
+}
+/**
+ * Deterministic decile-stratified sample: rows sorted by created_at, split
+ * into 10 equal deciles, `ceil(n/10)` drawn from each via the seeded PRNG
+ * (each decile shuffled by its own PRNG stream — index-independent). Same
+ * (rows, n, seed) always yields the same ordered selection.
+ */
+function stratifiedSample(rows, n, seed) {
+    if (rows.length === 0 || n <= 0)
+        return [];
+    const sorted = [...rows].sort((a, b) => a.created_at === b.created_at
+        ? a.id.localeCompare(b.id)
+        : a.created_at.localeCompare(b.created_at));
+    const decileSize = sorted.length / 10;
+    const perDecile = Math.max(1, Math.ceil(n / 10));
+    const out = [];
+    for (let d = 0; d < 10 && out.length < n; d++) {
+        const start = Math.floor(d * decileSize);
+        const end = d === 9 ? sorted.length : Math.floor((d + 1) * decileSize);
+        const decile = sorted.slice(start, end);
+        const rnd = mulberry32(seed * 31 + d);
+        // Fisher-Yates with the decile-local stream.
+        for (let i = decile.length - 1; i > 0; i--) {
+            const j = Math.floor(rnd() * (i + 1));
+            [decile[i], decile[j]] = [decile[j], decile[i]];
+        }
+        out.push(...decile.slice(0, Math.min(perDecile, n - out.length)));
+    }
+    return out;
+}
+/** Nearest-rank percentile on the ASCENDING-sorted values. */
+function percentile(sorted, p) {
+    if (sorted.length === 0)
+        return Number.NaN;
+    const idx = Math.min(sorted.length - 1, Math.max(0, Math.ceil((p / 100) * sorted.length) - 1));
+    return sorted[idx];
+}
+function summarizeScores(scores) {
+    const sorted = [...scores].sort((a, b) => a - b);
+    const histogram = {};
+    for (let b = 0; b < 10; b++)
+        histogram[`${b}-${b + 1}`] = 0;
+    for (const s of scores) {
+        const b = Math.min(9, Math.max(0, Math.floor(s * 10)));
+        histogram[`${b}-${b + 1}`]++;
+    }
+    return {
+        n: scores.length,
+        min: percentile(sorted, 0),
+        p25: percentile(sorted, 25),
+        median: percentile(sorted, 50),
+        p75: percentile(sorted, 75),
+        p90: percentile(sorted, 90),
+        max: percentile(sorted, 100),
+        atExactly1: scores.filter((s) => s === 1).length,
+        histogram,
+    };
+}
+/**
+ * Run the importance distribution measurement. Throws only on setup errors;
+ * an LLM/endpoint failure mid-run sets `aborted` (partial results returned —
+ * the caller decides exit code, always loudly).
+ */
+async function runImportanceEval(opts) {
+    const sampleSize = opts.sample ?? DEFAULT_SAMPLE;
+    const seed = opts.seed ?? DEFAULT_SEED;
+    const db = (0, eval_db_js_1.openSnapshot)(opts.snapshotPath);
+    let rows;
+    try {
+        rows = db
+            .prepare("SELECT id, content, created_at FROM memories WHERE COALESCE(status, '') != 'absorbed' ORDER BY id")
+            .all();
+    }
+    finally {
+        db.close();
+    }
+    if (rows.length === 0)
+        throw new Error("snapshot has no live memories");
+    const sample = stratifiedSample(rows, sampleSize, seed);
+    console.log(`[importance-eval] snapshot rows ${rows.length}, sampled ${sample.length} ` +
+        `(seed ${seed}, stratified over created_at deciles)`);
+    const batches = [];
+    const allScores = [];
+    for (let i = 0; i < sample.length; i += BATCH_SIZE) {
+        const batch = sample.slice(i, i + BATCH_SIZE);
+        const lines = batch.map((mem, idx) => `[${idx}] ${mem.content.slice(0, 500)}`);
+        const prompt = (0, prompts_js_1.importanceScoring)(lines.join("\n\n"));
+        try {
+            const r = await opts.llm.complete(prompt);
+            let scores = (0, consolidate_js_1.parseJsonLenient)(r.text, null);
+            if (!Array.isArray(scores))
+                scores = new Array(batch.length).fill(0.5);
+            while (scores.length < batch.length)
+                scores.push(0.5);
+            scores = scores.slice(0, batch.length);
+            const clamped = scores.map((s) => {
+                const v = Number(s);
+                return Number.isFinite(v) ? Math.max(0, Math.min(1, v)) : 0.5;
+            });
+            batches.push({ sent: batch.length, scores: clamped });
+            allScores.push(...clamped);
+            console.log(`[importance-eval] batch ${batches.length}: ${clamped.map((s) => s.toFixed(1)).join(", ")}`);
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            console.error(`[importance-eval] endpoint error at batch ${Math.floor(i / BATCH_SIZE) + 1}: ${msg}`);
+            const summary = summarizeScores(allScores);
+            return { summary, batches, aborted: true, error: msg };
+        }
+    }
+    return { summary: summarizeScores(allScores), batches, aborted: false };
+}
+function renderImportanceReport(args) {
+    const s = args.summary;
+    const L = [];
+    L.push("# Importance-scorer distribution (#425 — AC4)\n");
+    L.push(`Snapshot: \`${args.snapshotPath}\`  \nGenerated: ${new Date().toISOString()}  \n` +
+        `Model: ${args.model} (the configured production endpoint)  \n` +
+        `Prompt: the CURRENT production importanceScoring (whatever ships in this tree)\n`);
+    if (args.aborted) {
+        L.push(`**ABORTED MID-RUN** — ${args.error ?? "endpoint error"}; partial distribution over ${s.n} scores below.\n`);
+    }
+    L.push("## Distribution\n");
+    L.push("| stat | value |");
+    L.push("|---|---|");
+    L.push(`| n | ${s.n} |`);
+    L.push(`| min | ${s.min.toFixed(3)} |`);
+    L.push(`| p25 | ${s.p25.toFixed(3)} |`);
+    L.push(`| **median** | **${s.median.toFixed(3)}** |`);
+    L.push(`| p75 | ${s.p75.toFixed(3)} |`);
+    L.push(`| **p90** | **${s.p90.toFixed(3)}** |`);
+    L.push(`| max | ${s.max.toFixed(3)} |`);
+    L.push(`| at exactly 1.0 | ${s.atExactly1} |`);
+    L.push("");
+    L.push("| bucket | count |");
+    L.push("|---|---|");
+    for (const [bucket, count] of Object.entries(s.histogram)) {
+        L.push(`| ${bucket} | ${count} |`);
+    }
+    L.push("");
+    L.push(`Target band (owner D2, 2026-09-13): median 0.30-0.40 → ` +
+        `${s.median >= 0.3 && s.median <= 0.4 ? "**PASS**" : "**MISS**"} (${s.median.toFixed(3)}); ` +
+        `p90 <= 0.75 → ${s.p90 <= 0.75 ? "**PASS**" : "**MISS**"} (${s.p90.toFixed(3)}); ` +
+        `zero at 1.0 → ${s.atExactly1 === 0 ? "**PASS**" : "**MISS**"} (${s.atExactly1})\n`);
+    return L.join("\n");
+}
+// ---------------------------------------------------------------------------
+// CLI
+// ---------------------------------------------------------------------------
+function usage() {
+    console.error("Usage: npm run eval:importance -- <snapshot.db> [--sample N=200] [--seed S=1]\n" +
+        "       --llm-base-url U --llm-model M --llm-api-key K   (required: the scoring endpoint)\n" +
+        "       [--llm-thinking]   (thinking ON; default OFF — production parity)\n" +
+        "       [--report <out.md>]");
+    process.exit(1);
+}
+async function main() {
+    const argv = process.argv.slice(2);
+    const positional = [];
+    const flag = (name) => {
+        const i = argv.indexOf(name);
+        return i !== -1 && argv[i + 1] && !argv[i + 1].startsWith("--") ? argv[i + 1] : undefined;
+    };
+    for (let i = 0; i < argv.length; i++) {
+        if (!argv[i].startsWith("--"))
+            positional.push(argv[i]);
+    }
+    const snapshotPath = positional[0];
+    if (!snapshotPath || argv.includes("--help") || argv.includes("-h"))
+        usage();
+    const baseUrl = flag("--llm-base-url");
+    const model = flag("--llm-model");
+    const apiKey = flag("--llm-api-key");
+    if (!baseUrl || !model || !apiKey) {
+        console.error("[importance-eval] --llm-base-url, --llm-model and --llm-api-key are required (the production scoring endpoint)");
+        usage();
+    }
+    const sample = flag("--sample") ? parseInt(flag("--sample"), 10) : DEFAULT_SAMPLE;
+    const seed = flag("--seed") ? parseInt(flag("--seed"), 10) : DEFAULT_SEED;
+    if (!Number.isInteger(sample) || sample < 10 || sample > 5000) {
+        console.error("[importance-eval] --sample must be an integer in [10, 5000]");
+        process.exit(1);
+    }
+    if (!Number.isInteger(seed) || seed <= 0) {
+        console.error("[importance-eval] --seed must be a positive integer");
+        process.exit(1);
+    }
+    // OpenAI-compatible config built from flags ONLY (never hardcoded; the
+    // production endpoint is a runtime input, not a shipped value). Thinking
+    // defaults OFF (production parity: the scorer runs with thinking disabled —
+    // an unclosed think block can eat the whole output budget); opt in with
+    // --llm-thinking for a thinking-on endpoint.
+    const config = {
+        baseUrl,
+        model,
+        apiKey,
+        provider: "openai",
+        enableThinking: argv.includes("--llm-thinking") ? true : false,
+    };
+    const llm = new llm_js_1.LlmClient(config);
+    const t0 = Date.now();
+    const result = await runImportanceEval({
+        snapshotPath,
+        sample,
+        seed,
+        llm,
+    });
+    const report = renderImportanceReport({
+        snapshotPath,
+        summary: result.summary,
+        aborted: result.aborted,
+        error: result.error,
+        model,
+    });
+    const reportPath = flag("--report") ?? (0, node_path_1.join)(process.cwd(), "data", "importance-eval-report.md");
+    (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(reportPath), { recursive: true });
+    (0, node_fs_1.writeFileSync)(reportPath, report, "utf-8");
+    console.log(`[importance-eval] report written: ${reportPath}`);
+    console.log(report);
+    console.log(`[importance-eval] ${result.aborted ? "ABORTED" : "complete"} in ${Math.round((Date.now() - t0) / 1000)}s`);
+    process.exitCode = result.aborted ? 1 : 0;
+}
+if (process.argv[1] && process.argv[1].endsWith("importance-eval.js")) {
+    main().catch((err) => {
+        console.error("[importance-eval] FAILED:", err instanceof Error ? err.stack : String(err));
+        process.exitCode = 1;
+    });
+}

package/dist/eval/planted-eval.d.ts

@@ -0,0 +1,26 @@
+#!/usr/bin/env node
+/**
+ * Planted-pairs resolution gate — the #393 increment A acceptance harness.
+ *
+ *   npm run eval:planted -- [report.md] [--snapshot <db>]
+ *
+ * Builds the real-text planted corpus (planted-fixtures.ts) in a THROWAWAY
+ * writable DB, embeds it with the REAL bge-small-en-v1.5 embedder, runs the
+ * production resolution stage (`stageReconsolidation`, ground-truth stub
+ * judge — see planted-harness.ts), and writes the DETECTED / BOUND / RESOLVED
+ * gate table. This is the before/after photo every later #393 increment
+ * (scout, guard, walk) must re-run and beat.
+ *
+ * `--snapshot <db>` plants the same corpus into a COPY of a real snapshot
+ * instead of an empty DB (the real-corpus background). The copy is opened
+ * writable via initDb (migrations are idempotent) — the snapshot itself is
+ * never touched. With a fresh temp stateDir the stage re-scans the ENTIRE
+ * corpus (cursor 0) — on a 17k-memory snapshot that is a full pass with
+ * stub-verdict calls for every unlinked in-band pair (fast, no network); the
+ * live-LLM real-corpus acceptance run is the release-soak step (refine Q3),
+ * not this one.
+ *
+ * Never touches ~/.hicortex: DB, state dir, and backups all live under a
+ * mkdtemp directory that is removed on exit.
+ */
+export {};

package/dist/eval/planted-eval.js

@@ -0,0 +1,97 @@
+#!/usr/bin/env node
+"use strict";
+/**
+ * Planted-pairs resolution gate — the #393 increment A acceptance harness.
+ *
+ *   npm run eval:planted -- [report.md] [--snapshot <db>]
+ *
+ * Builds the real-text planted corpus (planted-fixtures.ts) in a THROWAWAY
+ * writable DB, embeds it with the REAL bge-small-en-v1.5 embedder, runs the
+ * production resolution stage (`stageReconsolidation`, ground-truth stub
+ * judge — see planted-harness.ts), and writes the DETECTED / BOUND / RESOLVED
+ * gate table. This is the before/after photo every later #393 increment
+ * (scout, guard, walk) must re-run and beat.
+ *
+ * `--snapshot <db>` plants the same corpus into a COPY of a real snapshot
+ * instead of an empty DB (the real-corpus background). The copy is opened
+ * writable via initDb (migrations are idempotent) — the snapshot itself is
+ * never touched. With a fresh temp stateDir the stage re-scans the ENTIRE
+ * corpus (cursor 0) — on a 17k-memory snapshot that is a full pass with
+ * stub-verdict calls for every unlinked in-band pair (fast, no network); the
+ * live-LLM real-corpus acceptance run is the release-soak step (refine Q3),
+ * not this one.
+ *
+ * Never touches ~/.hicortex: DB, state dir, and backups all live under a
+ * mkdtemp directory that is removed on exit.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+const node_fs_1 = require("node:fs");
+const node_os_1 = require("node:os");
+const node_path_1 = require("node:path");
+const embedder_js_1 = require("../embedder.js");
+const capture_js_1 = require("../capture.js");
+const planted_fixtures_js_1 = require("./planted-fixtures.js");
+const planted_harness_js_1 = require("./planted-harness.js");
+const DEFAULT_REPORT_PATH = (0, node_path_1.join)(process.cwd(), "data", "planted-eval-report.md");
+function usage() {
+    console.error("Usage: npm run eval:planted -- [report.md] [--snapshot <snapshot.db>]\n" +
+        "  [report.md]          output path (default data/planted-eval-report.md)\n" +
+        "  --snapshot <db>      plant into a COPY of a real snapshot (readonly source;\n" +
+        "                       the copy is writable, the snapshot is never touched)");
+    process.exitCode = 1;
+    process.exit(1);
+}
+async function main() {
+    const argv = process.argv.slice(2);
+    let reportPath;
+    let snapshotPath;
+    for (let i = 0; i < argv.length; i++) {
+        if (argv[i] === "--snapshot" && argv[i + 1]) {
+            snapshotPath = argv[++i];
+            continue;
+        }
+        if (!argv[i].startsWith("--"))
+            reportPath = argv[i];
+    }
+    if (argv.includes("--help") || argv.includes("-h"))
+        usage();
+    const workDir = (0, node_fs_1.mkdtempSync)((0, node_path_1.join)((0, node_os_1.tmpdir)(), "hicortex-planted-eval-"));
+    try {
+        const dbPath = (0, node_path_1.join)(workDir, "planted.db");
+        if (snapshotPath) {
+            (0, node_fs_1.copyFileSync)(snapshotPath, dbPath);
+            console.log(`[planted-eval] snapshot copied (readonly source): ${snapshotPath}`);
+        }
+        const stateDir = (0, node_path_1.join)(workDir, "state");
+        console.log("[planted-eval] loading real bge-small-en-v1.5 embedder...");
+        const t0 = Date.now();
+        const result = await (0, planted_harness_js_1.runPlantedGate)(planted_fixtures_js_1.REAL_TEXT_CORPUS, {
+            dbPath,
+            stateDir,
+            embedFn: embedder_js_1.embed,
+            acquireLock: capture_js_1.acquireCaptureLock, // real lock, but on the temp stateDir only
+        });
+        console.log(`[planted-eval] gate completed in ${Date.now() - t0}ms`);
+        const report = (0, planted_harness_js_1.renderPlantedReport)({
+            corpusLabel: snapshotPath
+                ? `real-text planted corpus ON snapshot copy \`${snapshotPath}\``
+                : "real-text planted corpus (synthetic texts, real embeddings)",
+            generatedAt: new Date().toISOString(),
+            embedderLabel: "real bge-small-en-v1.5 (Xenova, fp32) — cosines measured, never asserted",
+            result,
+        });
+        const outPath = reportPath ?? DEFAULT_REPORT_PATH;
+        (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(outPath), { recursive: true });
+        (0, node_fs_1.writeFileSync)(outPath, report, "utf-8");
+        console.log(`[planted-eval] report written: ${outPath}\n`);
+        // Stdout mirror of the gate tables (the issue-comment shaped summary).
+        console.log(report);
+    }
+    finally {
+        (0, node_fs_1.rmSync)(workDir, { recursive: true, force: true });
+    }
+}
+main().catch((err) => {
+    console.error("[planted-eval] FAILED:", err instanceof Error ? err.stack : String(err));
+    process.exitCode = 1;
+});

package/dist/eval/planted-fixtures.d.ts

@@ -0,0 +1,107 @@
+/**
+ * Planted-pair fixture corpus for the resolution acceptance gate (#393
+ * increment A — the eval-first harness).
+ *
+ * Five failure classes, each encoded as planted memory pairs with a DECLARED
+ * ground-truth relation and a DECLARED expected cosine band:
+ *
+ *   (a) cross_topic_correction — the correction rides inside a topically
+ *       unrelated experience memory; measured cosine ~0.5-0.6, BELOW the
+ *       `correctionMinSimilarity` floor (0.75) — the documented field hole
+ *       (0 `corrects` verdicts in 246 on the 17k snapshot).
+ *   (b) source_conflict — two live records that are both true AS RECORDS (each
+ *       faithfully reports a different source) at >= the deterministic-zone
+ *       ceiling (0.92). Guard-C closes the hole: the scout flags the newer
+ *       record contradiction-shaped, the judge answers `conflicts`, the link
+ *       guards the zone, and both stay live.
+ *   (c) version_chain — v1 -> v2 -> v3 of a revised decision record: the
+ *       0.78-0.96 stale-churn class (#392 owner calibration). v1-v2 sits in
+ *       the judged band; v2-v3 (numeric status churn inside a long shared
+ *       record) sits above the ceiling, where the zone blends the NEWEST
+ *       version into the STALE one (canonical = oldest created_at).
+ *   (d) same_fact_paraphrase — one fact, two wordings: should merge.
+ *   (e) complementary_facets — same subject, different facets: should keep
+ *       both (judge verdict `none`).
+ *
+ * Honesty rules:
+ *  - The texts are synthetic and generic (this package publishes to npm — no
+ *    real infrastructure, people, or fleet detail), but SHAPED like the field
+ *    failures: corrections ride in experience memories, conflicts share long
+ *    context tails, churn edits one field of a long record.
+ *  - Cosines are MEASURED at run time with the real bge-small-en-v1.5 embedder
+ *    (planted-eval.ts) — never asserted into existence. The declared bands
+ *    below were calibrated against that embedder (see the band table in the
+ *    report); a pair landing outside its band renders as a loud OUT-OF-BAND
+ *    flag rather than a hard failure, so an embedder change is visible, not
+ *    silent (same posture as run-eval).
+ *  - Neutral filler rows keep the KNN neighborhoods non-trivial and give the
+ *    collider analysis something to check (any non-ground-truth pair >= 0.70
+ *    is reported).
+ */
+/** The five failure classes the gate measures (one row per planted pair). */
+export type FixtureClass = "cross_topic_correction" | "source_conflict" | "version_chain" | "same_fact_paraphrase" | "complementary_facets";
+/**
+ * Ground truth for a planted pair — what a PERFECT judge would verdict
+ * (`none` here means "related but distinct — keep both"; every other
+ * relation is a verdict action since guard-C added `conflicts`).
+ */
+export type GroundTruthRelation = "corrects" | "supersedes" | "merge" | "conflict" | "none";
+export interface PlantedRow {
+    /** Stable identifier used by pairs, reports, and the ground-truth judge. */
+    key: string;
+    content: string;
+    /** ISO timestamp. Ordering is LOAD-BEARING: detection only pairs older -> newer. */
+    createdAt: string;
+    /** knowledge | experience | decision — drives the rewrite/mark-only fork. */
+    memoryType: string;
+}
+export interface PlantedPair {
+    class: FixtureClass;
+    olderKey: string;
+    newerKey: string;
+    relation: GroundTruthRelation;
+    /** Expected measured-cosine band [lo, hi] (inclusive). */
+    band: [number, number];
+    /**
+     * For `corrects` pairs: the scripted corrected text the ground-truth judge
+     * returns from the rewrite contract (REQUIRED for corrects — the harness
+     * throws if a corrects verdict ever reaches its rewrite call without one).
+     */
+    rewritten?: string;
+    /**
+     * For resolution-shaped pairs (`corrects`, `supersedes`, AND `conflict`):
+     * the distinctive terms of the referenced OLD claim, as a well-behaved
+     * scout LLM would extract them from the NEWER memory (REQUIRED for those
+     * relations — the ground-truth judge throws if the shape call reaches a
+     * resolution-shaped pair without one; guard-C added `conflict` because two
+     * records disagreeing on one quantity share MORE wording than a
+     * cross-topic correction does). Honesty rule: every term must appear
+     * VERBATIM in the older row (that is the field-failure mechanism — the
+     * correction contains the words of what it corrects; the harness verifies
+     * it in tests/planted-pairs.test.ts).
+     */
+    references?: string;
+}
+export interface PlantedCorpus {
+    /** Insertion order — keep it createdAt-ascending so rowid order matches age. */
+    rows: PlantedRow[];
+    pairs: PlantedPair[];
+}
+/** All planted rows share project + source_agent so the metadata rails never refuse a fixture merge. */
+export declare const PLANTED_PROJECT = "planted-eval";
+export declare const PLANTED_SOURCE_AGENT = "planted-eval";
+/**
+ * Measured with the real bge-small-en-v1.5 embedder at fixture-authoring time
+ * (2026-09-12): cross-topic 0.625, conflict 0.993, chain v1-v2 0.788 (judged
+ * band), v2-v3 0.998 (zone band), paraphrase 0.985, facets 0.774; no
+ * non-ground-truth pair >= 0.70. Bands are set with margin around those
+ * values — the report re-measures and flags drift.
+ */
+export declare const REAL_TEXT_CORPUS: PlantedCorpus;
+/**
+ * The version_chain class is measured BOTH per-pair and as a class: the
+ * desired end state is the chain's TERMINAL (newest member) live with every
+ * non-terminal demoted or absorbed. Members are derived from the declared
+ * pairs, ordered by createdAt.
+ */
+export declare function chainMembers(corpus: PlantedCorpus): string[];