@gamaze/hicortex 0.23.1 → 0.24.0

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

@@ -1,125 +0,0 @@
-/**
- * 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 unlinked-row identity (#449: unlinked rows' scores + mutual
- *     order must not drift; linked-row order drifts by design),
- *   - 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 (pre-#449): the FULL returned list must be byte-identical
- * (ids + order). Superseded as the --compare gate by `compareCase2Unlinked`
- * in #449 PR E — linked rows' connections credit RISES by design under the
- * reshape, so linked-row order drifts; kept for reference/re-recording old
- * photos.
- */
-export declare function compareCase2(baseline: string[], current: string[]): boolean;
-/** One recorded case-2 result row (the #449 per-row photo extension). */
-export interface Case2IdentityRow {
-    key: string;
-    score: number;
-    connections: number;
-}
-/** The photo sections the identity gate reads (baseline or current). */
-export interface Case2IdentityPhoto {
-    ftsHitRows?: number;
-    ids?: string[];
-    results?: Case2IdentityRow[];
-}
-export interface Case2IdentityResult {
-    pass: boolean;
-    failures: string[];
-}
-/**
- * #449 (spec AC-7): the unlinked-row identity gate REPLACING the ids+order
- * byte-gate for this PR — linked-row order drifts BY DESIGN (their
- * connections credit rises), while everything UNLINKED must be untouched:
- * the log term contributes exactly +0 at k = 0, so an unlinked row's score
- * is bit-identical pre/post change. On the extended photo (per-row results
- * with scores + measured connections) it checks that
- *   (i) FTS hits stay 0 on both sides (no both-channel candidate can exist
- *       — the case's structural inertness),
- *   (ii) every connections===0 row's recorded score is identical to the
- *        baseline's within CASE2_SCORE_TOLERANCE (matched by key — the
- *        log term contributes exactly +0 at k = 0; the tolerance absorbs
- *        the wall-clock drift of the time terms between recordings),
- *   (iii) the subsequence of unlinked keys in the returned list is
- *        identical (bit-identical scores + stable sort ⇒ their mutual
- *        order cannot flip), and
- *   (iv) every position change involves at least one LINKED row.
- *
- * A baseline photo without per-row results (pre-#449 harness) fails with a
- * re-record instruction — the gate refuses to compare what it cannot see.
- */
-export declare function compareCase2Unlinked(baseline: Case2IdentityPhoto, current: Case2IdentityPhoto, opts?: {
-    ftsHitMax?: number;
-}): Case2IdentityResult;
-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;

package/dist/eval/ranking-battery.js

@@ -1,289 +0,0 @@
-"use strict";
-/**
- * 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 unlinked-row identity (#449: unlinked rows' scores + mutual
- *     order must not drift; linked-row order drifts by design),
- *   - battery top-1 stability >= 90%,
- *   - no query losing a both-channel exact match from its top-3.
- */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.STOPWORDS = exports.SIRNAS_QUERY = void 0;
-exports.deriveBatteryQueries = deriveBatteryQueries;
-exports.compareCase2 = compareCase2;
-exports.compareCase2Unlinked = compareCase2Unlinked;
-exports.batteryComparison = batteryComparison;
-exports.SIRNAS_QUERY = "Sirnäs";
-/** Compact English stopword block (battery derivation only, not product). */
-exports.STOPWORDS = new Set(("the a an and or but if while with without for from into onto about after before during under over " +
-    "this that these those there here when where which who whom whose what why how all any both each " +
-    "few more most other some such no nor not only own same so than too very can will just should now " +
-    "was were been being are was is am be have has had having do does did doing would could might must " +
-    "also because through between against above below off again further then once its it their they " +
-    "them we you your our i me my he she his her him us of as at by in on to per via due using use " +
-    "used using make made get gets got set sets let run ran running work works working need needs " +
-    "added add adds change changed new next last first second one two three session sessions " +
-    "memory memories project projects user users system systems thing things stuff lot bit way ways " +
-    "time times day days week weeks month months year years")
-    .split(/\s+/));
-/**
- * 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).
- */
-function deriveBatteryQueries(rows) {
-    const docs = rows.map((r) => r.content.toLowerCase());
-    const df = new Map();
-    for (const doc of docs) {
-        const seen = new Set();
-        for (const m of doc.matchAll(/[\p{L}\p{N}]{5,}/gu)) {
-            const t = m[0];
-            if (exports.STOPWORDS.has(t) || seen.has(t))
-                continue;
-            seen.add(t);
-            df.set(t, (df.get(t) ?? 0) + 1);
-        }
-    }
-    const inWindow = (lo, hi) => [...df.entries()]
-        .filter(([t, d]) => d >= lo && d < hi && !exports.STOPWORDS.has(t))
-        .sort((a, b) => (b[1] - a[1] !== 0 ? b[1] - a[1] : a[0].localeCompare(b[0])))
-        .map(([t, d]) => [t, d]);
-    const queries = [
-        { q: exports.SIRNAS_QUERY, band: "proper-noun-fixed" },
-    ];
-    for (const [t] of inWindow(50, 401).slice(0, 10))
-        queries.push({ q: t, band: "high-df" });
-    for (const [t] of inWindow(10, 50).slice(0, 10))
-        queries.push({ q: t, band: "mid-df" });
-    for (const [t] of inWindow(3, 10).slice(0, 5))
-        queries.push({ q: t, band: "rare-df" });
-    // Proper nouns: capitalized, appearing mid-sentence (not the first word
-    // after a sentence break — cheap deterministic heuristic), df 2-8.
-    // "Sirnäs" itself may or may not surface here; the fixed query above
-    // guarantees coverage.
-    const capDf = new Map();
-    for (const content of rows.map((r) => r.content)) {
-        const seen = new Set();
-        for (const m of content.matchAll(/[^\s.!?;:]\s+([\p{Lu}][\p{L}\p{N}\p{M}-]{3,})/gu)) {
-            const t = m[1];
-            if (!exports.STOPWORDS.has(t.toLowerCase()))
-                seen.add(t);
-        }
-        for (const t of seen)
-            capDf.set(t, (capDf.get(t) ?? 0) + 1);
-    }
-    const properNouns = [...capDf.entries()]
-        .filter(([t, d]) => d >= 2 && d <= 8)
-        .sort((a, b) => (b[1] - a[1] !== 0 ? b[1] - a[1] : a[0].localeCompare(b[0])))
-        .map(([t]) => t);
-    for (const t of properNouns.slice(0, 4))
-        queries.push({ q: t, band: "proper-noun" });
-    return queries;
-}
-/**
- * Case 2 gate (pre-#449): the FULL returned list must be byte-identical
- * (ids + order). Superseded as the --compare gate by `compareCase2Unlinked`
- * in #449 PR E — linked rows' connections credit RISES by design under the
- * reshape, so linked-row order drifts; kept for reference/re-recording old
- * photos.
- */
-function compareCase2(baseline, current) {
-    return (baseline.length === current.length &&
-        baseline.every((id, i) => id === current[i]));
-}
-/**
- * Score-comparison tolerance for gate (ii) — the WALL-CLOCK drift of the
- * recorded scores, not slack. retrieve() scores with the live clock
- * (computeScore's `now`), and the time-curve + decay terms move every
- * row's score ≈1.5e-5/hour of wall time between photo recordings (measured
- * 2026-09-17: two SAME-BUILD runs minutes apart differ by ~1e-6; the
- * embedder itself is bit-deterministic across processes). The tolerance
- * covers ~7 hours of drift between recordings while staying 290x below the
- * smallest real movement this gate exists to catch — the k=1 linked-row
- * credit change (0.0367 − 0.0075 = 0.0292). TRUE bit-identity of the k=0
- * term is pinned at the unit level instead (tests/ranking-flip.test.ts,
- * fixed NOW, synthetic distances).
- */
-const CASE2_SCORE_TOLERANCE = 1e-4;
-/**
- * #449 (spec AC-7): the unlinked-row identity gate REPLACING the ids+order
- * byte-gate for this PR — linked-row order drifts BY DESIGN (their
- * connections credit rises), while everything UNLINKED must be untouched:
- * the log term contributes exactly +0 at k = 0, so an unlinked row's score
- * is bit-identical pre/post change. On the extended photo (per-row results
- * with scores + measured connections) it checks that
- *   (i) FTS hits stay 0 on both sides (no both-channel candidate can exist
- *       — the case's structural inertness),
- *   (ii) every connections===0 row's recorded score is identical to the
- *        baseline's within CASE2_SCORE_TOLERANCE (matched by key — the
- *        log term contributes exactly +0 at k = 0; the tolerance absorbs
- *        the wall-clock drift of the time terms between recordings),
- *   (iii) the subsequence of unlinked keys in the returned list is
- *        identical (bit-identical scores + stable sort ⇒ their mutual
- *        order cannot flip), and
- *   (iv) every position change involves at least one LINKED row.
- *
- * A baseline photo without per-row results (pre-#449 harness) fails with a
- * re-record instruction — the gate refuses to compare what it cannot see.
- */
-function compareCase2Unlinked(baseline, current, opts) {
-    const failures = [];
-    const ftsMax = opts?.ftsHitMax ?? 0;
-    if ((baseline.ftsHitRows ?? ftsMax) > ftsMax) {
-        failures.push(`baseline FTS hits ${baseline.ftsHitRows} (expected <= ${ftsMax})`);
-    }
-    if ((current.ftsHitRows ?? ftsMax) > ftsMax) {
-        failures.push(`current FTS hits ${current.ftsHitRows} (expected <= ${ftsMax})`);
-    }
-    if (!baseline.results || baseline.results.length === 0 || !current.results) {
-        failures.push("baseline photo lacks case-2 per-row results — re-record it with the #449 harness " +
-            "(the identity gate reads recorded scores + connections)");
-        return { pass: false, failures };
-    }
-    // (ii) every unlinked row's score identical to the baseline's within the
-    // wall-clock tolerance (both directions: no unlinked row may appear,
-    // disappear, or rescore beyond clock drift).
-    const baseByKey = new Map(baseline.results.map((r) => [r.key, r]));
-    for (const r of current.results) {
-        if (r.connections !== 0)
-            continue;
-        const b = baseByKey.get(r.key);
-        if (!b) {
-            failures.push(`unlinked row ${r.key} missing from baseline results`);
-            continue;
-        }
-        if (Math.abs(b.score - r.score) > CASE2_SCORE_TOLERANCE) {
-            failures.push(`unlinked row ${r.key} score ${r.score} vs baseline ${b.score} (|Δ| ${Math.abs(b.score - r.score).toExponential(2)} > ${CASE2_SCORE_TOLERANCE})`);
-        }
-    }
-    const curKeys = new Set(current.results.map((r) => r.key));
-    for (const b of baseline.results) {
-        if (b.connections === 0 && !curKeys.has(b.key)) {
-            failures.push(`baseline unlinked row ${b.key} missing from current results`);
-        }
-    }
-    // (iii) the unlinked-key subsequence (order included) is identical.
-    const unlinkedKeys = (rows) => rows.filter((r) => r.connections === 0).map((r) => r.key);
-    const baseSub = unlinkedKeys(baseline.results);
-    const curSub = unlinkedKeys(current.results);
-    if (baseSub.join("") !== curSub.join("")) {
-        failures.push(`unlinked-key subsequence changed: [${baseSub.join(", ")}] -> [${curSub.join(", ")}]`);
-    }
-    // (iv) every position change involves at least one linked row.
-    const connByKey = (photo) => new Map(photo.map((r) => [r.key, r.connections]));
-    const baseConn = connByKey(baseline.results);
-    const curConn = connByKey(current.results);
-    if (baseline.results.length !== current.results.length) {
-        failures.push(`returned-list length changed (${baseline.results.length} -> ${current.results.length})`);
-    }
-    else {
-        for (let i = 0; i < current.results.length; i++) {
-            const oldKey = baseline.results[i].key;
-            const newKey = current.results[i].key;
-            if (oldKey === newKey)
-                continue;
-            const oldLinked = (baseConn.get(oldKey) ?? 0) > 0;
-            const newLinked = (curConn.get(newKey) ?? 0) > 0;
-            if (!oldLinked && !newLinked) {
-                failures.push(`position ${i + 1} changed ${oldKey} -> ${newKey} with BOTH rows unlinked`);
-            }
-        }
-    }
-    return { pass: failures.length === 0, failures };
-}
-/** A both-channel row carrying the query term — the genuine-match signature. */
-function isBothChannelExact(m, id, term, contentById) {
-    if (m)
-        return m.source === "both" && m.term === true;
-    // Baseline photos recorded before `meta` existed: fall back to content
-    // containment; conservatively treat source as unknown (not "both").
-    const content = contentById.get(id);
-    return Boolean(content && content.toLowerCase().includes(term));
-}
-/**
- * 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.
- */
-function batteryComparison(baseline, current, contentById) {
-    const baseByQ = new Map(baseline.queries.map((b) => [b.q, b]));
-    const baseMeta = (b, rank) => b.meta?.[rank];
-    let stable = 0;
-    let stableExPromotions = 0;
-    let compared = 0;
-    const changedTop1 = [];
-    const lostBothChannelExact = [];
-    const lostExactMatches = [];
-    for (const cur of current.queries) {
-        const base = baseByQ.get(cur.q);
-        if (!base)
-            continue;
-        compared++;
-        if (cur.top8[0] === base.top8[0]) {
-            stable++;
-            stableExPromotions++;
-            continue;
-        }
-        changedTop1.push(cur.q);
-        const term = cur.q.toLowerCase();
-        const oldExact = baseMeta(base, 0) !== undefined
-            ? isBothChannelExact(baseMeta(base, 0), base.top8[0], term, contentById)
-            : null;
-        const newExact = cur.meta?.[0] !== undefined
-            ? isBothChannelExact(cur.meta[0], cur.top8[0], term, contentById)
-            : null;
-        // An intended promotion: the new top-1 is a both-channel exact match the
-        // old top-1 was not. (Null = provenance unknown — pre-meta baseline —
-        // counts as a plain change.)
-        if (newExact === true && oldExact === false)
-            stableExPromotions++;
-    }
-    for (const cur of current.queries) {
-        const base = baseByQ.get(cur.q);
-        if (!base || cur.q === exports.SIRNAS_QUERY)
-            continue;
-        const term = cur.q.toLowerCase();
-        const curTop3 = new Set(cur.top8.slice(0, 3));
-        let baseHadBothChannelExact = false;
-        for (let i = 0; i < Math.min(3, base.top8.length); i++) {
-            const id = base.top8[i];
-            const content = contentById.get(id);
-            const carries = Boolean(content && content.toLowerCase().includes(term));
-            if (carries && !curTop3.has(id))
-                lostExactMatches.push(`${cur.q}: ${id.slice(0, 8)}`);
-            const m = base.meta?.[i];
-            if (m ? m.source === "both" && m.term === true : false)
-                baseHadBothChannelExact = true;
-        }
-        if (baseHadBothChannelExact) {
-            const stillHas = cur.top8
-                .slice(0, 3)
-                .some((id, i) => cur.meta?.[i]?.source === "both" && cur.meta?.[i]?.term === true);
-            if (!stillHas)
-                lostBothChannelExact.push(cur.q);
-        }
-    }
-    return {
-        top1Stability: compared > 0 ? stable / compared : 1,
-        top1StabilityExPromotions: compared > 0 ? stableExPromotions / compared : 1,
-        changedTop1,
-        lostBothChannelExact,
-        lostExactMatches,
-    };
-}

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

@@ -1,61 +0,0 @@
-#!/usr/bin/env node
-/**
- * Search-trust ranking gate (#425) — the AC1/AC2/AC3 before/after photo.
- * Extended by #449 (items 1+3, PR E): the case-2 photo gains per-row
- * results (scores + measured connections) and its gate becomes the
- * unlinked-row identity comparator; a new planted case 3 (linked_fallback)
- * pins the connections-reshape expectations.
- *
- *   npm run eval:ranking [--snapshot <db>] [--photo <out.json>]
- *                        [--compare <baseline.json>] [--scoring '<json>']
- *
- *   --snapshot <db>    enables case 4: the deterministic real-query battery
- *                      against a READONLY snapshot (openSnapshot — never
- *                      initDb; the snapshot is never touched). Also reports
- *                      where the real "Sirnäs" memory ranks today (the
- *                      measured red photo pre-fix, AC10 pre-condition).
- *   --photo <out.json> where to write the machine photo (defaults to
- *                      data/ranking-eval-photo.json). ALWAYS written, even
- *                      on a red run — the photo IS the measurement.
- *   --compare <json>   gate against a previously recorded photo: case 2's
- *                      UNLINKED rows must keep their scores (within the
- *                      wall-clock tolerance) and mutual order — linked-row
- *                      order drifts BY DESIGN under #449 — and the battery
- *                      (when both sides have one) must hold top-1
- *                      stability >= 90% with no query losing a both-channel
- *                      exact match from its top-3.
- *   --scoring '<json>' a JSON object of ScoringWeights overrides passed to
- *                      configureScoring (the eval/test seam, #408) — the
- *                      sweep knob. Production runs omit it.
- *   --now <ISO>       #458: pin the eval clock — planted lastAccessed offsets
- *                      AND every retrieve() score against the SAME instant,
- *                      so before/after photos are wall-clock-independent.
- *                      Default: the live clock. The photo records the clock.
- *
- * Cases (fixtures: ranking-fixtures.ts, real bge-small-en-v1.5 embedder):
- *   1. sirnas_exact_match — planted corpus in a THROWAWAY writable DB;
- *      declared expectation: the proper-noun exact-match row returns #1.
- *      Exit code reflects the verdict (a pre-fix run is EXPECTED to exit
- *      non-zero — that red photo is the before picture).
- *   2. no_match_control — same corpus, a "mamma"-class query with zero FTS
- *      hits; records the full returned list (ids + per-row results) for the
- *      unlinked-identity comparison.
- *   3. linked_fallback (#449) — planted corpus in its OWN throwaway DB: a
- *      16-link vs 20-link identical-content hub pair (saturation tie,
- *      declared byte-equal post-change) + an unlinked higher-similarity row
- *      vs a 4-link lower-similarity row (direction pin). Measured under the
- *      eval seam rrfCompositeWeight=1 (finalScore = composite exactly —
- *      identical-content hubs differ by an RRF epsilon at the default
- *      blend). RED under the pre-#449 linear term: the recorded
- *      before-picture.
- *   4. real-query battery (needs --snapshot) — ~30 queries derived
- *      deterministically from the snapshot corpus (top/mid/rare-frequency
- *      distinctive terms + proper nouns) + the fixed "Sirnäs" query; top-8
- *      ids per query recorded to the photo.
- *
- * Honesty invariants: similarities are MEASURED (real embedder, embed-once,
- * queryEmbedding reuse), noStrengthen on every retrieve() (the probe never
- * perturbs the store), readonly snapshot access, and the planted corpora
- * live in mkdtemp dirs removed on exit. Never touches ~/.hicortex.
- */
-export {};