@gamaze/hicortex 0.23.1 → 0.24.0

package/dist/eval/graph-eval.js

@@ -1,246 +0,0 @@
-"use strict";
-/**
- * D6 — link-graph health audit (#191 mechanical baseline).
- *
- * Of the ~6.5k links: how many are meaningful vs near-duplicate noise, does
- * the stored `memory_links.strength` still match a fresh cosine recompute
- * (drift), and how do all these stats look before vs after the
- * `relinkCursor` watermark (the resumable `hicortex relink` migration to the
- * corrected cosine formula, #145).
- */
-var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    var desc = Object.getOwnPropertyDescriptor(m, k);
-    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
-      desc = { enumerable: true, get: function() { return m[k]; } };
-    }
-    Object.defineProperty(o, k2, desc);
-}) : (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    o[k2] = m[k];
-}));
-var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
-    Object.defineProperty(o, "default", { enumerable: true, value: v });
-}) : function(o, v) {
-    o["default"] = v;
-});
-var __importStar = (this && this.__importStar) || (function () {
-    var ownKeys = function(o) {
-        ownKeys = Object.getOwnPropertyNames || function (o) {
-            var ar = [];
-            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
-            return ar;
-        };
-        return ownKeys(o);
-    };
-    return function (mod) {
-        if (mod && mod.__esModule) return mod;
-        var result = {};
-        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
-        __setModuleDefault(result, mod);
-        return result;
-    };
-})();
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.seededSample = seededSample;
-exports.cosineBetween = cosineBetween;
-exports.byRelationshipCounts = byRelationshipCounts;
-exports.partitionByRelinkCursor = partitionByRelinkCursor;
-exports.runDegreeAudit = runDegreeAudit;
-exports.runDriftSample = runDriftSample;
-exports.runGraphAudit = runGraphAudit;
-const eval_db_js_1 = require("./eval-db.js");
-const storage = __importStar(require("../storage.js"));
-const state_js_1 = require("../state.js");
-const decay_eval_js_1 = require("./decay-eval.js");
-/** Matches the middle D1 duplicate threshold — a link between near-dups is noise, not signal. */
-const DUP_NOISE_THRESHOLD = 0.92;
-const DRIFT_SAMPLE_SIZE = 500;
-/**
- * Seed for the drift sample's PRNG (#460). SQLite's `random()` cannot be
- * seeded, so the draw happens client-side with a deterministic Fisher–Yates;
- * this fixed seed makes the sample — and therefore the whole DriftReport —
- * byte-identical across runs on the same build + snapshot, which lets
- * before/after eval comparisons require full-output identity.
- */
-const DRIFT_SAMPLE_SEED = 460;
-const DEGREE_BUCKET_EDGES = [0, 1, 2, 3, 5, 10, 20, 50, 100];
-const DRIFT_BUCKET_EDGES = [0, 0.01, 0.02, 0.05, 0.1, 0.2, 0.3, 0.5, 1.0];
-/**
- * mulberry32 — a 32-bit seeded PRNG (public-domain reference implementation).
- * JS number ops are deterministic across platforms, so a fixed seed yields
- * the same sequence everywhere.
- */
-function mulberry32(seed) {
-    let a = seed >>> 0;
-    return () => {
-        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 sample of `rows` (#460): a seeded partial Fisher–Yates
- * shuffles the LAST `size` slots from the back, and that shuffled tail is
- * the sample. Rows must already be in a stable order (the caller sorts by
- * PK) so the draw does not depend on SQLite's scan order.
- */
-function seededSample(rows, size, seed) {
-    const rand = mulberry32(seed);
-    const arr = [...rows];
-    const n = Math.min(size, arr.length);
-    for (let i = arr.length - 1; i > arr.length - 1 - n; i--) {
-        const j = Math.floor(rand() * (i + 1));
-        [arr[i], arr[j]] = [arr[j], arr[i]];
-    }
-    return arr.slice(arr.length - n);
-}
-// ---------------------------------------------------------------------------
-// Pure helpers (unit tested)
-// ---------------------------------------------------------------------------
-/** Cosine similarity between two L2-normalized embeddings (dot product). */
-function cosineBetween(a, b) {
-    let dot = 0;
-    for (let i = 0; i < a.length; i++)
-        dot += a[i] * b[i];
-    return dot;
-}
-function byRelationshipCounts(links) {
-    const counts = {};
-    for (const l of links) {
-        counts[l.relationship] = (counts[l.relationship] ?? 0) + 1;
-    }
-    return counts;
-}
-/**
- * Partition links by whether their SOURCE memory's rowid has been covered by
- * the `hicortex relink` watermark. `relinkCursor` is the last fully
- * committed rowid (relink.ts) — relink iterates memories by rowid and
- * discovers/refreshes links FROM each one, so a link's source rowid <=
- * cursor means a relink pass has already run for that source (current
- * formula); null cursor (never run) puts everything in "notYetRelinked".
- */
-function partitionByRelinkCursor(links, sourceRowid, relinkCursor) {
-    const relinked = [];
-    const notYetRelinked = [];
-    for (const l of links) {
-        const rowid = sourceRowid.get(l.source_id);
-        const covered = relinkCursor !== null && rowid !== undefined && rowid <= relinkCursor;
-        (covered ? relinked : notYetRelinked).push(l);
-    }
-    return { relinked, notYetRelinked };
-}
-function runDegreeAudit(db, topN = 10) {
-    const totalMemories = db.prepare("SELECT COUNT(*) AS c FROM memories").get().c;
-    const linkCounts = storage.getAllLinkCounts(db);
-    const degreeHistogram = (0, decay_eval_js_1.histogram)([...linkCounts.values()], DEGREE_BUCKET_EDGES);
-    const sortedIds = [...linkCounts.entries()].sort((a, b) => b[1] - a[1]).slice(0, topN);
-    const topHubs = sortedIds.map(([id, degree]) => {
-        const mem = storage.getMemory(db, id);
-        return {
-            id,
-            degree,
-            project: mem?.project ?? null,
-            domain: mem?.domain ?? null,
-            preview: (mem?.content ?? "").slice(0, 80),
-        };
-    });
-    return { memoriesWithLinks: linkCounts.size, totalMemories, degreeHistogram, topHubs };
-}
-/**
- * Recompute cosine for a link sample and compare to stored `strength` (post
- * migration-5 rescale, should track closely). The sample is deterministic
- * (#460): all link rows in stable PK order, drawn by a seeded Fisher–Yates —
- * two runs on the same build + snapshot produce an identical report, so
- * before/after comparisons can require full-output identity.
- */
-function runDriftSample(db, embeddings, sampleSize = DRIFT_SAMPLE_SIZE, seed = DRIFT_SAMPLE_SEED) {
-    const allLinks = db
-        .prepare("SELECT source_id, target_id, strength FROM memory_links ORDER BY source_id, target_id")
-        .all();
-    const sample = seededSample(allLinks, sampleSize, seed);
-    const drifts = [];
-    let skipped = 0;
-    for (const link of sample) {
-        const a = embeddings.get(link.source_id);
-        const b = embeddings.get(link.target_id);
-        if (!a || !b) {
-            skipped++;
-            continue;
-        }
-        const recomputed = cosineBetween(a, b);
-        drifts.push(Math.abs(recomputed - link.strength));
-    }
-    const meanAbsDrift = drifts.length > 0 ? drifts.reduce((s, d) => s + d, 0) / drifts.length : 0;
-    const maxAbsDrift = drifts.length > 0 ? Math.max(...drifts) : 0;
-    return {
-        sampleSize: drifts.length,
-        driftHistogram: (0, decay_eval_js_1.histogram)(drifts, DRIFT_BUCKET_EDGES),
-        meanAbsDrift,
-        maxAbsDrift,
-        skippedMissingEmbedding: skipped,
-    };
-}
-function statsFor(links, embeddings) {
-    let dupNoise = 0;
-    let measured = 0;
-    for (const l of links) {
-        const a = embeddings.get(l.source_id);
-        const b = embeddings.get(l.target_id);
-        if (!a || !b)
-            continue;
-        measured++;
-        if (cosineBetween(a, b) >= DUP_NOISE_THRESHOLD)
-            dupNoise++;
-    }
-    return {
-        linkCount: links.length,
-        byRelationship: byRelationshipCounts(links),
-        dupNoiseLinks: dupNoise,
-        dupNoiseShare: measured > 0 ? dupNoise / measured : 0,
-    };
-}
-/** Load every stored embedding once as id -> Float32Array. */
-function loadEmbeddings(db) {
-    const rows = db.prepare("SELECT id, embedding FROM memory_vectors").all();
-    return new Map(rows.map((r) => [r.id, (0, eval_db_js_1.blobToEmbedding)(r.embedding)]));
-}
-function runGraphAudit(db, stateDir) {
-    const links = db
-        .prepare("SELECT source_id, target_id, relationship, strength FROM memory_links")
-        .all();
-    const embeddings = loadEmbeddings(db);
-    const degree = runDegreeAudit(db);
-    const drift = runDriftSample(db, embeddings);
-    let dupNoiseCount = 0;
-    let dupNoiseMeasured = 0;
-    for (const l of links) {
-        const a = embeddings.get(l.source_id);
-        const b = embeddings.get(l.target_id);
-        if (!a || !b)
-            continue;
-        dupNoiseMeasured++;
-        if (cosineBetween(a, b) >= DUP_NOISE_THRESHOLD)
-            dupNoiseCount++;
-    }
-    const relinkCursor = (0, state_js_1.loadState)(stateDir).relinkCursor ?? null;
-    const rowidRows = db.prepare("SELECT id, rowid AS rowid FROM memories").all();
-    const sourceRowid = new Map(rowidRows.map((r) => [r.id, r.rowid]));
-    const { relinked, notYetRelinked } = partitionByRelinkCursor(links, sourceRowid, relinkCursor);
-    return {
-        totalLinks: links.length,
-        byRelationship: byRelationshipCounts(links),
-        degree,
-        drift,
-        dupNoise: {
-            threshold: DUP_NOISE_THRESHOLD,
-            count: dupNoiseCount,
-            share: dupNoiseMeasured > 0 ? dupNoiseCount / dupNoiseMeasured : 0,
-            measured: dupNoiseMeasured,
-        },
-        relinkCursor,
-        relinkedPartition: statsFor(relinked, embeddings),
-        notYetRelinkedPartition: statsFor(notYetRelinked, embeddings),
-    };
-}

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

@@ -1,85 +0,0 @@
-#!/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

@@ -1,286 +0,0 @@
-#!/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

@@ -1,30 +0,0 @@
-#!/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.
- *
- * `--now <ISO>` (#458) pins the clock the recall-surface retrieve() scores
- * against — before/after gate runs become wall-clock-independent. Default:
- * the live clock; the report records which clock produced it.
- *
- * Never touches ~/.hicortex: DB, state dir, and backups all live under a
- * mkdtemp directory that is removed on exit.
- */
-export {};