@gamaze/hicortex 0.23.1 → 0.24.0

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

@@ -1,20 +0,0 @@
-#!/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] [--now=<ISO>]
- *
- * `--now=<ISO>` (#458) pins the clock the age/decay-derived stats (structural
- * strength, adoption age buckets) measure against, so before/after audits are
- * wall-clock-independent. Default: the live clock; the report header records
- * which clock produced it. `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 {};

package/dist/eval/run-eval.js

@@ -1,299 +0,0 @@
-#!/usr/bin/env node
-"use strict";
-/**
- * #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] [--now=<ISO>]
- *
- * `--now=<ISO>` (#458) pins the clock the age/decay-derived stats (structural
- * strength, adoption age buckets) measure against, so before/after audits are
- * wall-clock-independent. Default: the live clock; the report header records
- * which clock produced it. `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.
- */
-Object.defineProperty(exports, "__esModule", { value: true });
-const node_path_1 = require("node:path");
-const node_fs_1 = require("node:fs");
-const eval_db_js_1 = require("./eval-db.js");
-const eval_clock_js_1 = require("./eval-clock.js");
-const dups_js_1 = require("./dups.js");
-const decay_eval_js_1 = require("./decay-eval.js");
-const graph_eval_js_1 = require("./graph-eval.js");
-const reflection_census_js_1 = require("./reflection-census.js");
-const retrieval_js_1 = require("../retrieval.js");
-// ---------------------------------------------------------------------------
-// Formatting helpers
-// ---------------------------------------------------------------------------
-function pct(n) {
-    return `${(n * 100).toFixed(1)}%`;
-}
-function round(n, places = 4) {
-    const f = 10 ** places;
-    return Math.round(n * f) / f;
-}
-/** Extract the leading number from a bucket label (e.g. "[0.2, 0.3)" -> 0.2) so buckets render in ascending order. */
-function bucketSortKey(label) {
-    const match = label.match(/-?\d+(\.\d+)?/);
-    return match ? Number(match[0]) : Number.POSITIVE_INFINITY;
-}
-function histTable(h) {
-    const entries = Object.entries(h).sort((a, b) => bucketSortKey(a[0]) - bucketSortKey(b[0]));
-    if (entries.length === 0)
-        return "_(no data)_\n";
-    return entries.map(([bucket, count]) => `| ${bucket} | ${count} |`).join("\n") + "\n";
-}
-// ---------------------------------------------------------------------------
-// Report sections
-// ---------------------------------------------------------------------------
-function renderDups(d) {
-    const lines = [];
-    lines.push("## D1 — Duplicate rate\n");
-    lines.push(`Top-${d.knnK} vector KNN per memory (${d.totalMemories} memories), pairs kept at cosine >= 0.90 and clustered per threshold (union-find). "Excess" = rows that would disappear if every cluster merged to one.\n`);
-    lines.push("| Threshold | Clusters | Excess (rows) |");
-    lines.push("|---|---|---|");
-    for (const t of d.thresholds) {
-        lines.push(`| ${t.threshold} | ${t.clusterCount} | ${t.excess} |`);
-    }
-    lines.push("");
-    lines.push(`**Pair attribution** (over all ${d.pairAttribution.totalPairs} pairs at/above the lowest threshold, 0.90): ` +
-        `${d.pairAttribution.recoveryReingest} recovery/re-ingest-suspect (${pct(d.pairAttribution.totalPairs > 0 ? d.pairAttribution.recoveryReingest / d.pairAttribution.totalPairs : 0)}), ${d.pairAttribution.organic} organic (${pct(d.pairAttribution.totalPairs > 0 ? d.pairAttribution.organic / d.pairAttribution.totalPairs : 0)}).\n`);
-    lines.push(`### Top ${d.topClusters.length} clusters (0.90 threshold, largest first)\n`);
-    d.topClusters.forEach((cluster, i) => {
-        // #206 decision 2: project is the only merge-safety rail (agent rail removed).
-        const mismatch = cluster.metadataMismatch;
-        const mismatchFlags = [mismatch.projectMismatch ? "project" : null].filter(Boolean);
-        lines.push(`**Cluster ${i + 1}** — size ${cluster.size}, attribution: ${cluster.attribution.recoveryReingest} recovery-pair(s) / ${cluster.attribution.organic} organic-pair(s)` +
-            (mismatchFlags.length > 0 ? `, metadata mismatch: ${mismatchFlags.join(", ")}` : ", metadata consistent"));
-        for (const m of cluster.members) {
-            lines.push(`  - \`${m.id.slice(0, 8)}\` ${m.created_at} — ${m.preview.replace(/\n/g, " ")}`);
-        }
-        lines.push("");
-    });
-    return lines.join("\n");
-}
-function renderDecay(backlog, prune, structural, adoption) {
-    const lines = [];
-    lines.push("## D4 — Decay / Prune / No-fit lifecycle + #192 adoption\n");
-    lines.push("### Domain classification backlog\n");
-    lines.push(`${backlog.nullDomainTotal} memories have NULL domain (of ${backlog.maxRowid} max rowid). Partitioned by ` +
-        `\`domainCursor\` (${backlog.domainCursor ?? "unset — classify-domains never run"}), documented in ` +
-        `classify-domains.ts as the last fully-committed rowid:\n`);
-    lines.push(`- **Never-classified backlog** (rowid > cursor): ${backlog.neverClassifiedBacklog}`);
-    lines.push(`- **Classified but no fitting domain** (rowid <= cursor, no-fit path): ${backlog.classifiedButEmpty}\n`);
-    lines.push("### Prune dry-run (real production predicate: `stageDecayPrune`, `dryRun: true`)\n");
-    lines.push(`Decay clock configured to \`decayHalfLifeDays: ${prune.decayHalfLifeDaysUsed}\` (bedrock has no override — this is the shipped default) before running.\n`);
-    lines.push(`- Candidates (would prune today): **${prune.candidates}**`);
-    lines.push(`- Pruned: ${prune.pruned} (0 expected — dry run)`);
-    lines.push(`- Failed: ${prune.failed}\n`);
-    lines.push("### Structural strength — who can EVER prune\n");
-    lines.push(`A memory can only ever cross the prune floor (effective strength < 0.01) if its asymptote is below that floor: ` +
-        `\`base_strength < sqrt(0.1) ≈ ${round(structural.everPrunableCeiling, 4)}\` (floor = base_strength × importance × 0.1, ` +
-        `importance defaults to base_strength).\n`);
-    lines.push(`**Ever-prunable: ${structural.everPrunableCount} / ${structural.totalMemories} (${pct(structural.totalMemories > 0 ? structural.everPrunableCount / structural.totalMemories : 0)})** — everyone else has a strength floor that never drops low enough to prune, no matter how long it goes unaccessed.\n`);
-    for (const [label, hist] of [
-        ["Effective strength now", structural.effectiveStrengthNowHistogram],
-        ["Simulated +180 days (no further access)", structural.effectiveStrengthAt180dHistogram],
-        ["Simulated +365 days (no further access)", structural.effectiveStrengthAt365dHistogram],
-        ["Asymptotic floor (never, base_strength² × 0.1)", structural.effectiveStrengthNeverHistogram],
-    ]) {
-        lines.push(`**${label}**\n`);
-        lines.push("| Bucket | Count |");
-        lines.push("|---|---|");
-        lines.push(histTable(hist));
-    }
-    lines.push("### Adoption (#192 shown_count / access_count)\n");
-    lines.push("`shown_count` (migration v8) was deployed ~2 days before this snapshot — near-zero shown counts reflect the " +
-        "feature's youth as much as its effectiveness; read this section as a baseline to compare against, not a verdict.\n");
-    lines.push(`- Total shown (sum): ${adoption.totalShown}, total access (sum): ${adoption.totalAccess}`);
-    lines.push(`- Uses per showing (overall): ${adoption.usesPerShowingOverall !== null ? round(adoption.usesPerShowingOverall) : "n/a (nothing shown yet)"}`);
-    lines.push(`- Cold (shown=0 AND access=0): ${adoption.coldShare.coldCount} / ${adoption.coldShare.total} (${pct(adoption.coldShare.share)})\n`);
-    lines.push("**shown_count distribution**\n\n| Bucket | Count |\n|---|---|\n" + histTable(adoption.shownCountHistogram));
-    lines.push("**access_count distribution**\n\n| Bucket | Count |\n|---|---|\n" + histTable(adoption.accessCountHistogram));
-    lines.push("**Uses per showing by source_agent** (agents with at least one showing)\n");
-    lines.push("| source_agent | shown | access | ratio |");
-    lines.push("|---|---|---|---|");
-    const byAgent = Object.entries(adoption.usesPerShowingBySourceAgent)
-        .filter(([, v]) => v.shown > 0 || v.access > 0)
-        .sort((a, b) => b[1].shown - a[1].shown);
-    for (const [agent, v] of byAgent) {
-        lines.push(`| ${agent} | ${v.shown} | ${v.access} | ${v.ratio !== null ? round(v.ratio) : "n/a"} |`);
-    }
-    lines.push("");
-    lines.push("**Exposure age profile** — are new memories getting shown?\n");
-    lines.push("| Age bucket | Total | Ever shown | Share shown |");
-    lines.push("|---|---|---|---|");
-    for (const b of adoption.exposureAgeProfile) {
-        lines.push(`| ${b.bucket} | ${b.total} | ${b.everShown} | ${pct(b.shareShown)} |`);
-    }
-    lines.push("");
-    return lines.join("\n");
-}
-function renderGraph(g) {
-    const lines = [];
-    lines.push("## D6 — Link-graph health\n");
-    lines.push(`Total links: **${g.totalLinks}**\n`);
-    lines.push("| Relationship | Count |");
-    lines.push("|---|---|");
-    for (const [rel, count] of Object.entries(g.byRelationship)) {
-        lines.push(`| ${rel} | ${count} |`);
-    }
-    lines.push("");
-    lines.push(`### Degree distribution (${g.degree.memoriesWithLinks} / ${g.degree.totalMemories} memories have at least one link)\n`);
-    lines.push("| Degree bucket | Count |");
-    lines.push("|---|---|");
-    lines.push(histTable(g.degree.degreeHistogram));
-    lines.push(`### Top ${g.degree.topHubs.length} hubs\n`);
-    lines.push("| id | degree | project | domain | preview |");
-    lines.push("|---|---|---|---|---|");
-    for (const h of g.degree.topHubs) {
-        lines.push(`| \`${h.id.slice(0, 8)}\` | ${h.degree} | ${h.project ?? "-"} | ${h.domain ?? "-"} | ${h.preview.replace(/\|/g, "/")} |`);
-    }
-    lines.push("");
-    lines.push(`### Cosine drift (stored \`memory_links.strength\` vs recomputed, ${g.drift.sampleSize}-link random sample` +
-        (g.drift.skippedMissingEmbedding > 0 ? `, ${g.drift.skippedMissingEmbedding} skipped for missing embeddings` : "") +
-        ")\n");
-    lines.push(`Mean |drift|: ${round(g.drift.meanAbsDrift, 8)}, max |drift|: ${round(g.drift.maxAbsDrift, 8)} ` +
-        "(float32 rounding-noise scale (~1e-7) counts as zero drift — strength was set from the same embeddings at link-creation time, so no staleness is expected).\n");
-    lines.push("| |drift| bucket | Count |");
-    lines.push("|---|---|");
-    lines.push(histTable(g.drift.driftHistogram));
-    lines.push(`### Dup-noise links (endpoints >= ${g.dupNoise.threshold} cosine, measured over ${g.dupNoise.measured} links with both embeddings)\n`);
-    lines.push(`${g.dupNoise.count} / ${g.dupNoise.measured} (${pct(g.dupNoise.share)}) of links connect near-duplicate memories.\n`);
-    lines.push(`### Relink migration partition (\`relinkCursor\`: ${g.relinkCursor ?? "unset — relink never run"})\n`);
-    lines.push("| Partition | Links | Dup-noise share |");
-    lines.push("|---|---|---|");
-    lines.push(`| Relinked (source rowid <= cursor) | ${g.relinkedPartition.linkCount} | ${pct(g.relinkedPartition.dupNoiseShare)} |`);
-    lines.push(`| Not yet relinked (source rowid > cursor) | ${g.notYetRelinkedPartition.linkCount} | ${pct(g.notYetRelinkedPartition.dupNoiseShare)} |`);
-    lines.push("");
-    return lines.join("\n");
-}
-function renderReflection(r) {
-    const lines = [];
-    lines.push("## Reflection census\n");
-    lines.push(`Lessons: ${r.totalLessons}, episodes: ${r.totalEpisodes}, yield ratio (lessons/episodes): ${r.yieldRatio !== null ? round(r.yieldRatio) : "n/a"}\n`);
-    lines.push("_Not a quality read — actionable-vs-noise sampling is deferred Phase-A grading work._\n");
-    if (r.lessonsByDate.length > 0) {
-        lines.push("| Date | Lessons |");
-        lines.push("|---|---|");
-        for (const row of r.lessonsByDate) {
-            lines.push(`| ${row.date} | ${row.count} |`);
-        }
-        lines.push("");
-    }
-    return lines.join("\n");
-}
-function renderPhaseB(dups, prune, structural, backlog, graph, adoption) {
-    const lines = [];
-    lines.push("## Phase-B decision inputs\n");
-    lines.push("**1. Merge-threshold curve (dup excess at each cosine)**\n");
-    for (const t of dups.thresholds) {
-        lines.push(`- ${t.threshold}: ${t.clusterCount} clusters, ${t.excess} excess rows`);
-    }
-    lines.push("");
-    lines.push("**2. Prune posture — inert by design or miscalibration?**\n");
-    lines.push(`- Dry-run candidates today: ${prune.candidates} (half-life ${prune.decayHalfLifeDaysUsed}d)`);
-    lines.push(`- Ever-prunable ceiling: ${structural.everPrunableCount} / ${structural.totalMemories} (${pct(structural.totalMemories > 0 ? structural.everPrunableCount / structural.totalMemories : 0)}) memories can EVER cross the floor regardless of age`);
-    lines.push(`- If the current trend holds, compare the now/+180d/+365d histograms above for how many additional memories drift into low-strength bands`);
-    lines.push("");
-    lines.push("**3. Classification backlog size**\n");
-    lines.push(`- ${backlog.neverClassifiedBacklog} never-classified (beyond domainCursor), ${backlog.classifiedButEmpty} classified-but-empty (no-fit), of ${backlog.nullDomainTotal} total NULL-domain`);
-    lines.push("");
-    lines.push("**4. Link-threshold pile-up evidence**\n");
-    lines.push(`- ${graph.dupNoise.count} / ${graph.dupNoise.measured} links (${pct(graph.dupNoise.share)}) connect near-duplicate memories (>= ${graph.dupNoise.threshold} cosine)`);
-    lines.push(`- Relinked partition dup-noise share: ${pct(graph.relinkedPartition.dupNoiseShare)} vs not-yet-relinked: ${pct(graph.notYetRelinkedPartition.dupNoiseShare)}`);
-    lines.push("");
-    lines.push("**5. Adoption snapshot**\n");
-    lines.push(`- Cold (never shown, never accessed): ${adoption.coldShare.coldCount} / ${adoption.coldShare.total} (${pct(adoption.coldShare.share)})`);
-    lines.push(`- Uses per showing overall: ${adoption.usesPerShowingOverall !== null ? round(adoption.usesPerShowingOverall) : "n/a"} — CAVEAT: shown_count is ~2 days old at snapshot time, read directionally only`);
-    lines.push("");
-    return lines.join("\n");
-}
-function renderReport(input) {
-    const parts = [];
-    parts.push("# Hicortex Mechanical Audit Baseline (#191)\n");
-    parts.push(`Snapshot: \`${input.dbPath}\`  \nGenerated: ${input.generatedAt}  \nClock: ${input.clock} (#458 — the instant the age/decay-derived stats measured against)  \nRead-only, zero LLM, zero human grading — mechanical measurement only.\n`);
-    parts.push(renderDups(input.dups));
-    parts.push(renderDecay(input.domainBacklog, input.pruneDryRun, input.structural, input.adoption));
-    parts.push(renderGraph(input.graph));
-    parts.push(renderReflection(input.reflection));
-    parts.push(renderPhaseB(input.dups, input.pruneDryRun, input.structural, input.domainBacklog, input.graph, input.adoption));
-    return parts.join("\n");
-}
-// ---------------------------------------------------------------------------
-// CLI entry
-// ---------------------------------------------------------------------------
-function main() {
-    // #458: --now=<ISO> pins the age/decay-derived stats' clock; positionals
-    // (snapshot, report path) keep working unchanged.
-    const positionals = [];
-    let nowIso;
-    for (const arg of process.argv.slice(2)) {
-        const m = arg.match(/^--now=(.+)$/);
-        if (m)
-            nowIso = m[1];
-        else
-            positionals.push(arg);
-    }
-    const [dbPathArg, reportPathArg] = positionals;
-    if (!dbPathArg) {
-        console.error("Usage: run-eval.js <snapshot.db> [report.md] [--now=<ISO>]");
-        process.exitCode = 1;
-        return;
-    }
-    let now;
-    try {
-        now = (0, eval_clock_js_1.parsePinnedNow)(nowIso);
-    }
-    catch (err) {
-        console.error(`[eval] ${err instanceof Error ? err.message : err}`);
-        process.exitCode = 1;
-        return;
-    }
-    console.log(`[eval] clock: ${(0, eval_clock_js_1.clockLabel)(now)}`);
-    const nowArg = now ?? new Date(); // the live clock, made explicit for threading
-    const dbPath = dbPathArg;
-    const stateDir = (0, node_path_1.dirname)(dbPath);
-    const reportPath = reportPathArg ?? (0, node_path_1.join)(stateDir, "eval-report.md");
-    const db = (0, eval_db_js_1.openSnapshot)(dbPath);
-    try {
-        console.log("[eval] D1 duplicate audit...");
-        const dups = (0, dups_js_1.runDupAudit)(db);
-        console.log("[eval] D4 domain backlog...");
-        const domainBacklog = (0, decay_eval_js_1.runDomainBacklogAudit)(db, stateDir);
-        console.log("[eval] D4 prune dry-run...");
-        const pruneDryRun = (0, decay_eval_js_1.runPruneDryRun)(db, retrieval_js_1.DEFAULT_DECAY_HALF_LIFE_DAYS);
-        console.log("[eval] D4 structural strength stats...");
-        const structural = (0, decay_eval_js_1.runStructuralStrengthStats)(db, nowArg);
-        console.log("[eval] D4 adoption stats...");
-        const adoption = (0, decay_eval_js_1.runAdoptionStats)(db, nowArg);
-        console.log("[eval] D6 link-graph audit...");
-        const graph = (0, graph_eval_js_1.runGraphAudit)(db, stateDir);
-        console.log("[eval] reflection census...");
-        const reflection = (0, reflection_census_js_1.runReflectionCensus)(db);
-        const report = renderReport({
-            dbPath,
-            generatedAt: new Date().toISOString(),
-            clock: (0, eval_clock_js_1.clockLabel)(now),
-            dups,
-            domainBacklog,
-            pruneDryRun,
-            structural,
-            adoption,
-            graph,
-            reflection,
-        });
-        (0, node_fs_1.writeFileSync)(reportPath, report, "utf-8");
-        console.log(`[eval] report written to ${reportPath}`);
-    }
-    finally {
-        db.close();
-    }
-}
-main();