hippo-memory 1.69.0 → 1.71.0

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

@@ -1,19 +1,11 @@
-/**
- * Recall eval harness.
- *
- * Given a corpus of (query, expected_memory_ids) cases, run recall against
- * the store and report ranking-quality metrics: MRR, Recall@K, NDCG@K.
- *
- * The goal is to make recall quality measurable so MMR lambda, embedding
- * 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';
-// ---------------------------------------------------------------------------
-// Metrics — pure functions. K is inclusive of position K.
-// ---------------------------------------------------------------------------
+/** Recall eval harness: runs recall over (query, expected_memory_ids) cases and reports MRR, Recall@K and NDCG@K.
+ *  It exists so MMR lambda, embedding weights and scoring tweaks are tuned against evidence instead of intuition. */
+import { hybridSearch } from '../search/hybrid.js';
+import { searchBothHybrid } from '../sharing/search-both.js';
+import { isInitialized } from '../store/open.js';
+// Generous so metrics are not truncated.
+const DEFAULT_EVAL_BUDGET = 100_000;
+const QUERY_WORDS = 8;
 /** Mean Reciprocal Rank for a single ranking given expected ids. */
 export function mrr(returned, expected) {
     if (expected.length === 0)
@@ -38,10 +30,8 @@ export function recallAtK(returned, expected, k) {
     }
     return hits / expected.length;
 }
-/**
- * Normalized Discounted Cumulative Gain at K with binary relevance.
- * gain_i = 1 if returned[i] ∈ expected else 0. discount = log2(i + 2).
- */
+/** Normalized Discounted Cumulative Gain at K with binary relevance.
+ *  gain_i = 1 if returned[i] ∈ expected else 0. discount = log2(i + 2). */
 export function ndcgAtK(returned, expected, k) {
     if (expected.length === 0)
         return 0;
@@ -60,32 +50,12 @@ export function ndcgAtK(returned, expected, k) {
     }
     return idcg === 0 ? 0 : dcg / idcg;
 }
-// ---------------------------------------------------------------------------
-// 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,11 +80,28 @@ export async function runEval(cases, entries, options = {}) {
         durationMs: Date.now() - start,
     };
 }
-/**
- * Compute pairwise deltas between a baseline and a current eval summary.
- * Cases are matched by EvalCase.id; any mismatch is surfaced in the onlyIn
- * arrays so the caller knows the corpora diverged.
- */
+/** 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, matching cases by EvalCase.id; mismatches land in the onlyIn arrays. */
 export function compareSummaries(baseline, current) {
     const aggregate = {
         mrr: current.meanMrr - baseline.meanMrr,
@@ -158,14 +145,7 @@ export function compareSummaries(baseline, current) {
         onlyInCurrent: [...curById.keys()].filter((id) => !baseById.has(id)),
     };
 }
-// ---------------------------------------------------------------------------
-// Bootstrap — generate a synthetic corpus from current memories
-// ---------------------------------------------------------------------------
-/**
- * For each memory, take its first 8 content words as a trivial query and
- * expect that memory back. Useful as a smoke test: if recall can't find a
- * memory by its own opening words, something is broken.
- */
+/** For each memory, use its first 8 content words as a trivial query and expect that memory back: a smoke test for recall. */
 export function bootstrapCorpus(entries, maxCases = 50) {
     const cases = [];
     for (const e of entries) {
@@ -174,7 +154,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,11 +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>;
 /** Judge many candidates under a bounded concurrency pool, order preserved. */
 export declare function judgeAll(contents: readonly string[], opts: JudgeOptions): Promise<(Judgment | null)[]>;
 //# sourceMappingURL=judgment.d.ts.map

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

@@ -1,12 +1,21 @@
 /** 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 { envTypesafeApiKey } from './env.js';
-import { fetchWithRetry } from './http-retry.js';
-import { log } from './log.js';
+import { fetchWithRetry } from '../util/http-retry.js';
+import { errorMessage, log } from '../util/log.js';
+import { readCappedJson } from '../util/capped-json.js';
+import { isJsonNumber, isJsonObject, isJsonString } from '../util/json.js';
 const ENDPOINT = 'https://api.typesafe.ai/v1/systemone';
 const DEFAULT_MODEL = 'jev-1.13.0';
 const MAX_CONCURRENCY = 8;
+// An honest reply is three short answers, a few hundred bytes; 1 MiB leaves room for a verbose envelope.
+const JUDGE_MAX_REPLY_BYTES = 1024 * 1024;
+/** One named answer of a Jev reply `{ answers: { <name>: Answer } }`; an empty object when the reply has none of that shape. */
+function answerNamed(reply, name) {
+    const answers = isJsonObject(reply) ? reply.answers : undefined;
+    const answer = isJsonObject(answers) ? answers[name] : undefined;
+    return isJsonObject(answer) ? answer : {};
+}
 const QUESTIONS = {
     durable: {
         type: 'noul',
@@ -36,12 +45,8 @@ const QUESTIONS = {
 };
 const KINDS = ['error', 'decision', 'convention', 'preference', 'trivia'];
 const VALENCES = ['critical', 'negative', 'positive', 'neutral'];
-/** Absent key means hippo keeps its pre-Jev behaviour and makes no HTTP call. */
-export function judgmentApiKey() {
-    return envTypesafeApiKey();
-}
 function oneOf(value, allowed) {
-    return allowed.find((option) => option === value) ?? null;
+    return isJsonString(value) ? allowed.find((option) => option === value) ?? null : null;
 }
 /** `verified` is unreachable: that tier means a human or a test confirmed it. */
 function toConfidenceTier(kindConfidence) {
@@ -68,14 +73,14 @@ async function post(content, opts) {
         }, { timeoutMs: JUDGE_TIMEOUT_MS, fetchFn: opts.fetcher });
     }
     catch (err) {
-        log.debug(`judge: request failed: ${err instanceof Error ? err.message : String(err)}`);
+        log.debug(`judge: request failed: ${errorMessage(err)}`);
         return null;
     }
     return res.ok ? res : null;
 }
 /** `null` on any failure, so a Jev outage degrades capture to today's
  *  behaviour instead of blocking the write. */
-export async function judge(content, opts) {
+async function judge(content, opts) {
     const trimmed = content.trim();
     if (trimmed.length < 3)
         return null;
@@ -84,21 +89,19 @@ export async function judge(content, opts) {
         return null;
     let data;
     try {
-        // SAFETY: the documented Jev response is `{ answers: { <name>: Answer } }`
-        // keyed by the question names posted above; every field read below is
-        // optional-chained and range-checked before use, so a lie here returns null.
-        data = await res.json();
+        data = await readCappedJson(res, JUDGE_MAX_REPLY_BYTES);
     }
     catch (err) {
-        log.debug(`judge: unreadable response: ${err instanceof Error ? err.message : String(err)}`);
+        log.debug(`judge: unreadable response: ${errorMessage(err)}`);
         return null;
     }
-    const durable = data.answers?.durable?.noul;
-    const kind = oneOf(data.answers?.kind?.choice, KINDS);
-    const valence = oneOf(data.answers?.valence?.choice, VALENCES);
-    if (durable === undefined || durable < 0 || durable > 1 || !kind || !valence)
+    const durable = answerNamed(data, 'durable').noul;
+    const kindAnswer = answerNamed(data, 'kind');
+    const kind = oneOf(kindAnswer.choice, KINDS);
+    const valence = oneOf(answerNamed(data, 'valence').choice, VALENCES);
+    if (!isJsonNumber(durable) || durable < 0 || durable > 1 || !kind || !valence)
         return null;
-    const kindConfidence = data.answers?.kind?.confidence ?? 0;
+    const kindConfidence = isJsonNumber(kindAnswer.confidence) ? kindAnswer.confidence : 0;
     return { durable, kind, valence, confidence: toConfidenceTier(kindConfidence), kindConfidence };
 }
 /** Judge many candidates under a bounded concurrency pool, order preserved. */

package/dist/extensions/openclaw-plugin/index.js

@@ -226,9 +226,8 @@ export default function register(api) {
         async execute(_id, params) {
             const cfg = getConfig(api);
             const budget = params.budget ?? cfg.budget ?? 1500;
-            const framing = cfg.framing ?? 'observe';
             const hippoCwd = resolveHippoCwdFromContext(api, ctx, cfg.root);
-            const result = runHippo(['recall', params.query, '--budget', String(budget), '--framing', framing], hippoCwd);
+            const result = runHippo(['recall', params.query, '--budget', String(budget)], hippoCwd);
             return { content: [{ type: 'text', text: result || 'No relevant memories found.' }] };
         },
     }));
@@ -281,7 +280,7 @@ export default function register(api) {
     // --- Tool: hippo_outcome ---
     api.registerTool((ctx) => ({
         name: 'hippo_outcome',
-        description: 'Report whether recalled memories were useful. Strengthens good memories (+5 days half-life) and weakens bad ones (-3 days). Call after completing work.',
+        description: "Report whether recalled memories were useful. Good outcomes slow a memory's decay and bad ones speed it up, in proportion to its record. Call after completing work.",
         parameters: {
             type: 'object',
             properties: {

package/dist/graph/delta.d.ts

@@ -1,4 +1,5 @@
-import type { GraphTxDb, EntityType, RelationType, SourceObjectRef } from './types.js';
+import type { DatabaseSyncLike } from '../db/index.js';
+import type { EntityType, RelationType, SourceObjectRef } from '../store/graph-rows.js';
 /** What names an object-derived entity across rebuilds; v38 has no UNIQUE on it, so the diff keeps one row per key. */
 export interface NaturalKey {
     readonly entityType: EntityType;
@@ -38,7 +39,7 @@ export type GraphOp = {
 };
 export declare function entityKey(k: NaturalKey): string;
 /** Ops that turn the stored graph into `desired`, in apply order; reads only, and keeps the lowest id per natural key. */
-export declare function graphDelta(db: GraphTxDb, tenantId: string, desired: DesiredGraph): GraphOp[];
+export declare function graphDelta(db: DatabaseSyncLike, tenantId: string, desired: DesiredGraph): GraphOp[];
 /** graphDelta on its own connection and outside any write lock; the apply re-checks each op against what changed since. */
 export declare function readGraphDelta(hippoRoot: string, tenantId: string, desired: DesiredGraph): GraphOp[];
 //# sourceMappingURL=delta.d.ts.map

package/dist/graph/delta.js

@@ -1,5 +1,4 @@
-// Diffs the derived graph against the stored rows, so a rebuild writes only what changed and an entity keeps the id its relations hang on.
-import { openHippoDb, closeHippoDb } from '../db.js';
+import { loadStoredGraph, storedGraphOn } from '../store/graph-reads.js';
 const keyText = (entityType, objectType, objectId) => `${entityType}|${objectType}:${objectId}`;
 export function entityKey(k) {
     return keyText(k.entityType, k.sourceObject.type, k.sourceObject.id);
@@ -15,17 +14,12 @@ function provenanceOf(memoryId, kinds) {
     const kind = memoryId === null ? undefined : kinds.get(memoryId);
     return kind === undefined ? '|distilled' : `${memoryId}|${kind}`;
 }
-function memoryKindsOf(db, desired) {
+function memoryIdsOf(desired) {
     const ids = new Set();
     for (const row of [...desired.entities, ...desired.relations])
         if (row.memoryId !== null)
             ids.add(row.memoryId);
-    if (ids.size === 0)
-        return new Map();
-    // SAFETY: the SELECT names exactly the two columns of the row type.
-    const rows = db.prepare(`SELECT id, kind FROM memories WHERE id IN (SELECT value FROM json_each(?))`)
-        .all(JSON.stringify([...ids]));
-    return new Map(rows.map((r) => [r.id, r.kind]));
+    return [...ids];
 }
 function firstByKey(rows, keyOf) {
     const out = new Map();
@@ -86,24 +80,16 @@ function diffRelations(stored, desired, keptKeyById, kinds) {
             inserts.push({ op: 'insertRelation', relation });
     return [...deletes, ...inserts];
 }
+function deltaOf(stored, desired) {
+    const entityDelta = diffEntities(stored.entities, desired.entities, stored.kinds);
+    return [...entityDelta.ops, ...diffRelations(stored.relations, desired.relations, entityDelta.keptKeyById, stored.kinds)];
+}
 /** Ops that turn the stored graph into `desired`, in apply order; reads only, and keeps the lowest id per natural key. */
 export function graphDelta(db, tenantId, desired) {
-    const kinds = memoryKindsOf(db, desired);
-    // SAFETY: the SELECT names exactly the columns of StoredEntity.
-    const entities = db.prepare(`SELECT id, entity_type, name, memory_id, source_kind, source_object_type, source_object_id FROM entities WHERE tenant_id = ? ORDER BY id`).all(tenantId);
-    // SAFETY: the SELECT names exactly the columns of StoredRelation.
-    const relations = db.prepare(`SELECT id, from_entity_id, to_entity_id, rel_type, memory_id, source_kind, source_object_type, source_object_id FROM relations WHERE tenant_id = ? ORDER BY id`).all(tenantId);
-    const entityDelta = diffEntities(entities, desired.entities, kinds);
-    return [...entityDelta.ops, ...diffRelations(relations, desired.relations, entityDelta.keptKeyById, kinds)];
+    return deltaOf(storedGraphOn(db, tenantId, memoryIdsOf(desired)), desired);
 }
 /** graphDelta on its own connection and outside any write lock; the apply re-checks each op against what changed since. */
 export function readGraphDelta(hippoRoot, tenantId, desired) {
-    const db = openHippoDb(hippoRoot);
-    try {
-        return graphDelta(db, tenantId, desired);
-    }
-    finally {
-        closeHippoDb(db);
-    }
+    return deltaOf(loadStoredGraph(hippoRoot, tenantId, memoryIdsOf(desired)), desired);
 }
 //# sourceMappingURL=delta.js.map

package/dist/{graph-extract.d.ts → graph/extract.d.ts}

@@ -1,34 +1,12 @@
-/**
- * Deterministic entity extraction.
- *
- * Populates the graph from the already-structured consolidated first-class object tables -
- * NO NLP, no precision gate for entities + supersedes. The graph is a pure derived
- * function of the current object state, so `extractGraph` is an idempotent REBUILD: derive
- * entities + `supersedes` relations from decisions /
- * policies / customer_notes / project_briefs (the four object types whose kind maps to the
- * `entity_type` enum), then write only their difference from the stored rows. All writes go
- * through the src/graph/write.ts consolidated-source guard; this module issues no raw SQL.
- *
- * Pass 3 adds the
- * first CROSS-OBJECT relations: a deterministic NAME-MATCH heuristic that emits a
- * `references` edge when one consolidated object's text contains another entity's name.
- * It is conservative (word-boundary, length-bounded, ambiguity-guarded, per-source
- * capped); its precision is measured + reported, not assumed.
- *
- * Deferred (follow-ups): NLP prose-extraction (semantic depends-on / blocked-by / owns);
- * skill/incident/process entities (not in the entity_type enum - needs a migration); the
- * `hippo sleep` enqueue-hook.
- */
-import { type EntityType } from './graph/types.js';
-import { type DesiredGraph } from './graph/delta.js';
-import { type WriteBudget } from './write-budget.js';
-/** Per-type load cap (the loaders default to 100). A type whose active or superseded
- *  set exceeds this is truncated; `ExtractResult.truncated` records it so the
- *  incompleteness is observable rather than silent. */
+/** Deterministic entity extraction: the graph is a pure function of the consolidated object tables (decisions, policies, customer_notes, project_briefs).
+ *  Writes go through the src/store/graph-writes.ts consolidated-source guard. Pass 3 adds `references` edges by a conservative name-match heuristic. */
+import { type EntityType } from '../store/graph-rows.js';
+import { type DesiredGraph } from './delta.js';
+import { type WriteBudget } from '../util/write-budget.js';
+/** Per-type load cap (the loaders default to 100); a type over it is truncated and `ExtractResult.truncated` records that. */
 export declare const MAX_EXTRACT_PER_TYPE = 10000;
-/** A target entity name must be in [MIN, MAX] chars to be matched: MIN skips short /
- *  generic words; MAX skips prose (a decision's prose name is never a target, only a
- *  source). */
+/** A target entity name must be in [MIN, MAX] chars to be matched: MIN skips short, generic words; MAX skips prose
+ *  (a decision's prose name is never a target, only a source). */
 export declare const MIN_REF_NAME_LEN = 4;
 export declare const MAX_REF_NAME_LEN = 80;
 /** Per-source cap so one object cannot explode the graph with references edges. */
@@ -62,7 +40,7 @@ export interface ExtractRow {
     /** The successor's object id (Y) when this row (X) is superseded; null otherwise. */
     supersededBy: number | null;
 }
-/** One object type's loaded rows. */
+/** One object type's rows, loaded and normalised. */
 export interface LoadedType {
     entityType: EntityType;
     rows: ExtractRow[];
@@ -85,4 +63,4 @@ export declare function extractGraph(hippoRoot: string, tenantId: string): Extra
 /** extractGraph for sleep: diffs outside the lock, then applies in transactions of about `budget.holdMs` with a pause
  *  between them. A run stopped between chunks leaves a mixed graph that the next run's diff finishes. */
 export declare function extractGraphChunked(hippoRoot: string, tenantId: string, budget?: WriteBudget): Promise<ExtractResult>;
-//# sourceMappingURL=graph-extract.d.ts.map
+//# sourceMappingURL=extract.d.ts.map

package/dist/{graph-extract.js → graph/extract.js}

@@ -1,43 +1,21 @@
-/**
- * Deterministic entity extraction.
- *
- * Populates the graph from the already-structured consolidated first-class object tables -
- * NO NLP, no precision gate for entities + supersedes. The graph is a pure derived
- * function of the current object state, so `extractGraph` is an idempotent REBUILD: derive
- * entities + `supersedes` relations from decisions /
- * policies / customer_notes / project_briefs (the four object types whose kind maps to the
- * `entity_type` enum), then write only their difference from the stored rows. All writes go
- * through the src/graph/write.ts consolidated-source guard; this module issues no raw SQL.
- *
- * Pass 3 adds the
- * first CROSS-OBJECT relations: a deterministic NAME-MATCH heuristic that emits a
- * `references` edge when one consolidated object's text contains another entity's name.
- * It is conservative (word-boundary, length-bounded, ambiguity-guarded, per-source
- * capped); its precision is measured + reported, not assumed.
- *
- * Deferred (follow-ups): NLP prose-extraction (semantic depends-on / blocked-by / owns);
- * skill/incident/process entities (not in the entity_type enum - needs a migration); the
- * `hippo sleep` enqueue-hook.
- */
-import { applyGraphOps, runGraphRebuildTransaction } from './graph/write.js';
-import { MAX_ENTITY_NAME_LEN } from './graph/types.js';
-import { graphDelta, readGraphDelta } from './graph/delta.js';
-import { WRITE_BUDGET } from './write-budget.js';
-import { SLEEP_DB_WAIT_MS } from './db.js';
-import { loadDecisions } from './decisions.js';
-import { loadPolicies } from './policies.js';
-import { loadCustomerNotes } from './customer-notes.js';
-import { loadProjectBriefs } from './project-briefs.js';
-import { assertTenantId } from './tenant.js';
-import { escapeRegex } from './escape.js';
-/** Per-type load cap (the loaders default to 100). A type whose active or superseded
- *  set exceeds this is truncated; `ExtractResult.truncated` records it so the
- *  incompleteness is observable rather than silent. */
+/** Deterministic entity extraction: the graph is a pure function of the consolidated object tables (decisions, policies, customer_notes, project_briefs).
+ *  Writes go through the src/store/graph-writes.ts consolidated-source guard. Pass 3 adds `references` edges by a conservative name-match heuristic. */
+import { applyGraphOps } from './write.js';
+import { runGraphRebuildTransaction } from '../store/graph-writes.js';
+import { MAX_ENTITY_NAME_LEN } from '../store/graph-rows.js';
+import { graphDelta, readGraphDelta } from './delta.js';
+import { WRITE_BUDGET } from '../util/write-budget.js';
+import { SLEEP_DB_WAIT_MS } from '../db/index.js';
+import { loadDecisions } from '../objects/decisions.js';
+import { loadPolicies } from '../objects/policies.js';
+import { loadCustomerNotes } from '../objects/customer-notes.js';
+import { loadProjectBriefs } from '../objects/project-briefs.js';
+import { assertTenantId } from '../store/tenant.js';
+import { escapeRegex } from '../util/escape.js';
+/** Per-type load cap (the loaders default to 100); a type over it is truncated and `ExtractResult.truncated` records that. */
 export const MAX_EXTRACT_PER_TYPE = 10000;
-// --- Pass 3 (cross-object references) tunables ------------------------------------
-/** A target entity name must be in [MIN, MAX] chars to be matched: MIN skips short /
- *  generic words; MAX skips prose (a decision's prose name is never a target, only a
- *  source). */
+/** A target entity name must be in [MIN, MAX] chars to be matched: MIN skips short, generic words; MAX skips prose
+ *  (a decision's prose name is never a target, only a source). */
 export const MIN_REF_NAME_LEN = 4;
 export const MAX_REF_NAME_LEN = 80;
 /** Per-source cap so one object cannot explode the graph with references edges. */
@@ -71,52 +49,33 @@ function sourceObjectOf(entityType, e2Id) {
 function pairKey(a, b) {
     return a < b ? `${a}:${b}` : `${b}:${a}`;
 }
-/**
- * Load a type's ACTIVE + SUPERSEDED rows (excluding `closed` = retired), normalised.
- * Calls the loader once per status so MAX_EXTRACT_PER_TYPE is a per-status budget
- * (closed rows never consume it). Sets `hitCap` when either status load is full.
- */
-function loadType(hippoRoot, tenantId, entityType, 
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-loadFn, 
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-nameOf, 
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-textOf) {
-    const rows = [];
-    let hitCap = false;
-    for (const status of ['active', 'superseded']) {
-        const loaded = loadFn(hippoRoot, tenantId, { status, limit: MAX_EXTRACT_PER_TYPE });
-        if (loaded.length === MAX_EXTRACT_PER_TYPE)
-            hitCap = true;
-        for (const r of loaded) {
-            // SAFETY: loadFn is always one of loadDecisions/loadPolicies/loadCustomerNotes/
-            // loadProjectBriefs (wired in GRAPH_SOURCES); every one of their row
-            // types declares id: number, memoryId: string | null, supersededBy: number | null.
-            // `any` here is the deliberate type-erasure boundary (see eslint-disable above)
-            // that lets one loop handle all four object row shapes.
-            rows.push({
-                entityType,
-                e2Id: r.id,
-                name: nameOf(r),
-                searchText: textOf(r),
-                memoryId: (r.memoryId ?? null),
-                supersededBy: (r.supersededBy ?? null),
-            });
+/** Close over one loader's row type so the table below holds uniform functions. Loads ACTIVE and SUPERSEDED rows (not `closed`),
+ *  one call per status, so MAX_EXTRACT_PER_TYPE is a per-status budget; `hitCap` is set when either load is full. */
+function source(entityType, load, nameOf, textOf) {
+    return (hippoRoot, tenantId) => {
+        const rows = [];
+        let hitCap = false;
+        for (const status of ['active', 'superseded']) {
+            const loaded = load(hippoRoot, tenantId, { status, limit: MAX_EXTRACT_PER_TYPE });
+            if (loaded.length === MAX_EXTRACT_PER_TYPE)
+                hitCap = true;
+            for (const r of loaded) {
+                rows.push({ entityType, e2Id: r.id, name: nameOf(r), searchText: textOf(r), memoryId: r.memoryId, supersededBy: r.supersededBy });
+            }
         }
-    }
-    return { entityType, rows, hitCap };
+        return { entityType, rows, hitCap };
+    };
 }
 const GRAPH_SOURCES = [
-    { entityType: 'decision', loadFn: loadDecisions, nameOf: (r) => r.decisionText, textOf: (r) => [r.decisionText, r.context].filter(Boolean).join(' ') },
-    { entityType: 'policy', loadFn: loadPolicies, nameOf: (r) => r.policyName, textOf: (r) => [r.policyName, r.policyText].filter(Boolean).join(' ') },
-    { entityType: 'customer', loadFn: loadCustomerNotes, nameOf: (r) => r.customer, textOf: (r) => [r.customer, r.note].filter(Boolean).join(' ') },
-    { entityType: 'project', loadFn: loadProjectBriefs, nameOf: (r) => r.repo, textOf: (r) => [r.repo, r.summary].filter(Boolean).join(' ') },
+    source('decision', loadDecisions, (r) => r.decisionText, (r) => [r.decisionText, r.context].filter(Boolean).join(' ')),
+    source('policy', loadPolicies, (r) => r.policyName, (r) => [r.policyName, r.policyText].filter(Boolean).join(' ')),
+    source('customer', loadCustomerNotes, (r) => r.customer, (r) => [r.customer, r.note].filter(Boolean).join(' ')),
+    source('project', loadProjectBriefs, (r) => r.repo, (r) => [r.repo, r.summary].filter(Boolean).join(' ')),
 ];
 /** Every source type's rows, each read on its own connection; callers load before any write lock is taken. */
 export function loadGraphSources(hippoRoot, tenantId) {
     assertTenantId('loadGraphSources', tenantId);
-    return GRAPH_SOURCES.map((src) => loadType(hippoRoot, tenantId, src.entityType, src.loadFn, src.nameOf, src.textOf));
+    return GRAPH_SOURCES.map((load) => load(hippoRoot, tenantId));
 }
 /** The tenant's graph as a pure function of its loaded objects; the write side diffs it against what is stored. */
 export function deriveGraph(loaded) {
@@ -261,7 +220,7 @@ export function extractGraph(hippoRoot, tenantId) {
     // Loaded first: opening a second connection under the rebuild's BEGIN IMMEDIATE dead-locks ('database is locked').
     const derived = deriveGraph(loadGraphSources(hippoRoot, tenantId));
     // Diffed and applied under one lock, so two concurrent rebuilds serialize instead of both inserting a missing row.
-    const skipped = runGraphRebuildTransaction(hippoRoot, tenantId, (txDb) => applyGraphOps(txDb, hippoRoot, tenantId, graphDelta(txDb, tenantId, derived), 0, { holdMs: Infinity }).skipped);
+    const skipped = runGraphRebuildTransaction(hippoRoot, tenantId, (txDb) => applyGraphOps(txDb, hippoRoot, tenantId, graphDelta(txDb, tenantId, derived), { from: 0, holdMs: Infinity }).skipped);
     return resultOf(derived, skipped);
 }
 /** extractGraph for sleep: diffs outside the lock, then applies in transactions of about `budget.holdMs` with a pause
@@ -278,11 +237,11 @@ export async function extractGraphChunked(hippoRoot, tenantId, budget = WRITE_BU
             await budget.pause(committedAt);
         const from = next;
         // Sleep's wait, not a server request's 250 ms: each chunk is a fresh BEGIN IMMEDIATE a hook's write could otherwise fail.
-        const chunk = runGraphRebuildTransaction(hippoRoot, tenantId, (txDb) => applyGraphOps(txDb, hippoRoot, tenantId, ops, from, { holdMs: budget.holdMs, clock: budget.clock }), { busyWaitMs: SLEEP_DB_WAIT_MS });
+        const chunk = runGraphRebuildTransaction(hippoRoot, tenantId, (txDb) => applyGraphOps(txDb, hippoRoot, tenantId, ops, { from, holdMs: budget.holdMs, clock: budget.clock }), { busyWaitMs: SLEEP_DB_WAIT_MS });
         committedAt = budget.clock();
         next = chunk.next;
         skipped += chunk.skipped;
     }
     return resultOf(derived, skipped);
 }
-//# sourceMappingURL=graph-extract.js.map
+//# sourceMappingURL=extract.js.map

package/dist/{graph-recall.d.ts → graph/recall.d.ts}

@@ -1,4 +1,4 @@
-import { type ResultCost, type SearchResult } from './search/types.js';
+import { type ResultCost, type SearchResult } from '../core/search-types.js';
 /** Hard cap on `--hops` (a higher value just walks more of a finite graph; this bounds
  *  worst-case work and keeps the flag honest). */
 export declare const MAX_HOPS = 3;
@@ -17,9 +17,8 @@ export interface GraphExpandOpts {
     tenantId: string;
     /** Mirror the recall handler's hard filters when re-loading graph-reached rows. */
     includeSuperseded?: boolean;
-    /** ISO date; bi-temporal as-of filter applied to graph-reached rows (full rule, matching
-     *  cmdRecall: a row is visible if valid_from <= asOf AND, when superseded, its successor
-     *  was not yet valid at asOf). */
+    /** ISO date; bi-temporal as-of filter applied to graph-reached rows, matching cmdRecall:
+     *  visible if valid_from <= asOf and, when superseded, its successor was not yet valid at asOf. */
     asOf?: string;
     /** Token budget for the augmented set (defaults to DEFAULT_RECALL_BUDGET, matching recall). */
     budget?: number;
@@ -28,28 +27,16 @@ export interface GraphExpandOpts {
     /** The recall --min-results floor: this many top base rows are kept regardless of
      *  budget, so graph expansion never violates the floor. Defaults to 1. */
     minResults?: number;
-    /** Recall-side envelope scope rule applied to graph-REACHED memories (the injected
-     *  rows), mirroring shared.ts SearchBothOptions.recallScope. Omitted = default-deny
-     *  (private + quarantine scopes excluded, NULL passes) — the fail-closed default for
-     *  bare/SDK callers. { requested, additive: true } = CLI --scope unlock semantics
-     *  (passesCliRecallScopeFilter); additive false/absent with requested set = api
-     *  exact-narrowing semantics (passesScopeFilterForRecall). Base results are the
-     *  caller's responsibility (they passed through the caller's own scope filter). */
+    /** Recall-side scope rule applied to graph-REACHED memories only (base results already passed the caller), mirroring HybridSearchOptions.recallScope.
+     *  Omitted = default-deny (private and quarantine excluded, NULL passes), the fail-closed default for SDK callers.
+     *  { requested, additive: true } is CLI --scope unlock (passesCliRecallScopeFilter); otherwise exact narrowing (passesScopeFilterForRecall). */
     recallScope?: {
         requested?: string;
         additive?: boolean;
         ownScope?: string;
     };
 }
-/**
- * Augment `baseResults` with memories reached by walking the graph `hops` edges out from
- * the seed results' entities (across the local AND global stores). Each graph hit is
- * inserted directly after the base result it descends from, scored just below that seed;
- * the base list's own order is preserved. Token-budget-bounded; deduped against the base
- * set and across stores.
- *
- * No-op (returns `baseResults` unchanged) when `hops <= 0`, there are no base results, the
- * graph is empty, no seed maps to an entity, or nothing new survives the filters/budget.
- */
+/** Augment `baseResults` with memories reached by walking `hops` graph edges from the seeds across local AND global stores, each placed after its seed.
+ *  Returns `baseResults` unchanged when `hops <= 0`, there are no base results, or nothing new survives the filters and the token budget. */
 export declare function graphExpandRecall(baseResults: SearchResult[], opts: GraphExpandOpts): SearchResult[];
-//# sourceMappingURL=graph-recall.d.ts.map
+//# sourceMappingURL=recall.d.ts.map