@gamaze/hicortex 0.20.7 → 0.20.10

package/dist/eval/planted-fixtures.js

@@ -0,0 +1,283 @@
+"use strict";
+/**
+ * Planted-pair fixture corpus for the resolution acceptance gate (#393
+ * increment A — the eval-first harness).
+ *
+ * Five failure classes, each encoded as planted memory pairs with a DECLARED
+ * ground-truth relation and a DECLARED expected cosine band:
+ *
+ *   (a) cross_topic_correction — the correction rides inside a topically
+ *       unrelated experience memory; measured cosine ~0.5-0.6, BELOW the
+ *       `correctionMinSimilarity` floor (0.75) — the documented field hole
+ *       (0 `corrects` verdicts in 246 on the 17k snapshot).
+ *   (b) source_conflict — two live records that are both true AS RECORDS (each
+ *       faithfully reports a different source) at >= the deterministic-zone
+ *       ceiling (0.92). Guard-C closes the hole: the scout flags the newer
+ *       record contradiction-shaped, the judge answers `conflicts`, the link
+ *       guards the zone, and both stay live.
+ *   (c) version_chain — v1 -> v2 -> v3 of a revised decision record: the
+ *       0.78-0.96 stale-churn class (#392 owner calibration). v1-v2 sits in
+ *       the judged band; v2-v3 (numeric status churn inside a long shared
+ *       record) sits above the ceiling, where the zone blends the NEWEST
+ *       version into the STALE one (canonical = oldest created_at).
+ *   (d) same_fact_paraphrase — one fact, two wordings: should merge.
+ *   (e) complementary_facets — same subject, different facets: should keep
+ *       both (judge verdict `none`).
+ *
+ * Honesty rules:
+ *  - The texts are synthetic and generic (this package publishes to npm — no
+ *    real infrastructure, people, or fleet detail), but SHAPED like the field
+ *    failures: corrections ride in experience memories, conflicts share long
+ *    context tails, churn edits one field of a long record.
+ *  - Cosines are MEASURED at run time with the real bge-small-en-v1.5 embedder
+ *    (planted-eval.ts) — never asserted into existence. The declared bands
+ *    below were calibrated against that embedder (see the band table in the
+ *    report); a pair landing outside its band renders as a loud OUT-OF-BAND
+ *    flag rather than a hard failure, so an embedder change is visible, not
+ *    silent (same posture as run-eval).
+ *  - Neutral filler rows keep the KNN neighborhoods non-trivial and give the
+ *    collider analysis something to check (any non-ground-truth pair >= 0.70
+ *    is reported).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.REAL_TEXT_CORPUS = exports.PLANTED_SOURCE_AGENT = exports.PLANTED_PROJECT = void 0;
+exports.chainMembers = chainMembers;
+/** All planted rows share project + source_agent so the metadata rails never refuse a fixture merge. */
+exports.PLANTED_PROJECT = "planted-eval";
+exports.PLANTED_SOURCE_AGENT = "planted-eval";
+// ---------------------------------------------------------------------------
+// The real-text corpus (embedded with the REAL embedder by planted-eval.ts)
+// ---------------------------------------------------------------------------
+const FILLER = [
+    [
+        "fill_recipe",
+        "Batch-cooked a tomato and butter sauce from the Rome cookbook: San Marzano tomatoes, one whole onion halved, and far more butter than seems reasonable. Simmered 45 minutes. The whole family preferred it to last month's pesto attempt.",
+        "2026-06-06T09:00:00.000Z",
+    ],
+    [
+        "fill_run",
+        "Half-marathon training week 6: three easy runs at conversational pace, one interval session on the track, and a 16-kilometer long run on Sunday. Left knee complains on downhills; foam rolling after every session keeps it quiet.",
+        "2026-06-07T09:00:00.000Z",
+    ],
+    [
+        "fill_books",
+        "Finished the third novel in the frontier trilogy. The middle book dragged through the mining-town chapters, but the finale pays everything off when the surveyor returns to the flooded valley and finally reads her grandmother's letters.",
+        "2026-06-08T09:00:00.000Z",
+    ],
+    [
+        "fill_travel",
+        "Train trip through the coastal towns in autumn: two nights in the fishing village with the breakwater walk, then the mountain line with the switchback tunnels. Pack the warm layer even when the departure platform is sunny.",
+        "2026-06-09T09:00:00.000Z",
+    ],
+    [
+        "fill_garden",
+        "The raised beds need refreshing before spring: compost the spent tomato vines, rotate the legume row to where the squash was, and prune the apple espalier before the buds swell.",
+        "2026-06-10T09:00:00.000Z",
+    ],
+    [
+        "fill_lang",
+        "Language study notes: the dative prepositions finally clicked after drilling them as a sung list. Irregular verbs still need spaced repetition; the flashcard app's new algorithm keeps resurfacing the ones I already know.",
+        "2026-06-21T09:00:00.000Z",
+    ],
+    [
+        "fill_music",
+        "Piano practice log: the Chopin nocturne's middle section is still uneven at tempo. Slow practice hands-separately for the polyrhythm bars, then glue the phrases at 80 percent speed before next week's lesson.",
+        "2026-06-22T09:00:00.000Z",
+    ],
+    [
+        "fill_car",
+        "Car maintenance records: switched the hatchback to the synthetic blend at the 90,000-kilometer service; the mechanic noted a slow weep on the rear shock that we watch for now instead of replacing immediately.",
+        "2026-06-23T09:00:00.000Z",
+    ],
+];
+/**
+ * Measured with the real bge-small-en-v1.5 embedder at fixture-authoring time
+ * (2026-09-12): cross-topic 0.625, conflict 0.993, chain v1-v2 0.788 (judged
+ * band), v2-v3 0.998 (zone band), paraphrase 0.985, facets 0.774; no
+ * non-ground-truth pair >= 0.70. Bands are set with margin around those
+ * values — the report re-measures and flags drift.
+ */
+exports.REAL_TEXT_CORPUS = {
+    rows: [
+        // --- old side (+ first filler block) ---
+        {
+            key: "xt_old",
+            content: "The analytics dashboard refreshes its data every 15 minutes through the scheduled ingestion job.",
+            createdAt: "2026-06-01T09:00:00.000Z",
+            memoryType: "knowledge",
+        },
+        {
+            key: "conflict_a",
+            content: "Per the provider's official pricing page, the vendor API rate limit is 60 requests per minute per account. " +
+                "Verified while sizing the sync worker retries; bursts above the limit return HTTP 429 with a Retry-After header.",
+            createdAt: "2026-06-02T09:00:00.000Z",
+            memoryType: "knowledge",
+        },
+        {
+            key: "chain_v1",
+            content: "Deployment strategy (decision record 14): all releases ship through the blue-green pipeline with an atomic " +
+                "traffic flip between two identical production environments. Rollback means flipping traffic back to the " +
+                "previous environment. Owner: platform team. Migration status: not started. Reviewed quarterly.",
+            createdAt: "2026-06-03T09:00:00.000Z",
+            memoryType: "decision",
+        },
+        {
+            key: "para_a",
+            content: "The team standup happens every weekday morning at 09:30 and never runs longer than fifteen minutes.",
+            createdAt: "2026-06-04T09:00:00.000Z",
+            memoryType: "knowledge",
+        },
+        {
+            key: "facet_a",
+            content: "The team wiki runs on a self-hosted instance behind the company VPN; only the ops group holds " +
+                "administrator rights on the wiki instance.",
+            createdAt: "2026-06-05T09:00:00.000Z",
+            memoryType: "knowledge",
+        },
+        ...FILLER.slice(0, 5).map(([key, content, createdAt]) => ({
+            key,
+            content,
+            createdAt,
+            memoryType: "experience",
+        })),
+        // --- new side (+ second filler block) ---
+        {
+            key: "xt_new",
+            content: "On-call shift recap: we chased a payment webhook outage for two hours; the root cause was a stale " +
+                "connection pool starving the workers under load. While verifying configs afterwards we also found the " +
+                "dashboard ingestion schedule quietly moved from every 15 minutes to hourly — the old 15-minute figure " +
+                "is outdated.",
+            createdAt: "2026-06-15T09:00:00.000Z",
+            memoryType: "experience",
+        },
+        {
+            key: "conflict_b",
+            content: "Per the provider's engineering wiki, the vendor API rate limit is 100 requests per minute per account. " +
+                "Verified while sizing the sync worker retries; bursts above the limit return HTTP 429 with a Retry-After header.",
+            createdAt: "2026-06-16T09:00:00.000Z",
+            memoryType: "knowledge",
+        },
+        {
+            key: "chain_v2",
+            content: "Deployment strategy (decision record 14): all releases now roll out through staged rollouts with automatic " +
+                "rollback on error-budget burn. Rollback means halting the rollout and reverting the release. " +
+                "Owner: platform team. Migration status: stage 2 of 4 complete. Reviewed quarterly.",
+            createdAt: "2026-06-17T09:00:00.000Z",
+            memoryType: "decision",
+        },
+        {
+            key: "chain_v3",
+            content: "Deployment strategy (decision record 14): all releases now roll out through staged rollouts with automatic " +
+                "rollback on error-budget burn. Rollback means halting the rollout and reverting the release. " +
+                "Owner: platform team. Migration status: stage 3 of 4 complete. Reviewed quarterly.",
+            createdAt: "2026-06-18T09:00:00.000Z",
+            memoryType: "decision",
+        },
+        {
+            key: "para_b",
+            content: "The team standup is every weekday at 09:30 in the morning; it never runs longer than fifteen minutes.",
+            createdAt: "2026-06-19T09:00:00.000Z",
+            memoryType: "knowledge",
+        },
+        {
+            key: "facet_b",
+            content: "The team wiki instance behind the company VPN is slow to load for read-only users because the " +
+                "self-hosted server has no page cache; ops plans to add one.",
+            createdAt: "2026-06-20T09:00:00.000Z",
+            memoryType: "knowledge",
+        },
+        ...FILLER.slice(5).map(([key, content, createdAt]) => ({
+            key,
+            content,
+            createdAt,
+            memoryType: "experience",
+        })),
+    ],
+    pairs: [
+        {
+            class: "cross_topic_correction",
+            olderKey: "xt_old",
+            newerKey: "xt_new",
+            relation: "corrects",
+            band: [0.4, 0.68],
+            rewritten: "The analytics dashboard refreshes its data hourly through the scheduled ingestion job; the refresh " +
+                "cadence was reduced from every 15 minutes during the June platform review.",
+            // xt_new says "the dashboard ingestion schedule ... moved from every 15
+            // minutes to hourly" — these five terms all appear verbatim in xt_old.
+            references: "dashboard ingestion every 15 minutes",
+        },
+        {
+            class: "source_conflict",
+            olderKey: "conflict_a",
+            newerKey: "conflict_b",
+            relation: "conflict",
+            band: [0.92, 1.0],
+            // conflict_b contradicts conflict_a on one quantity while sharing its
+            // whole context tail — every token appears verbatim in conflict_a (the
+            // guard-C fixture mechanism: the scout's FTS finds the old record, the
+            // re-tag rule lets the judge see a >=0.92 pair).
+            references: "vendor API rate limit requests per minute per account",
+        },
+        {
+            class: "version_chain",
+            olderKey: "chain_v1",
+            newerKey: "chain_v2",
+            relation: "supersedes",
+            band: [0.75, 0.91],
+            references: "deployment strategy decision record 14",
+        },
+        {
+            class: "version_chain",
+            olderKey: "chain_v2",
+            newerKey: "chain_v3",
+            relation: "supersedes",
+            band: [0.92, 1.0],
+            references: "deployment strategy decision record 14",
+        },
+        {
+            class: "version_chain",
+            olderKey: "chain_v1",
+            newerKey: "chain_v3",
+            relation: "supersedes",
+            band: [0.75, 0.91],
+            references: "deployment strategy decision record 14",
+        },
+        {
+            class: "same_fact_paraphrase",
+            olderKey: "para_a",
+            newerKey: "para_b",
+            relation: "merge",
+            band: [0.9, 1.0],
+        },
+        {
+            class: "complementary_facets",
+            olderKey: "facet_a",
+            newerKey: "facet_b",
+            relation: "none",
+            band: [0.7, 0.9],
+        },
+    ],
+};
+/**
+ * The version_chain class is measured BOTH per-pair and as a class: the
+ * desired end state is the chain's TERMINAL (newest member) live with every
+ * non-terminal demoted or absorbed. Members are derived from the declared
+ * pairs, ordered by createdAt.
+ */
+function chainMembers(corpus) {
+    const members = new Set();
+    for (const p of corpus.pairs) {
+        if (p.class !== "version_chain")
+            continue;
+        members.add(p.olderKey);
+        members.add(p.newerKey);
+    }
+    const byKey = new Map(corpus.rows.map((r) => [r.key, r]));
+    return [...members].sort((a, b) => {
+        const ra = byKey.get(a);
+        const rb = byKey.get(b);
+        const ca = ra?.createdAt ?? "";
+        const cb = rb?.createdAt ?? "";
+        return ca === cb ? a.localeCompare(b) : ca.localeCompare(cb);
+    });
+}

package/dist/eval/planted-harness.d.ts

@@ -0,0 +1,176 @@
+/**
+ * The planted-pairs acceptance gate (#393 increment A) — machinery shared by
+ * the CLI runner (planted-eval.ts, REAL embedder + real-text corpus) and the
+ * vitest suite (tests/planted-pairs.test.ts, controlled synthetic vectors).
+ *
+ * What it measures, per planted pair, before/after running the REAL
+ * production resolution stage (`stageReconsolidation`, which internally runs
+ * the deterministic merge zone LAST — guard-C: judgment outranks the sweep):
+ *
+ *   DETECTED — the pair entered the resolution machinery as a candidate: a
+ *     verdict call was made on it (judged band, logged by the ground-truth
+ *     judge) OR it co-clustered in the pre-stage `planDedup` discovery at the
+ *     zone ceiling. Tagged by source ("judge" = KNN/similarity, "scout" = the
+ *     #393 B reference-extraction source — attribution rule: a verdict call
+ *     on a below-floor pair can only be scout-sourced, "zone" = the
+ *     deterministic ceiling).
+ *   BOUND — a resolution structure reflecting the ground truth now connects
+ *     the pair: `corrected_by` / `superseded_by` / `conflicts` link, or a
+ *     merge (`dedup_log` row). Guard-C added the `conflicts` bind (the judge
+ *     flags a genuine conflict instead of leaving it inexpressible).
+ *   RESOLVED — the class-specific desired END STATE holds in the store:
+ *     corrects  = correction effective (older demoted/absorbed/rewritten) and
+ *                 the correction information live;
+ *     supersedes= older demoted-or-absorbed and newer live in recall;
+ *     merge     = exactly one live row remains, the other absorbed via dedup;
+ *     conflict  = both live AND not blended AND the conflicts link exists
+ *                 (guard-C's end state — the consumer sees both truths);
+ *     none      = both live, not blended, no resolution link between them.
+ *
+ * The version_chain CLASS end-state is measured on the RECALL surface, not
+ * the store (#393 D): a retrieval-only change cannot move a store probe, so
+ * post-stage the harness runs the production retrieve() (read-only: limit 3,
+ * below the cold-exposure threshold, noStrengthen) with the OLDEST chain
+ * member's content as query and requires the belief walk's guarantee — no
+ * superseded ancestor surfaces as a competing truth, and the linked chain's
+ * terminal surfaces. Store facts (terminal live, non-terminals gone) remain
+ * in the class note as corroboration.
+ *
+ * The judge is a GROUND-TRUTH-STUBBED LlmClient (the refine addendum's Q3
+ * recommendation): it answers each planted pair's declared relation and
+ * defaults unknown/collider pairs to `none`. This isolates the MACHINERY
+ * (detection sources, binding actions, merge guard, walk) from judge quality —
+ * the harness answers "would the pipeline resolve a KNOWN correction if the
+ * judge were perfect?". Live-LLM verdict quality is the real-corpus soak run.
+ *
+ * Read/write discipline: the gate NEVER touches ~/.hicortex — the fixture DB
+ * and the stage's stateDir are caller-supplied (temp) paths. A real snapshot
+ * is only ever PLANTED INTO A COPY (planted-eval.ts --snapshot).
+ */
+import type Database from "better-sqlite3";
+import type { LlmClient } from "../llm.js";
+import { type EmbedFn } from "../retrieval.js";
+import type { acquireCaptureLock } from "../capture.js";
+import { type ReconsolidationStageResult } from "../reconsolidation.js";
+import { type PlanDedupResult } from "../dedup.js";
+import { type PlantedCorpus, type FixtureClass, type GroundTruthRelation } from "./planted-fixtures.js";
+/** Insert the corpus into a writable DB (fresh, or a copy of a snapshot). */
+export declare function plantCorpus(db: Database.Database, corpus: PlantedCorpus, embedFn: EmbedFn): Promise<Map<string, string>>;
+export interface VerdictCall {
+    olderKey: string;
+    newerKey: string;
+    /** True when the pair matched a declared ground-truth pair; false = default-none fallback. */
+    grounded: boolean;
+}
+export interface RewriteCall {
+    targetKey: string;
+    triggerKeys: string[];
+}
+/** A scout correction-shape call (#393 B) on one memory, ground-truth answered. */
+export interface ScoutCall {
+    key: string;
+    correction: boolean;
+}
+export interface GroundTruthJudge {
+    llm: LlmClient;
+    verdictCalls: VerdictCall[];
+    rewriteCalls: RewriteCall[];
+    scoutCalls: ScoutCall[];
+}
+/**
+ * Deterministic, ground-truth-keyed judge. Parses each prompt back into its
+ * (older, newer) contents — the exact texts `buildCorrectionVerdictPrompt` /
+ * `buildRewritePrompt` embed — and answers from the corpus's declared
+ * relations:
+ *   corrects  -> {"action":"corrects","confidence":0.95}   (above the gate)
+ *   supersedes-> {"action":"supersedes","confidence":0.9}
+ *   merge     -> {"action":"merge","confidence":0.95}      (above the gate)
+ *   conflict  -> {"action":"conflicts","confidence":0.9}   (guard-C: flag,
+ *                both live, never blended)
+ *   none      -> {"action":"none","confidence":0.9}
+ * Unknown pairs (colliders, filler cross-pairs) default to none.
+ *
+ * #393 B: the judge also answers the scout's per-memory shape calls — a
+ * memory is correction-shaped iff it is the newer side of a declared
+ * corrects/supersedes/conflict pair (declared `references` returned verbatim,
+ * throwing if a resolution-shaped pair never declared them; guard-C added
+ * `conflict` to the shaped set — two records disagreeing on one quantity
+ * share their wording); everything else answers correction=false. Shape calls
+ * are logged in scoutCalls.
+ */
+export declare function makeGroundTruthJudge(corpus: PlantedCorpus, idByKey: Map<string, string>): GroundTruthJudge;
+export interface PlantedPairResult {
+    class: FixtureClass;
+    olderKey: string;
+    newerKey: string;
+    relation: GroundTruthRelation;
+    cosine: number;
+    inBand: boolean;
+    detected: boolean;
+    /**
+     * Which source(s) made the pair a candidate: "judge" (verdict call via the
+     * KNN similarity source), "scout" (verdict call on a BELOW-floor pair — only
+     * the scout can source one; #393 B), "zone" (co-clustered at the ceiling).
+     * In-band pairs the KNN source could have found are attributed "judge" even
+     * when the scout also found them — the attribution answers "what made this
+     * pair reachable", and for in-band pairs that is the similarity floor.
+     */
+    detectionSource: "" | "judge" | "zone" | "judge+zone" | "scout" | "scout+zone";
+    bound: boolean | null;
+    boundHow: string;
+    resolved: boolean;
+    notes: string;
+}
+export interface PlantedClassResult {
+    class: FixtureClass;
+    pairs: number;
+    detected: number;
+    bound: number;
+    resolved: number;
+    /** Class-level end state (version_chain: terminal live + non-terminals gone). */
+    classResolved: boolean;
+    notes: string;
+}
+export interface ColliderRow {
+    aKey: string;
+    bKey: string;
+    cosine: number;
+    verdictCalled: boolean;
+    merged: boolean;
+    bothLive: boolean;
+}
+export interface PlantedGateResult {
+    pairResults: PlantedPairResult[];
+    classResults: PlantedClassResult[];
+    colliders: ColliderRow[];
+    stageReport: ReconsolidationStageResult;
+    zonePlanBefore: PlanDedupResult;
+    /** Pre-run zone-blend predictions: ground-truth pair -> surviving (canonical) key. */
+    blendPredictions: Array<{
+        pair: string;
+        canonicalKey: string;
+        loserKey: string;
+    }>;
+}
+export interface PlantedGateOptions {
+    /** Writable fixture DB path — created fresh, or a snapshot COPY to plant into. */
+    dbPath: string;
+    /** Temp state dir for the stage (state.json cursor, backups, band stats). */
+    stateDir: string;
+    embedFn: EmbedFn;
+    /** Lock acquirer for the zone/merge windows. Default: always-acquire (hermetic). */
+    acquireLock?: typeof acquireCaptureLock;
+    /** Zone ceiling. Default: the production default (0.92). */
+    threshold?: number;
+}
+/**
+ * Build (or plant into) the DB, run the production stage, measure the gate.
+ * This is the ONE orchestration shared by the CLI runner and the vitest suite.
+ */
+export declare function runPlantedGate(corpus: PlantedCorpus, opts: PlantedGateOptions): Promise<PlantedGateResult>;
+export declare function renderPlantedReport(args: {
+    corpusLabel: string;
+    generatedAt: string;
+    embedderLabel: string;
+    result: PlantedGateResult;
+}): string;