@gamaze/hicortex 0.14.3 → 0.15.0

package/dist/eval/eval-db.js

@@ -0,0 +1,67 @@
+"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

@@ -0,0 +1,76 @@
+/**
+ * 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";
+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 random link sample and compare to stored `strength` (post migration-5 rescale, should track closely). */
+export declare function runDriftSample(db: Database.Database, embeddings: Map<string, Float32Array>, sampleSize?: 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

@@ -0,0 +1,200 @@
+"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.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;
+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];
+// ---------------------------------------------------------------------------
+// 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 random link sample and compare to stored `strength` (post migration-5 rescale, should track closely). */
+function runDriftSample(db, embeddings, sampleSize = DRIFT_SAMPLE_SIZE) {
+    const sample = db
+        .prepare("SELECT source_id, target_id, strength FROM memory_links ORDER BY RANDOM() LIMIT ?")
+        .all(sampleSize);
+    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/reflection-census.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Reflection census (#191 mechanical baseline) — lesson output volume over
+ * time and the lesson/episode yield ratio. This is NOT a quality read
+ * (sampling lessons for actionable-vs-noise is Phase-A grading work,
+ * deferred per the issue's owner comment until recall is active) — just the
+ * mechanical count.
+ */
+import type Database from "better-sqlite3";
+export interface ReflectionCensus {
+    lessonsByDate: Array<{
+        date: string;
+        count: number;
+    }>;
+    totalLessons: number;
+    totalEpisodes: number;
+    /** lessons / episodes — null when there are no episodes to divide by. */
+    yieldRatio: number | null;
+}
+export declare function runReflectionCensus(db: Database.Database): ReflectionCensus;

package/dist/eval/reflection-census.js

@@ -0,0 +1,25 @@
+"use strict";
+/**
+ * Reflection census (#191 mechanical baseline) — lesson output volume over
+ * time and the lesson/episode yield ratio. This is NOT a quality read
+ * (sampling lessons for actionable-vs-noise is Phase-A grading work,
+ * deferred per the issue's owner comment until recall is active) — just the
+ * mechanical count.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runReflectionCensus = runReflectionCensus;
+function runReflectionCensus(db) {
+    const lessonsByDate = db
+        .prepare(`SELECT date(created_at) AS date, COUNT(*) AS count
+       FROM memories WHERE memory_type = 'lesson'
+       GROUP BY date ORDER BY date`)
+        .all();
+    const totalLessons = db.prepare("SELECT COUNT(*) AS c FROM memories WHERE memory_type = 'lesson'").get().c;
+    const totalEpisodes = db.prepare("SELECT COUNT(*) AS c FROM memories WHERE memory_type = 'episode'").get().c;
+    return {
+        lessonsByDate,
+        totalLessons,
+        totalEpisodes,
+        yieldRatio: totalEpisodes > 0 ? totalLessons / totalEpisodes : null,
+    };
+}

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

@@ -0,0 +1,17 @@
+#!/usr/bin/env node
+/**
+ * #191 mechanical audit baseline — orchestrates every section (D1 duplicate
+ * rate, D4 decay/prune/no-fit + #192 adoption, D6 link-graph health, the
+ * reflection census) into one markdown report.
+ *
+ * Read-only end to end: opens the snapshot via eval-db.ts (`openSnapshot`,
+ * never `initDb()`), never writes to the DB. Not wired into `cli.ts` — this
+ * is an internal measurement tool, run via the `eval` npm script:
+ *
+ *   npm run eval -- <snapshot.db> [report.md]
+ *
+ * `state.json` is expected alongside the snapshot DB (same directory) for
+ * the `domainCursor`/`relinkCursor` watermarks. Report path defaults to
+ * `eval-report.md` next to the DB.
+ */
+export {};