hippo-memory 1.71.0 → 1.72.0

package/dist/cli/decisions.js

@@ -1,191 +1,16 @@
-// First-class object verbs for predictions, decisions and incidents.
+// First-class object verbs for decisions: record one (optionally superseding an older one's memory), list, get, close.
 import { getMemory } from '../api/memories.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 { printError } from './output.js';
-import { nonEmptyStringFlag, parseListLimit, flagIsTrue, isStringFlag, stringFlag } from './flag-values.js';
+import { nonEmptyStringFlag, flagIsTrue, stringFlag } from './flag-values.js';
 import { requireInit } from './shared.js';
 import { cliApiContext } from './api-context.js';
-import { closeObject, foundOrExit, idArgOrExit, listObjects, printLifecycleTail, requireStatus } from './object-verbs.js';
+import { closeObject, foundOrExit, idArgOrExit, listObjects, printLifecycleTail } from './object-verbs.js';
+import { parseObjectId } from './lenient-id.js';
 import { errorMessage } from '../util/log.js';
 import { CliExit } from './exit.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) {
-        printError(`Invalid ${noun} id: "${idRaw}"`);
-        throw new CliExit(1);
-    }
-    return id;
-}
-// Prediction first-class object
-function predictClose(hippoRoot, tenantId, args, flags) {
-    const id = idArgOrExit(args, 'Usage: hippo predict close <id> --state <closed|closed-unknown> [--actual <v>] [--note "..."]', 'prediction', parseObjectId);
-    const stateRaw = (stringFlag(flags, 'state') ?? '').trim();
-    // SAFETY: Set.has only compares by value, so a string outside the closure states is a plain miss.
-    if (!predictionsModule.VALID_CLOSURE_STATES.has(stateRaw) || stateRaw === 'open') {
-        printError(`Invalid --state: "${stateRaw}". Must be one of: closed | closed-unknown.`);
-        throw new CliExit(1);
-    }
-    const actualRaw = flags['actual'];
-    const actualValue = actualRaw !== undefined ? Number(actualRaw) : undefined;
-    if (actualRaw !== undefined && !Number.isFinite(actualValue)) {
-        printError(`Invalid --actual: "${actualRaw}". Must be a number.`);
-        throw new CliExit(1);
-    }
-    const closureNote = stringFlag(flags, 'note');
-    const closed = predictionsModule.closePrediction(hippoRoot, tenantId, id, {
-        // SAFETY: the check above exits unless stateRaw is in VALID_CLOSURE_STATES.
-        closureState: stateRaw,
-        actualValue,
-        closureNote,
-    });
-    console.log(`Prediction ${closed.id} closed: state=${closed.closureState}${closed.actualValue !== null ? ` actual=${closed.actualValue}` : ''}`);
-}
-function loadPredictionList(hippoRoot, tenantId, status, classTag, limit) {
-    if (status === 'open') {
-        return predictionsModule.loadOpenPredictions(hippoRoot, tenantId, {
-            classTag: classTag || undefined,
-            limit,
-        });
-    }
-    if (status === 'all') {
-        return classTag
-            ? predictionsModule.loadPredictionsByClass(hippoRoot, tenantId, classTag, { limit })
-            : predictionsModule.loadAllPredictions(hippoRoot, tenantId, { limit });
-    }
-    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.');
-        throw new CliExit(1);
-    }
-    return predictionsModule.loadPredictionsByClass(hippoRoot, tenantId, classTag, {
-        closureState,
-        limit,
-    });
-}
-function predictList(hippoRoot, tenantId, flags) {
-    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) {
-        console.log(classTag ? `No predictions in class "${classTag}".` : 'No predictions.');
-        return;
-    }
-    console.log(`Found ${results.length} predictions:\n`);
-    for (const p of results) {
-        const estPart = p.estimateValue !== null ? ` estimate=${p.estimateValue}${p.estimateUnit ? ` ${p.estimateUnit}` : ''}` : '';
-        const actPart = p.actualValue !== null ? ` actual=${p.actualValue}` : '';
-        const tgtPart = p.targetDate ? ` target=${p.targetDate}` : '';
-        console.log(`#${p.id} [${p.closureState}] class=${p.classTag}${estPart}${actPart}${tgtPart}`);
-        console.log(`    ${p.claimText}`);
-        if (p.closureNote)
-            console.log(`    note: ${p.closureNote}`);
-    }
-}
-function predictShow(hippoRoot, tenantId, args) {
-    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}`);
-    console.log(`  state: ${pred.closureState}`);
-    if (pred.estimateValue !== null)
-        console.log(`  estimate: ${pred.estimateValue}${pred.estimateUnit ? ' ' + pred.estimateUnit : ''}`);
-    if (pred.targetDate)
-        console.log(`  target: ${pred.targetDate}`);
-    if (pred.actualValue !== null)
-        console.log(`  actual: ${pred.actualValue}`);
-    if (pred.closedAt)
-        console.log(`  closed: ${pred.closedAt}`);
-    if (pred.closureNote)
-        console.log(`  note: ${pred.closureNote}`);
-    if (pred.memoryId)
-        console.log(`  memory: ${pred.memoryId}`);
-    console.log(`  created: ${pred.createdAt}`);
-}
-function predictBaserate(hippoRoot, tenantId, flags) {
-    // Reference-class / planning-fallacy detector
-    const classTag = stringFlag(flags, 'class')?.trim();
-    if (!classTag) {
-        printError('Usage: hippo predict baserate --class <c>');
-        throw new CliExit(1);
-    }
-    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`);
-        console.log(`  Close it later:  hippo predict close <id> --state closed --actual N`);
-        return;
-    }
-    console.log(baserate.summary);
-    console.log(`  n_closed:         ${baserate.nClosed}`);
-    console.log(`  n_ratio_eligible: ${baserate.nRatioEligible}`);
-    if (baserate.meanEstimate !== null)
-        console.log(`  mean_estimate:    ${baserate.meanEstimate.toFixed(BASERATE_DECIMALS)}`);
-    if (baserate.meanActual !== null)
-        console.log(`  mean_actual:      ${baserate.meanActual.toFixed(BASERATE_DECIMALS)}`);
-    if (baserate.meanRatio !== null)
-        console.log(`  mean_ratio:       ${baserate.meanRatio.toFixed(BASERATE_DECIMALS)}x`);
-    if (baserate.p50Ratio !== null)
-        console.log(`  p50_ratio:        ${baserate.p50Ratio.toFixed(BASERATE_DECIMALS)}x`);
-    if (baserate.mae !== null)
-        console.log(`  mae:              ${baserate.mae.toFixed(BASERATE_DECIMALS)}`);
-}
-export function handlePredict({ hippoRoot, tenantId, args, flags }) {
-    requireInit(hippoRoot);
-    const subcommand = args[0] ?? '';
-    if (subcommand === 'close')
-        return predictClose(hippoRoot, tenantId, args, flags);
-    if (subcommand === 'list')
-        return predictList(hippoRoot, tenantId, flags);
-    if (subcommand === 'show')
-        return predictShow(hippoRoot, tenantId, args);
-    if (subcommand === 'baserate')
-        return predictBaserate(hippoRoot, tenantId, flags);
-    // Default subcommand: create. args[0] is the claim text.
-    predictCreate(hippoRoot, tenantId, subcommand, flags);
-}
-function predictCreate(hippoRoot, tenantId, claimText, flags) {
-    if (!claimText) {
-        printError('Usage: hippo predict "<claim>" --class <c> [--estimate <v>] [--unit <u>] [--target <YYYY-MM-DD>]');
-        printError('       hippo predict close <id> --state <closed|closed-unknown> [--actual <v>] [--note "..."]');
-        printError('       hippo predict list [--class X] [--status open|closed|closed-unknown|all] [--limit N]');
-        printError('       hippo predict show <id>');
-        throw new CliExit(1);
-    }
-    const classTag = stringFlag(flags, 'class')?.trim();
-    if (!classTag) {
-        printError('--class is required for prediction creation.');
-        throw new CliExit(1);
-    }
-    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.`);
-        throw new CliExit(1);
-    }
-    const estimateUnit = stringFlag(flags, 'unit');
-    const targetDate = stringFlag(flags, 'target');
-    const created = predictionsModule.savePrediction(hippoRoot, tenantId, {
-        classTag,
-        claimText,
-        estimateValue,
-        estimateUnit,
-        targetDate,
-    });
-    console.log(`Prediction recorded: #${created.id} class=${created.classTag}`);
-    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 ?? '-'}`);
@@ -288,106 +113,4 @@ function printSupersedes(supersedesMemId, supersedesDecisionId) {
         : ' (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) {
-    listObjects(flags, {
-        plural: 'incidents',
-        states: incidentsModule.VALID_INCIDENT_STATES,
-        load: (opts) => incidentsModule.loadIncidents(hippoRoot, tenantId, opts),
-        printRow: printIncidentRow,
-    });
-}
-function incidentGet(hippoRoot, tenantId, args) {
-    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}`);
-    if (incident.context)
-        console.log(`  context: ${incident.context}`);
-    if (incident.resolutionText)
-        console.log(`  resolution: ${incident.resolutionText}`);
-    if (incident.resolvedAt)
-        console.log(`  resolved_at: ${incident.resolvedAt}`);
-    if (incident.closedAt)
-        console.log(`  closed_at: ${incident.closedAt}`);
-    if (incident.linkedMemoryIds.length > 0) {
-        console.log(`  linked memories: ${incident.linkedMemoryIds.join(', ')}`);
-    }
-    if (incident.memoryId)
-        console.log(`  memory: ${incident.memoryId}`);
-    console.log(`  created: ${incident.createdAt}`);
-}
-function incidentResolve(hippoRoot, tenantId, args, flags) {
-    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".');
-        throw new CliExit(1);
-    }
-    const resolved = incidentsModule.resolveIncident(hippoRoot, tenantId, id, resolutionRaw);
-    console.log(`Incident #${resolved.id} resolved.`);
-}
-function incidentClose(hippoRoot, tenantId, args) {
-    closeObject(args, INCIDENT, (id) => incidentsModule.closeIncident(hippoRoot, tenantId, id));
-}
-export function handleIncident({ hippoRoot, tenantId, args, flags }) {
-    requireInit(hippoRoot);
-    const subcommand = args[0] ?? '';
-    if (subcommand === 'list')
-        return incidentList(hippoRoot, tenantId, flags);
-    if (subcommand === 'get')
-        return incidentGet(hippoRoot, tenantId, args);
-    if (subcommand === 'resolve')
-        return incidentResolve(hippoRoot, tenantId, args, flags);
-    if (subcommand === 'close')
-        return incidentClose(hippoRoot, tenantId, args);
-    // Default subcommand is open (create): accept both `incident open "<text>"` and bare `incident "<text>"`;
-    // for the `open` keyword the text is args[1], otherwise args[0] is the text.
-    incidentCreate(hippoRoot, tenantId, subcommand === 'open' ? (args[1] ?? '') : subcommand, flags);
-}
-function incidentCreate(hippoRoot, tenantId, incidentText, flags) {
-    if (!incidentText) {
-        printError('Usage: hippo incident "<incident>" [--context "<details>"] [--link <memory-id>]...');
-        printError('       hippo incident list [--status open|resolved|closed|all] [--limit N]');
-        printError('       hippo incident get <id>');
-        printError('       hippo incident resolve <id> --resolution "<text>"');
-        printError('       hippo incident close <id>');
-        throw new CliExit(1);
-    }
-    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'];
-    let linkedMemoryIds;
-    if (Array.isArray(linkRaw)) {
-        linkedMemoryIds = linkRaw;
-    }
-    else if (isStringFlag(linkRaw)) {
-        linkedMemoryIds = [linkRaw];
-    }
-    else if (linkRaw === true) {
-        printError('--link requires a memory id, e.g. hippo incident "<text>" --link mem_abc123.');
-        throw new CliExit(1);
-    }
-    const incidentPathTags = extractPathTags(process.cwd());
-    const created = incidentsModule.saveIncident(hippoRoot, tenantId, {
-        incidentText,
-        context,
-        linkedMemoryIds,
-        extraTags: incidentPathTags,
-    });
-    console.log(`Incident recorded: #${created.id}`);
-    if (created.memoryId)
-        console.log(`  memory: ${created.memoryId}`);
-    if (created.linkedMemoryIds.length > 0) {
-        console.log(`  linked memories: ${created.linkedMemoryIds.join(', ')}`);
-    }
-}
 //# sourceMappingURL=decisions.js.map

package/dist/cli/eval.d.ts

@@ -1,3 +1,3 @@
 import { type CommandContext } from './flag-values.js';
-export declare function handleEval({ hippoRoot, args, flags }: CommandContext): Promise<void>;
+export declare function handleEval({ hippoRoot, tenantId, args, flags }: CommandContext): Promise<void>;
 //# sourceMappingURL=eval.d.ts.map

package/dist/cli/eval.js

@@ -1,7 +1,8 @@
 // The `hippo eval` verb; main() loads it lazily from the command table.
 import * as path from 'path';
 import * as fs from 'fs';
-import { loadAllEntries } from '../store/entry-reads.js';
+import { listMemories } from '../api/memories.js';
+import { cliApiContext } from './api-context.js';
 import { loadConfig } from '../core/config.js';
 import { getGlobalRoot } from '../sharing/global-store.js';
 import { runEval, bootstrapCorpus, compareSummaries } from '../eval/eval.js';
@@ -10,7 +11,7 @@ import { PACKAGE_VERSION } from '../util/version.js';
 import { printError } from './output.js';
 import { requireInit } from './shared.js';
 import { fmt } from './print.js';
-import { boolFlag } from './flag-values.js';
+import { boolFlag, numberFlag } from './flag-values.js';
 import { errorMessage } from '../util/log.js';
 import { CliExit } from './exit.js';
 const HIT_TOP_K = 10;
@@ -20,14 +21,14 @@ 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. */
-async function cmdEval(hippoRoot, corpusPath, flags) {
+async function cmdEval(hippoRoot, tenantId, corpusPath, flags) {
     const asJson = boolFlag(flags, 'json');
-    const minMrr = flags['min-mrr'] !== undefined ? parseFloat(String(flags['min-mrr'])) : null;
+    const minMrr = numberFlag(flags, 'min-mrr') ?? null;
     const comparePath = flags['compare'] ? String(flags['compare']) : null;
     // Suite mode doesn't need an initialized store
     if (!flags['suite'])
         requireInit(hippoRoot);
-    const entries = flags['suite'] ? [] : loadAllEntries(hippoRoot);
+    const entries = flags['suite'] ? [] : listMemories(cliApiContext(hippoRoot, tenantId), { everyTenant: true });
     if (flags['bootstrap']) {
         writeBootstrapCorpus(entries, flags);
         return;
@@ -55,22 +56,20 @@ async function runCorpusEval(hippoRoot, corpusPath, entries, flags) {
     const globalRoot = getGlobalRoot();
     const localBump = flags['equal-sources']
         ? 1.0
-        : flags['local-bump'] !== undefined
-            ? parseFloat(String(flags['local-bump']))
-            : loadConfig(hippoRoot).search.localBump;
+        : numberFlag(flags, 'local-bump') ?? loadConfig(hippoRoot).search.localBump;
     return runEval(cases, entries, {
         hippoRoot,
         globalRoot,
         mmr: !flags['no-mmr'],
-        mmrLambda: flags['mmr-lambda'] !== undefined ? parseFloat(String(flags['mmr-lambda'])) : undefined,
-        embeddingWeight: flags['embedding-weight'] !== undefined ? parseFloat(String(flags['embedding-weight'])) : undefined,
+        mmrLambda: numberFlag(flags, 'mmr-lambda'),
+        embeddingWeight: numberFlag(flags, 'embedding-weight'),
         localBump,
     });
 }
 /** Bootstrap mode: emit a synthetic corpus built from the store's own memories. */
 function writeBootstrapCorpus(entries, flags) {
     const outPath = flags['out'] ? String(flags['out']) : null;
-    const max = flags['max-cases'] !== undefined ? parseInt(String(flags['max-cases']), 10) : 50;
+    const max = numberFlag(flags, 'max-cases') ?? 50;
     const corpus = bootstrapCorpus(entries, max);
     const payload = JSON.stringify({ cases: corpus }, null, 2);
     if (outPath) {
@@ -220,8 +219,8 @@ function printEvalCompare(summary, comparePath, asJson) {
         }
     }
 }
-export async function handleEval({ hippoRoot, args, flags }) {
+export async function handleEval({ hippoRoot, tenantId, args, flags }) {
     const corpusPath = args[0] ? String(args[0]) : null;
-    await cmdEval(hippoRoot, corpusPath, flags);
+    await cmdEval(hippoRoot, tenantId, corpusPath, flags);
 }
 //# sourceMappingURL=eval.js.map

package/dist/cli/explain.d.ts

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

package/dist/cli/explain.js

@@ -1,15 +1,12 @@
 // The `hippo explain` verb; main() loads it lazily from the command table.
 import { confidenceFacets } from '../core/memory.js';
-import { isInitialized } from '../store/open.js';
-import { loadSearchEntries } from '../store/search-rows.js';
-import { loadIndex } from '../store/index-and-stats.js';
 import { DEFAULT_RECALL_BUDGET } from '../core/search-types.js';
 import { loadConfig } from '../core/config.js';
 import { dropHeldCopies } from '../util/same-text.js';
-import { detectScope } from '../sharing/scope.js';
+import { detectScope } from '../core/active-scope.js';
 import { getGlobalRoot } from '../sharing/global-store.js';
 import * as api from '../api/index.js';
-import { resolveTenantId } from '../store/tenant.js';
+import { cliRecallOrigin, scopeHiddenCount } from '../api/recall-cli.js';
 import { cliApiContext } from './api-context.js';
 import { printedTokens } from '../api/context-render.js';
 import { printError } from './output.js';
@@ -19,18 +16,13 @@ import { fmt, recallEntryText, recallHeading } from './print.js';
 import { CliExit } from './exit.js';
 const EXPLAIN_PREVIEW_CHARS = 48;
 /** The SQL predicate drops denied rows before the window, so an unscoped probe counts what the policy hides. */
-function noteScopeHidden(hippoRoot, globalRoot, query, tenantId, requested) {
-    const probe = [
-        ...loadSearchEntries(hippoRoot, query, undefined, tenantId),
-        ...(globalRoot ? loadSearchEntries(globalRoot, query, undefined, tenantId) : []),
-    ];
-    // Window-capped, so the count is a floor on large stores; fine for a "why is my row missing" hint.
-    const hidden = probe.filter((e) => !api.passesCliRecallScopeFilter(e.scope ?? null, requested)).length;
+function noteScopeHidden(ctx, globalRoot, query, requested) {
+    const hidden = scopeHiddenCount(ctx, query, globalRoot, requested);
     if (hidden > 0) {
         printError(`[note] ${hidden} candidate${hidden === 1 ? '' : 's'} hidden by recall scope policy (pass an explicit --scope to inspect).`);
     }
 }
-async function cmdExplain(hippoRoot, query, flags) {
+async function cmdExplain(hippoRoot, tenantId, query, flags) {
     requireInit(hippoRoot);
     const budget = parseBudgetFlag(flags['budget'], DEFAULT_RECALL_BUDGET);
     const limit = parseLimitFlag(flags['limit']);
@@ -38,25 +30,26 @@ async function cmdExplain(hippoRoot, query, flags) {
     const includeSuperseded = boolFlag(flags, 'include-superseded');
     const asOf = parseAsOfFlag(flags);
     const globalRoot = getGlobalRoot();
-    const tenantId = resolveTenantId({});
+    const ctx = cliApiContext(hippoRoot, tenantId);
     // Explain shows what recall would see, so it applies the same scope rule.
     const explicitScope = flags['scope'] !== undefined ? String(flags['scope']).trim() : null;
+    const activeScope = explicitScope || detectScope();
     // Unlike recall, explain reads the global store whenever it exists, even when it is the local root.
-    const explainGlobalOn = isInitialized(globalRoot);
-    noteScopeHidden(hippoRoot, explainGlobalOn ? globalRoot : undefined, query, tenantId, explicitScope || undefined);
+    const origin = cliRecallOrigin(ctx, { globalRoot, primaryIsGlobal: false, activeScope });
+    const explainGlobalOn = origin.globalOn;
+    noteScopeHidden(ctx, explainGlobalOn ? globalRoot : undefined, query, explicitScope || undefined);
     const config = loadConfig(hippoRoot);
     const engine = engineFlags(flags, config);
     // Priced as recall prints each result, so explain returns what recall's engines would.
-    const explainIndex = loadIndex(hippoRoot);
-    const cost = (r) => printedTokens(recallEntryText(r, query, false, explainGlobalOn && !explainIndex.entries[r.entry.id]));
+    const cost = (r) => printedTokens(recallEntryText(r, query, false, origin.isGlobal(r.entry.id)));
     const entryBudget = Math.max(0, budget - printedTokens(recallHeading(budget, budget, query)));
     const slot = {};
-    await api.retrieve(cliApiContext(hippoRoot, tenantId), {
+    await api.retrieve(ctx, {
         query,
         cliCore: {
             rank: {
                 budget: entryBudget, cost, limit, includeSuperseded, asOf,
-                explicitScope, activeScope: explicitScope || detectScope(),
+                explicitScope, activeScope,
                 search: { ...engine, multihop: false, explain: true },
             },
             sources: { globalRoot: explainGlobalOn ? globalRoot : undefined },
@@ -119,7 +112,8 @@ function printExplainTable(results, query, modeUsed, candidates) {
         const b = r.breakdown;
         const preview = r.entry.content.replace(/\s+/g, ' ').slice(0, EXPLAIN_PREVIEW_CHARS);
         const ageStr = b ? `${b.ageDays}d` : '?';
-        console.log(`${String(i + 1).padEnd(5)} ${fmt(r.score, 3).padEnd(7)} ${fmt(r.entry.strength).padEnd(9)} ${ageStr.padEnd(6)} ${r.entry.layer.padEnd(10)} ${r.entry.id.padEnd(17)} ${preview}`);
+        console.log(`${String(i + 1).padEnd(5)} ${fmt(r.score, 3).padEnd(7)} ${fmt(r.entry.strength).padEnd(9)} ${ageStr.padEnd(6)} ` +
+            `${r.entry.layer.padEnd(10)} ${r.entry.id.padEnd(17)} ${preview}`);
     }
     console.log();
 }
@@ -152,8 +146,10 @@ function printExplainBreakdown(r, i) {
             console.log(`    path:      x${fmt(b.pathBoost, 3)}  (cwd path tag overlap)`);
         if (b.sourceBump !== 1)
             console.log(`    source:    x${fmt(b.sourceBump, 2)}  (local priority bump over global)`);
-        if (b.outcomeBoost !== 1)
-            console.log(`    outcome:   x${fmt(b.outcomeBoost, 3)}  (user feedback: pos-neg = ${(r.entry.outcome_positive ?? 0) - (r.entry.outcome_negative ?? 0)})`);
+        if (b.outcomeBoost !== 1) {
+            console.log(`    outcome:   x${fmt(b.outcomeBoost, 3)}  ` +
+                `(user feedback: pos-neg = ${(r.entry.outcome_positive ?? 0) - (r.entry.outcome_negative ?? 0)})`);
+        }
         if (b.churnStaleMultiplier !== 1)
             console.log(`    churn:     x${fmt(b.churnStaleMultiplier, 2)}  (tagged 'churn-stale')`);
         if (b.preMmrRank !== undefined && b.postMmrRank !== undefined && b.preMmrRank !== b.postMmrRank) {
@@ -164,12 +160,12 @@ function printExplainBreakdown(r, i) {
     }
     console.log();
 }
-export async function handleExplain({ hippoRoot, args, flags }) {
+export async function handleExplain({ hippoRoot, tenantId, args, flags }) {
     const query = args.join(' ').trim();
     if (!query) {
         printError('Please provide a search query.');
         throw new CliExit(1);
     }
-    await cmdExplain(hippoRoot, query, flags);
+    await cmdExplain(hippoRoot, tenantId, query, flags);
 }
 //# sourceMappingURL=explain.js.map

package/dist/cli/flag-values.js

@@ -1,4 +1,5 @@
 // Readers that turn parsed CLI flags into typed values, and the flag types they share.
+import { resolveListLimit } from '../util/limits.js';
 import { printError } from './output.js';
 import { CliExit } from './exit.js';
 export function isBooleanFlag(value) {
@@ -35,7 +36,8 @@ export function parseBudgetFlag(value, fallback) {
     }
     return parsed;
 }
-// Whole-arg digits only: parseInt alone reads "1abc" as 1 and a mutating verb would hit the wrong row. Digits past 2^53 round to a neighbouring id, so they are refused too.
+// Whole-arg digits only: parseInt alone reads "1abc" as 1 and a mutating verb would hit the wrong row.
+// Digits past 2^53 round to a neighbouring id, so they are refused too.
 export function parsePositiveId(idRaw, label) {
     const s = String(idRaw ?? '').trim();
     const id = parseInt(s, 10);
@@ -47,8 +49,8 @@ export function parsePositiveId(idRaw, label) {
 }
 export function parseListLimit(flags) {
     const limitRaw = flags['limit'];
-    const limit = limitRaw !== undefined ? parseInt(String(limitRaw), 10) : 100;
-    if (!Number.isFinite(limit) || limit <= 0) {
+    const limit = resolveListLimit(limitRaw !== undefined ? parseInt(String(limitRaw), 10) : undefined);
+    if (limit === undefined) {
         printError(`Invalid --limit: "${limitRaw}". Must be a positive integer.`);
         throw new CliExit(1);
     }
@@ -73,9 +75,17 @@ export function stringListFlag(flags, name) {
 export function isOneOf(allowed, value) {
     return allowed.some((a) => a === value);
 }
+// A junk value exits instead of becoming NaN, which would pass every `<` gate.
 export function numberFlag(flags, name) {
     const v = flags[name];
-    return isStringFlag(v) ? Number(v) : undefined;
+    if (!isStringFlag(v))
+        return undefined;
+    const parsed = Number(v);
+    if (v.trim() === '' || !Number.isFinite(parsed)) {
+        printError(`Invalid --${name}: "${v}". Must be a number.`);
+        throw new CliExit(1);
+    }
+    return parsed;
 }
 // Any truthy value counts, so a string value is true too.
 export function boolFlag(flags, name) {
@@ -99,10 +109,10 @@ export function engineFlags(flags, config) {
         usePhysics: boolFlag(flags, 'physics') || (!flags['classic'] && config.physics.enabled !== false),
         physicsConfig: config.physics,
         mmr: !flags['no-mmr'] && config.mmr.enabled,
-        mmrLambda: flags['mmr-lambda'] !== undefined ? parseFloat(String(flags['mmr-lambda'])) : config.mmr.lambda,
+        mmrLambda: numberFlag(flags, 'mmr-lambda') ?? config.mmr.lambda,
         localBump: flags['equal-sources']
             ? 1.0
-            : flags['local-bump'] !== undefined ? parseFloat(String(flags['local-bump'])) : config.search.localBump,
+            : numberFlag(flags, 'local-bump') ?? config.search.localBump,
     };
 }
 // parseArgs turns a value-less flag into `true`; refuse rather than silently