@gamaze/hicortex 0.23.1 → 0.24.0

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

@@ -1,183 +0,0 @@
-/**
- * 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;
-    /** #458: the pinned clock for the recall-surface retrieve() (undefined =
-     *  live). Fixtures keep their absolute createdAt strings — only the
-     *  scoring instant is pinned. */
-    now?: Date;
-}
-/**
- * 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;
-    /** #458: clock-mode label ("pinned <ISO>" | "live") — the instant the
-     *  recall-surface retrieve() scored against. */
-    clock: string;
-    result: PlantedGateResult;
-}): string;