hippo-memory 1.70.0 → 1.72.0

package/dist/store/open.d.ts

@@ -1,9 +1,5 @@
 import { type MemoryEntry } from '../core/memory.js';
 import { type DatabaseSyncLike } from '../db/index.js';
-import { type ResolveProjectIdentityOpts } from '../core/project-identity.js';
-/** Nearest ancestor store like git; the strict join is the fallback so `hippo init` still creates `<cwd>/.hippo`. */
-export declare function getHippoRoot(cwd?: string, opts?: ResolveProjectIdentityOpts): string;
-export declare function isInitialized(hippoRoot: string): boolean;
 export declare function initStore(hippoRoot: string): void;
 /** One open connection with init done on it, for callers who used to pay for `initStore` + a second `openHippoDb`. */
 export declare function openStore(hippoRoot: string, opts?: {

package/dist/store/open.js

@@ -2,26 +2,15 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import { DEFAULT_HALF_LIFE_DAYS, Layer } from '../core/memory.js';
-import { closeHippoDb, currentRequestStores, openHippoDb, getMeta, setMeta, withWriteScope } from '../db/index.js';
+import { closeHippoDb, currentRequestStores, openHippoDb, getMeta, setMeta, withWriteScope, pruneConsolidationRuns, } from '../db/index.js';
 import { openHippoDbWithFacts } from '../db/open.js';
-import { findHippoStoreDir } from '../core/project-identity.js';
-import { realpathOrResolve } from '../util/real-path.js';
-import { RejectedValueError } from './rejection.js';
-import { errorMessage, log } from '../util/log.js';
+import { RejectedValueError } from '../core/api-errors.js';
+import { errorFields, errorMessage, log } from '../util/log.js';
 import { audit } from './audit-event.js';
-import { deserializeEntry } from './markdown.js';
+import { deserializeEntry } from '../core/markdown.js';
 import { stampOriginProjectForImport, upsertEntryRow } from './entry-row.js';
 import { ensureMirrorDirectories, syncMirrorFiles, layerDir } from './mirrors.js';
 import { isJsonObject } from '../util/json.js';
-/** Nearest ancestor store like git; the strict join is the fallback so `hippo init` still creates `<cwd>/.hippo`. */
-export function getHippoRoot(cwd = process.cwd(), opts) {
-    return findHippoStoreDir(cwd, opts) ?? path.join(realpathOrResolve(cwd), '.hippo');
-}
-export function isInitialized(hippoRoot) {
-    // autoInstallHooks / setupDailySchedule can create a bare .hippo with no hippo.db; counting
-    // that as initialized makes `hippo init` skip initStore, so only hippo.db counts.
-    return fs.existsSync(path.join(hippoRoot, 'hippo.db'));
-}
 export function initStore(hippoRoot) {
     closeHippoDb(openStore(hippoRoot));
 }
@@ -48,8 +37,9 @@ export function openStore(hippoRoot, opts) {
         try {
             closeHippoDb(db);
         }
-        catch {
-            // Best effort only; surface the original init error.
+        catch (closeErr) {
+            // The init error is the one thrown; the close failure is only logged.
+            log.error(`openStore: closing the handle after a failed init failed: ${errorMessage(closeErr)}`, errorFields(closeErr));
         }
         throw error;
     }
@@ -70,12 +60,8 @@ export const HALF_LIFE_BASE_META_KEY = 'default_half_life_base';
 export const TYPED_HALF_LIFE_META_KEY = 'typed_half_life_on_default';
 /** The flat half-life the decision, incident and other object writers gave their memories before they took the default. */
 export const LEGACY_TYPED_HALF_LIFE = 90;
-/**
- * A store with no memories starts on the current default half-life base, so
- * `hippo sleep` never migrates it. A store that already holds memories and
- * no recorded base predates the record, and keeps reading as the legacy
- * 7-day base until sleep migrates it.
- */
+/** A store with no memories starts on the current default half-life base so `hippo sleep` never migrates it; one that holds memories but no recorded base
+ * predates the record and keeps the legacy 7-day base until sleep migrates it. */
 function recordHalfLifeBaseForNewStore(db) {
     if (getMeta(db, HALF_LIFE_BASE_META_KEY, '') !== '')
         return;
@@ -146,6 +132,8 @@ function importLegacyIndexAndStats(db, hippoRoot) {
         const row = run;
         insertRun.run(String(row.timestamp ?? new Date().toISOString()), Number(row.decayed ?? 0), Number(row.merged ?? 0), Number(row.removed ?? 0));
     }
+    // Same cap as every later sleep, so stats.json and the table agree from the first open.
+    pruneConsolidationRuns(db);
 }
 export function loadLegacyEntriesFromMarkdown(hippoRoot) {
     const entries = [];
@@ -156,55 +144,47 @@ export function loadLegacyEntriesFromMarkdown(hippoRoot) {
         for (const file of fs.readdirSync(dir)) {
             if (!file.endsWith('.md'))
                 continue;
-            const raw = fs.readFileSync(path.join(dir, file), 'utf8');
-            const entry = deserializeEntry(raw);
-            if (entry)
-                entries.push(entry);
+            try {
+                const entry = deserializeEntry(fs.readFileSync(path.join(dir, file), 'utf8'));
+                if (entry)
+                    entries.push(entry);
+            }
+            catch (err) {
+                log.warn(`store: skipped unreadable legacy file ${file}: ${errorMessage(err)}`);
+            }
         }
     }
     return entries;
 }
-function loadLegacyIndexFile(hippoRoot) {
-    const indexPath = path.join(hippoRoot, 'index.json');
-    if (!fs.existsSync(indexPath)) {
-        return { version: 1, entries: {}, last_retrieval_ids: [], last_trace_id: null };
-    }
+function readLegacyJsonObject(file) {
+    let parsed;
     try {
-        // SAFETY: index.json is only ever written by writeIndexMirror below,
-        // which always serializes a HippoIndex; a hand-edited or corrupted file
-        // that violates the shape falls through to the catch block's fallback.
-        return JSON.parse(fs.readFileSync(indexPath, 'utf8'));
+        parsed = JSON.parse(fs.readFileSync(file, 'utf8'));
     }
     catch (err) {
-        log.debug(`store: unreadable index.json read as empty: ${errorMessage(err)}`);
-        return { version: 1, entries: {}, last_retrieval_ids: [], last_trace_id: null };
+        log.warn(`store: unreadable ${path.basename(file)} read as empty: ${errorMessage(err)}`);
+        return null;
+    }
+    if (!isJsonObject(parsed)) {
+        log.warn(`store: ${path.basename(file)} is not a JSON object, read as empty`);
+        return null;
     }
+    return parsed;
+}
+function loadLegacyIndexFile(hippoRoot) {
+    const indexPath = path.join(hippoRoot, 'index.json');
+    const empty = { version: 1, entries: {}, last_retrieval_ids: [], last_trace_id: null };
+    if (!fs.existsSync(indexPath))
+        return empty;
+    // SAFETY: index.json is written by writeIndexMirror as a HippoIndex; readers default every field, so only the object shape is checked.
+    return readLegacyJsonObject(indexPath) ?? empty;
 }
 function loadLegacyStatsFile(hippoRoot) {
     const statsPath = path.join(hippoRoot, 'stats.json');
-    if (!fs.existsSync(statsPath)) {
-        return {
-            total_remembered: 0,
-            total_recalled: 0,
-            total_forgotten: 0,
-            consolidation_runs: [],
-        };
-    }
-    try {
-        // SAFETY: stats.json is only ever written by writeStatsMirror below,
-        // which always emits exactly these four fields; callers additionally
-        // guard every read with `?? 0` / `Array.isArray`, tolerating a
-        // hand-edited or corrupted file even if this optimistic cast is wrong.
-        return JSON.parse(fs.readFileSync(statsPath, 'utf8'));
-    }
-    catch (err) {
-        log.debug(`store: unreadable stats.json read as zero: ${errorMessage(err)}`);
-        return {
-            total_remembered: 0,
-            total_recalled: 0,
-            total_forgotten: 0,
-            consolidation_runs: [],
-        };
-    }
+    const empty = { total_remembered: 0, total_recalled: 0, total_forgotten: 0, consolidation_runs: [] };
+    if (!fs.existsSync(statsPath))
+        return empty;
+    // SAFETY: callers guard every field read with `?? 0` / `Array.isArray`, so only the object shape is checked.
+    return readLegacyJsonObject(statsPath) ?? empty;
 }
 //# sourceMappingURL=open.js.map

package/dist/store/pilot-arm.d.ts

@@ -0,0 +1,12 @@
+import { type DatabaseSyncLike } from '../db/index.js';
+export type PilotArm = 'hippo' | 'holdout';
+/** Deterministic split: the same session and rate always land in the same arm. */
+export declare function hashArm(sessionId: string, rateBp: number): PilotArm;
+/** The session's first stored arm, or null; never writes. Without `tenantId` any tenant's row counts, since on one machine a session has one arm. */
+export declare function readPilotArm(db: DatabaseSyncLike, sessionId: string, tenantId?: string): PilotArm | null;
+/** The stored arm, else the hash arm written once; on any error the hash arm comes back unrecorded. */
+export declare function ensurePilotArm(db: DatabaseSyncLike, tenantId: string, sessionId: string, rateBp: number, opts?: {
+    ownTenantOnly?: boolean;
+    now?: string;
+}): PilotArm;
+//# sourceMappingURL=pilot-arm.d.ts.map

package/dist/store/pilot-arm.js

@@ -0,0 +1,42 @@
+// Pilot arm: one token_ledger row per session names its arm, `hippo` or `holdout`, so a pilot can compare them.
+// `items` holds the holdout rate in basis points; readers outside this repo depend on these rows, so their shape is fixed.
+import { createHash } from 'node:crypto';
+import { HOOK_DB_WAIT_MS, scopedBusyWait, withWriteScope } from '../db/index.js';
+import { errorMessage, log } from '../util/log.js';
+import { firstPilotArmHash } from './token-ledger-rows.js';
+import { recordTokenUse } from './token-ledger.js';
+/** Deterministic split: the same session and rate always land in the same arm. */
+export function hashArm(sessionId, rateBp) {
+    const bucket = parseInt(createHash('sha256').update(sessionId).digest('hex').slice(0, 8), 16) % 10000;
+    return bucket < rateBp ? 'holdout' : 'hippo';
+}
+/** The session's first stored arm, or null; never writes. Without `tenantId` any tenant's row counts, since on one machine a session has one arm. */
+export function readPilotArm(db, sessionId, tenantId) {
+    const row = firstPilotArmHash(db, sessionId, tenantId);
+    return row?.block_hash === 'holdout' || row?.block_hash === 'hippo' ? row.block_hash : null;
+}
+/** The stored arm, else the hash arm written once; on any error the hash arm comes back unrecorded. */
+// The wait is the caller's lock-wait scope (a hook's 1 s, a server request's 250 ms); it holds on a handle opened in that scope.
+export function ensurePilotArm(db, tenantId, sessionId, rateBp, opts = {}) {
+    const hashed = hashArm(sessionId, rateBp);
+    const readTenant = opts.ownTenantOnly ? tenantId : undefined;
+    try {
+        // A stored row is the common case after the first prompt, so it must not take the write lock.
+        const existing = readPilotArm(db, sessionId, readTenant);
+        if (existing !== null)
+            return existing;
+        return withWriteScope(db, 'pilot_arm', () => {
+            const stored = readPilotArm(db, sessionId, readTenant);
+            if (stored === null) {
+                recordTokenUse(db, { tenantId, sessionId, surface: 'pilot', event: 'arm', items: rateBp, tokens: 0, hash: hashed, now: opts.now });
+            }
+            return stored ?? hashed;
+        }, { busyWaitMs: scopedBusyWait() ?? HOOK_DB_WAIT_MS });
+    }
+    catch (err) {
+        // A prompt hook must not fail on pilot bookkeeping; concurrent callers still agree on the hash arm.
+        log.debug(`pilot arm not stored, using the hash arm: ${errorMessage(err)}`);
+        return hashed;
+    }
+}
+//# sourceMappingURL=pilot-arm.js.map

package/dist/store/planning-fallacy-evidence.d.ts

@@ -1,42 +1,14 @@
 import { type PredictionBaserate } from './predictions.js';
 export interface ClassResolution {
     classTag: string | null;
-    /** True when ≥2 classes tied at the best overlap score AND best ≥ 1.
-     *  Caller emits `recall_autodebias_hint_tiebreak` audit and returns
-     *  null hint (silent — prevents the "show wrong class half the time"
-     *  failure mode the alphabetical-tiebreak alternative would create). */
+    /** True when >=2 classes tied at the best overlap score AND best >= 1. Caller emits `recall_autodebias_hint_tiebreak` and returns a null hint
+     * (silent: an alphabetical tiebreak would show the wrong class half the time). */
     tiebreak: boolean;
 }
 /** The prediction class a forward claim resolves to, and that class's closed-prediction stats when one resolved. */
 export interface PlanningFallacyEvidence extends ClassResolution {
     readonly baserate: PredictionBaserate | null;
 }
-/**
- * Resolve a query-token set to a unique best-matching class_tag for the
- * tenant. Scores by lower-cased token overlap; requires best score ≥ 1
- * AND strictly greater than the 2nd-best score.
- *
- * Indexed via idx_predictions_tenant_class (db.ts:1015) → O(log n) seek
- * plus a small DISTINCT scan over the per-tenant class-tag set.
- *
- * Scope behaviour (deliberate): class_tag selection is TENANT-GLOBAL,
- * NOT scope-filtered against
- * the recall's opts.scope. The class_tag is an aggregator label across
- * historical predictions in the class, not a per-memory scope-bound
- * property. A no-scope recall CAN surface a class_tag from a privately-
- * scoped prediction's class in PlanningFallacyHint.classTag — by design,
- * because base-rate reasoning needs the full historical sample.
- * Implications:
- *   - The hint payload itself carries no memory content (only the aggregate
- *     summary string + numeric stats), so memory bodies do not leak.
- *   - The class_tag NAME is the side-channel. If sensitive labels are a
- *     concern, callers should either use opaque class names (e.g. hashes
- *     or numeric tokens) or set HIPPO_AUTODEBIAS=off.
- *   - tests/api-recall-autodebias.test.ts locks this with an explicit
- *     test asserting that scope-set predictions surface via no-scope
- *     recalls (so future "fix" attempts that scope-filter trip CI).
- */
-export declare function resolveClassFromTokens(hippoRoot: string, tenantId: string, queryTokens: readonly string[]): ClassResolution;
 /** Resolves a claim's tokens to one class and reads its baserate, writing no audit row. */
 export declare function planningFallacyEvidenceAt(hippoRoot: string, tenantId: string, classQueryTokens: readonly string[]): PlanningFallacyEvidence;
 //# sourceMappingURL=planning-fallacy-evidence.d.ts.map

package/dist/store/planning-fallacy-evidence.js

@@ -1,35 +1,11 @@
-import { closeHippoDb, openHippoDb } from '../db/index.js';
+import { onHandle } from './open.js';
 import { computePredictionBaserate } from './predictions.js';
-/**
- * Resolve a query-token set to a unique best-matching class_tag for the
- * tenant. Scores by lower-cased token overlap; requires best score ≥ 1
- * AND strictly greater than the 2nd-best score.
- *
- * Indexed via idx_predictions_tenant_class (db.ts:1015) → O(log n) seek
- * plus a small DISTINCT scan over the per-tenant class-tag set.
- *
- * Scope behaviour (deliberate): class_tag selection is TENANT-GLOBAL,
- * NOT scope-filtered against
- * the recall's opts.scope. The class_tag is an aggregator label across
- * historical predictions in the class, not a per-memory scope-bound
- * property. A no-scope recall CAN surface a class_tag from a privately-
- * scoped prediction's class in PlanningFallacyHint.classTag — by design,
- * because base-rate reasoning needs the full historical sample.
- * Implications:
- *   - The hint payload itself carries no memory content (only the aggregate
- *     summary string + numeric stats), so memory bodies do not leak.
- *   - The class_tag NAME is the side-channel. If sensitive labels are a
- *     concern, callers should either use opaque class names (e.g. hashes
- *     or numeric tokens) or set HIPPO_AUTODEBIAS=off.
- *   - tests/api-recall-autodebias.test.ts locks this with an explicit
- *     test asserting that scope-set predictions surface via no-scope
- *     recalls (so future "fix" attempts that scope-filter trip CI).
- */
-export function resolveClassFromTokens(hippoRoot, tenantId, queryTokens) {
+/** Resolve a query-token set to a unique best-matching class_tag for the tenant: lower-cased token overlap, best score >= 1 AND above the 2nd-best.
+ * TENANT-GLOBAL by design, not scope-filtered (base rates need the full sample): class_tag NAMES can cross scopes; use opaque names or HIPPO_AUTODEBIAS=off. */
+function resolveClassFromTokens(hippoRoot, tenantId, queryTokens) {
     if (queryTokens.length === 0)
         return { classTag: null, tiebreak: false };
-    const db = openHippoDb(hippoRoot);
-    try {
+    return onHandle(hippoRoot, (db) => {
         // SAFETY: rows' shape matches the single `class_tag` column named in the SELECT above.
         const rows = db.prepare(`SELECT DISTINCT class_tag FROM predictions WHERE tenant_id = ?`).all(tenantId);
         const querySet = new Set(queryTokens);
@@ -51,10 +27,8 @@ export function resolveClassFromTokens(hippoRoot, tenantId, queryTokens) {
                 bestClass = class_tag;
             }
             else if (score === bestScore && score > 0) {
-                // Tie at current best — bump secondBest. Do NOT update bestClass
-                // (alphabetical tiebreak would pick wrong class on ambiguous query
-                // like "migration will take 3 days" between migration-effort vs
-                // migration-risk; silent on tie instead).
+                // Tie at current best: bump secondBest, do NOT update bestClass (an alphabetical tiebreak would pick the wrong class on ambiguous queries; stay silent
+                // on tie).
                 secondBest = score;
             }
             else if (score > secondBest) {
@@ -66,10 +40,7 @@ export function resolveClassFromTokens(hippoRoot, tenantId, queryTokens) {
         if (bestScore === secondBest)
             return { classTag: null, tiebreak: true };
         return { classTag: bestClass, tiebreak: false };
-    }
-    finally {
-        closeHippoDb(db);
-    }
+    });
 }
 /** Resolves a claim's tokens to one class and reads its baserate, writing no audit row. */
 export function planningFallacyEvidenceAt(hippoRoot, tenantId, classQueryTokens) {