hippo-memory 1.70.0 → 1.72.0

package/dist/store/goals.js

@@ -1,9 +1,8 @@
 // src/store/goals.ts
 import { randomUUID } from 'node:crypto';
-import { openHippoDb, closeHippoDb, withWriteScope } from '../db/index.js';
-import { compareScoresDesc } from '../core/compare.js';
+import { withWriteScope } from '../db/index.js';
+import { onHandle } from './open.js';
 const MAX_ACTIVE_GOAL_DEPTH = 3;
-const MAX_FINAL_MULTIPLIER = 3.0;
 export function rowToGoal(row) {
     return {
         id: row.id,
@@ -21,26 +20,12 @@ export function rowToGoal(row) {
     };
 }
 export function pushGoal(hippoRoot, opts) {
-    const db = openHippoDb(hippoRoot);
-    try {
+    return onHandle(hippoRoot, (db) => {
         return pushGoalWithDb(db, opts);
-    }
-    finally {
-        closeHippoDb(db);
-    }
+    });
 }
-/**
- * Depth-cap enforcer shared by pushGoalWithDb and resumeGoal.
- * If the (tenant, session) has >= MAX_ACTIVE_GOAL_DEPTH active goals,
- * suspend the oldest `overflow` ones.
- *
- * **Precondition: caller MUST already be inside a `BEGIN IMMEDIATE`
- * transaction.** Helper does not open or commit -- name reflects this so it
- * is impossible to misread the contract at a call site. Both existing call
- * sites (pushGoalWithDb, resumeGoal) wrap in `BEGIN IMMEDIATE` already.
- *
- * @internal Internal goal-stack invariant. Subject to change.
- */
+/** Depth-cap enforcer for pushGoalWithDb and resumeGoal: suspends the oldest `overflow` goals; **caller MUST be inside a `BEGIN IMMEDIATE` transaction**.
+ * @internal Internal goal-stack invariant. Subject to change. */
 function enforceDepthCapWithinTx(db, tenantId, sessionId) {
     // SAFETY: the row comes from the SELECT above, which projects exactly one
     // column, `c`, as a COUNT(*).
@@ -121,29 +106,20 @@ function insertRetrievalPolicy(db, goalId, policy) {
     return policyId;
 }
 export function getActiveGoals(hippoRoot, opts) {
-    const db = openHippoDb(hippoRoot);
-    try {
+    return onHandle(hippoRoot, (db) => {
         return getActiveGoalsWithDb(db, opts);
-    }
-    finally {
-        closeHippoDb(db);
-    }
+    });
 }
 /** The active goals and their policies on one handle, so a goal and its policy never disagree. */
 export function activeGoalsWithPolicies(hippoRoot, opts) {
-    const db = openHippoDb(hippoRoot);
-    try {
+    return onHandle(hippoRoot, (db) => {
         const goals = getActiveGoalsWithDb(db, opts);
         return { goals, policies: loadGoalPolicies(db, goals) };
-    }
-    finally {
-        closeHippoDb(db);
-    }
+    });
 }
 /** Every goal of a (tenant, session), whatever its status, oldest first. */
 export function getSessionGoals(hippoRoot, opts) {
-    const db = openHippoDb(hippoRoot);
-    try {
+    return onHandle(hippoRoot, (db) => {
         // SAFETY: rows come from the SELECT below, which projects exactly GoalRow's columns.
         const rows = db.prepare(`
       SELECT id, session_id, tenant_id, goal_name, level, parent_goal_id, status,
@@ -153,10 +129,7 @@ export function getSessionGoals(hippoRoot, opts) {
       ORDER BY created_at ASC
     `).all(opts.tenantId, opts.sessionId);
         return rows.map(rowToGoal);
-    }
-    finally {
-        closeHippoDb(db);
-    }
+    });
 }
 function getActiveGoalsWithDb(db, opts) {
     // SAFETY: rows come from the SELECT above, which projects exactly
@@ -170,84 +143,34 @@ function getActiveGoalsWithDb(db, opts) {
   `).all(opts.tenantId, opts.sessionId);
     return rows.map(rowToGoal);
 }
-// Load retrieval_policy rows for active goals so per-policy multipliers
-// can compose onto the base goal-tag boost. Composed result is hard-capped
-// at MAX_FINAL_MULTIPLIER (3.0x) BEFORE applying to score -- even an
-// `errorPriority: 9.0` policy cannot exceed 3.0x.
+// Per-goal retrieval_policy multipliers compose onto the base goal-tag boost and are hard-capped at MAX_FINAL_MULTIPLIER (3.0x) before scoring.
 function loadGoalPolicies(db, active) {
     const policiesByGoalId = new Map();
+    const policyIds = [...new Set(active.flatMap((g) => (g.retrievalPolicyId ? [g.retrievalPolicyId] : [])))];
+    if (policyIds.length === 0)
+        return policiesByGoalId;
+    // SAFETY: the SELECT projects exactly these seven retrieval_policy columns; MAX_ACTIVE_GOAL_DEPTH bounds the IN list.
+    const rows = db.prepare(`
+    SELECT id, goal_id, policy_type, weight_schema_fit, weight_recency, weight_outcome, error_priority
+    FROM retrieval_policy WHERE id IN (${policyIds.map(() => '?').join(',')})
+  `).all(...policyIds);
+    const byId = new Map(rows.map((row) => [row.id, row]));
     for (const g of active) {
-        if (!g.retrievalPolicyId)
+        const row = g.retrievalPolicyId ? byId.get(g.retrievalPolicyId) : undefined;
+        if (!row)
             continue;
-        // SAFETY: the row comes from the SELECT above, which projects exactly
-        // these seven retrieval_policy columns.
-        const row = db.prepare(`
-      SELECT id, goal_id, policy_type, weight_schema_fit, weight_recency, weight_outcome, error_priority
-      FROM retrieval_policy WHERE id = ?
-    `).get(g.retrievalPolicyId);
-        if (row) {
-            policiesByGoalId.set(g.id, {
-                id: row.id,
-                goalId: row.goal_id,
-                policyType: row.policy_type,
-                weightSchemaFit: row.weight_schema_fit,
-                weightRecency: row.weight_recency,
-                weightOutcome: row.weight_outcome,
-                errorPriority: row.error_priority,
-            });
-        }
+        policiesByGoalId.set(g.id, {
+            id: row.id,
+            goalId: row.goal_id,
+            policyType: row.policy_type,
+            weightSchemaFit: row.weight_schema_fit,
+            weightRecency: row.weight_recency,
+            weightOutcome: row.weight_outcome,
+            errorPriority: row.error_priority,
+        });
     }
     return policiesByGoalId;
 }
-/** The capped boost for one row whose tags match `matches` active goals. */
-function goalBoostMultiplier(entry, tags, matches, goalsByTag, policiesByGoalId) {
-    // Base 2.0x for first match, +0.5x per additional, capped at 3.0x.
-    let multiplier = Math.min(2.0 + 0.5 * (matches.length - 1), MAX_FINAL_MULTIPLIER);
-    // Compose per-policy multipliers per matched tag.
-    for (const tag of matches) {
-        const goal = goalsByTag.get(tag);
-        const policy = policiesByGoalId.get(goal.id);
-        if (!policy)
-            continue;
-        if (policy.policyType === 'error-prioritized' && tags.includes('error')) {
-            multiplier *= policy.errorPriority;
-        }
-        else if (policy.policyType === 'schema-fit-biased') {
-            // Linearly weight schema_fit in [0,1] up to (weightSchemaFit)x.
-            // Default 1.0 is a no-op.
-            multiplier *=
-                1.0 +
-                    Math.max(0, policy.weightSchemaFit - 1.0) *
-                        (entry.schema_fit ?? 0.5);
-        }
-        else if (policy.policyType === 'recency-first') {
-            multiplier *= policy.weightRecency;
-        }
-        else if (policy.policyType === 'hybrid') {
-            multiplier *= policy.weightOutcome;
-        }
-    }
-    // Hard cap AFTER all composition.
-    return Math.min(multiplier, MAX_FINAL_MULTIPLIER);
-}
-/** Log rows for the top `limit` boosted rows, one per matched goal. */
-function buildGoalRecallLog(boosted, matchesByEntryId, goalsByTag, opts) {
-    const { sessionId, tenantId, limit } = opts;
-    const recalledAt = new Date().toISOString();
-    const log = [];
-    for (const r of boosted.slice(0, limit)) {
-        const matches = matchesByEntryId.get(r.entry.id);
-        if (!matches || matches.length === 0)
-            continue;
-        for (const tag of matches) {
-            const goal = goalsByTag.get(tag);
-            if (!goal)
-                continue;
-            log.push({ goalId: goal.id, memoryId: r.entry.id, tenantId, sessionId, recalledAt, score: r.score });
-        }
-    }
-    return log;
-}
 /** The rows whose memory lives in this store: goal_recall_log.memory_id references memories, so a global row would fail
  *  the insert. A global result keeps its boost; it only earns no log row, so no outcome propagation. */
 export function localGoalRecallRows(db, rows) {
@@ -259,53 +182,7 @@ export function localGoalRecallRows(db, rows) {
     const localIds = new Set(local.map((r) => r.id));
     return rows.filter((r) => localIds.has(r.memoryId));
 }
-/** The goal-stack boost over goals already read, touching no store; a caller skips it under an explicit goal tag. Its log covers the top
- *  `limit` rows and keeps those whose memory is global, since only the store can tell them apart; {@link localGoalRecallRows} drops those before the write. */
-export function boostByGoals(results, active, opts) {
-    const { trace } = opts;
-    if (active.goals.length === 0)
-        return { results, log: [] };
-    const goalsByTag = new Map(active.goals.map((g) => [g.goalName, g]));
-    const policiesByGoalId = active.policies;
-    // Goal-tag matches per boosted row, keyed by entry id. Kept as a side table
-    // (rather than a spread-on `_goalMatches` marker property) so `boosted`
-    // stays exactly R[] end to end, with no cast-tag-then-strip round trip.
-    const matchesByEntryId = new Map();
-    const boosted = results
-        .map((r) => {
-        const tags = r.entry.tags ?? [];
-        const matches = tags.filter((t) => goalsByTag.has(t));
-        if (matches.length === 0)
-            return r;
-        const multiplier = goalBoostMultiplier(r.entry, tags, matches, goalsByTag, policiesByGoalId);
-        // Recall-trace side-channel: record the goal-boost step BEFORE the
-        // score is mutated, keyed by entry id; a pure read of r.score.
-        if (trace) {
-            trace.set(r.entry.id, {
-                stage: 'goal-boost',
-                multiplier,
-                scoreBefore: r.score,
-                scoreAfter: r.score * multiplier,
-                note: matches.join(', '),
-            });
-        }
-        matchesByEntryId.set(r.entry.id, matches);
-        // SAFETY: spreading a generic-constrained `r: R` widens the result to
-        // the spread's plain object type; only `score` changes, so the value
-        // still satisfies R's shape exactly.
-        return { ...r, score: r.score * multiplier };
-    })
-        // Deliberately a PLAIN stable score sort, no compareEntryIdentity
-        // tail -- a re-sort of an already deterministically-ordered ranking
-        // inherits its determinism via sort stability, and ties preserve the
-        // prior (meaningful) rank instead of reordering by content.
-        .sort((a, b) => compareScoresDesc(a.score, b.score));
-    return { results: boosted, log: buildGoalRecallLog(boosted, matchesByEntryId, goalsByTag, opts) };
-}
-/**
- * Writes goal-boost log rows. INSERT OR IGNORE because UNIQUE(memory_id, goal_id)
- * makes a re-recall during the same goal life a no-op for outcome attribution.
- */
+/** INSERT OR IGNORE: UNIQUE(memory_id, goal_id) makes a re-recall during the same goal life a no-op for outcome attribution. */
 export function writeGoalRecallLog(db, rows) {
     if (rows.length === 0)
         return;
@@ -323,8 +200,7 @@ const NEGATIVE_OUTCOME_THRESHOLD = 0.3;
 const STRENGTH_BOOST = 1.10;
 const STRENGTH_DECAY = 0.85;
 export function completeGoal(hippoRoot, goalId, opts) {
-    const db = openHippoDb(hippoRoot);
-    try {
+    return onHandle(hippoRoot, (db) => {
         const completedAt = new Date().toISOString();
         const score = opts.outcomeScore ?? null;
         withWriteScope(db, 'complete_goal', () => {
@@ -349,9 +225,7 @@ export function completeGoal(hippoRoot, goalId, opts) {
                 else if (score < NEGATIVE_OUTCOME_THRESHOLD)
                     multiplier = STRENGTH_DECAY;
                 if (multiplier !== 1) {
-                    // Lifespan window: only memories whose recall happened during this
-                    // goal's active life. UNIQUE(memory_id, goal_id) guarantees one
-                    // adjustment per (memory, goal) pair.
+                    // Lifespan window: only recalls during this goal's active life; UNIQUE(memory_id, goal_id) gives one adjustment per pair.
                     db.prepare(`
             UPDATE memories
             SET strength = MIN(1.0, MAX(0.0, strength * ?))
@@ -365,23 +239,15 @@ export function completeGoal(hippoRoot, goalId, opts) {
                 }
             }
         });
-    }
-    finally {
-        closeHippoDb(db);
-    }
+    });
 }
 export function suspendGoal(hippoRoot, goalId) {
-    const db = openHippoDb(hippoRoot);
-    try {
+    onHandle(hippoRoot, (db) => {
         db.prepare(`UPDATE goal_stack SET status = 'suspended' WHERE id = ? AND status = 'active'`).run(goalId);
-    }
-    finally {
-        closeHippoDb(db);
-    }
+    });
 }
 export function resumeGoal(hippoRoot, goalId) {
-    const db = openHippoDb(hippoRoot);
-    try {
+    return onHandle(hippoRoot, (db) => {
         withWriteScope(db, 'resume_goal', () => {
             // SAFETY: the row comes from the SELECT above, which projects exactly
             // the session_id, tenant_id, and status columns of goal_stack.
@@ -391,9 +257,6 @@ export function resumeGoal(hippoRoot, goalId) {
             enforceDepthCapWithinTx(db, row.tenant_id, row.session_id);
             db.prepare(`UPDATE goal_stack SET status = 'active' WHERE id = ?`).run(goalId);
         });
-    }
-    finally {
-        closeHippoDb(db);
-    }
+    });
 }
 //# sourceMappingURL=goals.js.map

package/dist/store/graph-queue.d.ts

@@ -1,27 +1,11 @@
-/**
- * Fail-soft producer hook: mark a tenant dirty for graph re-extraction by
- * enqueuing its consolidated mirror memory. NEVER throws into the caller — a
- * graph-dirty signal failing must not abort a core object write. Graph staleness is
- * recoverable (next sleep / manual `graph extract`); a broken `hippo decide` is
- * not. Called POST-COMMIT from the graph-source save/close mutations of
- * decision, policy, customer_note and project_brief. A null memoryId (a
- * forgotten mirror) is a no-op.
- */
+/** Fail-soft producer hook: mark a tenant dirty for graph re-extraction by enqueuing its consolidated mirror memory. NEVER throws: a failed dirty signal
+ * must not abort an object write. Call POST-COMMIT from the graph-source save/close mutations; a null memoryId (forgotten mirror) is a no-op. */
 export declare function markGraphDirty(hippoRoot: string, tenantId: string, memoryId: string | null): void;
-/**
- * Mark every pending queue item for a tenant with `id <= maxId` processed, in
- * one UPDATE. Status/processed_at only, so the consolidated-source guard trigger
- * is not involved. Returns the count marked.
- * The `<= maxId` watermark excludes items enqueued after the drain snapshot.
- */
+/** Mark every pending item for a tenant with `id <= maxId` processed in one UPDATE (status/processed_at only, so the source guard trigger is not involved).
+ * The watermark excludes items enqueued after the drain snapshot. Returns the count marked. */
 export declare function markPendingProcessedUpTo(hippoRoot: string, tenantId: string, maxId: number): number;
-/**
- * The dirty tenants awaiting graph re-extraction, each with the MAX pending
- * queue id at read time (a watermark). The sleep drain rebuilds each tenant's
- * graph, then marks only items at or below the watermark processed, so items
- * enqueued DURING the rebuild stay pending for the next sleep (no lost-update
- * race). Host-wide read (the queue is per-tenant but sleep is cross-tenant).
- */
+/** Dirty tenants awaiting graph re-extraction, each with the MAX pending queue id at read time (a watermark); host-wide, as sleep is cross-tenant.
+ * The drain marks only items at or below it processed, so items enqueued DURING the rebuild stay pending (no lost update). */
 export declare function loadPendingExtractionTenants(hippoRoot: string): {
     tenantId: string;
     maxPendingId: number;

package/dist/store/graph-queue.js

@@ -1,18 +1,14 @@
 // The graph extraction queue: the consolidated memories that wait for a graph rebuild, and the watermark the sleep drain marks them by.
-import { openHippoDb, closeHippoDb } from '../db/index.js';
+import { onHandle } from './open.js';
 import { assertTenantId } from './tenant.js';
 import { errorMessage, log } from '../util/log.js';
 import { rowToQueueItem, QUEUE_COLS } from './graph-rows.js';
 import { resolveConsolidatedSource } from './graph-writes.js';
-/**
- * Enqueue a consolidated memory for later graph extraction. Rejects a raw / missing /
- * cross-tenant memory (the DB trigger is the backstop).
- */
+/** Enqueue a consolidated memory for later graph extraction; rejects a raw / missing / cross-tenant memory (the DB trigger is the backstop). */
 function enqueueExtraction(hippoRoot, tenantId, memoryId) {
     assertTenantId('enqueueExtraction', tenantId);
     const now = new Date().toISOString();
-    const db = openHippoDb(hippoRoot);
-    try {
+    return onHandle(hippoRoot, (db) => {
         // enqueue is memory-keyed (no source object), so a missing memory still throws (correct -
         // you cannot enqueue a forgotten mirror); memoryId is non-null here by construction.
         const { sourceKind } = resolveConsolidatedSource(db, tenantId, memoryId, null, 'enqueueExtraction');
@@ -26,20 +22,10 @@ function enqueueExtraction(hippoRoot, tenantId, memoryId) {
         if (!row)
             throw new Error('enqueueExtraction: failed to reload queue item');
         return rowToQueueItem(row);
-    }
-    finally {
-        closeHippoDb(db);
-    }
+    });
 }
-/**
- * Fail-soft producer hook: mark a tenant dirty for graph re-extraction by
- * enqueuing its consolidated mirror memory. NEVER throws into the caller — a
- * graph-dirty signal failing must not abort a core object write. Graph staleness is
- * recoverable (next sleep / manual `graph extract`); a broken `hippo decide` is
- * not. Called POST-COMMIT from the graph-source save/close mutations of
- * decision, policy, customer_note and project_brief. A null memoryId (a
- * forgotten mirror) is a no-op.
- */
+/** Fail-soft producer hook: mark a tenant dirty for graph re-extraction by enqueuing its consolidated mirror memory. NEVER throws: a failed dirty signal
+ * must not abort an object write. Call POST-COMMIT from the graph-source save/close mutations; a null memoryId (forgotten mirror) is a no-op. */
 export function markGraphDirty(hippoRoot, tenantId, memoryId) {
     if (!memoryId)
         return;
@@ -52,38 +38,24 @@ export function markGraphDirty(hippoRoot, tenantId, memoryId) {
         log.warn(`markGraphDirty: enqueue failed for tenant=${tenantId} memory=${memoryId}: ${errorMessage(err)}`);
     }
 }
-/**
- * Mark every pending queue item for a tenant with `id <= maxId` processed, in
- * one UPDATE. Status/processed_at only, so the consolidated-source guard trigger
- * is not involved. Returns the count marked.
- * The `<= maxId` watermark excludes items enqueued after the drain snapshot.
- */
+/** Mark every pending item for a tenant with `id <= maxId` processed in one UPDATE (status/processed_at only, so the source guard trigger is not involved).
+ * The watermark excludes items enqueued after the drain snapshot. Returns the count marked. */
 export function markPendingProcessedUpTo(hippoRoot, tenantId, maxId) {
     assertTenantId('markPendingProcessedUpTo', tenantId);
     const now = new Date().toISOString();
-    const db = openHippoDb(hippoRoot);
-    try {
+    return onHandle(hippoRoot, (db) => {
         const res = db.prepare(`
       UPDATE graph_extraction_queue
       SET status = 'processed', processed_at = ?
       WHERE tenant_id = ? AND status = 'pending' AND id <= ?
     `).run(now, tenantId, maxId);
         return Number(res.changes ?? 0);
-    }
-    finally {
-        closeHippoDb(db);
-    }
+    });
 }
-/**
- * The dirty tenants awaiting graph re-extraction, each with the MAX pending
- * queue id at read time (a watermark). The sleep drain rebuilds each tenant's
- * graph, then marks only items at or below the watermark processed, so items
- * enqueued DURING the rebuild stay pending for the next sleep (no lost-update
- * race). Host-wide read (the queue is per-tenant but sleep is cross-tenant).
- */
+/** Dirty tenants awaiting graph re-extraction, each with the MAX pending queue id at read time (a watermark); host-wide, as sleep is cross-tenant.
+ * The drain marks only items at or below it processed, so items enqueued DURING the rebuild stay pending (no lost update). */
 export function loadPendingExtractionTenants(hippoRoot) {
-    const db = openHippoDb(hippoRoot);
-    try {
+    return onHandle(hippoRoot, (db) => {
         // SAFETY: rows' shape matches the two aliased columns (tenant_id, max_id)
         // named in the SELECT above.
         const rows = db.prepare(`
@@ -93,9 +65,6 @@ export function loadPendingExtractionTenants(hippoRoot) {
       GROUP BY tenant_id
     `).all();
         return rows.map((r) => ({ tenantId: r.tenant_id, maxPendingId: Number(r.max_id) }));
-    }
-    finally {
-        closeHippoDb(db);
-    }
+    });
 }
 //# sourceMappingURL=graph-queue.js.map

package/dist/store/graph-reads.d.ts

@@ -1,9 +1,7 @@
 import { type DatabaseSyncLike } from '../db/index.js';
 import { type EntityType, type Entity, type Relation, type StoredGraph } from './graph-rows.js';
-/** Entities with an exact `name` (read), bounded by `limit` in SQL with a
- *  deterministic order. Lets the graph-view focus query find the `--entity NAME`
- *  entity DIRECTLY (not from a globally-capped list) WITHOUT materializing every
- *  same-name row when a name maps to many entities. */
+/** Entities with an exact `name`, bounded by `limit` in SQL with a deterministic order, so graph-view focus finds `--entity NAME` directly
+ * without materializing every same-name row. */
 export declare function loadEntitiesByName(hippoRoot: string, tenantId: string, name: string, opts?: {
     limit?: number;
 }, txDb?: DatabaseSyncLike): Entity[];
@@ -18,48 +16,26 @@ export declare function loadRelations(hippoRoot: string, tenantId: string, opts?
 /** Chunk size for IN-list queries: well under SQLite's 999-bound-variable default
  *  (leaves headroom for the tenant_id param + the doubled list in neighbour lookups). */
 export declare const IN_LIST_CHUNK = 400;
-/**
- * Load entities by their primary ids. Resolves the entity rows reached during the BFS
- * (whose `memory_id` maps back to a recall result). Tenant-scoped, read-only.
- */
+/** Load entities by primary id (the BFS-reached rows whose `memory_id` maps back to a recall result). Tenant-scoped, read-only. */
 export declare function loadEntitiesByIds(hippoRoot: string, tenantId: string, ids: number[], txDb?: DatabaseSyncLike): Entity[];
-/**
- * All relations touching ANY of `entityIds` in EITHER direction (from OR to): the
- * per-hop neighbour query for multi-hop traversal. ONE query for the whole frontier
- * (not one per node): this is the bidirectional read `loadRelations` (from-only) lacks,
- * and avoids an N+1 across BFS frontier nodes. `limit` caps rows for the frontier and
- * must be a non-negative integer (the raw `LIMIT ?` rejects a fractional value).
- */
+/** All relations touching ANY of `entityIds` in EITHER direction: the per-hop neighbour query for multi-hop traversal, one query for the whole frontier
+ * (no N+1). `limit` caps rows and must be a non-negative integer (raw `LIMIT ?` rejects a fraction). */
 export declare function loadNeighborRelations(hippoRoot: string, tenantId: string, entityIds: number[], opts?: {
     limit?: number;
 }, txDb?: DatabaseSyncLike): Relation[];
-/**
- * Relations with BOTH endpoints in `entityIds` (edges AMONG the set, not merely
- * touching it). Read. Used by the graph-view focus subgraph so the displayed
- * edges are exactly the intra-union edges: the `LIMIT` only caps genuinely-many
- * intra-union edges: no out-of-union row can evict a valid in-set edge. The
- * caller bounds `entityIds` (<= the view limit), so a single query is safe.
- */
+/** Relations with BOTH endpoints in `entityIds` (edges AMONG the set), for the graph-view focus subgraph; `LIMIT` caps only intra-union edges,
+ * so no out-of-union row evicts a valid one. The caller bounds `entityIds` (<= view limit), so a single query is safe. */
 export declare function loadRelationsAmong(hippoRoot: string, tenantId: string, entityIds: number[], opts?: {
     limit?: number;
 }, txDb?: DatabaseSyncLike): Relation[];
-/**
- * Map consolidated source memory ids -> their graph entities. The SEED step of
- * multi-hop recall (recall result memory ids -> entities to traverse from). Tenant-
- * scoped, read-only; chunks the IN-list under the SQLite variable cap.
- */
+/** Map consolidated source memory ids to their graph entities: the SEED step of multi-hop recall. Tenant-scoped, read-only; chunks the IN-list under the
+ * SQLite variable cap. */
 export declare function loadEntitiesByMemoryId(hippoRoot: string, tenantId: string, memoryIds: string[]): Entity[];
 /** The stored rows a rebuild diffs against, read on the caller's handle so the diff and the apply can share one write lock. */
 export declare function storedGraphOn(db: DatabaseSyncLike, tenantId: string, memoryIds: readonly string[]): StoredGraph;
 /** storedGraphOn on its own connection, outside any write lock. */
 export declare function loadStoredGraph(hippoRoot: string, tenantId: string, memoryIds: readonly string[]): StoredGraph;
-/**
- * Run `fn` inside ONE read transaction (a single WAL snapshot) so every graph read
- * it performs (pass the supplied `txDb` to the `load*` functions) sees a consistent
- * view, even if a `graph extract` / sleep-drain rebuild commits concurrently between
- * reads (the rebuild clears + reinserts entities, so separate reads could otherwise
- * mix old entity ids with new relation ids). Reads only; the connection is opened
- * once and closed after.
- */
+/** Run `fn` in ONE read transaction (a single WAL snapshot) so every `load*` read via `txDb` sees a consistent view
+ * even if a rebuild commits concurrently (it clears and reinserts entities, so separate reads could mix old entity ids with new relation ids). */
 export declare function withGraphReadSnapshot<T>(hippoRoot: string, fn: (txDb: DatabaseSyncLike) => T): T;
 //# sourceMappingURL=graph-reads.d.ts.map