hippo-memory 1.69.0 → 1.70.0

package/dist/cli/decisions.js

@@ -1,23 +1,21 @@
 // First-class object verbs for predictions, decisions and incidents.
 import { writeEntry } from '../store/entry-writes.js';
 import { readEntry } from '../store/entry-reads.js';
-import { extractPathTags } from '../path-context.js';
-import * as predictionsModule from '../predictions/store.js';
-import * as decisionsModule from '../decisions.js';
-import * as incidentsModule from '../incidents.js';
-import { resolveTenantId } from '../tenant.js';
+import { extractPathTags } from '../search/path-context.js';
+import * as predictionsModule from '../store/predictions.js';
+import * as decisionsModule from '../objects/decisions.js';
+import * as incidentsModule from '../objects/incidents.js';
+import { resolveTenantId } from '../store/tenant.js';
 import { printError } from './output.js';
+import { nonEmptyStringFlag, parseListLimit, flagIsTrue, stringFlag } from './flag-values.js';
 import { requireInit } from './shared.js';
-function parseListLimit(flags) {
-    const limitRaw = flags['limit'];
-    const limit = limitRaw !== undefined ? parseInt(String(limitRaw), 10) : 100;
-    if (!Number.isFinite(limit) || limit <= 0) {
-        printError(`Invalid --limit: "${limitRaw}". Must be a positive integer.`);
-        process.exit(1);
-    }
-    return limit;
-}
-/** parseInt-based id parse for predictions and decisions; incidents use the strict parse below. */
+import { closeObject, foundOrExit, idArgOrExit, listObjects, printLifecycleTail, requireStatus } from './object-verbs.js';
+import { errorMessage } from '../util/log.js';
+const BASERATE_DECIMALS = 3;
+const DECISION = { cmd: 'decide', noun: 'Decision', idLabel: 'decision' };
+const INCIDENT = { cmd: 'incident', noun: 'Incident', idLabel: 'incident' };
+const PREDICTION_NOUN = 'Prediction';
+// Lenient on purpose (parseInt reads "1abc" as 1) until the next major version; incidents use the strict parser.
 function parseObjectId(idRaw, noun) {
     const id = parseInt(String(idRaw), 10);
     if (!Number.isFinite(id) || id <= 0) {
@@ -30,13 +28,8 @@ function parseObjectId(idRaw, noun) {
 // Prediction first-class object
 // ---------------------------------------------------------------------------
 function predictClose(hippoRoot, tenantId, args, flags) {
-    const idRaw = args[1];
-    if (!idRaw) {
-        printError('Usage: hippo predict close <id> --state <closed|closed-unknown> [--actual <v>] [--note "..."]');
-        process.exit(1);
-    }
-    const id = parseObjectId(idRaw, 'prediction');
-    const stateRaw = typeof flags['state'] === 'string' ? flags['state'].trim() : '';
+    const id = idArgOrExit(args, 'Usage: hippo predict close <id> --state <closed|closed-unknown> [--actual <v>] [--note "..."]', 'prediction', parseObjectId);
+    const stateRaw = (stringFlag(flags, 'state') ?? '').trim();
     if (!predictionsModule.VALID_CLOSURE_STATES.has(stateRaw) || stateRaw === 'open') {
         printError(`Invalid --state: "${stateRaw}". Must be one of: closed | closed-unknown.`);
         process.exit(1);
@@ -47,8 +40,7 @@ function predictClose(hippoRoot, tenantId, args, flags) {
         printError(`Invalid --actual: "${actualRaw}". Must be a number.`);
         process.exit(1);
     }
-    const noteRaw = flags['note'];
-    const closureNote = typeof noteRaw === 'string' ? noteRaw : undefined;
+    const closureNote = stringFlag(flags, 'note');
     const closed = predictionsModule.closePrediction(hippoRoot, tenantId, id, {
         closureState: stateRaw,
         actualValue,
@@ -68,25 +60,20 @@ function loadPredictionList(hippoRoot, tenantId, status, classTag, limit) {
             ? predictionsModule.loadPredictionsByClass(hippoRoot, tenantId, classTag, { limit })
             : predictionsModule.loadAllPredictions(hippoRoot, tenantId, { limit });
     }
-    if (!predictionsModule.VALID_CLOSURE_STATES.has(status)) {
-        printError(`Invalid --status: "${status}". Must be one of: open | closed | closed-unknown | all.`);
-        process.exit(1);
-    }
+    const closureState = requireStatus(status, predictionsModule.VALID_CLOSURE_STATES);
     if (!classTag) {
         // status filter without class — scan all classes is more complex; v1 requires --class for non-default status
         printError('--status filter (non-open) requires --class to be set.');
         process.exit(1);
     }
     return predictionsModule.loadPredictionsByClass(hippoRoot, tenantId, classTag, {
-        closureState: status,
+        closureState,
         limit,
     });
 }
 function predictList(hippoRoot, tenantId, flags) {
-    const classTagRaw = flags['class'];
-    const classTag = typeof classTagRaw === 'string' ? classTagRaw.trim() : '';
-    const statusRaw = flags['status'];
-    const status = typeof statusRaw === 'string' ? statusRaw.trim() : 'all';
+    const classTag = stringFlag(flags, 'class')?.trim() ?? '';
+    const status = stringFlag(flags, 'status')?.trim() ?? 'all';
     const limit = parseListLimit(flags);
     const results = loadPredictionList(hippoRoot, tenantId, status, classTag, limit);
     if (results.length === 0) {
@@ -105,17 +92,8 @@ function predictList(hippoRoot, tenantId, flags) {
     }
 }
 function predictShow(hippoRoot, tenantId, args) {
-    const idRaw = args[1];
-    if (!idRaw) {
-        printError('Usage: hippo predict show <id>');
-        process.exit(1);
-    }
-    const id = parseObjectId(idRaw, 'prediction');
-    const pred = predictionsModule.loadPredictionById(hippoRoot, tenantId, id);
-    if (!pred) {
-        printError(`Prediction ${id} not found.`);
-        process.exit(1);
-    }
+    const id = idArgOrExit(args, 'Usage: hippo predict show <id>', 'prediction', parseObjectId);
+    const pred = foundOrExit(predictionsModule.loadPredictionById(hippoRoot, tenantId, id), PREDICTION_NOUN, id);
     console.log(`Prediction #${pred.id}`);
     console.log(`  class: ${pred.classTag}`);
     console.log(`  claim: ${pred.claimText}`);
@@ -136,12 +114,12 @@ function predictShow(hippoRoot, tenantId, args) {
 }
 function predictBaserate(hippoRoot, tenantId, flags) {
     // Reference-class / planning-fallacy detector
-    const classTagRaw = flags['class'];
-    if (typeof classTagRaw !== 'string' || !classTagRaw.trim()) {
+    const classTag = stringFlag(flags, 'class')?.trim();
+    if (!classTag) {
         printError('Usage: hippo predict baserate --class <c>');
         process.exit(1);
     }
-    const baserate = predictionsModule.computePredictionBaserate(hippoRoot, tenantId, classTagRaw.trim());
+    const baserate = predictionsModule.computePredictionBaserate(hippoRoot, tenantId, classTag);
     if (baserate.nClosed === 0) {
         console.log(`No closed predictions in class "${baserate.classTag}" yet.`);
         console.log(`  Create one with: hippo predict "<claim>" --class ${baserate.classTag} --estimate N`);
@@ -152,15 +130,15 @@ function predictBaserate(hippoRoot, tenantId, flags) {
     console.log(`  n_closed:         ${baserate.nClosed}`);
     console.log(`  n_ratio_eligible: ${baserate.nRatioEligible}`);
     if (baserate.meanEstimate !== null)
-        console.log(`  mean_estimate:    ${baserate.meanEstimate.toFixed(3)}`);
+        console.log(`  mean_estimate:    ${baserate.meanEstimate.toFixed(BASERATE_DECIMALS)}`);
     if (baserate.meanActual !== null)
-        console.log(`  mean_actual:      ${baserate.meanActual.toFixed(3)}`);
+        console.log(`  mean_actual:      ${baserate.meanActual.toFixed(BASERATE_DECIMALS)}`);
     if (baserate.meanRatio !== null)
-        console.log(`  mean_ratio:       ${baserate.meanRatio.toFixed(3)}x`);
+        console.log(`  mean_ratio:       ${baserate.meanRatio.toFixed(BASERATE_DECIMALS)}x`);
     if (baserate.p50Ratio !== null)
-        console.log(`  p50_ratio:        ${baserate.p50Ratio.toFixed(3)}x`);
+        console.log(`  p50_ratio:        ${baserate.p50Ratio.toFixed(BASERATE_DECIMALS)}x`);
     if (baserate.mae !== null)
-        console.log(`  mae:              ${baserate.mae.toFixed(3)}`);
+        console.log(`  mae:              ${baserate.mae.toFixed(BASERATE_DECIMALS)}`);
 }
 export function cmdPredict(hippoRoot, args, flags) {
     requireInit(hippoRoot);
@@ -185,22 +163,19 @@ function predictCreate(hippoRoot, tenantId, claimText, flags) {
         printError('       hippo predict show <id>');
         process.exit(1);
     }
-    const classTagRaw = flags['class'];
-    if (typeof classTagRaw !== 'string' || !classTagRaw.trim()) {
+    const classTag = stringFlag(flags, 'class')?.trim();
+    if (!classTag) {
         printError('--class is required for prediction creation.');
         process.exit(1);
     }
-    const classTag = classTagRaw.trim();
     const estimateRaw = flags['estimate'];
     const estimateValue = estimateRaw !== undefined ? Number(estimateRaw) : undefined;
     if (estimateRaw !== undefined && !Number.isFinite(estimateValue)) {
         printError(`Invalid --estimate: "${estimateRaw}". Must be a number.`);
         process.exit(1);
     }
-    const unitRaw = flags['unit'];
-    const estimateUnit = typeof unitRaw === 'string' ? unitRaw : undefined;
-    const targetRaw = flags['target'];
-    const targetDate = typeof targetRaw === 'string' ? targetRaw : undefined;
+    const estimateUnit = stringFlag(flags, 'unit');
+    const targetDate = stringFlag(flags, 'target');
     const created = predictionsModule.savePrediction(hippoRoot, tenantId, {
         classTag,
         claimText,
@@ -212,73 +187,33 @@ function predictCreate(hippoRoot, tenantId, claimText, flags) {
     if (created.memoryId)
         console.log(`  memory: ${created.memoryId}`);
 }
+function printDecisionRow(d) {
+    const supPart = d.supersededBy !== null ? ` superseded_by=#${d.supersededBy}` : '';
+    console.log(`#${d.id} [${d.status}]${supPart} memory=${d.memoryId ?? '-'}`);
+    console.log(`    ${d.decisionText}`);
+    if (d.context)
+        console.log(`    context: ${d.context}`);
+}
 function decideList(hippoRoot, tenantId, flags) {
-    const statusRaw = flags['status'];
-    const status = typeof statusRaw === 'string' ? statusRaw.trim() : 'all';
-    const limit = parseListLimit(flags);
-    let results;
-    if (status === 'all') {
-        results = decisionsModule.loadDecisions(hippoRoot, tenantId, { limit });
-    }
-    else {
-        if (!decisionsModule.VALID_DECISION_STATES.has(status)) {
-            printError(`Invalid --status: "${status}". Must be one of: active | superseded | closed | all.`);
-            process.exit(1);
-        }
-        results = decisionsModule.loadDecisions(hippoRoot, tenantId, {
-            status: status,
-            limit,
-        });
-    }
-    if (results.length === 0) {
-        console.log('No decisions.');
-        return;
-    }
-    console.log(`Found ${results.length} decisions:\n`);
-    for (const d of results) {
-        const supPart = d.supersededBy !== null ? ` superseded_by=#${d.supersededBy}` : '';
-        console.log(`#${d.id} [${d.status}]${supPart} memory=${d.memoryId ?? '-'}`);
-        console.log(`    ${d.decisionText}`);
-        if (d.context)
-            console.log(`    context: ${d.context}`);
-    }
+    listObjects(flags, {
+        plural: 'decisions',
+        states: decisionsModule.VALID_DECISION_STATES,
+        load: (opts) => decisionsModule.loadDecisions(hippoRoot, tenantId, opts),
+        printRow: printDecisionRow,
+    });
 }
 function decideGet(hippoRoot, tenantId, args) {
-    const idRaw = args[1];
-    if (!idRaw) {
-        printError('Usage: hippo decide get <id>');
-        process.exit(1);
-    }
-    const id = parseObjectId(idRaw, 'decision');
-    const decision = decisionsModule.loadDecisionById(hippoRoot, tenantId, id);
-    if (!decision) {
-        printError(`Decision ${id} not found.`);
-        process.exit(1);
-    }
+    const id = idArgOrExit(args, 'Usage: hippo decide get <id>', DECISION.idLabel, parseObjectId);
+    const decision = foundOrExit(decisionsModule.loadDecisionById(hippoRoot, tenantId, id), DECISION.noun, id);
     console.log(`Decision #${decision.id}`);
     console.log(`  status: ${decision.status}`);
     console.log(`  text: ${decision.decisionText}`);
     if (decision.context)
         console.log(`  context: ${decision.context}`);
-    if (decision.supersededBy !== null)
-        console.log(`  superseded_by: #${decision.supersededBy}`);
-    if (decision.supersededAt)
-        console.log(`  superseded_at: ${decision.supersededAt}`);
-    if (decision.closedAt)
-        console.log(`  closed_at: ${decision.closedAt}`);
-    if (decision.memoryId)
-        console.log(`  memory: ${decision.memoryId}`);
-    console.log(`  created: ${decision.createdAt}`);
+    printLifecycleTail(decision);
 }
 function decideClose(hippoRoot, tenantId, args) {
-    const idRaw = args[1];
-    if (!idRaw) {
-        printError('Usage: hippo decide close <id>');
-        process.exit(1);
-    }
-    const id = parseObjectId(idRaw, 'decision');
-    const closed = decisionsModule.closeDecision(hippoRoot, tenantId, id);
-    console.log(`Decision #${closed.id} closed.`);
+    closeObject(args, DECISION, (id) => decisionsModule.closeDecision(hippoRoot, tenantId, id), parseObjectId);
 }
 export function cmdDecide(hippoRoot, args, flags) {
     requireInit(hippoRoot);
@@ -294,22 +229,16 @@ export function cmdDecide(hippoRoot, args, flags) {
     decideCreate(hippoRoot, tenantId, subcommand, flags);
 }
 function decideCreate(hippoRoot, tenantId, decisionText, flags) {
-    if (!decisionText) {
-        printError('Usage: hippo decide "<decision>" [--context "<why>"] [--supersedes <memory-id>]');
-        printError('       hippo decide list [--status active|superseded|closed|all] [--limit N]');
-        printError('       hippo decide get <id>');
-        printError('       hippo decide close <id>');
-        process.exit(1);
-    }
-    const contextRaw = flags['context'];
-    const context = typeof contextRaw === 'string' && contextRaw ? contextRaw : undefined;
+    if (!decisionText)
+        exitWithDecideUsage();
+    const context = nonEmptyStringFlag(flags, 'context');
     // A value-less `--supersedes` asks to supersede but gives no memory id: reject it rather
     // than silently creating a non-superseding decision.
-    if (flags['supersedes'] === true) {
+    if (flagIsTrue(flags, 'supersedes')) {
         printError('--supersedes requires a memory id, e.g. hippo decide "<text>" --supersedes mem_abc123.');
         process.exit(1);
     }
-    const supersedesMemId = typeof flags['supersedes'] === 'string' ? flags['supersedes'] : null;
+    const supersedesMemId = stringFlag(flags, 'supersedes') ?? null;
     // Backward-compat: --supersedes takes a MEMORY id. Validate it exists and
     // resolve it to the active decision row (if any). Commit the
     // canonical table create+supersede FIRST (inside saveDecision's SAVEPOINT),
@@ -333,88 +262,62 @@ function decideCreate(hippoRoot, tenantId, decisionText, flags) {
         supersedesDecisionId,
         extraTags: decisionPathTags,
     });
-    // Legacy memory-weaken (best-effort, LAST): half-life halved, marked stale +
-    // 'superseded' tag. Preserves the exact pre-promotion behavior for the memory
-    // mirror; the canonical table supersession already committed above.
-    if (oldEntry) {
-        // Best-effort: saveDecision already committed. Failing here would make a retry find no active
-        // decision for the old memory and create a duplicate active successor, so warn instead.
-        try {
-            oldEntry.half_life_days = Math.max(1, Math.floor(oldEntry.half_life_days / 2));
-            oldEntry.confidence = 'stale';
-            if (!oldEntry.tags.includes('superseded'))
-                oldEntry.tags.push('superseded');
-            writeEntry(hippoRoot, oldEntry);
-        }
-        catch (e) {
-            printError(`  warning: decision recorded and superseded, but failed to weaken the prior memory ${supersedesMemId}: ${e.message}`);
-        }
-    }
+    if (oldEntry)
+        weakenSupersededMemory(hippoRoot, oldEntry, supersedesMemId);
     console.log(`Decision recorded: #${created.id}`);
     if (created.memoryId)
         console.log(`  memory: ${created.memoryId}`);
-    if (supersedesMemId) {
-        const tail = supersedesDecisionId !== undefined
-            ? ` (decision #${supersedesDecisionId} superseded)`
-            : ' (no active decision row; memory weakened only)';
-        console.log(`  supersedes memory: ${supersedesMemId}${tail}`);
-    }
+    if (supersedesMemId)
+        printSupersedes(supersedesMemId, supersedesDecisionId);
 }
-// Strict positive-integer parse for incident id args. parseInt() alone accepts
-// trailing junk ("1abc" -> 1), which would let a mutating subcommand (close/
-// resolve) silently hit the wrong row; require the whole arg to be digits.
-function parsePositiveIncidentId(idRaw) {
-    const s = String(idRaw ?? '').trim();
-    const id = parseInt(s, 10);
-    if (!/^\d+$/.test(s) || id <= 0) {
-        printError(`Invalid incident id: "${idRaw}" (expected a positive integer).`);
-        process.exit(1);
+function exitWithDecideUsage() {
+    printError('Usage: hippo decide "<decision>" [--context "<why>"] [--supersedes <memory-id>]');
+    printError('       hippo decide list [--status active|superseded|closed|all] [--limit N]');
+    printError('       hippo decide get <id>');
+    printError('       hippo decide close <id>');
+    process.exit(1);
+}
+function weakenSupersededMemory(hippoRoot, oldEntry, supersedesMemId) {
+    // Legacy memory-weaken (best-effort, LAST): half-life halved, marked stale +
+    // 'superseded' tag. Preserves the exact pre-promotion behavior for the memory
+    // mirror; the canonical table supersession already committed above.
+    // Best-effort: saveDecision already committed. Failing here would make a retry find no active
+    // decision for the old memory and create a duplicate active successor, so warn instead.
+    try {
+        oldEntry.half_life_days = Math.max(1, Math.floor(oldEntry.half_life_days / 2));
+        oldEntry.confidence = 'stale';
+        if (!oldEntry.tags.includes('superseded'))
+            oldEntry.tags.push('superseded');
+        writeEntry(hippoRoot, oldEntry);
+    }
+    catch (e) {
+        printError(`  warning: decision recorded and superseded, but failed to weaken the prior memory ${supersedesMemId}: ${errorMessage(e)}`);
     }
-    return id;
+}
+function printSupersedes(supersedesMemId, supersedesDecisionId) {
+    const tail = supersedesDecisionId !== undefined
+        ? ` (decision #${supersedesDecisionId} superseded)`
+        : ' (no active decision row; memory weakened only)';
+    console.log(`  supersedes memory: ${supersedesMemId}${tail}`);
+}
+function printIncidentRow(inc) {
+    const linkPart = inc.linkedMemoryIds.length > 0 ? ` links=${inc.linkedMemoryIds.length}` : '';
+    console.log(`#${inc.id} [${inc.status}]${linkPart} memory=${inc.memoryId ?? '-'}`);
+    console.log(`    ${inc.incidentText}`);
+    if (inc.context)
+        console.log(`    context: ${inc.context}`);
 }
 function incidentList(hippoRoot, tenantId, flags) {
-    const statusRaw = flags['status'];
-    const status = typeof statusRaw === 'string' ? statusRaw.trim() : 'all';
-    const limit = parseListLimit(flags);
-    let results;
-    if (status === 'all') {
-        results = incidentsModule.loadIncidents(hippoRoot, tenantId, { limit });
-    }
-    else {
-        if (!incidentsModule.VALID_INCIDENT_STATES.has(status)) {
-            printError(`Invalid --status: "${status}". Must be one of: open | resolved | closed | all.`);
-            process.exit(1);
-        }
-        results = incidentsModule.loadIncidents(hippoRoot, tenantId, {
-            status: status,
-            limit,
-        });
-    }
-    if (results.length === 0) {
-        console.log('No incidents.');
-        return;
-    }
-    console.log(`Found ${results.length} incidents:\n`);
-    for (const inc of results) {
-        const linkPart = inc.linkedMemoryIds.length > 0 ? ` links=${inc.linkedMemoryIds.length}` : '';
-        console.log(`#${inc.id} [${inc.status}]${linkPart} memory=${inc.memoryId ?? '-'}`);
-        console.log(`    ${inc.incidentText}`);
-        if (inc.context)
-            console.log(`    context: ${inc.context}`);
-    }
+    listObjects(flags, {
+        plural: 'incidents',
+        states: incidentsModule.VALID_INCIDENT_STATES,
+        load: (opts) => incidentsModule.loadIncidents(hippoRoot, tenantId, opts),
+        printRow: printIncidentRow,
+    });
 }
 function incidentGet(hippoRoot, tenantId, args) {
-    const idRaw = args[1];
-    if (!idRaw) {
-        printError('Usage: hippo incident get <id>');
-        process.exit(1);
-    }
-    const id = parsePositiveIncidentId(idRaw);
-    const incident = incidentsModule.loadIncidentById(hippoRoot, tenantId, id);
-    if (!incident) {
-        printError(`Incident ${id} not found.`);
-        process.exit(1);
-    }
+    const id = idArgOrExit(args, 'Usage: hippo incident get <id>', INCIDENT.idLabel);
+    const incident = foundOrExit(incidentsModule.loadIncidentById(hippoRoot, tenantId, id), INCIDENT.noun, id);
     console.log(`Incident #${incident.id}`);
     console.log(`  status: ${incident.status}`);
     console.log(`  text: ${incident.incidentText}`);
@@ -434,14 +337,9 @@ function incidentGet(hippoRoot, tenantId, args) {
     console.log(`  created: ${incident.createdAt}`);
 }
 function incidentResolve(hippoRoot, tenantId, args, flags) {
-    const idRaw = args[1];
-    if (!idRaw) {
-        printError('Usage: hippo incident resolve <id> --resolution "<text>"');
-        process.exit(1);
-    }
-    const id = parsePositiveIncidentId(idRaw);
-    const resolutionRaw = flags['resolution'];
-    if (typeof resolutionRaw !== 'string' || !resolutionRaw.trim()) {
+    const id = idArgOrExit(args, 'Usage: hippo incident resolve <id> --resolution "<text>"', INCIDENT.idLabel);
+    const resolutionRaw = stringFlag(flags, 'resolution');
+    if (!resolutionRaw?.trim()) {
         printError('--resolution requires a non-empty value, e.g. hippo incident resolve <id> --resolution "root cause fixed".');
         process.exit(1);
     }
@@ -449,14 +347,7 @@ function incidentResolve(hippoRoot, tenantId, args, flags) {
     console.log(`Incident #${resolved.id} resolved.`);
 }
 function incidentClose(hippoRoot, tenantId, args) {
-    const idRaw = args[1];
-    if (!idRaw) {
-        printError('Usage: hippo incident close <id>');
-        process.exit(1);
-    }
-    const id = parsePositiveIncidentId(idRaw);
-    const closed = incidentsModule.closeIncident(hippoRoot, tenantId, id);
-    console.log(`Incident #${closed.id} closed.`);
+    closeObject(args, INCIDENT, (id) => incidentsModule.closeIncident(hippoRoot, tenantId, id));
 }
 export function cmdIncident(hippoRoot, args, flags) {
     requireInit(hippoRoot);
@@ -484,8 +375,7 @@ function incidentCreate(hippoRoot, tenantId, incidentText, flags) {
         printError('       hippo incident close <id>');
         process.exit(1);
     }
-    const contextRaw = flags['context'];
-    const context = typeof contextRaw === 'string' && contextRaw ? contextRaw : undefined;
+    const context = nonEmptyStringFlag(flags, 'context');
     // --link is a repeatable flag (collected into an array by parseArgs). A
     // single --link <id> yields a string; normalize both to string[].
     const linkRaw = flags['link'];

package/dist/cli/eval.d.ts

@@ -1,5 +1,3 @@
-import { type CommandContext } from './shared.js';
-/** Runs `hippo eval`: --bootstrap writes a corpus, --suite runs the built-in feature eval, else it scores a corpus file. */
-export declare function cmdEval(hippoRoot: string, corpusPath: string | null, flags: Record<string, string | boolean | string[]>): Promise<void>;
+import { type CommandContext } from './flag-values.js';
 export declare function handleEval({ hippoRoot, args, flags }: CommandContext): Promise<void>;
 //# sourceMappingURL=eval.d.ts.map

package/dist/cli/eval.js

@@ -2,16 +2,25 @@
 import * as path from 'path';
 import * as fs from 'fs';
 import { loadAllEntries } from '../store/entry-reads.js';
-import { loadConfig } from '../config.js';
-import { getGlobalRoot } from '../shared.js';
-import { runEval, bootstrapCorpus, compareSummaries } from '../eval.js';
-import { runFeatureEval, formatResult, resultToBaseline, detectRegressions } from '../eval-suite.js';
-import { PACKAGE_VERSION } from '../version.js';
+import { loadConfig } from '../core/config.js';
+import { getGlobalRoot } from '../sharing/shared.js';
+import { runEval, bootstrapCorpus, compareSummaries } from '../eval/eval.js';
+import { runFeatureEval, formatResult, resultToBaseline, detectRegressions } from '../eval/eval-suite.js';
+import { PACKAGE_VERSION } from '../util/version.js';
 import { printError } from './output.js';
-import { requireInit, fmt } from './shared.js';
+import { requireInit } from './shared.js';
+import { fmt } from './print.js';
+import { boolFlag } from './flag-values.js';
+import { errorMessage } from '../util/log.js';
+const HIT_TOP_K = 10;
+const MAX_FAILING_SHOWN = 10;
+const TOP_IDS_SHOWN = 3;
+const MAX_MISSED_SHOWN = 4;
+const QUERY_PREVIEW_CHARS = 60;
+const MAX_DELTAS_SHOWN = 5;
 /** Runs `hippo eval`: --bootstrap writes a corpus, --suite runs the built-in feature eval, else it scores a corpus file. */
-export async function cmdEval(hippoRoot, corpusPath, flags) {
-    const asJson = Boolean(flags['json']);
+async function cmdEval(hippoRoot, corpusPath, flags) {
+    const asJson = boolFlag(flags, 'json');
     const minMrr = flags['min-mrr'] !== undefined ? parseFloat(String(flags['min-mrr'])) : null;
     const comparePath = flags['compare'] ? String(flags['compare']) : null;
     // Suite mode doesn't need an initialized store
@@ -26,6 +35,21 @@ export async function cmdEval(hippoRoot, corpusPath, flags) {
         await runEvalSuite(hippoRoot, flags, asJson, minMrr);
         return;
     }
+    const summary = await runCorpusEval(hippoRoot, corpusPath, entries, flags);
+    if (asJson) {
+        console.log(JSON.stringify(summary, null, 2));
+    }
+    else {
+        printEvalSummary(summary, boolFlag(flags, 'show-cases'));
+    }
+    if (minMrr !== null && summary.meanMrr < minMrr) {
+        printError(`MRR ${fmt(summary.meanMrr, 4)} below threshold ${minMrr}`);
+        process.exit(1);
+    }
+    if (comparePath)
+        printEvalCompare(summary, comparePath, asJson);
+}
+async function runCorpusEval(hippoRoot, corpusPath, entries, flags) {
     const cases = readCorpus(corpusPath);
     const globalRoot = getGlobalRoot();
     const localBump = flags['equal-sources']
@@ -33,7 +57,7 @@ export async function cmdEval(hippoRoot, corpusPath, flags) {
         : flags['local-bump'] !== undefined
             ? parseFloat(String(flags['local-bump']))
             : loadConfig(hippoRoot).search.localBump;
-    const summary = await runEval(cases, entries, {
+    return runEval(cases, entries, {
         hippoRoot,
         globalRoot,
         mmr: !flags['no-mmr'],
@@ -41,18 +65,6 @@ export async function cmdEval(hippoRoot, corpusPath, flags) {
         embeddingWeight: flags['embedding-weight'] !== undefined ? parseFloat(String(flags['embedding-weight'])) : undefined,
         localBump,
     });
-    if (asJson) {
-        console.log(JSON.stringify(summary, null, 2));
-    }
-    else {
-        printEvalSummary(summary, Boolean(flags['show-cases']));
-    }
-    if (minMrr !== null && summary.meanMrr < minMrr) {
-        printError(`MRR ${fmt(summary.meanMrr, 4)} below threshold ${minMrr}`);
-        process.exit(1);
-    }
-    if (comparePath)
-        printEvalCompare(summary, comparePath, asJson);
 }
 /** Bootstrap mode: emit a synthetic corpus built from the store's own memories. */
 function writeBootstrapCorpus(entries, flags) {
@@ -119,7 +131,7 @@ function readCorpus(corpusPath) {
             throw new Error('Corpus JSON must be an array or { cases: [...] }');
     }
     catch (err) {
-        printError(`Failed to read corpus: ${err instanceof Error ? err.message : err}`);
+        printError(`Failed to read corpus: ${errorMessage(err)}`);
         process.exit(1);
     }
     return cases;
@@ -137,14 +149,14 @@ function printEvalSummary(summary, showCases) {
         for (const c of summary.cases) {
             const exp = c.case.expectedIds.length;
             const expectedSet = new Set(c.case.expectedIds);
-            const hitTop10 = c.returnedIds.slice(0, 10).filter((id) => expectedSet.has(id));
-            const missed = c.case.expectedIds.filter((id) => !c.returnedIds.slice(0, 10).includes(id));
+            const hitTop10 = c.returnedIds.slice(0, HIT_TOP_K).filter((id) => expectedSet.has(id));
+            const missed = c.case.expectedIds.filter((id) => !c.returnedIds.slice(0, HIT_TOP_K).includes(id));
             console.log();
             console.log(`[${c.case.id}] R@10=${fmt(c.recallAt10, 2)}  MRR=${fmt(c.mrr, 2)}  expected=${exp}  hit=${hitTop10.length}`);
             console.log(`  query: ${c.case.query}`);
-            console.log(`  top 3: ${c.returnedIds.slice(0, 3).join(', ') || '(none)'}`);
+            console.log(`  top 3: ${c.returnedIds.slice(0, TOP_IDS_SHOWN).join(', ') || '(none)'}`);
             if (missed.length > 0) {
-                const shown = missed.slice(0, 4);
+                const shown = missed.slice(0, MAX_MISSED_SHOWN);
                 const more = missed.length > shown.length ? ` +${missed.length - shown.length} more` : '';
                 console.log(`  missed: ${shown.join(', ')}${more}`);
             }
@@ -154,8 +166,8 @@ function printEvalSummary(summary, showCases) {
     const failing = summary.cases.filter((c) => c.mrr === 0);
     if (failing.length > 0) {
         console.log(`${failing.length} case(s) returned zero relevant results:`);
-        for (const f of failing.slice(0, 10)) {
-            console.log(`  [${f.case.id}] "${f.case.query.slice(0, 60)}"`);
+        for (const f of failing.slice(0, MAX_FAILING_SHOWN)) {
+            console.log(`  [${f.case.id}] "${f.case.query.slice(0, QUERY_PREVIEW_CHARS)}"`);
         }
         if (failing.length > 10)
             console.log(`  ...and ${failing.length - 10} more`);
@@ -171,7 +183,7 @@ function printEvalCompare(summary, comparePath, asJson) {
         baseline = JSON.parse(fs.readFileSync(comparePath, 'utf8'));
     }
     catch (err) {
-        printError(`Failed to parse baseline: ${err instanceof Error ? err.message : err}`);
+        printError(`Failed to parse baseline: ${errorMessage(err)}`);
         process.exit(1);
     }
     const cmp = compareSummaries(baseline, summary);
@@ -196,11 +208,11 @@ function printEvalCompare(summary, comparePath, asJson) {
         console.log(`  only in current:  ${cmp.onlyInCurrent.length}`);
     const showPerCase = cmp.improved.length + cmp.regressed.length > 0;
     if (showPerCase) {
-        for (const d of cmp.improved.slice(0, 5)) {
+        for (const d of cmp.improved.slice(0, MAX_DELTAS_SHOWN)) {
             const delta = d.ndcgAfter - d.ndcgBefore;
             console.log(`  + [${d.id}] NDCG ${fmt(d.ndcgBefore, 2)} -> ${fmt(d.ndcgAfter, 2)} (+${fmt(delta, 3)})`);
         }
-        for (const d of cmp.regressed.slice(0, 5)) {
+        for (const d of cmp.regressed.slice(0, MAX_DELTAS_SHOWN)) {
             const delta = d.ndcgAfter - d.ndcgBefore;
             console.log(`  - [${d.id}] NDCG ${fmt(d.ndcgBefore, 2)} -> ${fmt(d.ndcgAfter, 2)} (${fmt(delta, 3)})`);
         }

package/dist/cli/explain.d.ts

@@ -1,4 +1,4 @@
-import { type CliFlags, type CommandContext } from './shared.js';
+import { type CliFlags, type CommandContext } from './flag-values.js';
 export declare function cmdExplain(hippoRoot: string, query: string, flags: CliFlags): Promise<void>;
 export declare function handleExplain({ hippoRoot, args, flags }: CommandContext): Promise<void>;
 //# sourceMappingURL=explain.d.ts.map