@gamaze/hicortex 0.23.0 → 0.23.2

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

@@ -1,25 +0,0 @@
-/**
- * Read-only snapshot access for the #191 mechanical audit baseline.
- *
- * The eval NEVER touches a live database — it runs against a checkpointed
- * copy (`data/audit-<date>/snapshot.db`, gitignored). This module opens that
- * copy in better-sqlite3's `readonly` mode and loads the sqlite-vec
- * extension the same way `db.ts#initDb` does, WITHOUT calling `initDb()`
- * itself: `initDb` runs schema migrations, which write to the file. A
- * snapshot is assumed to already be at the current schema version (verified
- * by `assertReadonly`, which also proves no migration silently ran).
- */
-import Database from "better-sqlite3";
-/**
- * Open a DB snapshot for read-only analysis.
- *
- * Throws if the path does not exist, or if a write attempt against the
- * returned connection would (surprisingly) succeed — the second check is a
- * belt-and-suspenders guard against a future better-sqlite3/OS combination
- * where `readonly: true` is silently ignored (e.g. a non-standard
- * filesystem), so a bug can never turn the audit into a mutation of
- * production data.
- */
-export declare function openSnapshot(dbPath: string): Database.Database;
-/** Convert a sqlite-vec embedding BLOB (as read back from `memory_vectors`) to a Float32Array. */
-export declare function blobToEmbedding(blob: Buffer): Float32Array;

package/dist/eval/eval-db.js

@@ -1,67 +0,0 @@
-"use strict";
-/**
- * Read-only snapshot access for the #191 mechanical audit baseline.
- *
- * The eval NEVER touches a live database — it runs against a checkpointed
- * copy (`data/audit-<date>/snapshot.db`, gitignored). This module opens that
- * copy in better-sqlite3's `readonly` mode and loads the sqlite-vec
- * extension the same way `db.ts#initDb` does, WITHOUT calling `initDb()`
- * itself: `initDb` runs schema migrations, which write to the file. A
- * snapshot is assumed to already be at the current schema version (verified
- * by `assertReadonly`, which also proves no migration silently ran).
- */
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.openSnapshot = openSnapshot;
-exports.blobToEmbedding = blobToEmbedding;
-const better_sqlite3_1 = __importDefault(require("better-sqlite3"));
-const node_fs_1 = require("node:fs");
-/**
- * Open a DB snapshot for read-only analysis.
- *
- * Throws if the path does not exist, or if a write attempt against the
- * returned connection would (surprisingly) succeed — the second check is a
- * belt-and-suspenders guard against a future better-sqlite3/OS combination
- * where `readonly: true` is silently ignored (e.g. a non-standard
- * filesystem), so a bug can never turn the audit into a mutation of
- * production data.
- */
-function openSnapshot(dbPath) {
-    if (!(0, node_fs_1.existsSync)(dbPath)) {
-        throw new Error(`Snapshot DB not found at ${dbPath}`);
-    }
-    const db = new better_sqlite3_1.default(dbPath, { readonly: true });
-    // eslint-disable-next-line @typescript-eslint/no-var-requires
-    const sqliteVec = require("sqlite-vec");
-    sqliteVec.load(db);
-    assertReadonly(db);
-    return db;
-}
-/**
- * Verify the connection truly refuses writes. Uses a table guaranteed to
- * exist in any migrated Hicortex DB (`schema_version`) and a no-op-shaped
- * statement (touches a version number that cannot exist) so that even if the
- * guard somehow failed open, the blast radius is a single junk row rather
- * than corruption of real data.
- */
-function assertReadonly(db) {
-    let wroteSuccessfully = false;
-    try {
-        db.prepare("INSERT INTO schema_version (version, name, applied_at) VALUES (-1, '__eval_readonly_probe__', '')").run();
-        wroteSuccessfully = true;
-    }
-    catch {
-        // Expected: SQLITE_READONLY. The connection is safe to use.
-    }
-    if (wroteSuccessfully) {
-        throw new Error("Snapshot DB accepted a write — refusing to run the eval against a " +
-            "connection that is not truly read-only. Check the better-sqlite3 " +
-            "readonly option and filesystem permissions.");
-    }
-}
-/** Convert a sqlite-vec embedding BLOB (as read back from `memory_vectors`) to a Float32Array. */
-function blobToEmbedding(blob) {
-    return new Float32Array(blob.buffer, blob.byteOffset, blob.byteLength / 4);
-}

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

@@ -1,89 +0,0 @@
-/**
- * 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).
- */
-import type Database from "better-sqlite3";
-/**
- * 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.
- */
-export declare function seededSample<T>(rows: T[], size: number, seed: number): T[];
-export interface LinkRow {
-    source_id: string;
-    target_id: string;
-    relationship: string;
-    strength: number;
-}
-/** Cosine similarity between two L2-normalized embeddings (dot product). */
-export declare function cosineBetween(a: Float32Array, b: Float32Array): number;
-export declare function byRelationshipCounts(links: LinkRow[]): Record<string, number>;
-/**
- * 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".
- */
-export declare function partitionByRelinkCursor(links: LinkRow[], sourceRowid: Map<string, number>, relinkCursor: number | null): {
-    relinked: LinkRow[];
-    notYetRelinked: LinkRow[];
-};
-export interface HubEntry {
-    id: string;
-    degree: number;
-    project: string | null;
-    domain: string | null;
-    preview: string;
-}
-export interface DegreeReport {
-    memoriesWithLinks: number;
-    totalMemories: number;
-    degreeHistogram: Record<string, number>;
-    topHubs: HubEntry[];
-}
-export declare function runDegreeAudit(db: Database.Database, topN?: number): DegreeReport;
-export interface DriftReport {
-    sampleSize: number;
-    driftHistogram: Record<string, number>;
-    meanAbsDrift: number;
-    maxAbsDrift: number;
-    skippedMissingEmbedding: number;
-}
-/**
- * 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.
- */
-export declare function runDriftSample(db: Database.Database, embeddings: Map<string, Float32Array>, sampleSize?: number, seed?: number): DriftReport;
-export interface PartitionStats {
-    linkCount: number;
-    byRelationship: Record<string, number>;
-    dupNoiseLinks: number;
-    dupNoiseShare: number;
-}
-export interface GraphReport {
-    totalLinks: number;
-    byRelationship: Record<string, number>;
-    degree: DegreeReport;
-    drift: DriftReport;
-    dupNoise: {
-        threshold: number;
-        count: number;
-        share: number;
-        measured: number;
-    };
-    relinkCursor: number | null;
-    relinkedPartition: PartitionStats;
-    notYetRelinkedPartition: PartitionStats;
-}
-export declare function runGraphAudit(db: Database.Database, stateDir?: string): GraphReport;

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;