hippo-memory 1.43.3 → 1.45.0

package/dist/server.js

@@ -22,7 +22,7 @@ export function __resetSessionRecallHistoryHttp() {
 import { PACKAGE_VERSION } from './version.js';
 import { validateApiKey } from './auth.js';
 import { createRateLimiter } from './rate-limit.js';
-import { remember, recall, RecallContractError, drillDown, assemble, forget, promote, supersede, archiveRaw, authCreate, authList, authRevoke, auditList, outcome, outcomeForLastRecall, getContext, sleep, adminActor, } from './api.js';
+import { remember, retrieve, RecallContractError, ForbiddenError, drillDown, assemble, forget, promote, supersede, archiveRaw, authCreate, authList, authRevoke, auditList, outcome, outcomeForLastRecall, getContext, sleep, adminActor, } from './api.js';
 import { buildGraphModel } from './graph-view.js';
 import { MAX_ENTITY_NAME_LEN } from './graph.js';
 import { savePrediction, closePrediction, loadPredictionById, loadPredictionsByClass, loadOpenPredictions, computePredictionBaserate, VALID_CLOSURE_STATES, } from './predictions.js';
@@ -289,10 +289,13 @@ async function parseJsonBody(req) {
  *   - /unknown/i    → 404 (auth_revoke on unknown key_id)
  *   - /already superseded/i → 409 (chain conflict)
  *   - /not raw/i    → 400 (archive_raw on non-raw row)
- * Everything else maps to 400 (bad input).
+ * ForbiddenError maps to 403; everything else to 400 (bad input).
  */
 function mapApiError(err) {
     const message = err instanceof Error ? err.message : String(err);
+    if (err instanceof ForbiddenError) {
+        return { status: 403, message };
+    }
     const lower = message.toLowerCase();
     if (/not found/.test(lower) || /^unknown /.test(lower)) {
         return { status: 404, message };
@@ -354,6 +357,25 @@ export function isLoopback(remoteAddress) {
         return true;
     return false;
 }
+// Any other Host on a loopback socket is DNS rebinding: a hostile page resolved to 127.0.0.1.
+export const LOOPBACK_HOST_HEADER = /^(localhost|127\.0\.0\.1|\[::1\])(:\d+)?$/i;
+/** A browser request sent by another site. Non-browser clients send neither header and pass. */
+export function isCrossSite(req) {
+    const site = req.headers['sec-fetch-site'];
+    if (site !== undefined && site !== 'same-origin' && site !== 'none')
+        return true;
+    const origin = req.headers.origin;
+    return origin !== undefined && origin !== `http://${req.headers.host}`;
+}
+// A browser on this machine is loopback too, so the no-key fallback also needs a local Host and a same-site caller.
+function assertLocalCaller(req) {
+    if (!isLoopback(req.socket.remoteAddress))
+        throw new HttpError(401, 'auth required');
+    const host = req.headers.host;
+    if ((host !== undefined && !LOOPBACK_HOST_HEADER.test(host)) || isCrossSite(req)) {
+        throw new HttpError(403, 'cross-site or non-local request refused; send an API key');
+    }
+}
 function readAuthHeader(req) {
     const raw = req.headers['authorization'];
     if (raw === undefined)
@@ -455,9 +477,7 @@ function buildContextWithAuth(req, hippoRoot) {
     if (process.env.HIPPO_REQUIRE_AUTH === '1') {
         throw new HttpError(401, 'auth required');
     }
-    if (!isLoopback(req.socket.remoteAddress)) {
-        throw new HttpError(401, 'auth required');
-    }
+    assertLocalCaller(req);
     // v1.12.0: loopback fallback is process-local, treat as admin.
     return {
         hippoRoot,
@@ -492,9 +512,7 @@ function requireAuth(req, hippoRoot) {
     if (process.env.HIPPO_REQUIRE_AUTH === '1') {
         throw new HttpError(401, 'auth required');
     }
-    if (!isLoopback(req.socket.remoteAddress)) {
-        throw new HttpError(401, 'auth required');
-    }
+    assertLocalCaller(req);
 }
 function getString(obj, key) {
     const v = obj[key];
@@ -632,10 +650,7 @@ async function handleRequest(req, res, opts, startedAt, limiter) {
             throw new HttpError(400, 'q is required');
         }
         const limitRaw = query.get('limit');
-        const limit = limitRaw === null ? undefined : Number(limitRaw);
-        if (limit !== undefined && (!Number.isFinite(limit) || limit <= 0)) {
-            throw new HttpError(400, 'limit must be a positive number');
-        }
+        const limit = limitRaw === null ? undefined : parseListLimit(limitRaw);
         const mode = query.get('mode');
         if (mode !== null && mode !== 'bm25' && mode !== 'hybrid' && mode !== 'physics') {
             throw new HttpError(400, "mode must be 'bm25', 'hybrid', or 'physics'");
@@ -671,11 +686,12 @@ async function handleRequest(req, res, opts, startedAt, limiter) {
         const summarizeOverflow = summarizeOverflowRaw === null
             ? undefined
             : (summarizeOverflowRaw === '1' || summarizeOverflowRaw === 'true');
-        // v1.7.2 T4: forward as Number(...) — NaN, 0, negative all reach
-        // recall() which throws RecallContractError with code='invalid_scorer_window'.
-        // No transport-side validation; recall() owns the contract.
+        // recall() owns the shape rule (NaN, 0 and negatives throw invalid_scorer_window); the transport caps remote cost.
         const scorerWindowRaw = query.get('scorer_window');
         const scorerWindow = scorerWindowRaw === null ? undefined : Number(scorerWindowRaw);
+        if (scorerWindow !== undefined && scorerWindow > 1000) {
+            throw new HttpError(400, 'scorer_window must be <= 1000');
+        }
         // v1.7.4: session_id for the dlPFC goal-stack boost. 256-char cap mirrors
         // fresh_tail_session_id (above). Trim then drop if empty so api.recall
         // sees undefined when the param is omitted or whitespace-only.
@@ -757,7 +773,7 @@ async function handleRequest(req, res, opts, startedAt, limiter) {
             recallExtra.recallHistory = httpRecallHistory;
         if (explain)
             recallExtra.explain = explain;
-        const result = recall(ctx, {
+        const result = await retrieve(ctx, {
             query: q,
             limit,
             mode: mode ?? undefined,
@@ -1038,7 +1054,8 @@ async function handleRequest(req, res, opts, startedAt, limiter) {
     // Tenant scope (Episode A follow-up tracked in TODOS.md): api.sleep operates
     // on the WHOLE hippoRoot (cross-tenant by design, matching CLI cmdSleep).
     // The loopback-only guard is the trust boundary today. Future non-loopback
-    // serving needs an admin-role gate before exposing this route.
+    // serving must also zero the cross-tenant counters for other tenants
+    // (D1 in docs/decisions/2026-05-24-blocked-items.md).
     if (method === 'POST' && path === '/v1/sleep') {
         // Defensive per-request loopback guard. Uses the canonical isLoopback()
         // helper above so any future extension (additional mapped/IPv6 forms,
@@ -1084,11 +1101,7 @@ async function handleRequest(req, res, opts, startedAt, limiter) {
         }
         // v1.12.3: optional body.role mirrors the --role CLI flag. Validated
         // strictly — anything other than 'admin'|'member' is a 400 (no silent
-        // fallback to admin). Required note: admin Bearer can mint a member
-        // key for the same tenant; member Bearer minting an admin key is NOT
-        // blocked here today (auth_create is currently unaudited per the A5 v2
-        // note in authCreate doc). The HTTP layer trusts the buildContextWithAuth
-        // role check at admin-gated routes; mint surface remains permissive.
+        // fallback to admin). authCreate refuses a member caller with a 403.
         const roleRaw = body['role'];
         let role;
         if (roleRaw !== undefined) {
@@ -1128,10 +1141,9 @@ async function handleRequest(req, res, opts, startedAt, limiter) {
         sendJson(res, 200, result);
         return;
     }
-    // DELETE /v1/auth/keys/:keyId — revoke. authRevoke throws "Unknown key_id"
-    // for missing OR cross-tenant keys (no info leak), which mapApiError
-    // converts to 404. We return 200 with the result body rather than 204 to
-    // surface revokedAt to the caller.
+    // DELETE /v1/auth/keys/:keyId — revoke. Missing or cross-tenant keys are 404
+    // (no info leak); a member key targeting any key but its own is 403.
+    // 200 with the body rather than 204 so the caller sees revokedAt.
     const keyMatch = matchPath('/v1/auth/keys/:keyId', path);
     if (method === 'DELETE' && keyMatch) {
         validateIdSegment(keyMatch.keyId, 'key id');
@@ -3228,9 +3240,7 @@ export async function serve(opts) {
             server.close(() => resolve());
         });
     };
-    // Skip signal handlers under vitest so each test run does not register a
-    // stray SIGTERM/SIGINT listener that survives until the runner exits.
-    if (!process.env.VITEST) {
+    if (opts.handleSignals) {
         let shuttingDown = false;
         const gracefulShutdown = async (signal) => {
             if (shuttingDown)

package/dist/shared.js

@@ -153,7 +153,7 @@ export async function searchBothHybrid(query, localRoot, globalRoot, options = {
         if (!fs.existsSync(root))
             return [];
         return recallScope
-            ? loadRecallSearchEntries(root, query, searchWindow, tenantId, recallScope.requested, recallScope.additive ? 'additive' : 'exact')
+            ? loadRecallSearchEntries(root, query, searchWindow, tenantId, recallScope.requested, recallScope.additive ? 'additive' : 'exact', Boolean(includeSuperseded) || Boolean(asOf))
             : loadSearchEntries(root, query, searchWindow, tenantId);
     };
     let localEntries = loadEntries(localRoot);

package/dist/stdin.d.ts

@@ -0,0 +1,12 @@
+/** `timedOut` means the window closed with stdin still open, so absent
+ * `text` is "unknown", not "none", and present `text` may be truncated.
+ * Treating absence as a manual run is only safe when it is false. */
+export interface BoundedStdin {
+    text?: string;
+    timedOut: boolean;
+}
+/** Never blocks: a TTY resolves at once, otherwise waits up to `waitMs` of
+ * idle (default 1000ms, or `HIPPO_STDIN_WAIT_MS`), refreshed on each chunk
+ * so a slow but real write is not cut off, and capped at `waitMs * 10`. */
+export declare function readStdinBounded(waitMs?: number): Promise<BoundedStdin>;
+//# sourceMappingURL=stdin.d.ts.map

package/dist/stdin.js

@@ -0,0 +1,41 @@
+function defaultWaitMs() {
+    const parsed = Number.parseInt(process.env.HIPPO_STDIN_WAIT_MS ?? '', 10);
+    return parsed > 0 ? parsed : 1000;
+}
+/** Never blocks: a TTY resolves at once, otherwise waits up to `waitMs` of
+ * idle (default 1000ms, or `HIPPO_STDIN_WAIT_MS`), refreshed on each chunk
+ * so a slow but real write is not cut off, and capped at `waitMs * 10`. */
+export function readStdinBounded(waitMs = defaultWaitMs()) {
+    let stdin;
+    try {
+        stdin = process.stdin;
+    }
+    catch {
+        return Promise.resolve({ timedOut: false });
+    }
+    if (stdin.isTTY)
+        return Promise.resolve({ timedOut: false });
+    return new Promise((resolve) => {
+        const chunks = [];
+        const finish = (timedOut) => {
+            clearTimeout(timer);
+            clearTimeout(hardCap);
+            stdin.off('data', onData);
+            stdin.off('end', done);
+            stdin.off('error', done);
+            stdin.pause();
+            stdin.unref?.();
+            resolve({ text: chunks.length ? Buffer.concat(chunks).toString('utf8') : undefined, timedOut });
+        };
+        const done = () => finish(false);
+        const onData = (c) => { chunks.push(c); timer.refresh(); };
+        const timer = setTimeout(() => finish(true), waitMs);
+        // The idle timer refreshes per chunk, so a host that dribbles bytes
+        // forever without ending would never resolve without this ceiling.
+        const hardCap = setTimeout(() => finish(true), waitMs * 10);
+        stdin.on('data', onData);
+        stdin.once('end', done);
+        stdin.once('error', done);
+    });
+}
+//# sourceMappingURL=stdin.js.map

package/dist/store.d.ts

@@ -203,9 +203,7 @@ export declare function buildIndexFromDb(db: ReturnType<typeof openHippoDb>): Hi
  * `buildIndexFromDb`'s query.
  */
 export declare function writeIndexMirror(hippoRoot: string, index: HippoIndex): void;
-/**
- * Load the current derived index from SQLite and refresh the mirror file.
- */
+/** Load the derived index from SQLite. Read-only: writers refresh index.json, so readers never race on it. */
 export declare function loadIndex(hippoRoot: string): HippoIndex;
 /**
  * Persist mutable index metadata. Entry rows themselves are derived from SQLite.
@@ -298,6 +296,9 @@ export declare function readEntry(hippoRoot: string, id: string, tenantId?: stri
  * to fetch parent summaries for a set of overflowed leaves.
  */
 export declare function loadEntriesByIds(hippoRoot: string, ids: readonly string[], tenantId?: string): MemoryEntry[];
+/** Strengthen what a read returned: update only the four retrieval columns on the live row, never a stale copy.
+ *  Best effort: a failure logs and never fails the read. Returns the ids found in this store. */
+export declare function strengthenRetrieved(hippoRoot: string, ids: readonly string[], tenantId?: string): Set<string>;
 /**
  * All `kind='raw'` rows for a given session, tenant-scoped, returned
  * oldest-first. Used by `api.assemble` to walk a session's chronological
@@ -375,12 +376,14 @@ export declare function loadChildrenOf(hippoRoot: string, parentId: string, tena
  * removed) and `resolveConflict` (`conflict_resolve` row per resolution).
  * Default keeps `deleteEntry` byte-identical to its pre-split behavior.
  *
- * Returns `{tenantId, dagParentId}` for the removed row, or `null` if no row
- * with `id` existed.
+ * Returns `{tenantId, dagParentId}` for the removed row, or `null` if no row with `id`
+ * existed or `automatic` refused it (pinned or raw at DELETE time, so a late pin wins).
  */
 export declare function deleteEntryCore(db: ReturnType<typeof openHippoDb>, id: string, opts?: {
     actor?: string;
     suppressForgetAudit?: boolean;
+    reason?: string;
+    automatic?: boolean;
 }): {
     tenantId: string;
     dagParentId: string | null;
@@ -398,12 +401,14 @@ export declare function deleteEntryCore(db: ReturnType<typeof openHippoDb>, id:
  */
 export declare function deleteEntry(hippoRoot: string, id: string, opts?: {
     actor?: string;
+    reason?: string;
+    automatic?: boolean;
 }): boolean;
-/**
- * Batch-write and batch-delete entries in a single transaction.
- * Used by consolidation to avoid N open/close cycles.
- */
-export declare function batchWriteAndDelete(hippoRoot: string, toWrite: MemoryEntry[], toDeleteIds: string[]): void;
+/** Consolidation's flush, one transaction. With `snapshot` (rows as the caller loaded them), a write keeps only
+ *  the fields the caller changed, takes the rest from the live row, and never resurrects a row that is gone. */
+export declare function batchWriteAndDelete(hippoRoot: string, toWrite: MemoryEntry[], toDeleteIds: string[], opts?: {
+    snapshot?: ReadonlyMap<string, MemoryEntry>;
+}): string[];
 /**
  * Load all entries from SQLite.
  *
@@ -445,7 +450,7 @@ export declare function loadSearchEntries(hippoRoot: string, query: string, limi
  * mode (its `tenantId` option is optional); `loadSearchRows` already treats
  * undefined as "no tenant filter" for legacy callers.
  */
-export declare function loadRecallSearchEntries(hippoRoot: string, query: string, limit?: number, tenantId?: string, requestedScope?: string, explicitScopeMode?: 'exact' | 'additive'): MemoryEntry[];
+export declare function loadRecallSearchEntries(hippoRoot: string, query: string, limit?: number, tenantId?: string, requestedScope?: string, explicitScopeMode?: 'exact' | 'additive', includeSuperseded?: boolean): MemoryEntry[];
 /**
  * Rebuild mirrors from SQLite, importing any legacy markdown files not already present.
  */
@@ -462,6 +467,8 @@ export declare function appendConsolidationRun(hippoRoot: string, run: {
     merged: number;
     removed: number;
 }): void;
+/** Rows a tenant created since the last sleep (runs are host-wide), looking back at most 24 hours. */
+export declare function countCreatedSinceLastSleep(hippoRoot: string, tenantId: string, now?: Date): number;
 /**
  * Session decay context: provides the data needed for session-based and adaptive decay.
  */