@aperdomoll90/ledger-ai 1.4.0 → 1.4.2

package/dist/lib/domains.js

@@ -0,0 +1,116 @@
+// --- Domain Model ---
+// Pure functions for domain, protection, type validation, and v1→v2 migration.
+// No Supabase dependency — fully unit testable.
+// --- Domain → Types mapping ---
+export const DOMAIN_TYPES = {
+    persona: ['personality', 'behavioral-rule', 'preference', 'skill', 'claude-md', 'hook', 'plugin-config'],
+    system: ['hook', 'plugin-config', 'type-registry', 'sync-rule', 'skill'],
+    workspace: ['dashboard', 'device-registry', 'environment', 'eval-result', 'skill', 'hook', 'plugin-config'],
+    project: ['architecture', 'project-status', 'event', 'error', 'reference', 'knowledge', 'skill', 'eval-result'],
+    general: ['reference', 'knowledge', 'general'],
+};
+// --- Protection defaults per type ---
+export const TYPE_DEFAULTS = {
+    // Persona
+    'personality': { protection: 'protected', autoLoad: true },
+    'behavioral-rule': { protection: 'protected', autoLoad: true },
+    'preference': { protection: 'guarded', autoLoad: true },
+    'claude-md': { protection: 'protected', autoLoad: true },
+    // System
+    'hook': { protection: 'protected', autoLoad: false },
+    'plugin-config': { protection: 'guarded', autoLoad: false },
+    'type-registry': { protection: 'immutable', autoLoad: false },
+    'sync-rule': { protection: 'immutable', autoLoad: false },
+    // Workspace
+    'dashboard': { protection: 'guarded', autoLoad: false },
+    'device-registry': { protection: 'guarded', autoLoad: false },
+    'environment': { protection: 'guarded', autoLoad: false },
+    // Project
+    'architecture': { protection: 'guarded', autoLoad: false },
+    'project-status': { protection: 'open', autoLoad: false },
+    'event': { protection: 'open', autoLoad: false },
+    'error': { protection: 'open', autoLoad: false },
+    'reference': { protection: 'open', autoLoad: false },
+    'knowledge': { protection: 'open', autoLoad: false },
+    'eval-result': { protection: 'open', autoLoad: false },
+};
+// Note: 'skill' has domain-dependent defaults handled by getProtectionDefault/getAutoLoadDefault
+// --- v1 → v2 type migration map ---
+export const TYPE_MIGRATION = {
+    'user-preference': { domain: 'persona', type: 'preference' },
+    'persona-rule': { domain: 'persona', type: 'behavioral-rule' },
+    'code-craft': { domain: 'persona', type: 'preference' },
+    'system-rule': { domain: 'system', type: 'sync-rule' },
+    'architecture-decision': { domain: 'project', type: 'architecture' },
+    'project-status': { domain: 'project', type: 'project-status' },
+    'skill-reference': { domain: 'persona', type: 'skill' },
+    'knowledge-guide': { domain: 'general', type: 'knowledge' },
+};
+// --- Inference functions ---
+/**
+ * Given a v2 type name, return which domain it belongs to.
+ * For ambiguous types (skill, reference, knowledge): returns first match based on DOMAIN_TYPES order.
+ * Note: reference/knowledge appear in both project and general — project wins because it's listed first.
+ * When creating a note without a project, callers should explicitly set domain: 'general'.
+ */
+export function inferDomain(type) {
+    // Types that exist in multiple domains — explicit defaults
+    // Types that exist in multiple domains — explicit defaults
+    if (type === 'hook')
+        return 'system'; // most hooks are infrastructure; persona/workspace for personal ones
+    if (type === 'plugin-config')
+        return 'system'; // most plugins are system; persona/workspace for personal ones
+    if (type === 'skill')
+        return 'persona'; // most skills are personal; system/workspace/project to override
+    for (const [domain, types] of Object.entries(DOMAIN_TYPES)) {
+        if (types.includes(type))
+            return domain;
+    }
+    return 'general'; // default for unknown types
+}
+/** Given a type name, return the default protection level. */
+export function getProtectionDefault(type) {
+    // Skill defaults depend on context; use protected as sensible default
+    if (type === 'skill')
+        return 'protected';
+    return TYPE_DEFAULTS[type]?.protection ?? 'open';
+}
+/** Given a domain and type, return the default auto_load value. */
+export function getAutoLoadDefault(domain, _type) {
+    if (domain === 'system')
+        return true;
+    if (domain === 'persona')
+        return true;
+    return false;
+}
+/** Validate that a type belongs to the specified domain. Returns null if valid, error string if not. */
+export function validateDomainType(domain, type) {
+    const validTypes = DOMAIN_TYPES[domain];
+    if (!validTypes)
+        return `Unknown domain: ${domain}`;
+    if (!validTypes.includes(type)) {
+        return `Type "${type}" is not valid for domain "${domain}". Valid types: ${validTypes.join(', ')}`;
+    }
+    return null;
+}
+/** Resolve a v1 type name to its v2 domain + type. Returns null if no migration needed. */
+export function resolveV1Type(oldType) {
+    return TYPE_MIGRATION[oldType] ?? null;
+}
+/** Get a flat, deduplicated list of all v2 type names. */
+export function getAllV2Types() {
+    const seen = new Set();
+    for (const types of Object.values(DOMAIN_TYPES)) {
+        for (const type of types)
+            seen.add(type);
+    }
+    return [...seen];
+}
+/** Check if a type name is a valid v2 type (exists in any domain). */
+export function isV2Type(type) {
+    return getAllV2Types().includes(type);
+}
+/** Check if a type name is a v1 type that needs migration. */
+export function isV1Type(type) {
+    return type in TYPE_MIGRATION;
+}

package/dist/lib/embeddings.js

@@ -0,0 +1,190 @@
+// embeddings.ts
+// Prepares data for the database: generate embeddings, chunk text, format vectors.
+// The database can't call OpenAI or split text — that's TypeScript's job.
+import { createHash } from 'crypto';
+// =============================================================================
+// Constants
+// =============================================================================
+const EMBEDDING_MODEL = 'text-embedding-3-small';
+const DEFAULT_MAX_CHUNK_CHARS = 2000;
+const DEFAULT_OVERLAP_CHARS = 200;
+// =============================================================================
+// Pure functions — no API calls, no database, fully testable
+// =============================================================================
+/**
+ * SHA-256 hash of text content.
+ * Used for change detection: "has this document's content changed since last sync?"
+ * Same algorithm used in Postgres via pgcrypto.
+ */
+export function contentHash(text) {
+    return createHash('sha256').update(text, 'utf-8').digest('hex');
+}
+/**
+ * Format a number[] embedding as a Postgres vector string.
+ * Supabase RPC can't send number[] as vector(1536) — it needs this string format.
+ * Example: [0.021, -0.007, 0.045] → "[0.021,-0.007,0.045]"
+ */
+export function toVectorString(embedding) {
+    return `[${embedding.join(',')}]`;
+}
+/**
+ * Parse a Postgres vector back into a number[].
+ * Supabase REST API returns vector(1536) columns as strings like "[0.021,-0.007,0.045]".
+ * If the value is already a number[] (e.g. from a mock in tests), it passes through unchanged.
+ */
+export function parseVector(raw) {
+    if (Array.isArray(raw))
+        return raw;
+    if (typeof raw === 'string')
+        return JSON.parse(raw);
+    throw new Error(`Cannot parse vector: expected string or number[], got ${typeof raw}`);
+}
+/**
+ * Split text into smaller pieces for embedding.
+ *
+ * Why chunk: embedding models produce better search results on focused text
+ * (500-2000 chars) than on large mixed-topic documents (10,000+ chars).
+ *
+ * How it works:
+ * 1. If text is under maxChars, return it as one chunk
+ * 2. Split on paragraph boundaries (\n\n)
+ * 3. Accumulate paragraphs until a chunk would exceed maxChars
+ * 4. Include overlap between chunks so context isn't lost at boundaries
+ * 5. Force-split any remaining chunks that are still too long
+ */
+export function chunkText(text, strategy = 'paragraph', maxChars = DEFAULT_MAX_CHUNK_CHARS, overlapChars = DEFAULT_OVERLAP_CHARS) {
+    // Short text = one chunk
+    if (text.length <= maxChars) {
+        return [{
+                content: text,
+                chunk_index: 0,
+                content_type: 'text',
+                strategy,
+                overlap_chars: 0,
+            }];
+    }
+    // Split on paragraph boundaries
+    const paragraphs = text.split(/\n\n+/);
+    const rawChunks = [];
+    let current = '';
+    // Greedy paragraph packing — three stages per chunk:
+    //
+    // 1. First paragraph: size check may pass but current is empty (length 0),
+    //    so the guard (current.length > 0) fails → paragraph goes into current.
+    // 2. Next paragraphs: current + paragraph + 2 (blank-line separator) still
+    //    fits under maxChars → keep appending to current.
+    // 3. Overflow: current + paragraph + 2 exceeds maxChars AND current has
+    //    content → flush current as a finished chunk, slice its tail as overlap
+    //    context, start a new current with that tail + the new paragraph.
+    //
+    // The guard prevents flushing an empty chunk when a single paragraph is
+    // already larger than maxChars — the force-split below handles that case.
+    for (const paragraph of paragraphs) {
+        if (current.length + paragraph.length + 2 > maxChars && current.length > 0) {
+            rawChunks.push(current.trim());
+            // Overlap: carry the end of this chunk into the start of the next
+            const overlap = current.slice(-overlapChars);
+            current = overlap + '\n\n' + paragraph;
+        }
+        else {
+            current = current ? current + '\n\n' + paragraph : paragraph;
+        }
+    }
+    // The loop only flushes when a paragraph overflows. After the last paragraph,
+    // current may still hold a partially filled chunk that never triggered a flush.
+    if (current.trim()) {
+        rawChunks.push(current.trim());
+    }
+    // Force-split any chunks still over maxChars.
+    // This handles text with no blank lines (e.g. a JSON blob, base64 string, or
+    // a wall of text). The paragraph loop above can't split those — it produces a
+    // single oversized chunk because the empty-box guard prevents flushing when
+    // current is empty. Here we cut at character positions as a last resort.
+    const result = [];
+    let finalIndex = 0;
+    for (const chunk of rawChunks) {
+        if (chunk.length <= maxChars) {
+            result.push({
+                content: chunk,
+                chunk_index: finalIndex,
+                content_type: 'text',
+                strategy,
+                overlap_chars: finalIndex > 0 ? overlapChars : 0,
+            });
+            finalIndex++;
+        }
+        else {
+            // Force split at character boundaries (step must be positive)
+            const step = Math.max(1, maxChars - overlapChars);
+            for (let i = 0; i < chunk.length; i += step) {
+                result.push({
+                    content: chunk.slice(i, i + maxChars),
+                    chunk_index: finalIndex,
+                    content_type: 'text',
+                    strategy: 'forced',
+                    overlap_chars: i > 0 ? overlapChars : 0,
+                });
+                finalIndex++;
+            }
+        }
+    }
+    return result;
+}
+// =============================================================================
+// API functions — call OpenAI and/or database
+// =============================================================================
+/**
+ * Call OpenAI to convert text into an array of 1,536 numbers.
+ * These numbers represent the "meaning" of the text in a mathematical space.
+ * Similar texts produce similar numbers — that's how search works.
+ */
+export async function generateEmbedding(openai, text) {
+    const response = await openai.embeddings.create({
+        model: EMBEDDING_MODEL,
+        input: text,
+    });
+    return response.data[0].embedding;
+}
+/**
+ * Get an embedding for a search query, using the cache to avoid repeat API calls.
+ *
+ * Flow:
+ * 1. Check query_cache table for this exact query text
+ * 2. If cached: return the cached embedding, update hit_count
+ * 3. If not cached: call OpenAI, save to cache, return embedding
+ *
+ * Why cache: each OpenAI embedding call costs money. If you search
+ * "how does auth work" three times, the cache saves 2 API calls.
+ */
+export async function getOrCacheQueryEmbedding(clients, query) {
+    // Normalize query to avoid cache misses from capitalization/whitespace differences
+    const normalizedQuery = query.toLowerCase().trim();
+    // Check cache
+    const { data: cached } = await clients.supabase
+        .from('query_cache')
+        .select('embedding, hit_count')
+        .eq('query_text', normalizedQuery)
+        .single();
+    if (cached?.embedding) {
+        // Update cache stats
+        await clients.supabase
+            .from('query_cache')
+            .update({
+            hit_count: cached.hit_count + 1,
+            last_used_at: new Date().toISOString(),
+        })
+            .eq('query_text', normalizedQuery);
+        return parseVector(cached.embedding);
+    }
+    // Generate and cache — send original query to OpenAI (preserves meaning),
+    // but store under normalized key (so "Auth" and "auth" share one cache entry)
+    const embedding = await generateEmbedding(clients.openai, query);
+    await clients.supabase
+        .from('query_cache')
+        .insert({
+        query_text: normalizedQuery,
+        embedding: toVectorString(embedding),
+        embedding_model_id: 'openai/text-embedding-3-small',
+    });
+    return embedding;
+}

package/dist/lib/errors.js

@@ -11,11 +11,13 @@ export var ExitCode;
     ExitCode[ExitCode["SUCCESS"] = 0] = "SUCCESS";
     ExitCode[ExitCode["GENERAL_ERROR"] = 1] = "GENERAL_ERROR";
     ExitCode[ExitCode["FILE_NOT_FOUND"] = 2] = "FILE_NOT_FOUND";
-    ExitCode[ExitCode["NOTE_NOT_FOUND"] = 3] = "NOTE_NOT_FOUND";
+    ExitCode[ExitCode["DOCUMENT_NOT_FOUND"] = 3] = "DOCUMENT_NOT_FOUND";
     ExitCode[ExitCode["SUPABASE_ERROR"] = 4] = "SUPABASE_ERROR";
     ExitCode[ExitCode["EMBEDDING_ERROR"] = 5] = "EMBEDDING_ERROR";
     ExitCode[ExitCode["CONFLICT"] = 6] = "CONFLICT";
     ExitCode[ExitCode["INVALID_INPUT"] = 7] = "INVALID_INPUT";
+    ExitCode[ExitCode["PROTECTED"] = 8] = "PROTECTED";
+    ExitCode[ExitCode["VERIFY_MISMATCH"] = 9] = "VERIFY_MISMATCH";
 })(ExitCode || (ExitCode = {}));
 export function fatal(message, code = ExitCode.GENERAL_ERROR) {
     console.error(message);

package/dist/lib/eval/eval-advanced.js

@@ -0,0 +1,289 @@
+// eval-advanced.ts
+// Advanced eval utilities — confidence intervals via bootstrap resampling,
+// score calibration for relevant vs irrelevant result distributions.
+// Pure functions — no I/O, no database calls.
+import { computeMetrics, HIT_THRESHOLD } from './eval.js';
+// =============================================================================
+// resampleWithReplacement
+// =============================================================================
+/**
+ * Creates a new array of the same length by randomly picking items from the
+ * original with replacement. Each position independently draws a random item,
+ * so the same item may appear multiple times.
+ */
+export function resampleWithReplacement(results) {
+    const resampled = [];
+    for (let sampleIndex = 0; sampleIndex < results.length; sampleIndex++) {
+        const randomIndex = Math.floor(Math.random() * results.length);
+        resampled.push(results[randomIndex]);
+    }
+    return resampled;
+}
+// =============================================================================
+// percentile
+// =============================================================================
+/**
+ * Computes the percentile of a sorted array using linear interpolation.
+ * fraction=0.025 gives the 2.5th percentile; fraction=0.975 gives 97.5th.
+ *
+ * Assumes sortedValues is already sorted ascending.
+ */
+export function percentile(sortedValues, fraction) {
+    if (sortedValues.length === 0)
+        return 0;
+    if (sortedValues.length === 1)
+        return sortedValues[0];
+    const position = fraction * (sortedValues.length - 1);
+    const lowerIndex = Math.floor(position);
+    const upperIndex = Math.ceil(position);
+    if (lowerIndex === upperIndex)
+        return sortedValues[lowerIndex];
+    const lowerValue = sortedValues[lowerIndex];
+    const upperValue = sortedValues[upperIndex];
+    const fraction_ = position - lowerIndex;
+    return lowerValue + fraction_ * (upperValue - lowerValue);
+}
+// =============================================================================
+// buildInterval
+// =============================================================================
+/**
+ * Sorts bootstrap values, computes the 2.5th and 97.5th percentiles, then
+ * returns a complete IConfidenceIntervalProps with point estimate, lower,
+ * upper, and width.
+ */
+export function buildInterval(bootstrapValues, pointEstimate) {
+    const sortedValues = [...bootstrapValues].sort((valueA, valueB) => valueA - valueB);
+    const lower = percentile(sortedValues, 0.025);
+    const upper = percentile(sortedValues, 0.975);
+    return {
+        point: pointEstimate,
+        lower,
+        upper,
+        width: upper - lower,
+    };
+}
+// =============================================================================
+// computeConfidenceIntervals
+// =============================================================================
+/**
+ * Computes 95% confidence intervals for all eval metrics using bootstrap
+ * resampling.
+ *
+ * 1. Computes point estimates from actual results via computeMetrics().
+ * 2. Runs `iterations` bootstrap rounds, each resampling with replacement.
+ * 3. For each metric, sorts the collected bootstrap values and takes the
+ *    2.5th and 97.5th percentiles as lower and upper bounds.
+ */
+export function computeConfidenceIntervals(results, iterations = 1000) {
+    const pointMetrics = computeMetrics(results);
+    const bootstrapHitRates = [];
+    const bootstrapFirstResultAccuracies = [];
+    const bootstrapRecalls = [];
+    const bootstrapZeroResultRates = [];
+    const bootstrapMeanReciprocalRanks = [];
+    const bootstrapNormalizedDiscountedCumulativeGainValues = [];
+    for (let iteration = 0; iteration < iterations; iteration++) {
+        const resampledResults = resampleWithReplacement(results);
+        const resampledMetrics = computeMetrics(resampledResults);
+        bootstrapHitRates.push(resampledMetrics.hitRate);
+        bootstrapFirstResultAccuracies.push(resampledMetrics.firstResultAccuracy);
+        bootstrapRecalls.push(resampledMetrics.recall);
+        bootstrapZeroResultRates.push(resampledMetrics.zeroResultRate);
+        bootstrapMeanReciprocalRanks.push(resampledMetrics.meanReciprocalRank);
+        bootstrapNormalizedDiscountedCumulativeGainValues.push(resampledMetrics.normalizedDiscountedCumulativeGain);
+    }
+    return {
+        hitRate: buildInterval(bootstrapHitRates, pointMetrics.hitRate),
+        firstResultAccuracy: buildInterval(bootstrapFirstResultAccuracies, pointMetrics.firstResultAccuracy),
+        recall: buildInterval(bootstrapRecalls, pointMetrics.recall),
+        zeroResultRate: buildInterval(bootstrapZeroResultRates, pointMetrics.zeroResultRate),
+        meanReciprocalRank: buildInterval(bootstrapMeanReciprocalRanks, pointMetrics.meanReciprocalRank),
+        normalizedDiscountedCumulativeGain: buildInterval(bootstrapNormalizedDiscountedCumulativeGainValues, pointMetrics.normalizedDiscountedCumulativeGain),
+    };
+}
+// =============================================================================
+// computeDistribution
+// =============================================================================
+/**
+ * Computes summary statistics for an array of numeric scores.
+ * Returns all-zero IScoreDistributionProps if the array is empty.
+ * Median is the middle value of the sorted array, or the average of the two
+ * middle values when the array has even length.
+ */
+export function computeDistribution(scores) {
+    if (scores.length === 0) {
+        return { count: 0, mean: 0, median: 0, min: 0, max: 0 };
+    }
+    const sorted = [...scores].sort((scoreA, scoreB) => scoreA - scoreB);
+    const count = sorted.length;
+    const sum = sorted.reduce((total, score) => total + score, 0);
+    const mean = sum / count;
+    const middleIndex = Math.floor(count / 2);
+    const median = count % 2 === 1
+        ? sorted[middleIndex]
+        : (sorted[middleIndex - 1] + sorted[middleIndex]) / 2;
+    return {
+        count,
+        mean,
+        median,
+        min: sorted[0],
+        max: sorted[count - 1],
+    };
+}
+// =============================================================================
+// computeScoreCalibration
+// =============================================================================
+/**
+ * Separates scores into relevant (returned doc graded >= HIT_THRESHOLD) and
+ * irrelevant buckets, then computes distribution stats for each.
+ *
+ * Out-of-scope results (no judgments at grade >= HIT_THRESHOLD) are skipped.
+ * Separation = relevant mean − irrelevant mean.
+ */
+export function computeScoreCalibration(results) {
+    const relevantScoreValues = [];
+    const irrelevantScoreValues = [];
+    for (const result of results) {
+        const relevantDocIds = new Set(result.testCase.judgments
+            .filter(judgment => judgment.grade >= HIT_THRESHOLD)
+            .map(judgment => judgment.document_id));
+        if (relevantDocIds.size === 0)
+            continue;
+        for (let position = 0; position < result.returnedIds.length; position++) {
+            const docId = result.returnedIds[position];
+            const score = result.returnedScores[position];
+            if (relevantDocIds.has(docId)) {
+                relevantScoreValues.push(score);
+            }
+            else {
+                irrelevantScoreValues.push(score);
+            }
+        }
+    }
+    const relevantScores = computeDistribution(relevantScoreValues);
+    const irrelevantScores = computeDistribution(irrelevantScoreValues);
+    return {
+        relevantScores,
+        irrelevantScores,
+        separation: relevantScores.mean - irrelevantScores.mean,
+    };
+}
+// =============================================================================
+// computeCoverageAnalysis
+// =============================================================================
+/**
+ * Analyses golden set coverage — which parts of the knowledge base are
+ * well-tested vs blind spots.
+ *
+ * - Normal queries: at least one judgment at grade >= HIT_THRESHOLD
+ * - Out-of-scope queries: no judgments at grade >= HIT_THRESHOLD
+ * - queriesPerTag: how many queries carry each tag
+ * - expectedDocumentIds: deduplicated union of all grade>=HIT_THRESHOLD doc ids, sorted ascending
+ */
+export function computeCoverageAnalysis(results) {
+    let normalCount = 0;
+    let outOfScopeCount = 0;
+    const queriesPerTag = {};
+    const seenDocumentIds = new Set();
+    for (const result of results) {
+        const relevantJudgments = result.testCase.judgments.filter(judgment => judgment.grade >= HIT_THRESHOLD);
+        if (relevantJudgments.length === 0) {
+            outOfScopeCount++;
+        }
+        else {
+            normalCount++;
+        }
+        for (const tag of result.testCase.tags) {
+            queriesPerTag[tag] = (queriesPerTag[tag] ?? 0) + 1;
+        }
+        for (const judgment of relevantJudgments) {
+            seenDocumentIds.add(judgment.document_id);
+        }
+    }
+    const expectedDocumentIds = [...seenDocumentIds].sort((documentIdA, documentIdB) => documentIdA - documentIdB);
+    return {
+        totalQueries: results.length,
+        normalCount,
+        outOfScopeCount,
+        totalTags: Object.keys(queriesPerTag).length,
+        queriesPerTag,
+        uniqueExpectedDocuments: expectedDocumentIds.length,
+        expectedDocumentIds,
+    };
+}
+// =============================================================================
+// formatAdvancedReport
+// =============================================================================
+/**
+ * Formats confidence intervals, score calibration, and coverage analysis into
+ * a human-readable string for display in the CLI or eval runner.
+ *
+ * - Percentage metrics (hitRate, firstResultAccuracy, recall, zeroResultRate)
+ *   render as: 88.5% (±4.2%, 95% CI: 84.3–92.7%)
+ * - Ratio metrics (meanReciprocalRank, normalizedDiscountedCumulativeGain)
+ *   render as: 0.601 (±0.052, 95% CI: 0.549–0.653)
+ * - Tags with fewer than 3 queries are marked as undertested.
+ */
+export function formatAdvancedReport(intervals, calibration, coverage) {
+    const lines = [];
+    // ---------------------------------------------------------------------------
+    // Section 1 — CONFIDENCE INTERVALS
+    // ---------------------------------------------------------------------------
+    lines.push('='.repeat(60));
+    lines.push('CONFIDENCE INTERVALS (95%, bootstrap)');
+    lines.push('='.repeat(60));
+    lines.push('');
+    function formatPercentInterval(interval) {
+        const halfWidth = interval.width / 2;
+        return `${interval.point.toFixed(1)}% (±${halfWidth.toFixed(1)}%, 95% CI: ${interval.lower.toFixed(1)}–${interval.upper.toFixed(1)}%)`;
+    }
+    function formatRatioInterval(interval) {
+        const intervalWidth = interval.width / 2;
+        return `${interval.point.toFixed(3)} (±${intervalWidth.toFixed(3)}, 95% CI: ${interval.lower.toFixed(3)}–${interval.upper.toFixed(3)})`;
+    }
+    lines.push(`  Hit rate:              ${formatPercentInterval(intervals.hitRate)}`);
+    lines.push(`  First-result accuracy: ${formatPercentInterval(intervals.firstResultAccuracy)}`);
+    lines.push(`  Recall:                ${formatPercentInterval(intervals.recall)}`);
+    lines.push(`  Zero-result rate:      ${formatPercentInterval(intervals.zeroResultRate)}`);
+    lines.push(`  MRR:                   ${formatRatioInterval(intervals.meanReciprocalRank)}`);
+    lines.push(`  NDCG@k:                ${formatRatioInterval(intervals.normalizedDiscountedCumulativeGain)}`);
+    lines.push('');
+    // ---------------------------------------------------------------------------
+    // Section 2 — SCORE CALIBRATION
+    // ---------------------------------------------------------------------------
+    lines.push('='.repeat(60));
+    lines.push('SCORE CALIBRATION');
+    lines.push('='.repeat(60));
+    lines.push('');
+    const relevant = calibration.relevantScores;
+    const irrelevant = calibration.irrelevantScores;
+    lines.push(`  Relevant scores   (n=${relevant.count}):`);
+    lines.push(`    mean: ${relevant.mean.toFixed(3)}, median: ${relevant.median.toFixed(3)}, range: [${relevant.min.toFixed(3)}–${relevant.max.toFixed(3)}]`);
+    lines.push('');
+    lines.push(`  Irrelevant scores (n=${irrelevant.count}):`);
+    lines.push(`    mean: ${irrelevant.mean.toFixed(3)}, median: ${irrelevant.median.toFixed(3)}, range: [${irrelevant.min.toFixed(3)}–${irrelevant.max.toFixed(3)}]`);
+    lines.push('');
+    lines.push(`  separation: ${calibration.separation.toFixed(3)} (higher = better distinction between relevant and irrelevant)`);
+    lines.push('');
+    // ---------------------------------------------------------------------------
+    // Section 3 — COVERAGE ANALYSIS
+    // ---------------------------------------------------------------------------
+    lines.push('='.repeat(60));
+    lines.push('COVERAGE ANALYSIS');
+    lines.push('='.repeat(60));
+    lines.push('');
+    lines.push(`  Total queries:    ${coverage.totalQueries} (${coverage.normalCount} normal, ${coverage.outOfScopeCount} out-of-scope)`);
+    lines.push(`  Unique docs:      ${coverage.uniqueExpectedDocuments}`);
+    lines.push(`  Tags covered:     ${coverage.totalTags}`);
+    lines.push('');
+    const sortedTagEntries = Object.entries(coverage.queriesPerTag).sort(([, countA], [, countB]) => countB - countA);
+    for (const [tag, count] of sortedTagEntries) {
+        const undertested = count < 3 ? ' ← undertested' : '';
+        lines.push(`    ${tag}: ${count}${undertested}`);
+    }
+    if (sortedTagEntries.length === 0) {
+        lines.push('    (no tags)');
+    }
+    lines.push('');
+    return lines.join('\n');
+}