hippo-memory 1.68.0 → 1.70.0

package/dist/doctor.js

@@ -7,18 +7,21 @@
 import * as fs from 'node:fs';
 import * as os from 'node:os';
 import * as path from 'node:path';
-import { findHippoStoreDir } from './project-identity.js';
-import { getGlobalRoot } from './shared.js';
+import { findHippoStoreDir } from './core/project-identity.js';
+import { getGlobalRoot } from './sharing/shared.js';
 import { isInitialized } from './store/open.js';
-import { loadConfig } from './config.js';
-import { openHippoDbReadOnly, closeHippoDb, getSchemaVersion, getCurrentSchemaVersion, countTableRows, ftsRowCounts, IncompatibleBinaryError } from './db.js';
-import { REPLAY_AFTER_MS, TRANSCRIPT_FILL_WINDOW_MS } from './compaction-record.js';
-import { SPOOL_DIR, spoolCounts } from './compaction-spool.js';
-import { isEmbeddingAvailable } from './local-embedding.js';
-import { CODEX_TRUST_LINE, claudeConfigDir, codexHomeDir, isCodexPresent, isJsonObject } from './hooks/shared.js';
-import { planProjectRepair } from './project-merge.js';
-import { resolveTenantId } from './tenant.js';
-import { readJsonFile } from './json.js';
+import { readStoreHealth } from './store/diagnostics.js';
+import { loadConfig } from './core/config.js';
+import { openHippoDbReadOnly, closeHippoDb, getCurrentSchemaVersion, IncompatibleBinaryError } from './db/index.js';
+import { REPLAY_AFTER_MS, TRANSCRIPT_FILL_WINDOW_MS } from './capture/compaction-record.js';
+import { SPOOL_DIR, spoolCounts } from './capture/compaction-spool.js';
+import { isEmbeddingAvailable } from './store/embeddings/local.js';
+import { CODEX_TRUST_LINE, claudeConfigDir, codexHomeDir, isCodexPresent } from './hooks/shared.js';
+import { planProjectRepair } from './sharing/project-merge.js';
+import { resolveTenantId } from './store/tenant.js';
+import { errorMessage, log } from './util/log.js';
+import { readJsonFile, isJsonObjectLiteral } from './util/json.js';
+import { DAY_MS } from './util/time.js';
 /** Minimum Node.js version hippo supports (package.json engines). */
 export const MIN_NODE = '22.16.0';
 function versionAtLeast(actual, min) {
@@ -46,7 +49,7 @@ function codexCheck(home) {
     const file = path.join(codexHomeDir(home), 'hooks.json');
     const parsed = readJson(file);
     // Codex drops every hook in a hooks.json it cannot parse, hippo's included.
-    if (fs.existsSync(file) && !isJsonObject(parsed)) {
+    if (fs.existsSync(file) && !isJsonObjectLiteral(parsed)) {
         return { id: 'codex', status: 'warn', detail: "Codex's hooks.json is not a JSON object, so Codex runs no hook from it", fix: 'repair hooks.json, then run: hippo hook install codex' };
     }
     const text = JSON.stringify(parsed ?? '');
@@ -67,40 +70,30 @@ function codexCheck(home) {
 // Migration 46 creates failure_log; a read-only open no longer creates it on an older store.
 const FAILURE_LOG_SCHEMA = 46;
 /** The failed-tool-call count over the last 7 days, or why it could not be read. */
-function failuresCheck(db, since, schemaVersion) {
-    try {
-        // SAFETY: COUNT aggregate row.
-        const row = db.prepare(`SELECT COUNT(*) AS n FROM failure_log WHERE ts >= ?`).get(since);
-        return { id: 'failures', status: 'info', detail: `${Number(row?.n ?? 0)} failed tool calls logged in 7 days (hippo failures for detail)` };
+function failuresCheck(failures, schemaVersion) {
+    if (failures.ok) {
+        return { id: 'failures', status: 'info', detail: `${failures.value} failed tool calls logged in 7 days (hippo failures for detail)` };
     }
-    catch (err) {
-        const message = err instanceof Error ? err.message : String(err);
-        if (!message.includes('no such table')) {
-            return { id: 'failures', status: 'warn', detail: `cannot read the failure log: ${message}` };
-        }
-        return schemaVersion < FAILURE_LOG_SCHEMA
-            ? { id: 'failures', status: 'info', detail: 'no failure log yet (hippo creates it on the next write)' }
-            : { id: 'failures', status: 'warn', detail: 'the failure_log table is missing, so failed tool calls are not being logged' };
+    if (!failures.message.includes('no such table')) {
+        return { id: 'failures', status: 'warn', detail: `cannot read the failure log: ${failures.message}` };
     }
+    return schemaVersion < FAILURE_LOG_SCHEMA
+        ? { id: 'failures', status: 'info', detail: 'no failure log yet (hippo creates it on the next write)' }
+        : { id: 'failures', status: 'warn', detail: 'the failure_log table is missing, so failed tool calls are not being logged' };
 }
 /** How long ago the store last slept (consolidated), or why that history could not be read. */
-function sleepCheck(db, now) {
-    try {
-        // SAFETY: row's shape matches the single `timestamp` column named in the SELECT above.
-        const row = db.prepare(`SELECT timestamp FROM consolidation_runs ORDER BY timestamp DESC, id DESC LIMIT 1`).get();
-        const when = row?.timestamp !== undefined ? Date.parse(row.timestamp) : Number.NaN;
-        if (Number.isNaN(when)) {
-            return { id: 'sleep', status: 'warn', detail: 'hippo has never slept (consolidated) in this store', fix: 'hippo sleep   (the session-end hook runs it automatically)' };
-        }
-        const days = Math.floor((now.getTime() - when) / 86_400_000);
-        return days > 7
-            ? { id: 'sleep', status: 'warn', detail: `last sleep ${days} days ago`, fix: 'hippo sleep, and check the session-end hook is installed' }
-            : { id: 'sleep', status: 'pass', detail: `last sleep ${days === 0 ? 'today' : `${days} day${days === 1 ? '' : 's'} ago`}` };
-    }
-    catch (err) {
-        const message = err instanceof Error ? err.message : String(err);
-        return { id: 'sleep', status: 'info', detail: `sleep history unavailable (${message})` };
-    }
+function sleepCheck(lastSleep, now) {
+    if (!lastSleep.ok)
+        return { id: 'sleep', status: 'info', detail: `sleep history unavailable (${lastSleep.message})` };
+    const last = lastSleep.value;
+    const when = last !== undefined ? Date.parse(last) : Number.NaN;
+    if (Number.isNaN(when)) {
+        return { id: 'sleep', status: 'warn', detail: 'hippo has never slept (consolidated) in this store', fix: 'hippo sleep   (the session-end hook runs it automatically)' };
+    }
+    const days = Math.floor((now.getTime() - when) / DAY_MS);
+    return days > 7
+        ? { id: 'sleep', status: 'warn', detail: `last sleep ${days} days ago`, fix: 'hippo sleep, and check the session-end hook is installed' }
+        : { id: 'sleep', status: 'pass', detail: `last sleep ${days === 0 ? 'today' : `${days} day${days === 1 ? '' : 's'} ago`}` };
 }
 /** Spool counts in their own try, so a spool that cannot be read never hides the database counts. */
 function readSpool(store, now) {
@@ -108,44 +101,32 @@ function readSpool(store, now) {
         return { counts: spoolCounts(store, now, REPLAY_AFTER_MS), unread: '' };
     }
     catch (err) {
-        return { counts: { waiting: 0, stale: 0, bad: 0 }, unread: `; spool not read: ${err instanceof Error ? err.message : String(err)}` };
+        return { counts: { waiting: 0, stale: 0, bad: 0 }, unread: `; spool not read: ${errorMessage(err)}` };
     }
 }
 /** Compaction records the PostCompact hook left unfinished and spool files a replay has not finished, which `hippo sleep` replays. */
-function compactionsCheck(db, store, now) {
-    const stuckBefore = new Date(now.getTime() - REPLAY_AFTER_MS).toISOString();
-    const transcriptFloor = new Date(now.getTime() - TRANSCRIPT_FILL_WINDOW_MS).toISOString();
-    try {
-        // SAFETY: COUNT aggregate row.
-        const row = db.prepare(`SELECT COUNT(*) AS total,
-              COUNT(CASE WHEN status = 'summarised' AND summarised_at < ? THEN 1 END) AS summarised,
-              COUNT(CASE WHEN status = 'started' AND started_at < ? AND started_at > ? AND transcript_path IS NOT NULL THEN 1 END) AS started
-       FROM compactions`).get(stuckBefore, stuckBefore, transcriptFloor);
-        const total = Number(row?.total ?? 0);
-        const summarised = Number(row?.summarised ?? 0);
-        const started = Number(row?.started ?? 0);
-        const stuck = summarised + started;
-        const { counts: spool, unread } = readSpool(store, now);
-        const spooled = spool.waiting + spool.stale + spool.bad > 0;
-        const recorded = `${total} compaction${total === 1 ? '' : 's'} recorded, none stuck`;
-        if (stuck === 0 && !spooled && unread === '')
-            return { id: 'compactions', status: 'pass', detail: recorded };
-        const fix = [
-            stuck + spool.waiting + spool.stale > 0 ? 'hippo sleep   (replays them)' : '',
-            spool.bad > 0 ? `open the .bad files in ${path.join(store, SPOOL_DIR)}, save what you still need with hippo remember, then delete them` : '',
-        ].filter((s) => s !== '');
-        const unfinished = stuck === 0
-            ? `${recorded} in the store`
-            : `${stuck} compaction${stuck === 1 ? '' : 's'} unfinished after 10 minutes (${summarised} with a summary whose memories are not saved yet, ${started} with no summary yet)`;
-        const note = spooled ? `; spool: ${spool.waiting} waiting, ${spool.stale} left by a replay that stopped, ${spool.bad} .bad` : '';
-        return { id: 'compactions', status: 'warn', detail: `${unfinished}${note}${unread}`, fix: fix.join('; ') };
-    }
-    catch (err) {
-        const message = err instanceof Error ? err.message : String(err);
-        return message.includes('no such table')
+function compactionsCheck(compactions, store, now) {
+    if (!compactions.ok) {
+        return compactions.message.includes('no such table')
             ? { id: 'compactions', status: 'info', detail: 'no compaction records yet (hippo creates them on the next write)' }
-            : { id: 'compactions', status: 'warn', detail: `cannot read the compaction records: ${message}` };
-    }
+            : { id: 'compactions', status: 'warn', detail: `cannot read the compaction records: ${compactions.message}` };
+    }
+    const { total, summarised, started } = compactions.value;
+    const stuck = summarised + started;
+    const { counts: spool, unread } = readSpool(store, now);
+    const spooled = spool.waiting + spool.stale + spool.bad > 0;
+    const recorded = `${total} compaction${total === 1 ? '' : 's'} recorded, none stuck`;
+    if (stuck === 0 && !spooled && unread === '')
+        return { id: 'compactions', status: 'pass', detail: recorded };
+    const fix = [
+        stuck + spool.waiting + spool.stale > 0 ? 'hippo sleep   (replays them)' : '',
+        spool.bad > 0 ? `open the .bad files in ${path.join(store, SPOOL_DIR)}, save what you still need with hippo remember, then delete them` : '',
+    ].filter((s) => s !== '');
+    const unfinished = stuck === 0
+        ? `${recorded} in the store`
+        : `${stuck} compaction${stuck === 1 ? '' : 's'} unfinished after 10 minutes (${summarised} with a summary whose memories are not saved yet, ${started} with no summary yet)`;
+    const note = spooled ? `; spool: ${spool.waiting} waiting, ${spool.stale} left by a replay that stopped, ${spool.bad} .bad` : '';
+    return { id: 'compactions', status: 'warn', detail: `${unfinished}${note}${unread}`, fix: fix.join('; ') };
 }
 /** Old project tags in the global store, counted by the repair's own plan so a truly user-global merge never warns. */
 function projectsCheck(globalRoot) {
@@ -164,7 +145,7 @@ function projectsCheck(globalRoot) {
             : { id: 'projects', status: 'warn', detail: `global store: ${found.join('; ')}`, fix: 'hippo projects repair --global   (dry run; add --apply to write)' };
     }
     catch (err) {
-        return { id: 'projects', status: 'info', detail: `project tags not checked (${err instanceof Error ? err.message : String(err)})` };
+        return { id: 'projects', status: 'info', detail: `project tags not checked (${errorMessage(err)})` };
     }
     finally {
         if (db !== null)
@@ -197,9 +178,7 @@ function schemaCheck(have, want) {
             ? { id: 'schema', status: 'fail', detail: `database schema v${have} is newer than this hippo (v${want})`, fix: 'npm install -g hippo-memory@latest' }
             : { id: 'schema', status: 'info', detail: `database schema v${have}; hippo migrates it to v${want} on the next write` };
 }
-function memoriesCheck(db) {
-    const memories = countTableRows(db, 'memories');
-    const dormant = countTableRows(db, 'dormant_memories');
+function memoriesCheck(memories, dormant) {
     const memoryCheck = { id: 'memories', status: 'info', detail: `${memories ?? '?'} memories${dormant !== null ? `, ${dormant} dormant` : ''}` };
     if (memories === 0) {
         memoryCheck.status = 'warn';
@@ -208,70 +187,60 @@ function memoriesCheck(db) {
     return memoryCheck;
 }
 /** Whether the full-text index still matches `memories`; opening a current store no longer checks, so doctor reports and sleep repairs. */
-function ftsCheck(db) {
-    try {
-        const counts = ftsRowCounts(db);
-        if (counts === null)
-            return { id: 'fts', status: 'info', detail: 'no full-text index; search uses slower LIKE matching' };
-        if (counts.memories === counts.fts)
-            return { id: 'fts', status: 'pass', detail: `full-text index in sync (${counts.fts} rows)` };
-        return {
-            id: 'fts',
-            status: 'warn',
-            detail: `full-text index out of sync: ${counts.fts} indexed rows for ${counts.memories} memories, so search can miss memories or match removed ones`,
-            fix: 'hippo sleep   (re-syncs the index)',
-        };
-    }
-    catch (err) {
-        return { id: 'fts', status: 'warn', detail: `cannot read the full-text index: ${err instanceof Error ? err.message : String(err)}` };
-    }
+function ftsCheck(fts) {
+    if (!fts.ok)
+        return { id: 'fts', status: 'warn', detail: `cannot read the full-text index: ${fts.message}` };
+    const counts = fts.value;
+    if (counts === null)
+        return { id: 'fts', status: 'info', detail: 'no full-text index; search uses slower LIKE matching' };
+    if (counts.memories === counts.fts)
+        return { id: 'fts', status: 'pass', detail: `full-text index in sync (${counts.fts} rows)` };
+    return {
+        id: 'fts',
+        status: 'warn',
+        detail: `full-text index out of sync: ${counts.fts} indexed rows for ${counts.memories} memories, so search can miss memories or match removed ones`,
+        fix: 'hippo sleep   (re-syncs the index)',
+    };
 }
-function tokensCheck(db, since) {
-    try {
-        // SAFETY: COUNT/SUM aggregate row.
-        const row = db.prepare(`SELECT COUNT(CASE WHEN event = 'inject' THEN 1 END) AS n,
-              COALESCE(SUM(CASE WHEN event = 'inject' THEN tokens END), 0) AS t,
-              COALESCE(SUM(CASE WHEN event = 'reread' THEN tokens END), 0) AS r
-       FROM token_ledger WHERE ts >= ?`).get(since);
-        return {
-            id: 'tokens',
-            status: 'info',
-            detail: `${Number(row?.n ?? 0)} memory blocks sent to agents in 7 days, about ${Number(row?.t ?? 0)} tokens sent and ${Number(row?.r ?? 0)} re-read by later model calls (hippo tokens for detail)`,
-        };
-    }
-    catch {
+function tokensCheck(tokens) {
+    if (!tokens.ok) {
+        log.debug(`doctor: token ledger not read: ${tokens.message}`);
         return { id: 'tokens', status: 'info', detail: 'no token ledger yet (created on the next write)' };
     }
+    const tally = tokens.value;
+    return {
+        id: 'tokens',
+        status: 'info',
+        detail: `${tally.injected} memory blocks sent to agents in 7 days, about ${tally.tokensSent} tokens sent and ${tally.tokensReread} re-read by later model calls (hippo tokens for detail)`,
+    };
 }
-/** Checks that read the store's database; a failed open becomes a failed schema check after whatever already passed. */
+/** Checks that read the store's database; a store that cannot be opened becomes one failed schema check. */
 function databaseChecks(store, now) {
-    const checks = [];
-    let db = null;
+    let health;
     try {
-        db = openHippoDbReadOnly(store);
-        const have = getSchemaVersion(db);
-        checks.push(schemaCheck(have, getCurrentSchemaVersion()));
-        checks.push(memoriesCheck(db));
-        checks.push(ftsCheck(db));
-        const since = new Date(now.getTime() - 7 * 86_400_000).toISOString();
-        checks.push(tokensCheck(db, since));
-        checks.push(failuresCheck(db, since, have));
-        checks.push(sleepCheck(db, now));
-        checks.push(compactionsCheck(db, store, now));
-    }
-    catch (err) {
-        checks.push({
-            id: 'schema',
-            status: 'fail',
-            detail: `cannot open the database: ${err instanceof Error ? err.message : String(err)}`,
-            fix: err instanceof IncompatibleBinaryError ? 'npm install -g hippo-memory@latest' : 'check file permissions on the .hippo folder',
+        health = readStoreHealth(store, {
+            since: new Date(now.getTime() - 7 * DAY_MS).toISOString(),
+            stuckBefore: new Date(now.getTime() - REPLAY_AFTER_MS).toISOString(),
+            transcriptFloor: new Date(now.getTime() - TRANSCRIPT_FILL_WINDOW_MS).toISOString(),
         });
     }
-    finally {
-        if (db !== null)
-            closeHippoDb(db);
-    }
-    return checks;
+    catch (err) {
+        return [{
+                id: 'schema',
+                status: 'fail',
+                detail: `cannot open the database: ${errorMessage(err)}`,
+                fix: err instanceof IncompatibleBinaryError ? 'npm install -g hippo-memory@latest' : 'check file permissions on the .hippo folder',
+            }];
+    }
+    return [
+        schemaCheck(health.schemaVersion, getCurrentSchemaVersion()),
+        memoriesCheck(health.memories, health.dormant),
+        ftsCheck(health.fts),
+        tokensCheck(health.tokens),
+        failuresCheck(health.failures, health.schemaVersion),
+        sleepCheck(health.lastSleep, now),
+        compactionsCheck(health.compactions, store, now),
+    ];
 }
 // Each hook and what it does, so a partial install says what is missing.
 const CLAUDE_CODE_HOOKS = [

package/dist/entry/json-hooks.d.ts

@@ -1,3 +1,3 @@
 export { installJsonHooks, resolveJsonHookPaths, uninstallJsonHooks, writeSettingsFile, type InstallResult, type JsonHookPaths } from '../hooks/json-hooks.js';
-export { readJsonFile } from '../json.js';
+export { readJsonFile } from '../util/json.js';
 //# sourceMappingURL=json-hooks.d.ts.map

package/dist/entry/json-hooks.js

@@ -1,4 +1,4 @@
 // The hippo-memory/json-hooks subpath: only what the changelog publishes, so the module's other exports stay internal.
 export { installJsonHooks, resolveJsonHookPaths, uninstallJsonHooks, writeSettingsFile } from '../hooks/json-hooks.js';
-export { readJsonFile } from '../json.js';
+export { readJsonFile } from '../util/json.js';
 //# sourceMappingURL=json-hooks.js.map

package/dist/entry/project-identity.d.ts

@@ -1,2 +1,2 @@
-export { MAX_PROJECT_ALIASES, MCP_PROJECT_SCOPED_HEADER, resolveProjectIdentity, type ProjectIdentity, type ResolveProjectIdentityOpts } from '../project-identity.js';
+export { MAX_PROJECT_ALIASES, MCP_PROJECT_SCOPED_HEADER, resolveProjectIdentity, type ProjectIdentity, type ResolveProjectIdentityOpts } from '../core/project-identity.js';
 //# sourceMappingURL=project-identity.d.ts.map

package/dist/entry/project-identity.js

@@ -1,3 +1,3 @@
 // The hippo-memory/project-identity subpath: only what the changelog publishes, so the module's other exports stay internal.
-export { MAX_PROJECT_ALIASES, MCP_PROJECT_SCOPED_HEADER, resolveProjectIdentity } from '../project-identity.js';
+export { MAX_PROJECT_ALIASES, MCP_PROJECT_SCOPED_HEADER, resolveProjectIdentity } from '../core/project-identity.js';
 //# sourceMappingURL=project-identity.js.map

package/dist/entry/session-text.d.ts

@@ -1,7 +1,7 @@
 export { collectSessionTurns, sessionTail, type SessionTurn } from '../capture/transcript.js';
-export { scrubForSharing } from '../share-scrub.js';
+export { scrubForSharing } from '../capture/share-scrub.js';
 export { transcriptWorkingState, WORKING_STATE_CAPS } from '../capture/working-state.js';
 export { lessonFromFailure, failureReport, type FailureReport } from '../capture/failure-reading.js';
-export { collectHandoffEvidence } from '../handoff-evidence.js';
-export { compactSummaryBody, parseCompactionItems, COMPACTION_ITEM_MAX_CHARS, COMPACTION_ITEM_ROW_CAP } from '../compaction-items.js';
+export { collectHandoffEvidence } from '../capture/handoff-evidence.js';
+export { compactSummaryBody, parseCompactionItems, COMPACTION_ITEM_MAX_CHARS, COMPACTION_ITEM_ROW_CAP } from '../capture/compaction-items.js';
 //# sourceMappingURL=session-text.d.ts.map

package/dist/entry/session-text.js

@@ -1,8 +1,8 @@
 // The hippo-memory/session-text subpath: what a hook reads from a session (turns, working state, failures, git state, compaction items) and the sharing scrub, with no store, database or server in its imports.
 export { collectSessionTurns, sessionTail } from '../capture/transcript.js';
-export { scrubForSharing } from '../share-scrub.js';
+export { scrubForSharing } from '../capture/share-scrub.js';
 export { transcriptWorkingState, WORKING_STATE_CAPS } from '../capture/working-state.js';
 export { lessonFromFailure, failureReport } from '../capture/failure-reading.js';
-export { collectHandoffEvidence } from '../handoff-evidence.js';
-export { compactSummaryBody, parseCompactionItems, COMPACTION_ITEM_MAX_CHARS, COMPACTION_ITEM_ROW_CAP } from '../compaction-items.js';
+export { collectHandoffEvidence } from '../capture/handoff-evidence.js';
+export { compactSummaryBody, parseCompactionItems, COMPACTION_ITEM_MAX_CHARS, COMPACTION_ITEM_ROW_CAP } from '../capture/compaction-items.js';
 //# sourceMappingURL=session-text.js.map

package/dist/{eval-stats.js → eval/eval-stats.js}

@@ -11,6 +11,9 @@
  * Deterministic: every resampling function takes a seed, so a published
  * result can be reproduced exactly.
  */
+const DEFAULT_ITERATIONS = 5000;
+const DEFAULT_TWO_LEVEL_ITERATIONS = 10_000;
+const DEFAULT_ALPHA = 0.05;
 /** Sum several usages bucket by bucket. */
 export function addUsage(...usages) {
     const total = { inputTokens: 0, cacheWriteTokens: 0, cacheReadTokens: 0, outputTokens: 0 };
@@ -64,8 +67,8 @@ function mean(xs) {
  * calling a difference real.
  */
 export function pairedBootstrap(diffs, opts = {}) {
-    const iterations = opts.iterations ?? 5000;
-    const alpha = opts.alpha ?? 0.05;
+    const iterations = opts.iterations ?? DEFAULT_ITERATIONS;
+    const alpha = opts.alpha ?? DEFAULT_ALPHA;
     if (diffs.length === 0)
         return { estimate: 0, low: 0, high: 0, iterations: 0 };
     const rand = seededRandom(opts.seed ?? 1);
@@ -85,8 +88,8 @@ export function pairedBootstrap(diffs, opts = {}) {
  * cluster share causes and are not independent draws.
  */
 export function clusteredPairedBootstrap(diffsByCluster, opts = {}) {
-    const iterations = opts.iterations ?? 5000;
-    const alpha = opts.alpha ?? 0.05;
+    const iterations = opts.iterations ?? DEFAULT_ITERATIONS;
+    const alpha = opts.alpha ?? DEFAULT_ALPHA;
     const clusters = [...diffsByCluster.values()].filter((c) => c.length > 0);
     const all = clusters.flat();
     if (all.length === 0)
@@ -123,8 +126,8 @@ export function costPerResolvedDelta(control, treatment, opts = {}) {
     if (control.length !== treatment.length) {
         throw new Error('control and treatment must list the same tasks in the same order');
     }
-    const iterations = opts.iterations ?? 5000;
-    const alpha = opts.alpha ?? 0.05;
+    const iterations = opts.iterations ?? DEFAULT_ITERATIONS;
+    const alpha = opts.alpha ?? DEFAULT_ALPHA;
     const c = costPerResolved(control);
     const t = costPerResolved(treatment);
     const rand = seededRandom(opts.seed ?? 1);
@@ -213,7 +216,7 @@ function twoSidedP(samples, nullValue) {
 /** Resamples repositories, then families inside each; only the repository draw carries a shared-store fault.
  * The statistic never uses the PRNG, so a second call on one seed draws the same resamples. */
 export function twoLevelBootstrap(repos, statistic, opts = {}) {
-    const requested = opts.iterations ?? 10_000;
+    const requested = opts.iterations ?? DEFAULT_TWO_LEVEL_ITERATIONS;
     if (!Number.isInteger(requested) || requested <= 0) {
         throw new RangeError(`iterations must be a positive integer, got ${requested}`);
     }
@@ -233,7 +236,7 @@ export function twoLevelBootstrap(repos, statistic, opts = {}) {
         return notANumber(nullValue, dropped);
     const estimate = statistic(kept.flatMap((r) => r.flat()));
     const p = kept.length < 2 ? Number.NaN : twoSidedP(samples, nullValue);
-    const interval = percentileInterval(samples, opts.alpha ?? 0.05);
+    const interval = percentileInterval(samples, opts.alpha ?? DEFAULT_ALPHA);
     return { estimate, ...interval, p, iterations: samples.length, dropped, nullValue };
 }
 /** Holm step-down in input order; the family size is `ps.length`, as preregistered.
@@ -263,7 +266,7 @@ export function verdict(e, adjustedP, spec) {
         return inconclusive;
     const nullValue = e.nullValue;
     const lowerIsHelpful = spec.helpful === 'lower';
-    if (adjustedP < (spec.alpha ?? 0.05)) {
+    if (adjustedP < (spec.alpha ?? DEFAULT_ALPHA)) {
         const helpfulSide = lowerIsHelpful ? e.estimate < nullValue : e.estimate > nullValue;
         const harmfulSide = lowerIsHelpful ? e.estimate > nullValue : e.estimate < nullValue;
         if (harmfulSide)

package/dist/{eval-suite.d.ts → eval/eval-suite.d.ts}

@@ -11,7 +11,7 @@
  *  - Fast (<60s for full suite)
  *  - Per-feature breakdown so you see exactly what a change helped/hurt
  */
-import { type MemoryEntry } from './memory.js';
+import { type MemoryEntry } from '../core/memory.js';
 export type FeatureCategory = 'direct-recall' | 'extraction-preference' | 'dag-drilldown' | 'temporal' | 'noise-resistance' | 'multi-hop';
 export interface FeatureTestCase {
     id: string;

package/dist/{eval-suite.js → eval/eval-suite.js}

@@ -11,16 +11,17 @@
  *  - Fast (<60s for full suite)
  *  - Per-feature breakdown so you see exactly what a change helped/hurt
  */
-import { createMemory, Layer } from './memory.js';
-import { search } from './search/bm25-search.js';
-import { multihopSearch } from './multihop.js';
+import { createMemory, Layer } from '../core/memory.js';
+import { search } from '../search/bm25-search.js';
+import { multihopSearch } from '../search/multihop.js';
 import { mrr, recallAtK, ndcgAtK } from './eval.js';
+import { DAY_MS } from '../util/time.js';
 // ---------------------------------------------------------------------------
 // Synthetic corpus — deterministic, no API calls
 // ---------------------------------------------------------------------------
 const BASE_DATE = new Date('2026-01-15T10:00:00Z');
 function dateOffset(days) {
-    const d = new Date(BASE_DATE.getTime() + days * 86400000);
+    const d = new Date(BASE_DATE.getTime() + days * DAY_MS);
     return d.toISOString();
 }
 function mem(id, content, opts = {}) {
@@ -142,9 +143,25 @@ export function buildSyntheticCorpus() {
     addMultiHop(entries, cases);
     return { entries, cases };
 }
-// ---------------------------------------------------------------------------
-// Runner — evaluates each case against the synthetic corpus
-// ---------------------------------------------------------------------------
+/** Each category's mean scores, in the order the corpus first names the category. */
+function featureAverages(cases, caseResults) {
+    const categories = [...new Set(cases.map(c => c.category))];
+    return categories.map(cat => {
+        const catCases = caseResults.filter(r => r.case.category === cat);
+        const n = catCases.length;
+        const avgMrr = catCases.reduce((s, r) => s + r.mrrVal, 0) / n;
+        const avgR5 = catCases.reduce((s, r) => s + r.r5, 0) / n;
+        const avgNdcg5 = catCases.reduce((s, r) => s + r.ndcg5, 0) / n;
+        return {
+            category: cat,
+            cases: n,
+            mrr: avgMrr,
+            recallAt5: avgR5,
+            ndcgAt5: avgNdcg5,
+            passed: true,
+        };
+    });
+}
 export async function runFeatureEval(version) {
     const start = Date.now();
     const { entries, cases } = buildSyntheticCorpus();
@@ -166,22 +183,7 @@ export async function runFeatureEval(version) {
             ndcg5: ndcgAtK(returnedIds, c.expectedIds, 5),
         });
     }
-    const categories = [...new Set(cases.map(c => c.category))];
-    const features = categories.map(cat => {
-        const catCases = caseResults.filter(r => r.case.category === cat);
-        const n = catCases.length;
-        const avgMrr = catCases.reduce((s, r) => s + r.mrrVal, 0) / n;
-        const avgR5 = catCases.reduce((s, r) => s + r.r5, 0) / n;
-        const avgNdcg5 = catCases.reduce((s, r) => s + r.ndcg5, 0) / n;
-        return {
-            category: cat,
-            cases: n,
-            mrr: avgMrr,
-            recallAt5: avgR5,
-            ndcgAt5: avgNdcg5,
-            passed: true,
-        };
-    });
+    const features = featureAverages(cases, caseResults);
     const totalCases = caseResults.length;
     const overallMrr = caseResults.reduce((s, r) => s + r.mrrVal, 0) / totalCases;
     const overallR5 = caseResults.reduce((s, r) => s + r.r5, 0) / totalCases;

package/dist/{eval.d.ts → eval/eval.d.ts}

@@ -8,7 +8,7 @@
  * weights, and future scoring tweaks can be tuned against evidence instead
  * of intuition.
  */
-import type { MemoryEntry } from './memory.js';
+import type { MemoryEntry } from '../core/memory.js';
 export interface EvalCase {
     /** Free-form ID for humans to reference the case. */
     id: string;

package/dist/{eval.js → eval/eval.js}

@@ -8,9 +8,12 @@
  * weights, and future scoring tweaks can be tuned against evidence instead
  * of intuition.
  */
-import { hybridSearch } from './search/hybrid.js';
-import { searchBothHybrid } from './shared.js';
-import { isInitialized } from './store/open.js';
+import { hybridSearch } from '../search/hybrid.js';
+import { searchBothHybrid } from '../sharing/shared.js';
+import { isInitialized } from '../store/open.js';
+// Generous so metrics are not truncated.
+const DEFAULT_EVAL_BUDGET = 100_000;
+const QUERY_WORDS = 8;
 // ---------------------------------------------------------------------------
 // Metrics — pure functions. K is inclusive of position K.
 // ---------------------------------------------------------------------------
@@ -64,28 +67,11 @@ export function ndcgAtK(returned, expected, k) {
 // Runner
 // ---------------------------------------------------------------------------
 export async function runEval(cases, entries, options = {}) {
-    const budget = options.budget ?? 100_000; // generous so metrics aren't truncated
     const start = Date.now();
     const results = [];
     const useBothStores = Boolean(options.globalRoot && options.hippoRoot && isInitialized(options.globalRoot));
     for (const c of cases) {
-        const ranked = useBothStores
-            ? await searchBothHybrid(c.query, options.hippoRoot, options.globalRoot, {
-                budget,
-                now: options.now,
-                embeddingWeight: options.embeddingWeight,
-                mmr: options.mmr,
-                mmrLambda: options.mmrLambda,
-                localBump: options.localBump,
-            })
-            : await hybridSearch(c.query, entries, {
-                budget,
-                now: options.now,
-                hippoRoot: options.hippoRoot,
-                embeddingWeight: options.embeddingWeight,
-                mmr: options.mmr,
-                mmrLambda: options.mmrLambda,
-            });
+        const ranked = await rankForCase(c.query, entries, options, useBothStores);
         const returnedIds = ranked.map((r) => r.entry.id);
         results.push({
             case: c,
@@ -110,6 +96,27 @@ export async function runEval(cases, entries, options = {}) {
         durationMs: Date.now() - start,
     };
 }
+/** One case's ranking: across the local and global stores when `useBothStores`, else over `entries` alone. */
+function rankForCase(query, entries, options, useBothStores) {
+    const budget = options.budget ?? DEFAULT_EVAL_BUDGET;
+    return useBothStores
+        ? searchBothHybrid(query, options.hippoRoot, options.globalRoot, {
+            budget,
+            now: options.now,
+            embeddingWeight: options.embeddingWeight,
+            mmr: options.mmr,
+            mmrLambda: options.mmrLambda,
+            localBump: options.localBump,
+        })
+        : hybridSearch(query, entries, {
+            budget,
+            now: options.now,
+            hippoRoot: options.hippoRoot,
+            embeddingWeight: options.embeddingWeight,
+            mmr: options.mmr,
+            mmrLambda: options.mmrLambda,
+        });
+}
 /**
  * Compute pairwise deltas between a baseline and a current eval summary.
  * Cases are matched by EvalCase.id; any mismatch is surfaced in the onlyIn
@@ -174,7 +181,7 @@ export function bootstrapCorpus(entries, maxCases = 50) {
         const words = e.content.trim().split(/\s+/).filter((w) => w.length > 2);
         if (words.length < 3)
             continue;
-        const query = words.slice(0, 8).join(' ');
+        const query = words.slice(0, QUERY_WORDS).join(' ');
         cases.push({
             id: `bootstrap_${e.id}`,
             query,

package/dist/{judgment.d.ts → eval/judgment.d.ts}

@@ -1,7 +1,7 @@
 /** Typed judgment over capture candidates via TypeSafe's Jev (System One).
  *  Regex picks WHAT is a candidate; it cannot say what is worth keeping, so
  *  every captured memory currently lands on a flat schema_fit of 0.5. */
-import { ConfidenceLevel, EmotionalValence } from './memory.js';
+import { ConfidenceLevel, EmotionalValence } from '../core/memory.js';
 export type JudgedKind = 'error' | 'decision' | 'convention' | 'preference' | 'trivia';
 export interface Judgment {
     /** Jev noul, 0..1. Maps to `schema_fit` on the written entry. */
@@ -20,8 +20,6 @@ export interface JudgeOptions {
     /** Bounded parallelism for `judgeAll`. */
     concurrency?: number;
 }
-/** Absent key means hippo keeps its pre-Jev behaviour and makes no HTTP call. */
-export declare function judgmentApiKey(): string | undefined;
 /** `null` on any failure, so a Jev outage degrades capture to today's
  *  behaviour instead of blocking the write. */
 export declare function judge(content: string, opts: JudgeOptions): Promise<Judgment | null>;