@gamaze/hicortex 0.20.9 → 0.21.0

package/dist/db.js

@@ -547,6 +547,111 @@ const MIGRATIONS = [
             db.exec("CREATE INDEX IF NOT EXISTS idx_memory_history_memory ON memory_history(memory_id)");
         },
     },
+    {
+        version: 15,
+        name: "source_machine",
+        up: (db) => {
+            // #421 owner direction (machine × harness identity): nullable, NO
+            // backfill — honesty over guesses. Rows written before this column
+            // stay NULL and group under "earlier captures" in the console; that
+            // bucket shrinks as nights accumulate stamped captures. Stamped by the
+            // nightly capture path (config `machineName` ?? os.hostname()) and
+            // accepted optionally by /distill + /ingest. Idempotent via hasColumn.
+            if (!hasColumn(db, "memories", "source_machine")) {
+                db.exec("ALTER TABLE memories ADD COLUMN source_machine TEXT");
+            }
+        },
+    },
+    {
+        version: 16,
+        name: "distill_activity",
+        up: (db) => {
+            // #422 Phase 2 — /distill capture-health accounting. One row per POST
+            // (every outcome incl. held/skipped), written by
+            // capture-health.ts:recordDistillActivity from the /distill handler's
+            // exits. This is OPERATIONS telemetry, not memory data: rows prune
+            // after 7 days (in-module, once per process per UTC day), so the table
+            // stays bounded while giving the console's capture-health card a real
+            // posts/sessions/bytes/held picture per machine × agent. `retried` is
+            // computed at insert (an earlier row with the same session_id +
+            // segment_id means this POST is a client retry of a cursor-held
+            // segment) — never updated afterwards. Sidecar table (no memories FK):
+            // the memory rows of a failed POST may never exist; the activity row
+            // must record the attempt anyway. Idempotent: IF NOT EXISTS everywhere.
+            db.exec(`
+        CREATE TABLE IF NOT EXISTS distill_activity (
+          ts TEXT NOT NULL,
+          day TEXT NOT NULL,
+          machine TEXT NOT NULL DEFAULT '',
+          agent TEXT NOT NULL DEFAULT '',
+          session_id TEXT,
+          segment_id TEXT,
+          bytes INTEGER NOT NULL DEFAULT 0,
+          outcome TEXT NOT NULL,
+          retried INTEGER NOT NULL DEFAULT 0
+        )
+      `);
+            db.exec("CREATE INDEX IF NOT EXISTS idx_distill_activity_day ON distill_activity(day)");
+            db.exec("CREATE INDEX IF NOT EXISTS idx_distill_activity_session_segment ON distill_activity(session_id, segment_id)");
+        },
+    },
+    {
+        version: 17,
+        name: "memory_corroboration",
+        up: (db) => {
+            // #423 phase 3 — explicit owner corroboration trail (POST /enrich).
+            // DEFAULT 0 with NO backfill: a pre-v17 row was never enriched and 0 is
+            // the honest count. /memory rides it via SELECT * (the console detail's
+            // "corroborated × N"); the enrich itself writes base_strength — it
+            // never fakes access/shown counts (those are the recall-adoption
+            // signal). Idempotent via hasColumn (the v15 pattern).
+            if (!hasColumn(db, "memories", "corroboration_count")) {
+                db.exec("ALTER TABLE memories ADD COLUMN corroboration_count INTEGER NOT NULL DEFAULT 0");
+            }
+        },
+    },
+    {
+        version: 18,
+        name: "capture_pauses",
+        up: (db) => {
+            // #423 phase 3, D3 — server-side 200-skip for a paused machine ×
+            // harness bundle. A row EXISTS = paused; absence = capturing (no
+            // "paused" flag to keep honest). Deliberately NO retention/pruning: the
+            // rows are few and operator-owned, and pruning one would silently
+            // resume capture the operator meant to hold. Idempotent: IF NOT EXISTS.
+            db.exec(`
+        CREATE TABLE IF NOT EXISTS capture_pauses (
+          machine TEXT NOT NULL DEFAULT '',
+          harness TEXT NOT NULL,
+          paused_at TEXT NOT NULL,
+          PRIMARY KEY(machine, harness)
+        )
+      `);
+        },
+    },
+    {
+        version: 19,
+        name: "add_importance_scored_at",
+        up: (db) => {
+            // #425 — scored-at watermark for importance scoring. getUnscoredMemories
+            // keys on importance_scored_at IS NULL (v19+), replacing the old
+            // base_strength = 0.5 sentinel, which re-rolled every row the model
+            // genuinely scored 0.5 every night. Backfill: existing rows that are NOT
+            // at the 0.5 sentinel are stamped "settled" (COALESCE(updated_at,
+            // ingested_at, created_at)) — they carry a real historical score and
+            // leave the nightly pool. Rows AT the sentinel stay NULL so the next
+            // nightly scores them ONCE under the new rubric (bounded — the watermark
+            // write in stageImportance then takes them out of the pool). The
+            // rescore-importance backfill CLI re-judges settled rows wholesale under
+            // its own cursor; this migration only makes the NIGHTLY pool honest.
+            // Idempotent via hasColumn (the v8 pattern).
+            if (!hasColumn(db, "memories", "importance_scored_at")) {
+                db.exec("ALTER TABLE memories ADD COLUMN importance_scored_at TEXT");
+            }
+            db.exec(`UPDATE memories SET importance_scored_at = COALESCE(updated_at, ingested_at, created_at)
+         WHERE importance_scored_at IS NULL AND base_strength != 0.5`);
+        },
+    },
 ];
 /**
  * Run all pending migrations against the database.

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-fixtures.d.ts

@@ -65,7 +65,7 @@ export interface PlantedPair {
     /**
      * 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 the rewrite phase without one).
+     * throws if a corrects verdict ever reaches its rewrite call without one).
      */
     rewritten?: string;
     /**

package/dist/eval/ranking-battery.d.ts

@@ -0,0 +1,78 @@
+/**
+ * The real-query battery for the #425 ranking gate — the DETERMINISTIC,
+ * dependency-free half (kept out of ranking-eval.ts so vitest can import
+ * it without pulling the ONNX embedder; same split as planted-fixtures vs
+ * planted-eval).
+ *
+ * The battery is a stable set of ~30 queries derived from the SNAPSHOT
+ * CORPUS ITSELF: fixed df windows over content tokens, fixed tie-breaks —
+ * same snapshot, same queries, every run. Bands: 10 high-df (50-400 docs),
+ * 10 mid-df (10-50), 5 rare-df (3-10), 4 mid-sentence capitalized proper
+ * nouns (df 2-8), plus the fixed "Sirnäs" query (the owner's live case).
+ *
+ * Also carries the photo-comparison gates the sweep protocol defines:
+ *   - case 2 byte-stability (no-match queries must not drift),
+ *   - battery top-1 stability >= 90%,
+ *   - no query losing a both-channel exact match from its top-3.
+ */
+export declare const SIRNAS_QUERY = "Sirn\u00E4s";
+/** Compact English stopword block (battery derivation only, not product). */
+export declare const STOPWORDS: Set<string>;
+export interface BatteryQuery {
+    q: string;
+    band: "proper-noun-fixed" | "high-df" | "mid-df" | "rare-df" | "proper-noun";
+}
+export interface BatteryResult {
+    q: string;
+    band: string;
+    top8: string[];
+    /** Per-result provenance (ranking-eval fills it; the gates read it). */
+    meta?: Array<{
+        id: string;
+        source: string | null;
+        term: boolean | null;
+    }>;
+}
+export interface BatteryPhoto {
+    queries: BatteryResult[];
+    /** Rank (1-based) of the real Sirnäs memory for the fixed query; null = not in top-8. */
+    sirnasRank: number | null;
+}
+/**
+ * Derive the battery from live corpus contents — DETERMINISTIC given the
+ * snapshot: fixed stopword list, fixed df windows, fixed tie-breaks
+ * (df desc, then token asc).
+ */
+export declare function deriveBatteryQueries(rows: Array<{
+    id: string;
+    content: string;
+}>): BatteryQuery[];
+/** Case 2 gate: the FULL returned list must be byte-identical (ids + order). */
+export declare function compareCase2(baseline: string[], current: string[]): boolean;
+export interface BatteryComparison {
+    top1Stability: number;
+    /** Stability with intended D3 promotions excluded: old top-1 was NOT a
+     *  both-channel exact match and the new top-1 IS one (the boost doing its
+     *  job on real queries — reported, not gated). */
+    top1StabilityExPromotions: number;
+    changedTop1: string[];
+    /** Queries whose top-3 LOST every both-channel exact match (the gate:
+     *  must be empty). */
+    lostBothChannelExact: string[];
+    /** Per-id exact-match (term-carrying) rows displaced from top-3 — reported
+     *  for the sweep record, not gated (multiple genuine matches make per-id
+     *  membership arbitrary). */
+    lostExactMatches: string[];
+}
+/**
+ * Battery gates vs a recorded baseline photo. `contentById` maps memory id →
+ * content for the corpus BOTH photos were recorded against.
+ *
+ * Gates: (a) any query whose baseline top-3 held a BOTH-CHANNEL exact match
+ * (vector+FTS agreeing on a term-carrying row) must still hold one — the
+ * genuine-match guarantee never regresses; (b) top-1 stability. Intended D3
+ * promotions (a both-channel exact match taking top-1 from a non-exact or
+ * single-channel row) are counted separately — they are the feature firing,
+ * and the sweep record shows both numbers.
+ */
+export declare function batteryComparison(baseline: BatteryPhoto, current: BatteryPhoto, contentById: Map<string, string>): BatteryComparison;