@gamaze/hicortex 0.16.0 → 0.16.2

package/README.md

@@ -164,6 +164,7 @@ npx @gamaze/hicortex context edit <name>       # Edit a context section in $EDIT
 npx @gamaze/hicortex context show --agent <id> # Show a specific agent's resolved context (0.13)
 npx @gamaze/hicortex init --agent-name <name>  # Opt in to a per-agent context id (default: unset — shared global context)
 npx @gamaze/hicortex init --agent-name ""      # Clear it back to global context
+npx @gamaze/hicortex init --repair-config      # Recover from a malformed config.json (see below)
 npx @gamaze/hicortex telemetry                 # Show exactly what anonymous telemetry sends
 npx @gamaze/hicortex status                    # Show config, DB stats
 npx @gamaze/hicortex uninstall                 # Remove CC integration (keeps DB)
@@ -226,6 +227,7 @@ Config at `~/.hicortex/config.json`. Created by `init`. Key options:
 | `recallMinSimilarity` | Relevance floor for index entries (default: 0.55; text-search matches always pass) |
 | `recallReshowTurns` | Turns before an already-shown memory may reappear in the same session (default: 30) |
 | `recallMinPromptChars` | Prompts shorter than this skip the recall index (default: 20) |
+| `recallTitleChars` | Chars of each memory's first line shown in an index entry (default: 150, range 40–400). Raised from 100 on 2026-08-02: with topic-first memory titles, 150 chars carries the subject *and* its claim, where 100 cut the claim mid-sentence. Costs roughly +74 tokens per 6-line block |
 | `sessionIntentWeight` | Blend weight of the session-intent rolling centroid in the recall search vector: `query = (1-w)·prompt + w·centroid` (default: 0.33; set 0 to disable — pure-prompt recall, the kill-switch). The first turn of a session searches with pure prompt and seeds the centroid; subsequent turns blend so recall follows the session's intent instead of being query-literal. The EMA rate (0.4) is a shipped constant, not configurable |
 | `dedupMergeThreshold` | Minimum cosine similarity for `hicortex dedup` to cluster memories as near-duplicates (default: 0.92) |
 | `supersessionMinSimilarity` | Minimum cosine similarity for a nightly supersession candidate pair (default: 0.80) |
@@ -329,6 +331,13 @@ npm test
 
 ## Troubleshooting
 
+**`init` fails with "Refusing to write ~/.hicortex/config.json":** the file exists but is not valid JSON — usually a hand-edit slip (a trailing comma, a truncated write). `init` refuses rather than overwriting it, because overwriting would lose `authToken`, `licenseKey`, `distillApiKey`, and your `domains` list. Two ways out:
+
+1. **Preferred — fix the JSON.** The error names the parse failure and its position. Correct it and re-run `init`. Nothing is lost.
+2. **`npx @gamaze/hicortex init --repair-config`.** Moves the broken file to `config.json.corrupt-<timestamp>` and rebuilds from scratch. Nothing is deleted, and it prints the top-level key names it found (names only — never secret values) so you know what to copy back. **This mints a new `authToken`**, so every thin client pointing at this server must be updated or its recall will silently 401 (recall is fail-soft — you will see no error, just no memories).
+
+The nightly and the server behave differently on purpose: a malformed config makes them log a warning and run degraded rather than refuse to start, so a broken config never takes recall offline.
+
 **Tools not visible to agent (OC):** The plugin auto-adds tools to `tools.allow` on startup. Restart the gateway after install.
 
 **OC plugin: "Server unreachable":** The plugin requires a running Hicortex server. Run `npx @gamaze/hicortex init` on the same machine, or set `serverUrl` in the plugin config to point at a remote server.

package/dist/capture.d.ts

@@ -52,11 +52,17 @@ export interface Segment {
 export interface DistillBody {
     text: string;
     source_agent: string;
+    /** Stable client UUID (config.json `agentId`). Attribution only. */
+    source_agent_id?: string | null;
+    /** Client-declared topic/domain of the capturing agent. Provenance only. */
+    source_domain?: string | null;
     project: string;
     session_id: string;
     segment_id: string;
     session_date: string;
-    privacy: string;
+    /** 0.16.x: optional/vestigial. The distiller no longer sets it; a legacy
+     *  client may. Honored if present, else the memory stores NULL. */
+    privacy?: string;
 }
 /** Normalized POST result the caller's transport returns. */
 export interface PostResult {
@@ -73,6 +79,17 @@ export interface CaptureOptions {
     dryRun?: boolean;
     /** Segment size cap; defaults to SEGMENT_MAX_CHARS. Lowered in tests. */
     segmentMaxChars?: number;
+    /**
+     * Per-client attribution UUID (config.json `agentId`). Sent on every
+     * segment as `source_agent_id`. Null when the client has no `agentId`
+     * (e.g. a pre-0.16.x config that has not re-run init).
+     */
+    sourceAgentId?: string | null;
+    /**
+     * Per-client declared topic/domain (config.json `sourceDomain`). Sent as
+     * `source_domain` provenance. Null when undeclared.
+     */
+    sourceDomain?: string | null;
 }
 export interface CaptureResult {
     memoriesIngested: number;

package/dist/capture.js

@@ -134,7 +134,7 @@ function packSegments(entries, startCursor, entryCursors, maxChars = exports.SEG
  * boundary) while other sessions continue. A 429/401 stops the whole loop.
  */
 async function captureBatches(batches, opts) {
-    const { post, cursorStore, dryRun = false, segmentMaxChars = exports.SEGMENT_MAX_CHARS } = opts;
+    const { post, cursorStore, dryRun = false, segmentMaxChars = exports.SEGMENT_MAX_CHARS, sourceAgentId, sourceDomain } = opts;
     let memoriesIngested = 0;
     let sessionsSent = 0;
     let hadTransientFailure = false;
@@ -186,11 +186,12 @@ async function captureBatches(batches, opts) {
             const body = {
                 text: seg.text,
                 source_agent: batch.sourceAgent ?? `claude-code/${batch.projectName}`,
+                source_agent_id: sourceAgentId ?? null,
+                source_domain: sourceDomain ?? null,
                 project: batch.projectName,
                 session_id: batch.sessionId,
                 segment_id: `${genPrefix}${seg.segStart}-${seg.segEnd}${seg.idSuffix}`,
                 session_date: batch.date,
-                privacy: "WORK",
             };
             let result;
             try {

package/dist/classify-domains.d.ts

@@ -16,7 +16,7 @@
  *     reflect tier), same as the nightly. The LLM emits ONLY the ordered tag
  *     set; per-tag weights come from the domain prototypes (computed once at
  *     run start) and the PRIMARY (memories.domain) is derived (argmax weight,
- *     compartment override, LLM order breaking ties) inside
+ *     LLM order breaking ties) inside
  *     storage.setMemoryTags. After a completed (non-aborted) run the
  *     prototypes, all weights, and all primaries are recomputed from the
  *     final tag sets — same reconsolidation pass as the nightly.

package/dist/classify-domains.js

@@ -17,7 +17,7 @@
  *     reflect tier), same as the nightly. The LLM emits ONLY the ordered tag
  *     set; per-tag weights come from the domain prototypes (computed once at
  *     run start) and the PRIMARY (memories.domain) is derived (argmax weight,
- *     compartment override, LLM order breaking ties) inside
+ *     LLM order breaking ties) inside
  *     storage.setMemoryTags. After a completed (non-aborted) run the
  *     prototypes, all weights, and all primaries are recomputed from the
  *     final tag sets — same reconsolidation pass as the nightly.
@@ -195,7 +195,6 @@ async function runClassifyDomains(options = {}) {
         // Prototypes once at run start — newly classified memories get their
         // weights from these; the post-run reconsolidation pass refreshes
         // everything from the final tag sets.
-        const compartments = (0, schema_prototypes_js_1.compartmentSet)(domains);
         const { prototypes } = await (0, schema_prototypes_js_1.computeDomainPrototypes)(db, domains, getEmbedFn);
         // Scope filter: default = NULL / not-in-set / no tags yet; --all = everything.
         const placeholders = domains.map(() => "?").join(", ");
@@ -255,10 +254,9 @@ async function runClassifyDomains(options = {}) {
                     continue;
                 }
                 // Derived primary (argmax weight from the run-start prototypes,
-                // compartment override, LLM order breaking ties) — the same value
-                // setMemoryTags will write below.
+                // LLM order breaking ties) — the same value setMemoryTags writes below.
                 const weights = (0, schema_prototypes_js_1.computeTagWeights)(db, row.id, result.tags, prototypes);
-                const derived = (0, schema_prototypes_js_1.derivePrimary)(result.tags.map((tag) => ({ tag, weight: weights[tag] ?? null })), compartments);
+                const derived = (0, schema_prototypes_js_1.derivePrimary)(result.tags.map((tag) => ({ tag, weight: weights[tag] ?? null })));
                 if (derived === row.domain) {
                     batchUnchanged++;
                 }
@@ -273,10 +271,10 @@ async function runClassifyDomains(options = {}) {
             const tx = db.transaction(() => {
                 for (const w of writes) {
                     if (w.kind === "tags") {
-                        storage.setMemoryTags(db, w.id, w.tags, { weights: w.weights, compartments });
+                        storage.setMemoryTags(db, w.id, w.tags, { weights: w.weights });
                     }
                     else if (w.resolution.kind === "weak_primary") {
-                        (0, nofit_js_1.applyWeakPrimary)(db, w.id, w.resolution.domain, w.resolution.weight, compartments);
+                        (0, nofit_js_1.applyWeakPrimary)(db, w.id, w.resolution.domain, w.resolution.weight);
                     }
                     else {
                         (0, nofit_js_1.applyNoAssociationDecay)(db, w.id);

package/dist/cli.js

@@ -43,9 +43,14 @@ switch (command) {
             console.error("[hicortex] init: --agent-name requires a value, e.g. --agent-name lenovo");
             process.exit(1);
         }
+        const repairConfig = process.argv.includes("--repair-config");
         import("./init.js").then(({ runInit }) => {
-            runInit({ serverUrl, agentName }).catch((err) => {
-                console.error("[hicortex] Init failed:", err);
+            runInit({ serverUrl, agentName, repairConfig }).catch((err) => {
+                // Operator-fixable failures (a malformed config.json) carry a complete,
+                // actionable message — print that alone. A stack trace would bury it.
+                // Anything else is a real bug and gets the full error object.
+                const operatorFixable = err instanceof Error && /^Refusing to (read|write) /.test(err.message);
+                console.error("[hicortex] Init failed:", operatorFixable ? err.message : err);
                 process.exit(1);
             });
         });
@@ -250,6 +255,9 @@ Commands:
   init --server <url>  Set up as client (remote server)
   init --agent-name <name>  Opt in to a per-agent context id (default: unset — shared global context)
                             Pass --agent-name "" to clear it back to global
+  init --repair-config  Recover from a malformed ~/.hicortex/config.json: move it to
+                        config.json.corrupt-<timestamp> and rebuild. Nothing is deleted.
+                        Mints a NEW authToken — every thin client must be updated.
   nightly         Run nightly denoise + capture + consolidate
   relink          Resumable link-discovery pass over the ENTIRE corpus (server mode)
   dedup           Cluster + merge near-duplicate memories (server mode; dry run by default)

package/dist/cluster.d.ts

@@ -25,18 +25,19 @@ export declare class UnionFind {
 export declare function clusterEdges(edges: Edge[], threshold: number): string[][];
 /** Excess = sum(cluster size − 1) — rows that would disappear if every cluster merged to one. */
 export declare function clusterExcess(clusters: string[][]): number;
-/** The three metadata fields a merge candidate cluster must agree on. */
+/** Metadata fields a merge candidate cluster must agree on. `privacy` is on the row (the
+ *  column still exists) but is NOT a merge-safety field — vestigial since 0.16.2. */
 export interface ClusterMetaRow {
     project: string | null;
-    privacy: string;
+    privacy: string | null;
     source_agent: string;
 }
 export interface ClusterMetadataMismatch {
     projectMismatch: boolean;
-    privacyMismatch: boolean;
     sourceAgentMismatch: boolean;
 }
-/** Do cluster members disagree on project/privacy/source_agent? (merge-safety input for #100). */
+/** Do cluster members disagree on project / source_agent? (merge-safety input for #100).
+ *  Privacy is intentionally NOT checked — it is vestigial since 0.16.2. */
 export declare function clusterMetadataMismatch(members: ClusterMetaRow[]): ClusterMetadataMismatch;
 /**
  * Build the max-cosine edge set via top-K KNN on `memory_vectors`, keeping

package/dist/cluster.js

@@ -69,14 +69,13 @@ function clusterEdges(edges, threshold) {
 function clusterExcess(clusters) {
     return clusters.reduce((sum, c) => sum + (c.length - 1), 0);
 }
-/** Do cluster members disagree on project/privacy/source_agent? (merge-safety input for #100). */
+/** Do cluster members disagree on project / source_agent? (merge-safety input for #100).
+ *  Privacy is intentionally NOT checked — it is vestigial since 0.16.2. */
 function clusterMetadataMismatch(members) {
     const projects = new Set(members.map((m) => m.project ?? "\u0000null"));
-    const privacies = new Set(members.map((m) => m.privacy));
     const agents = new Set(members.map((m) => m.source_agent));
     return {
         projectMismatch: projects.size > 1,
-        privacyMismatch: privacies.size > 1,
         sourceAgentMismatch: agents.size > 1,
     };
 }

package/dist/consolidate.js

@@ -307,7 +307,10 @@ async function stageReflection(db, memories, llm, budget, embedFn, dryRun) {
             const severity = String(lo.severity ?? "important");
             const confidence = String(lo.confidence ?? "medium");
             const sourcePattern = String(lo.source_pattern ?? "");
-            let content = `## Lesson: ${lessonText}\n\n`;
+            // No `## Lesson:` prefix: memory_type='lesson' carries the type, and the
+            // text is the topic-first first line (display reads the first line, not a
+            // header parse — see lessons-context.ts / index.ts).
+            let content = `${lessonText}\n\n`;
             content += `**Type:** ${lessonType}\n`;
             content += `**Severity:** ${severity}\n`;
             content += `**Confidence:** ${confidence}\n`;
@@ -353,7 +356,6 @@ async function stageReflection(db, memories, llm, budget, embedFn, dryRun) {
                         project,
                         memoryType: "lesson",
                         baseStrength: baseStrength[severity] ?? 0.8,
-                        privacy: "WORK",
                     });
                     generated++;
                 }
@@ -433,7 +435,6 @@ async function stageContentDomains(db, domains, llm, budget, embedFn, dryRun, st
         return { curated: false, domains: domains.length, classified: 0, reason: `dry_run (${rows.length} would classify)` };
     }
     const getEmbedFn = async () => embedFn;
-    const compartments = (0, schema_prototypes_js_1.compartmentSet)(domains);
     let classified = 0;
     let weakPrimary = 0;
     let noAssociationDecayed = 0;
@@ -462,7 +463,7 @@ async function stageContentDomains(db, domains, llm, budget, embedFn, dryRun, st
                 // double-halves.
                 const resolution = (0, nofit_js_1.resolveNoFit)(db, row.id, domains, startPrototypes, weakPrimaryFloor);
                 if (resolution.kind === "weak_primary") {
-                    (0, nofit_js_1.applyWeakPrimary)(db, row.id, resolution.domain, resolution.weight, compartments);
+                    (0, nofit_js_1.applyWeakPrimary)(db, row.id, resolution.domain, resolution.weight);
                     weakPrimary++;
                 }
                 else {
@@ -472,7 +473,7 @@ async function stageContentDomains(db, domains, llm, budget, embedFn, dryRun, st
                 continue;
             }
             const weights = (0, schema_prototypes_js_1.computeTagWeights)(db, row.id, result.tags, startPrototypes);
-            storage.setMemoryTags(db, row.id, result.tags, { weights, compartments });
+            storage.setMemoryTags(db, row.id, result.tags, { weights });
             classified++;
         }
     }

package/dist/db.js

@@ -441,6 +441,29 @@ const MIGRATIONS = [
       `);
         },
     },
+    {
+        version: 11,
+        name: "add_source_attribution",
+        up: (db) => {
+            // 0.16.x attribution + provenance. Two nullable columns on `memories`,
+            // both populated ONLY by capture (/distill) from client-declared values;
+            // nothing filters, scopes, or scores on either (attribution + echo).
+            //
+            // `source_agent_id`: the capturing client's stable UUID (config.json
+            //   `agentId`, generated once by init). Survives agent/machine renames
+            //   — unlike `source_agent`, a readable name. NULL on legacy rows.
+            // `source_domain`: the client-declared topic/domain of the capturing
+            //   agent (config.json `domain`). Distinct from the content-classified
+            //   `domain` column (which stays the LLM/prototype-derived primary).
+            // Guarded with hasColumn for idempotency across partially-migrated DBs.
+            if (!hasColumn(db, "memories", "source_agent_id")) {
+                db.exec("ALTER TABLE memories ADD COLUMN source_agent_id TEXT");
+            }
+            if (!hasColumn(db, "memories", "source_domain")) {
+                db.exec("ALTER TABLE memories ADD COLUMN source_domain TEXT");
+            }
+        },
+    },
 ];
 /**
  * Run all pending migrations against the database.

package/dist/dedup.js

@@ -287,7 +287,7 @@ async function runDedup(options = {}) {
             if (members.length < 2)
                 continue; // defensive — a member vanished between KNN and load
             const mismatch = (0, cluster_js_1.clusterMetadataMismatch)(members);
-            if (mismatch.projectMismatch || mismatch.privacyMismatch || mismatch.sourceAgentMismatch) {
+            if (mismatch.projectMismatch || mismatch.sourceAgentMismatch) {
                 mismatchSkipped.push({ size: members.length, memberIds: members.map((m) => m.id), mismatch });
                 continue;
             }

package/dist/distiller.js

@@ -314,6 +314,14 @@ async function distillChunk(llm, transcript, projectName, date) {
         return { entries: [], dropped: [] };
     }
     const parsed = parseDistilledEntries(result);
+    // Smoke alarm (PR #218 review): the prompt enforces topic-first, but models
+    // sometimes ignore constraints (cf. the prior max-15-bullet failure). Count
+    // entries that still look actor-led or bracket-led so a format regression
+    // shows in nightly logs, not months later in the next eval. Non-blocking.
+    const offTopic = parsed.filter((e) => /^\s*(user|ai|the user|assistant)\b/i.test(e) || /^\s*\[/.test(e)).length;
+    if (parsed.length > 0 && offTopic > 0) {
+        console.log(`[hicortex]     topic-first check: ${offTopic}/${parsed.length} entries look actor/bracket-led (prompt may be ignored)`);
+    }
     const entries = [];
     const dropped = [];
     for (const entry of parsed) {
@@ -409,23 +417,22 @@ function hasMinimalSubstance(entry) {
 function parseDistilledEntries(markdown) {
     const entries = [];
     const lines = markdown.split("\n");
-    let currentSection = "";
     for (const line of lines) {
         const trimmed = line.trim();
-        // Section headers
-        if (trimmed.startsWith("### ")) {
-            currentSection = trimmed.slice(4).trim();
+        // Skip all markdown headers (session title, section headings). Sections
+        // are NOT prefixed onto entries: each bullet already
+        // starts with its [SUBJECT] (topic-first, enforced by prompts.ts), and
+        // prepending "[Section]" re-introduced the category-first prefix the
+        // 2026-08-02 corpus rewrite removed. The section label is unused
+        // downstream (distilled memories all store memory_type='episode').
+        if (trimmed.startsWith("# ") ||
+            trimmed.startsWith("## ") ||
+            trimmed.startsWith("### ")) {
             continue;
         }
-        // Skip top-level headers and classification
-        if (trimmed.startsWith("# ") || trimmed.startsWith("## "))
-            continue;
-        // Bullet items are individual memories
+        // Bullet items are individual, already topic-first memories.
         if (trimmed.startsWith("- ") && trimmed.length > 5) {
-            const entry = currentSection
-                ? `[${currentSection}] ${trimmed.slice(2)}`
-                : trimmed.slice(2);
-            entries.push(entry);
+            entries.push(trimmed.slice(2));
         }
     }
     return entries;

package/dist/domain-classify.d.ts

@@ -18,7 +18,7 @@
  *     (the order is used solely as an exact-weight tiebreak downstream).
  * The PRIMARY (memories.domain) is NO LONGER requested from the LLM — audits
  * proved LLM primaries a coin-flip on overlapping spheres. It is DERIVED
- * deterministically (argmax association weight + compartment override) in
+ * deterministically (argmax association weight, LLM tag order breaking ties) in
  * schema-prototypes.ts / storage.setMemoryTags.
  *
  * NO-FIT = EMPTY TAG SET (owner amendment 07.07): "Unsorted" is a non-tag —

package/dist/domain-classify.js

@@ -19,7 +19,7 @@
  *     (the order is used solely as an exact-weight tiebreak downstream).
  * The PRIMARY (memories.domain) is NO LONGER requested from the LLM — audits
  * proved LLM primaries a coin-flip on overlapping spheres. It is DERIVED
- * deterministically (argmax association weight + compartment override) in
+ * deterministically (argmax association weight, LLM tag order breaking ties) in
  * schema-prototypes.ts / storage.setMemoryTags.
  *
  * NO-FIT = EMPTY TAG SET (owner amendment 07.07): "Unsorted" is a non-tag —
@@ -84,10 +84,6 @@ function parseConfigDomains(config) {
         if (!name)
             continue;
         const def = { name, description };
-        // Compartment policy passthrough (graded-schema spec): a domain flagged
-        // `compartment: true` becomes the primary whenever tagged.
-        if (d.compartment === true)
-            def.compartment = true;
         out.push(def);
     }
     return out.length > 0 ? out : null;

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

@@ -0,0 +1,64 @@
+#!/usr/bin/env node
+/**
+ * Real-query relevance + SNIPPET eval — recall QUALITY on real agent prompts.
+ *
+ * v2 (spec `specs/2026-08-02-relevance-eval.md`) extends the v1 selection-only
+ * eval with the SNIPPET layer: v1 asked "did retrieve() surface the right
+ * memories?" (judge sees up to 2000 chars). Production shows the agent only a
+ * ~100-char one-liner (`recall-index.ts#memoryTitle`), so a memory can be
+ * genuinely relevant while its rendered line is useless — v1 scored that as a
+ * win. v2 grades BOTH: `full_verdict` (selection quality, judge sees full
+ * content) and `line_verdict` (snippet quality, judge sees ONLY the rendered
+ * production one-liner — imported from `recall-index.ts`, never reimplemented).
+ *
+ * v2 additions (spec §4, §5, §6, §6b) layered onto the v1 base (prompt
+ * sampling, readonly snapshot handling, embed-once + neverCalledEmbed,
+ * lenient JSON parse, distribution/CI reporting):
+ *   1. Dual verdict per surfaced memory — TWO separate, blind judge calls.
+ *   2. Snippet-length sweep (100/200/300/title+1st-sentence) on a fixed
+ *      40-prompt subset (8 per source).
+ *   3. Similarity-floor + retrieval-source analysis (near-free — logged, not
+ *      re-judged).
+ *   4. Token-cost estimate (char/4) per K and per snippet-length variant.
+ *   5. ~20 rendered ACTUAL production blocks dumped into the report.
+ *   6. Redundancy — one set-level judge call per (prompt × mode) over the
+ *      production 6.
+ *   7. Rate limiting + resumability (§6b, MANDATORY): serial calls,
+ *      `--judge-delay-ms` (default 2000), exponential backoff with jitter on
+ *      429/5xx/timeout (5→10→20→40→80s, max 5 retries, respects
+ *      `Retry-After`), checkpoint-per-call to a `.jsonl` sidecar, `--resume`,
+ *      progress logging, 10%-error-rate abort, `--max-calls` budget guard
+ *      (default 900).
+ *
+ * Prompt corpus (spec §2, owner decision §11.1): EVEN split, 20 prompts per
+ * source × 5 sources — Hermes (lenny, raider, nano) + CC (the DevOps
+ * `infrastructure` project, the `aironic-marine` project). Saved to
+ * `data/prompts.json`, stable/reused verbatim once a valid v2 set exists.
+ *
+ * Judge: GLM-5.2 via z.ai — the INSTRUMENT only. It never picks candidates;
+ * retrieve() (LLM-free) does. A dedicated raw HTTP caller (NOT `LlmClient`) is
+ * used here on purpose: `LlmClient.completeReflect` bakes in a
+ * nightly-tolerant retry policy (30s/60s/120s, unlimited rate-limit patience)
+ * that conflicts with §6b's specific real-time batch policy (5/10/20/40/80s +
+ * jitter, 5 retries, a hard call budget). Implemented directly here rather
+ * than adding a second retry mode to `llm.ts` (out of scope for this eval,
+ * and another agent is concurrently working elsewhere in this repo).
+ *
+ * Honesty invariants (non-negotiable — mirror recall-sweep.ts + spec §7):
+ *   - Snapshot opened READONLY via openSnapshot — never initDb.
+ *   - noStrengthen: true on every retrieve() call.
+ *   - Real bge-small-en-v1.5 embedder, embed-once + queryEmbedding reuse.
+ *   - neverCalledEmbed self-check ABORTS the run if retrieve() ignores
+ *     queryEmbedding (would invalidate every measured number).
+ *   - GLM-5.2 is the JUDGE only, real prompts, no synthetic queries.
+ *   - Production renderer (`formatIndexLine`/`memoryTitle`) imported from
+ *     `recall-index.ts`, never reimplemented.
+ *   - judge_error batches/units excluded from every denominator, reported
+ *     separately.
+ *
+ * Run:
+ *   npm run eval:relevance -- <snapshot.db> [prompts.json] [report.md] \
+ *       [--judge-delay-ms=2000] [--max-calls=900] [--resume] \
+ *       [--verdicts-json=path] [--verdicts-jsonl=path]
+ */
+export {};