hippo-memory 1.63.1 → 1.64.0

package/dist/graph-extract.js

@@ -3,11 +3,11 @@
  *
  * 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: clear
- * the tenant's graph, then re-derive entities + `supersedes` relations from decisions /
+ * 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). All writes go through the src/graph.ts consolidated-source guard
- * (insertEntity / insertRelation / clearGraph); this module issues no raw SQL.
+ * `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
@@ -19,8 +19,11 @@
  * skill/incident/process entities (not in the entity_type enum - needs a migration); the
  * `hippo sleep` enqueue-hook.
  */
-import { clearGraph, insertEntity, insertRelation, runGraphRebuildTransaction } from './graph/write.js';
+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';
@@ -64,7 +67,7 @@ function sourceObjectOf(entityType, e2Id) {
         throw new Error(`graph-extract: entityType '${entityType}' has no source_object_type mapping`);
     return { type, id: e2Id };
 }
-/** Unordered entity-id pair key, so a relation between a,b is found in either direction. */
+/** Unordered entity-key pair, so a relation between a,b is found in either direction. */
 function pairKey(a, b) {
     return a < b ? `${a}:${b}` : `${b}:${a}`;
 }
@@ -88,7 +91,7 @@ textOf) {
             hitCap = true;
         for (const r of loaded) {
             // SAFETY: loadFn is always one of loadDecisions/loadPolicies/loadCustomerNotes/
-            // loadProjectBriefs (wired at each extractGraph call site); every one of their row
+            // 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.
@@ -102,144 +105,97 @@ textOf) {
             });
         }
     }
-    return { rows, hitCap };
+    return { entityType, rows, hitCap };
 }
-/**
- * Idempotent rebuild of the tenant's deterministic graph from its consolidated first-class
- * objects. Returns the entity/relation counts (+ which types were truncated at the
- * per-type cap). Safe to re-run: output is a pure function of the current object state.
- */
-export function extractGraph(hippoRoot, tenantId) {
-    assertTenantId('extractGraph', tenantId);
-    const 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(' ') },
-    ];
-    // READ PHASE: load every source's rows on their own connections BEFORE the
-    // write transaction. Holding the rebuild's BEGIN IMMEDIATE write lock while
-    // opening a second connection for these reads dead-locks ('database is
-    // locked'); preloading keeps the transaction single-connection.
-    const loaded = sources.map((src) => {
-        const { rows, hitCap } = loadType(hippoRoot, tenantId, src.entityType, src.loadFn, src.nameOf, src.textOf);
-        return { entityType: src.entityType, rows, hitCap };
-    });
-    // WRITE PHASE: clear + every insert run in ONE transaction, so two
-    // concurrent rebuilds serialize on the SQLite write lock (no duplicate rows)
-    // and a throw mid-rebuild rolls back the clear (no bricked graph). No second
-    // connection is opened inside.
-    return runGraphRebuildTransaction(hippoRoot, tenantId, (txDb) => rebuildGraphRows(txDb, hippoRoot, tenantId, loaded));
+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(' ') },
+];
+/** 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));
+}
+/** 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) {
+    const pass = deriveEntities(loaded);
+    const supersedes = deriveSupersedes(pass);
+    const references = deriveReferences(pass.created, supersedes.supersededPairs, pass.truncated);
+    return {
+        entities: pass.created.map((e) => ({ entityType: e.entityType, sourceObject: e.sourceObject, name: e.name, memoryId: e.memoryId })),
+        relations: [...supersedes.relations, ...references],
+        byType: pass.byType,
+        truncated: pass.truncated,
+        references: references.length,
+    };
 }
-// Pass 1: entities. Every ACTIVE/SUPERSEDED object row becomes an entity ANCHORED to its
-// authoritative object (source_object_type/id) - it survives a forgotten mirror
-// (memory_id NULL). The mirror memory is passed through only when it still exists
-// (it remains a recall pointer until forgotten/pruned).
-function insertEntityRows(txDb, hippoRoot, tenantId, loaded) {
-    const pass = { byType: {}, truncated: [], allRows: [], entityIdByKey: new Map(), memoryIdByKey: new Map(), created: [] };
+const naturalKeyOf = (e) => ({ entityType: e.entityType, sourceObject: e.sourceObject });
+// Pass 1: every active or superseded object row becomes an entity anchored to its object, so it survives a
+// forgotten mirror; the mirror memory rides along only while it exists.
+function deriveEntities(loaded) {
+    const pass = { byType: {}, truncated: [], allRows: [], byKey: new Map(), created: [] };
     for (const { entityType, rows, hitCap } of loaded) {
         if (hitCap)
             pass.truncated.push(entityType);
         pass.byType[entityType] = 0;
         for (const row of rows) {
             pass.allRows.push(row);
-            // Name fields are uncapped at source and insertEntity rejects an over-cap or empty name,
-            // which after clearGraph would brick the rebuild. Trim before capping so leading
-            // whitespace cannot slice to ''; skip a still-empty label rather than throw.
-            const name = (row.name ?? '').trim().slice(0, MAX_ENTITY_NAME_LEN);
-            if (name.length === 0)
+            // Names are uncapped at source; trimming on both sides of the cap gives the exact name insertEntity stores.
+            const name = (row.name ?? '').trim().slice(0, MAX_ENTITY_NAME_LEN).trim();
+            const key = keyOf(row.entityType, row.e2Id);
+            // A row seen twice was superseded between the two status loads; its first sighting stands.
+            if (name.length === 0 || pass.byKey.has(key))
                 continue;
-            const sourceObject = sourceObjectOf(row.entityType, row.e2Id);
-            const entity = insertEntity(hippoRoot, tenantId, {
+            const entity = {
                 entityType: row.entityType,
+                sourceObject: sourceObjectOf(row.entityType, row.e2Id),
                 name,
                 memoryId: row.memoryId,
-                sourceObject,
-            }, txDb);
-            const k = keyOf(row.entityType, row.e2Id);
-            pass.entityIdByKey.set(k, entity.id);
-            pass.memoryIdByKey.set(k, row.memoryId);
-            pass.created.push({ entityId: entity.id, entityType: row.entityType, memoryId: row.memoryId, sourceObject, name, searchText: row.searchText ?? '', superseded: row.supersededBy !== null });
+                key,
+                searchText: row.searchText ?? '',
+                superseded: row.supersededBy !== null,
+            };
+            pass.byKey.set(key, entity);
+            pass.created.push(entity);
             pass.byType[entityType] += 1;
         }
     }
     return pass;
 }
-// "Y supersedes X" - but only when BOTH X and Y were EXTRACTED (e.g. Y may be closed
-// and absent). The emit guard is ENTITY presence (entityIdByKey), not memory presence:
-// a forgotten successor mirror must still emit the edge. The relation is anchored to Y's
-// authoritative object; Y's mirror memory is passed only when it still lives.
-function insertSupersedesRelations(txDb, hippoRoot, tenantId, pass) {
-    let relations = 0;
-    // Entity-id pairs already related by supersedes (unordered). Pass 3 skips a references
-    // edge for such a pair: a version-extends-its-predecessor's-name containment (e.g.
-    // "Adopt X (managed)" contains "Adopt X") is a name artifact, not a cross-reference,
-    // and supersedes already captures their relationship.
+// Pass 2: "Y supersedes X" when both were derived (Y may be closed and absent). The edge is anchored to the
+// successor's object and carries its mirror memory only while that lives.
+function deriveSupersedes(pass) {
+    const relations = [];
+    // Pass 3 skips these pairs: "Adopt X (managed)" containing "Adopt X" is a version, not a cross-reference.
     const supersededPairs = new Set();
     for (const row of pass.allRows) {
         if (row.supersededBy === null)
             continue;
-        const xKey = keyOf(row.entityType, row.e2Id);
-        const yKey = keyOf(row.entityType, row.supersededBy);
-        const fromId = pass.entityIdByKey.get(yKey); // successor Y
-        const toId = pass.entityIdByKey.get(xKey); // superseded X
-        if (fromId === undefined || toId === undefined)
+        const successor = pass.byKey.get(keyOf(row.entityType, row.supersededBy));
+        const superseded = pass.byKey.get(keyOf(row.entityType, row.e2Id));
+        if (!successor || !superseded)
             continue;
-        const yMemoryId = pass.memoryIdByKey.get(yKey) ?? null; // successor's mirror, null if gone
-        insertRelation(hippoRoot, tenantId, {
-            fromEntityId: fromId,
-            toEntityId: toId,
+        relations.push({
+            from: naturalKeyOf(successor),
+            to: naturalKeyOf(superseded),
             relType: 'supersedes',
-            memoryId: yMemoryId,
-            sourceObject: sourceObjectOf(row.entityType, row.supersededBy), // successor Y's object
-        }, txDb);
-        supersededPairs.add(pairKey(fromId, toId));
-        relations += 1;
+            memoryId: successor.memoryId,
+            sourceObject: successor.sourceObject,
+        });
+        supersededPairs.add(pairKey(successor.key, superseded.key));
     }
     return { relations, supersededPairs };
 }
-/**
- * The deterministic rebuild WRITES, run inside `runGraphRebuildTransaction`'s
- * transaction (`txDb` is its connection). Clears the tenant's graph then
- * re-derives entities + `supersedes` + `references` from the preloaded rows. All
- * DB access here is on `txDb` (or in-memory) — no other connection is opened.
- */
-function rebuildGraphRows(txDb, hippoRoot, tenantId, loaded) {
-    // Rebuild from scratch: the graph is derived, so clear then re-derive.
-    clearGraph(hippoRoot, tenantId, txDb);
-    const pass = insertEntityRows(txDb, hippoRoot, tenantId, loaded);
-    const { byType, truncated, created } = pass;
-    const supersedes = insertSupersedesRelations(txDb, hippoRoot, tenantId, pass);
-    let relations = supersedes.relations;
-    // Pass 3: cross-object `references` edges via conservative name matching. A source's
-    // text containing a target entity's name -> "source references target". Sources +
-    // targets are CREATED entities only, each anchored to its source object (so the
-    // edge survives a forgotten source mirror).
-    const references = extractReferences(hippoRoot, tenantId, created, supersedes.supersededPairs, truncated, txDb);
-    relations += references;
-    const entities = created.length;
-    return { entities, relations, references, byType, truncated };
-}
-/**
- * Pass 3. Build a target-name index from the created entities (names within the length
- * bounds, ambiguous names dropped), scan each created entity's text once with one
- * combined word-boundary regex, and emit `references` edges (self-skipped, deduped,
- * per-source capped). Each edge is anchored to the source entity's object (memoryId
- * passed through only when the mirror lives). Returns the number of references edges written.
- */
-function extractReferences(hippoRoot, tenantId, created, supersededPairs, truncated, txDb) {
-    // Build the target index: normalised name -> single entity id. A name is a target only
-    // if its length is in bounds; a name shared by >1 entity is AMBIGUOUS and dropped.
-    const nameToId = new Map();
+/** Normalised name to its single target; a name two entities share is ambiguous and dropped. */
+function referenceTargets(created) {
+    const byName = new Map();
     const ambiguous = new Set();
     for (const e of created) {
-        // References are among ACTIVE entities only: a superseded (outdated) row is not a
-        // current cross-reference target.
         if (e.superseded)
             continue;
-        // Decisions are SOURCE-only: their name is decision prose, referenced by supersedes,
-        // not by name-mention. Excluding them as targets also prevents a decision's own name
-        // (== its searchText) from whole-string self-matching and shadowing embedded targets.
+        // Decisions are sources only: their name is their prose, which would self-match and shadow embedded targets.
         if (e.entityType === 'decision')
             continue;
         const norm = e.name.trim().toLowerCase();
@@ -247,59 +203,86 @@ function extractReferences(hippoRoot, tenantId, created, supersededPairs, trunca
             continue;
         if (ambiguous.has(norm))
             continue;
-        if (nameToId.has(norm)) {
-            // Second distinct entity with this name (and not its own id repeated) -> ambiguous.
-            if (nameToId.get(norm) !== e.entityId) {
-                nameToId.delete(norm);
-                ambiguous.add(norm);
-            }
-            continue;
+        const seen = byName.get(norm);
+        if (seen === undefined)
+            byName.set(norm, e);
+        else if (seen.key !== e.key) {
+            byName.delete(norm);
+            ambiguous.add(norm);
         }
-        nameToId.set(norm, e.entityId);
     }
-    if (nameToId.size === 0)
-        return 0;
-    // Record the truncation (observability, mirroring MAX_EXTRACT_PER_TYPE) so a >cap
-    // store's under-matched references are not silent.
-    if (nameToId.size > MAX_TARGET_NAMES)
+    return byName;
+}
+// Pass 3: a `references` edge when one object's text names another entity, matched on word boundaries,
+// self-skipped, deduped and capped per source; the edge is anchored to the source object.
+function deriveReferences(created, supersededPairs, truncated) {
+    const byName = referenceTargets(created);
+    if (byName.size === 0)
+        return [];
+    if (byName.size > MAX_TARGET_NAMES)
         truncated.push('references-targets');
-    // LONGEST name first, then alphabetical: JS regex alternation is leftmost-first, so
-    // ordering longer names before their prefixes makes the match longest-at-position
-    // (`postgres pro` wins over `postgres`). Deterministic, so truncation is stable.
-    const targetNames = [...nameToId.keys()]
+    // Longest first, then alphabetical: regex alternation is leftmost-first, so `postgres pro` beats `postgres`.
+    const targetNames = [...byName.keys()]
         .sort((a, b) => b.length - a.length || (a < b ? -1 : a > b ? 1 : 0))
         .slice(0, MAX_TARGET_NAMES);
-    const pattern = `\\b(?:${targetNames.map(escapeRegex).join('|')})\\b`;
-    const re = new RegExp(pattern, 'gi');
-    let references = 0;
+    const re = new RegExp(`\\b(?:${targetNames.map(escapeRegex).join('|')})\\b`, 'gi');
+    const relations = [];
     for (const src of created) {
-        if (src.superseded)
-            continue; // superseded sources hold only stale references
-        if (!src.searchText)
+        if (src.superseded || !src.searchText)
             continue;
-        const targets = new Set();
+        const targets = new Map();
         for (const m of src.searchText.matchAll(re)) {
-            const targetId = nameToId.get(m[0].toLowerCase());
-            if (targetId === undefined || targetId === src.entityId)
-                continue; // miss / self
-            if (supersededPairs.has(pairKey(src.entityId, targetId)))
-                continue; // already version-related
-            targets.add(targetId);
+            const target = byName.get(m[0].toLowerCase());
+            if (target === undefined || target.key === src.key)
+                continue;
+            if (supersededPairs.has(pairKey(src.key, target.key)))
+                continue;
+            targets.set(target.key, target);
             if (targets.size >= MAX_REFERENCES_PER_OBJECT)
-                break; // per-source cap
+                break;
         }
-        for (const targetId of targets) {
-            insertRelation(hippoRoot, tenantId, {
-                fromEntityId: src.entityId,
-                toEntityId: targetId,
-                relType: 'references',
-                // Anchored to the source object; its mirror memory is passed only when it lives.
-                memoryId: src.memoryId,
-                sourceObject: src.sourceObject,
-            }, txDb);
-            references += 1;
+        for (const target of targets.values()) {
+            relations.push({ from: naturalKeyOf(src), to: naturalKeyOf(target), relType: 'references', memoryId: src.memoryId, sourceObject: src.sourceObject });
         }
     }
-    return references;
+    return relations;
+}
+function resultOf(derived, skipped) {
+    const { entities, relations, references, byType, truncated } = derived;
+    const result = { entities: entities.length, relations: relations.length, references, byType, truncated };
+    if (skipped > 0)
+        result.skipped = skipped;
+    return result;
+}
+/** Idempotent rebuild of the tenant's graph from its consolidated objects, in one transaction; safe to re-run.
+ *  Returns the derived counts and which types hit the per-type cap. */
+export function extractGraph(hippoRoot, tenantId) {
+    assertTenantId('extractGraph', 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);
+    return resultOf(derived, skipped);
+}
+/** 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 async function extractGraphChunked(hippoRoot, tenantId, budget = WRITE_BUDGET) {
+    assertTenantId('extractGraphChunked', tenantId);
+    const derived = deriveGraph(loadGraphSources(hippoRoot, tenantId));
+    const ops = readGraphDelta(hippoRoot, tenantId, derived);
+    let next = 0;
+    let skipped = 0;
+    let committedAt = 0;
+    while (next < ops.length) {
+        if (next > 0)
+            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 });
+        committedAt = budget.clock();
+        next = chunk.next;
+        skipped += chunk.skipped;
+    }
+    return resultOf(derived, skipped);
 }
 //# sourceMappingURL=graph-extract.js.map

package/dist/graph-recall.d.ts

@@ -38,6 +38,7 @@ export interface GraphExpandOpts {
     recallScope?: {
         requested?: string;
         additive?: boolean;
+        ownScope?: string;
     };
 }
 /**

package/dist/graph-recall.js

@@ -137,8 +137,8 @@ function passesRecallFilters(mem, via, successorValidFrom, opts) {
         return false; // default recall drops superseded
     }
     return recallScope.additive
-        ? passesCliRecallScopeFilter(mem.scope ?? null, recallScope.requested)
-        : passesScopeFilterForRecall(mem.scope ?? null, recallScope.requested);
+        ? passesCliRecallScopeFilter(mem.scope ?? null, recallScope.requested) || passesScopeFilterForRecall(mem.scope ?? null, undefined, recallScope.ownScope)
+        : passesScopeFilterForRecall(mem.scope ?? null, recallScope.requested, recallScope.ownScope);
 }
 /** Traverse one store's graph from its seeds into `hitsByOrigin`. Pure reads; mutates `seenMemoryIds`
  *  and `seenContent` so a memory, or a share/promote copy of it, surfaces at most once across stores. */

package/dist/graph-view.d.ts

@@ -36,6 +36,7 @@ export declare const DEFAULT_VIEW_LIMIT = 500;
 export declare function buildGraphModel(hippoRoot: string, tenantId: string, opts?: {
     entity?: string;
     limit?: number;
+    canRead?: (scope: string | null) => boolean;
 }): GraphModel;
 /**
  * Deterministic Fruchterman-Reingold-style force layout. Seeded circular init +

package/dist/graph-view.js

@@ -10,6 +10,25 @@
 import { loadEntities, loadEntitiesByName, loadEntitiesByIds, loadRelations, loadNeighborRelations, loadRelationsAmong, withGraphReadSnapshot, } from './graph/read.js';
 /** Default bound for the CLI viewer / show so an unbounded set is never laid out. */
 export const DEFAULT_VIEW_LIMIT = 500;
+// graph/read.ts's IN-list chunk, so one statement stays far under SQLite's bound-parameter limit.
+const MEMORY_ID_CHUNK = 400;
+/** The items whose source memory `canRead` admits: a NULL memoryId has no scope to hide, and a missing memory fails closed. */
+function readableOnly(db, tenantId, items, canRead) {
+    if (!canRead)
+        return items;
+    const ids = [...new Set(items.flatMap((i) => (i.memoryId === null ? [] : [i.memoryId])))];
+    const readable = new Set();
+    for (let i = 0; i < ids.length; i += MEMORY_ID_CHUNK) {
+        const slice = ids.slice(i, i + MEMORY_ID_CHUNK);
+        // SAFETY: rows' shape matches the id and scope columns named in the SELECT.
+        const rows = db.prepare(`SELECT id, scope FROM memories WHERE tenant_id = ? AND id IN (${slice.map(() => '?').join(',')})`)
+            .all(tenantId, ...slice);
+        for (const r of rows)
+            if (canRead(r.scope))
+                readable.add(r.id);
+    }
+    return items.filter((i) => i.memoryId === null || readable.has(i.memoryId));
+}
 /**
  * Build the view-model from the graph (reads only). With `opts.entity`, returns a
  * focus subgraph: every entity whose name === entity, plus their 1-hop neighbours,
@@ -32,7 +51,9 @@ export function buildGraphModel(hippoRoot, tenantId, opts = {}) {
             // cap the focus matches. (3) Discover 1-hop neighbours and cap the UNION to
             // `limit` nodes. (4) Load ALL edges AMONG the union so neighbour-to-neighbour
             // edges that don't touch the focus are included too.
-            const focus = loadEntitiesByName(hippoRoot, tenantId, opts.entity, { limit }, db);
+            const named = loadEntitiesByName(hippoRoot, tenantId, opts.entity, { limit }, db);
+            // A hidden focus must not answer through its neighbours that the name exists.
+            const focus = readableOnly(db, tenantId, named, opts.canRead);
             if (focus.length === 0)
                 return { nodes: [], edges: [], truncated: false };
             const focusIds = focus.map((e) => e.id);
@@ -54,7 +75,7 @@ export function buildGraphModel(hippoRoot, tenantId, opts = {}) {
             // edge in favour of out-of-union rows.
             relations = loadRelationsAmong(hippoRoot, tenantId, unionIds, { limit }, db);
             truncated =
-                focus.length >= limit ||
+                named.length >= limit ||
                     hop.length >= limit || // neighbour scan capped -> a 1-hop neighbour may be omitted
                     neighboursCapped || // node cap filled before all neighbours were consumed
                     union.size > unionIds.length ||
@@ -65,6 +86,8 @@ export function buildGraphModel(hippoRoot, tenantId, opts = {}) {
             relations = loadRelations(hippoRoot, tenantId, { limit }, db);
             truncated = nodeEntities.length >= limit || relations.length >= limit;
         }
+        nodeEntities = readableOnly(db, tenantId, nodeEntities, opts.canRead);
+        relations = readableOnly(db, tenantId, relations, opts.canRead);
         const nodeIds = new Set(nodeEntities.map((e) => e.id));
         const nodes = nodeEntities.map((e) => ({
             id: e.id,

package/dist/half-life-migration.js

@@ -169,7 +169,11 @@ function writePlan(db, plan, old, move) {
     const byTenant = new Map();
     for (const e of plan) {
         update.run(e.half_life_days, e.id);
-        byTenant.set(e.tenantId, { ...byTenant.get(e.tenantId), [e.id]: old.get(e.id) });
+        // One record per tenant, filled in place: copying it per row made the write grow with the square of the store.
+        let record = byTenant.get(e.tenantId);
+        if (!record)
+            byTenant.set(e.tenantId, (record = {}));
+        record[e.id] = old.get(e.id);
     }
     for (const [tenantId, oldHalfLives] of byTenant) {
         appendAuditEvent(db, { tenantId, actor: move.actor, op: 'half_life_migrate', metadata: { from: move.from, to: move.to, ids: Object.keys(oldHalfLives), oldHalfLives } });

package/dist/handoff-evidence.d.ts

@@ -0,0 +1,5 @@
+import type { HandoffEvidence } from './handoff.js';
+export declare function collectHandoffEvidence(cwd: string, testStatus: HandoffEvidence['testStatus'], options?: {
+    timeoutMs?: number;
+}): HandoffEvidence;
+//# sourceMappingURL=handoff-evidence.d.ts.map

package/dist/handoff-evidence.js

@@ -0,0 +1,30 @@
+// A handoff's git evidence, read with no store, so a hook with no store can send it with the session's end.
+import { execFileSync } from 'child_process';
+// Best-effort git state; a missing git, non-repo cwd, or a call past timeoutMs (each call, default 2 s)
+// yields null fields rather than throw, so a hook with a hard deadline can cap a slow repo.
+export function collectHandoffEvidence(cwd, testStatus, options = {}) {
+    const timeoutMs = options.timeoutMs ?? 2000;
+    let gitRef = null;
+    try {
+        gitRef = execFileSync('git', ['rev-parse', 'HEAD'], {
+            cwd, encoding: 'utf8', timeout: timeoutMs, stdio: ['ignore', 'pipe', 'ignore'], windowsHide: true,
+        }).trim() || null;
+    }
+    catch {
+        // No git, not a repo, or timed out: evidence is optional, so the field stays null.
+        gitRef = null;
+    }
+    let dirtyTree = null;
+    try {
+        const status = execFileSync('git', ['status', '--porcelain'], {
+            cwd, encoding: 'utf8', timeout: timeoutMs, stdio: ['ignore', 'pipe', 'ignore'], windowsHide: true,
+        });
+        dirtyTree = status.trim().length > 0;
+    }
+    catch {
+        // Same as gitRef: unknown tree state is reported as null, never as an error.
+        dirtyTree = null;
+    }
+    return { gitRef, dirtyTree, testStatus };
+}
+//# sourceMappingURL=handoff-evidence.js.map

package/dist/home-path.d.ts

@@ -0,0 +1,5 @@
+/** One pattern per path shape that carries a user name: Windows, Git Bash and WSL mounts, extended-length, UNC home shares, Linux, macOS and 8.3 short names. */
+export declare const USER_SEGMENT: readonly RegExp[];
+/** `text` with each home-directory segment replaced by `[home]`. */
+export declare function maskHomePaths(text: string): string;
+//# sourceMappingURL=home-path.d.ts.map

package/dist/home-path.js

@@ -0,0 +1,24 @@
+// Home-directory paths name their user, so text bound for a shared store tests or masks them here; no imports keep it light.
+// VS Code writes file links URL-encoded, so a separator may be %5C or %2F.
+const WIN_SEP = String.raw `(?:[\\/]|%5C|%2F)`;
+const WIN_CHAR = String.raw `(?:(?!%5C|%2F)[^\\/:*?"<>|\s])`;
+// A Windows name never holds a quote, so JSON stops it; one with spaces runs to a separator, quote, closing mark or line end, leaving the mark, as stopping at its first word leaks the surname.
+const WIN_USER = String.raw `(?:${WIN_CHAR}+(?: ${WIN_CHAR}+){0,3}(?=${WIN_SEP}|["'\`)\]>,;]|\.(?=\s|$)|(?<!\.)(?:[^\S ]|$))(?<![\`)\],;'])|${WIN_CHAR}+)`;
+/** One pattern per path shape that carries a user name: Windows, Git Bash and WSL mounts, extended-length, UNC home shares, Linux, macOS and 8.3 short names. */
+export const USER_SEGMENT = [
+    new RegExp(String.raw `[A-Za-z](?::|%3A)${WIN_SEP}+(?:Users|Documents and Settings)${WIN_SEP}+${WIN_USER}`, 'i'),
+    new RegExp(String.raw `(?<![\w.])(?:\/mnt)?\/[A-Za-z]\/Users\/${WIN_USER}`, 'i'),
+    /\\\\\?\\/,
+    new RegExp(String.raw `\\\\[^\\/\s]+\\+(?:homes?|users|profiles?)\$?\\+${WIN_USER}`, 'i'),
+    /(?<![\w.~-])(?:\/var)?\/home\/[^/\s]+/,
+    /(?<![\w.~-])(?:\/var)?\/root(?![\w.-])/,
+    /(?<![\w.~-])\/Users\/[^/\s]+/,
+    /[\\/][A-Z0-9_$]{1,6}~\d{1,6}(?:\.[A-Z0-9]{1,3})?(?![\w~])|\b[A-Z0-9_$]{1,6}~\d{1,6}(?:\.[A-Z0-9]{1,3})?[\\/]/,
+];
+// Global copies, so the shared test patterns keep their lastIndex at 0.
+const USER_SEGMENT_ALL = USER_SEGMENT.map((re) => new RegExp(re.source, `${re.flags}g`));
+/** `text` with each home-directory segment replaced by `[home]`. */
+export function maskHomePaths(text) {
+    return USER_SEGMENT_ALL.reduce((out, re) => out.replace(re, '[home]'), text);
+}
+//# sourceMappingURL=home-path.js.map

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

@@ -10,8 +10,9 @@
  *        sequence, writing both outputs to the log file. The parent returns in
  *        <100ms so the TUI teardown can't kill the child before it finishes.
  *      - SessionStart: `hippo last-sleep --path <path>` - prints the log
- *        written by the previous session's detached worker to stderr, which
- *        keeps it out of the model's context, and then clears it.
+ *        written by the previous session's detached worker on stderr and
+ *        clears it. Stdout carries only a `systemMessage` problems line,
+ *        because Claude Code shows that to the user, not the model.
  *    Earlier Claude Code forms are detected and migrated automatically:
  *      - < 0.20.2: `Stop` hook firing `hippo sleep` on every assistant turn.
  *      - < 0.21.0: bare `hippo sleep` in SessionEnd, no `--log-file`.
@@ -33,11 +34,14 @@
  *    `hooks` block from opencode.json.
  */
 import { type JsonHookTarget } from './shared.js';
+import { type JsonValue } from '../json.js';
+/** A target's hook settings file, the log its SessionEnd hook writes, and the tool's display name. */
 export interface JsonHookPaths {
     settings: string;
     logFile: string;
     display: string;
 }
+/** What installJsonHooks wrote, migrated or left alone in one target's settings file. */
 export interface InstallResult {
     target: JsonHookTarget;
     settingsPath: string;
@@ -57,7 +61,14 @@ export interface InstallResult {
     /** The file exists but is not JSON hippo can merge into, so it was left untouched. */
     invalidJson: boolean;
 }
+/** The paths for `target` under the current home directory; reads and writes nothing. */
 export declare function resolveJsonHookPaths(target: JsonHookTarget): JsonHookPaths;
+/** Adds hippo's hooks to `target`'s settings file and migrates older hippo entries; a file that is not JSON stays untouched. */
 export declare function installJsonHooks(target: JsonHookTarget): InstallResult;
+/** Swaps the file in with one rename, so a crash mid-write cannot leave a truncated settings.json that Claude Code cannot parse. */
+export declare function writeSettingsFile(file: string, settings: JsonValue): void;
+/** Removes hippo's own hook handlers from `target`'s settings file and keeps every other handler; true when the file changed. */
 export declare function uninstallJsonHooks(target: JsonHookTarget): boolean;
+/** Whether uninstall can edit settings.json; `invalidJson` marks a file that exists but is not JSON hippo can edit, which `uninstallJsonHooks` reports only as false. */
+export declare function checkUninstallable(target: JsonHookTarget): Pick<InstallResult, 'settingsPath' | 'invalidJson'>;
 //# sourceMappingURL=json-hooks.d.ts.map