hippo-memory 1.70.0 → 1.72.0

package/dist/connectors/slack/webhook.js

@@ -9,25 +9,9 @@ import { resolveTenantForSlackTeam } from './tenant-routing.js';
 import { resolveTenantId } from '../../store/tenant.js';
 import { HttpError, JSON_HEADERS, isHeaderString, closeIfBodyUnread, readWebhookBody, sendJson } from '../../util/http-util.js';
 import { isJsonObject } from '../../util/json.js';
-/**
- * Slack Events API webhook. Auth is signature-based (HMAC over the raw
- * body with SLACK_SIGNING_SECRET); Bearer is NOT required, which is why
- * this route is in PUBLIC_ROUTES. The route is responsible for:
- *   1. Echoing the one-time url_verification challenge.
- *   2. Verifying the HMAC on every other inbound payload.
- *   3. Resolving body.team_id → tenantId via slack_workspaces, falling
- *      back to HIPPO_TENANT then 'default'.
- *   4. Dispatching event_callback envelopes to ingestMessage /
- *      handleMessageDeleted.
- *   5. Parking malformed or unhandled payloads in slack_dlq and STILL
- *      ACKing 200 - Slack retries forever otherwise.
- *
- * When SLACK_SIGNING_SECRET is unset we return 404, not
- * 503, so an external probe cannot distinguish "route gated off by config"
- * from "route does not exist on this build".
- *
- * Bearer auth is skipped on purpose: server.ts checks isPublicRoute before calling this.
- */
+/** Slack Events API webhook: HMAC over the raw body with SLACK_SIGNING_SECRET, no Bearer (its route row declares webhook-signature);
+ *  malformed payloads go to slack_dlq, ACK 200.
+ *  404 (not 503) when the secret is unset, so a probe cannot tell a gated-off route from a missing one. */
 export async function handleSlackEventsWebhook(request, store) {
     const { req, res, opts } = request;
     // Secret and headers before the body, so a caller with neither cannot make the server buffer one.
@@ -104,10 +88,8 @@ async function routeSignedSlackPayload(d) {
     }
     if (answerUrlVerification(res, body))
         return;
-    // Resolve tenant, failing closed: when slack_workspaces is non-empty
-    // and the team_id is unknown, resolveTenantForTeam returns null and we
-    // park the envelope in slack_dlq with bucket='unroutable'. Mandatory ACK
-    // 200 so Slack stops retrying; do NOT call ingest.
+    // Fail closed: resolveTenantForSlackTeam returns null for an unknown team on a non-empty slack_workspaces; park it in slack_dlq (bucket='unroutable')
+    // and still ACKs 200 so Slack stops retrying; never call ingest.
     let resolvedTenant = null;
     if (body !== undefined && isSlackEventEnvelope(body)) {
         resolvedTenant = await resolveTenantForSlackTeam(d.hippoRoot, body.team_id, d.store);
@@ -169,9 +151,7 @@ async function dispatchSlackEvent(d, ctx, body) {
         }
         const r = await ingestMessage(ctx, {
             teamId: body.team_id,
-            // channel privacy isn't on the inner event; use channel_type as a
-            // proxy. 'group'|'im'|'mpim' → private. 'channel' → public. Unknown
-            // → private (fail closed).
+            // Channel privacy is not on the inner event, so channel_type is the proxy: 'group'|'im'|'mpim' private, 'channel' public, unknown private.
             channel: {
                 id: inner.channel,
                 is_private: inner.channel_type !== 'channel',

package/dist/connectors/slack/workspaces.d.ts

@@ -1,23 +1,5 @@
-/**
- * Slack workspace registration helpers.
- *
- * The `slack_workspaces` table maps Slack `team_id` → hippo `tenant_id`.
- * Empty table = single-tenant install (HIPPO_TENANT fallback).
- * Non-empty = multi-workspace install (fail-closed routing via
- * `resolveTenantForTeam`).
- *
- * These helpers give the CLI (`hippo slack workspaces add|list|remove`) a
- * surface, so operators with multiple workspaces need no direct SQL.
- *
- * Design choices:
- *   - `add` is an upsert (ON CONFLICT UPDATE). Re-registering an
- *     existing team_id with a different tenant_id intentionally
- *     overwrites — operators move workspaces between tenants and the
- *     CLI shouldn't require a delete+add dance.
- *   - `list` sorts by team_id for stable output.
- *   - `remove` returns a boolean for the CLI to distinguish "removed"
- *     from "not found" without an extra SELECT.
- */
+/** Slack workspace registration helpers: the `slack_workspaces` table maps `team_id` to `tenant_id` (empty = single-tenant, non-empty = fail-closed routing).
+ *  `add` is an upsert that overwrites an existing team_id's tenant on purpose, so moving a workspace needs no delete+add. */
 import { type SlackWorkspace } from '../../store/connectors/slack.js';
 export type { SlackWorkspace };
 export { listSlackWorkspaces as listWorkspaces, removeSlackWorkspace as removeWorkspace } from '../../store/connectors/slack.js';
@@ -25,9 +7,7 @@ export interface AddWorkspaceOpts {
     teamId: string;
     tenantId: string;
 }
-/**
- * Register or re-register a Slack team → tenant mapping. Upserts on
- * team_id conflict (operators move workspaces between tenants).
- */
+/** Register or re-register a Slack team → tenant mapping. Upserts on
+ *  team_id conflict (operators move workspaces between tenants). */
 export declare function addWorkspace(hippoRoot: string, opts: AddWorkspaceOpts): SlackWorkspace;
 //# sourceMappingURL=workspaces.d.ts.map

package/dist/connectors/slack/workspaces.js

@@ -1,29 +1,9 @@
-/**
- * Slack workspace registration helpers.
- *
- * The `slack_workspaces` table maps Slack `team_id` → hippo `tenant_id`.
- * Empty table = single-tenant install (HIPPO_TENANT fallback).
- * Non-empty = multi-workspace install (fail-closed routing via
- * `resolveTenantForTeam`).
- *
- * These helpers give the CLI (`hippo slack workspaces add|list|remove`) a
- * surface, so operators with multiple workspaces need no direct SQL.
- *
- * Design choices:
- *   - `add` is an upsert (ON CONFLICT UPDATE). Re-registering an
- *     existing team_id with a different tenant_id intentionally
- *     overwrites — operators move workspaces between tenants and the
- *     CLI shouldn't require a delete+add dance.
- *   - `list` sorts by team_id for stable output.
- *   - `remove` returns a boolean for the CLI to distinguish "removed"
- *     from "not found" without an extra SELECT.
- */
+/** Slack workspace registration helpers: the `slack_workspaces` table maps `team_id` to `tenant_id` (empty = single-tenant, non-empty = fail-closed routing).
+ *  `add` is an upsert that overwrites an existing team_id's tenant on purpose, so moving a workspace needs no delete+add. */
 import { upsertSlackWorkspace } from '../../store/connectors/slack.js';
 export { listSlackWorkspaces as listWorkspaces, removeSlackWorkspace as removeWorkspace } from '../../store/connectors/slack.js';
-/**
- * Register or re-register a Slack team → tenant mapping. Upserts on
- * team_id conflict (operators move workspaces between tenants).
- */
+/** Register or re-register a Slack team → tenant mapping. Upserts on
+ *  team_id conflict (operators move workspaces between tenants). */
 export function addWorkspace(hippoRoot, opts) {
     return upsertSlackWorkspace(hippoRoot, opts.teamId, opts.tenantId);
 }

package/dist/consolidate/conflicts.js

@@ -1,14 +1,10 @@
 import { Layer, calculateStrength } from '../core/memory.js';
 import { jaccardMinShared, overlapPartners } from './overlap-index.js';
 import { isQuarantineScope } from '../trust/quarantine.js';
-import { isPersonalScope } from '../store/recall-scope.js';
+import { isPersonalScope } from '../core/recall-scope.js';
 import { DECAY_THRESHOLD } from './decay.js';
-// Contradictions should be gated by content overlap, not shared tags. Tags like
-// `feedback` / `policy` are too coarse and can make unrelated rules look like
-// conflicts before the polarity heuristics run.
-// Jaccard threshold on stopword-filtered tokens. Only applied after a polarity
-// signal has already been detected (explicit pair or inferred negation), so
-// this just filters out drive-by topic similarity, not semantic drift.
+// Gate contradictions on content overlap, not shared tags (`feedback`/`policy` are too coarse). The Jaccard threshold on stopword-filtered tokens
+// only applies after a polarity signal, so it filters drive-by topic similarity, not semantic drift.
 const CONFLICT_OVERLAP_THRESHOLD = 0.5;
 // Minimum distinctive shared tokens before we trust an overlap score. Filters
 // out cases where two memories share only common English + a project name.
@@ -41,9 +37,8 @@ rescuedIds = new Set()) {
     const partnersOf = overlapPartners(profiles.map((p) => p.distinct), jaccardMinShared(CONFLICT_OVERLAP_THRESHOLD, CONFLICT_MIN_RARE_SHARED));
     for (let i = 0; i < survivors.length; i++) {
         for (const j of partnersOf(i)) {
-            // Traces are variants of each other, not contradictions. Two
-            // strategies for the same task can both be valid; conflict detection
-            // exists for stated-rule disagreement, not strategy diversity.
+            // Traces are variants of each other, not contradictions: two strategies for the same task can both be valid,
+            // and conflict detection is for stated-rule disagreement, not strategy diversity.
             if (survivors[i].layer === Layer.Trace && survivors[j].layer === Layer.Trace)
                 continue;
             if (survivors[i].superseded_by || survivors[j].superseded_by)
@@ -77,8 +72,7 @@ function recalledTogether(a, b) {
 }
 function conflictProfile(text) {
     const opening = openingWindow(text);
-    // Polarity is measured only in the first POLARITY_WINDOW_WORDS, so a stray
-    // negation deep in a prose memory doesn't flip the intent.
+    // Polarity is measured only in the first POLARITY_WINDOW_WORDS, so a stray negation deep in a prose memory doesn't flip the intent.
     // Pad with spaces so space-delimited patterns match words at the start/end.
     return { distinct: distinctiveTokens(text), polarity: inferConflictPolarity(opening), window: ' ' + opening.toLowerCase() + ' ' };
 }
@@ -128,9 +122,7 @@ function openingWindow(text) {
 }
 // Takes opening windows only, so " on " and " off " as prepositions deep in long prose don't read as enabled/disabled.
 function classifyConflictType(a, b, aPolarity, bPolarity) {
-    // Tightened tokens: require whole-word boundaries so " on " alone doesn't
-    // match "on/off". Pair only `enabled` ↔ `disabled` and explicit on/off in
-    // imperative context.
+    // Whole-word boundaries so " on " alone doesn't match "on/off"; pair only `enabled` <-> `disabled` and explicit on/off in imperative context.
     const enabledDisabled = (containsAny(a, [' enabled ', ' enable ']) && containsAny(b, [' disabled ', ' disable ']))
         || (containsAny(b, [' enabled ', ' enable ']) && containsAny(a, [' disabled ', ' disable ']));
     if (enabledDisabled)

package/dist/consolidate/dag-summary.d.ts

@@ -0,0 +1,8 @@
+export interface DagSummaryOptions {
+    apiKey: string;
+    model?: string;
+    fetcher?: typeof fetch;
+    onError?: (msg: string) => void;
+}
+export declare function generateDagSummary(label: string, factContents: string[], opts: DagSummaryOptions): Promise<string | null>;
+//# sourceMappingURL=dag-summary.d.ts.map

package/dist/consolidate/dag-summary.js

@@ -0,0 +1,41 @@
+// The one LLM call behind every DAG summary, kept apart from the graph writes so its request bytes are tested on their own.
+import { redactSecretsStrict } from '../util/secret-detect.js';
+import { describeMessageFailure, sendAnthropicMessage } from '../util/anthropic-messages.js';
+import { certainDefect } from '../core/memory-quality.js';
+const DAG_SUMMARY_PROMPT = `You are summarizing a cluster of facts about a specific topic/entity for a memory system.
+
+Topic: {label}
+Facts:
+{facts}
+
+` +
+    'Write a single concise paragraph (2-4 sentences) that captures all the key information from these facts. ' +
+    'This summary will be used to quickly determine if this cluster is relevant to a future query, ' +
+    'so include specific names, dates, numbers, and key details. Output ONLY the summary paragraph, no preamble.';
+// Output budget for one summary paragraph, and the shortest reply kept as a summary.
+const SUMMARY_MAX_TOKENS = 400;
+const SUMMARY_MIN_CHARS = 20;
+export async function generateDagSummary(label, factContents, opts) {
+    const factsBlock = factContents.map((f, i) => `${i + 1}. ${redactSecretsStrict(f)}`).join('\n');
+    const prompt = DAG_SUMMARY_PROMPT
+        .replace('{label}', redactSecretsStrict(label))
+        .replace('{facts}', factsBlock);
+    const reply = await sendAnthropicMessage({
+        apiKey: opts.apiKey,
+        model: opts.model,
+        maxTokens: SUMMARY_MAX_TOKENS,
+        prompt,
+        fetcher: opts.fetcher,
+    });
+    if (!reply.ok) {
+        opts.onError?.(describeMessageFailure(reply.failure));
+        return null;
+    }
+    const defect = certainDefect(reply.text);
+    if (defect !== null) {
+        opts.onError?.(`summary quality refused: ${defect}`);
+        return null;
+    }
+    return reply.text.length >= SUMMARY_MIN_CHARS ? reply.text : null;
+}
+//# sourceMappingURL=dag-summary.js.map

package/dist/consolidate/dag.d.ts

@@ -1,17 +1,11 @@
 import { type MemoryEntry } from '../core/memory.js';
+import { type DagSummaryOptions } from './dag-summary.js';
 export interface FactCluster {
     label: string;
     members: MemoryEntry[];
     entityTags: string[];
 }
 export declare function clusterFacts(facts: MemoryEntry[]): FactCluster[];
-export interface DagSummaryOptions {
-    apiKey: string;
-    model?: string;
-    fetcher?: typeof fetch;
-    onError?: (msg: string) => void;
-}
-export declare function generateDagSummary(label: string, factContents: string[], opts: DagSummaryOptions): Promise<string | null>;
 export interface DagBuildResult {
     candidateClusters: number;
     summariesCreated: number;
@@ -29,19 +23,8 @@ export interface DagRebuildResult {
     failed: number;
     capped: boolean;
 }
-/**
- * Sleep-cycle phase that drains the dirty L2 summary queue.
- * Thin orchestrator; the heavy lifting lives in store.ts (load + apply)
- * and dag.ts:generateDagSummary (LLM call).
- *
- * Per-summary try/catch: one throwing rebuild does NOT abort the rest of the queue.
- *
- * Race-loser handling: applyRebuildResult's UPDATE WHERE includes
- * AND summary_dirty=1, so concurrent sleep's second writer returns
- * changed=false. Silent skip (neither rebuilt++ nor refused++ nor failed++).
- *
- * A tombstone hit counts as `refused`, not `rebuilt`; dirty clears either way.
- */
+/** Sleep-cycle phase draining the dirty L2 summary queue; one throwing rebuild does not abort the rest.
+ * A concurrent sleep's second writer gets changed=false (UPDATE requires summary_dirty=1) and is skipped silently; a tombstone hit counts as `refused`. */
 export declare function rebuildDirtySummaries(hippoRoot: string, opts: DagSummaryOptions & {
     cap?: number;
 }): Promise<DagRebuildResult>;
@@ -54,13 +37,7 @@ export interface EntityProfilesBuildResult {
      *  `failed`: a tombstone hit is a deliberate refusal, not an error. */
     rejected: number;
 }
-/**
- * Build L3 entity profiles by clustering L2 summaries with
- * shared entity tags. Threshold 2+ L2s per entity. Mirrors buildDag L1->L2
- * pattern, one level up.
- *
- * Born-dirty cancellation: each L2 link write marks the new L3 dirty, so clear it
- * or the same sleep cycle's rebuild re-rebuilds the freshly built L3.
- */
+/** Build L3 entity profiles by clustering L2 summaries sharing entity tags (2+ L2s per entity).
+ * Each L2 link write marks the new L3 dirty, so clear it or the same cycle re-rebuilds it. */
 export declare function buildEntityProfiles(hippoRoot: string, l2Summaries: MemoryEntry[], opts: DagSummaryOptions): Promise<EntityProfilesBuildResult>;
 //# sourceMappingURL=dag.d.ts.map

package/dist/consolidate/dag.js

@@ -1,20 +1,24 @@
 import { createMemory, Layer } from '../core/memory.js';
 import { writeEntry, writeEntriesTogether } from '../store/entry-writes.js';
 import { loadAllDirtySummaries, loadChildrenOfSummary, applyRebuildResult, clearSummaryDirtyAfterBuild, } from '../store/summaries.js';
-import { RejectedValueError } from '../store/rejection.js';
-import { redactSecretsStrict } from '../util/secret-detect.js';
-import { describeMessageFailure, sendAnthropicMessage } from '../util/anthropic-messages.js';
-import { derivationScope, derivationPartitionKey } from '../store/recall-scope.js';
+import { RejectedValueError } from '../core/api-errors.js';
+import { generateDagSummary } from './dag-summary.js';
+import { overlapPartners } from './overlap-index.js';
+import { derivationScope, derivationPartitionKey } from '../core/recall-scope.js';
 import { loadConfig } from '../core/config.js';
-import { neverAutoShareTags } from '../sharing/shared.js';
-import { errorMessage, log } from '../util/log.js';
-import { certainDefect } from '../core/memory-quality.js';
+import { neverAutoShareTags } from '../sharing/share.js';
+import { errorFields, errorMessage, log } from '../util/log.js';
 const SUMMARY_FALLBACK_CHARS = 40;
 const DEFAULT_REBUILD_CAP = 20;
+// Facts join a cluster when their tag sets overlap at least this much.
+const CLUSTER_JACCARD_MIN = 0.5;
 export function clusterFacts(facts) {
     if (facts.length === 0)
         return [];
     const entityTags = facts.map((f) => f.tags.filter((t) => t.startsWith('speaker:') || t.startsWith('topic:')));
+    const tagSets = entityTags.map((tags) => new Set(tags));
+    // Every tag indexed, not a prefix: a repeated tag counts twice in `shared`, so the prefix-filter bound would not hold.
+    const partnersOf = overlapPartners(tagSets, () => 1);
     const assigned = new Set();
     const clusters = [];
     for (let i = 0; i < facts.length; i++) {
@@ -22,19 +26,18 @@ export function clusterFacts(facts) {
             continue;
         const cluster = [i];
         assigned.add(i);
-        for (let j = i + 1; j < facts.length; j++) {
+        for (const j of partnersOf(i)) {
             if (assigned.has(j))
                 continue;
-            const shared = entityTags[i].filter((t) => entityTags[j].includes(t));
-            const union = new Set([...entityTags[i], ...entityTags[j]]);
-            const jaccard = union.size > 0 ? shared.length / union.size : 0;
-            if (jaccard >= 0.5) {
+            const shared = entityTags[i].filter((t) => tagSets[j].has(t)).length;
+            const inBoth = [...tagSets[i]].filter((t) => tagSets[j].has(t)).length;
+            if (shared / (tagSets[i].size + tagSets[j].size - inBoth) >= CLUSTER_JACCARD_MIN) {
                 cluster.push(j);
                 assigned.add(j);
             }
         }
         const members = cluster.map((idx) => facts[idx]);
-        const sharedTags = entityTags[cluster[0]].filter((t) => cluster.every((idx) => entityTags[idx].includes(t)));
+        const sharedTags = entityTags[cluster[0]].filter((t) => cluster.every((idx) => tagSets[idx].has(t)));
         const label = sharedTags
             .map((t) => t.split(':')[1])
             .join(': ') || members[0].content.slice(0, SUMMARY_FALLBACK_CHARS);
@@ -42,41 +45,7 @@ export function clusterFacts(facts) {
     }
     return clusters;
 }
-const DAG_SUMMARY_PROMPT = `You are summarizing a cluster of facts about a specific topic/entity for a memory system.
-
-Topic: {label}
-Facts:
-{facts}
-
-Write a single concise paragraph (2-4 sentences) that captures all the key information from these facts. This summary will be used to quickly determine if this cluster is relevant to a future query, so include specific names, dates, numbers, and key details. Output ONLY the summary paragraph, no preamble.`;
-// Output budget for one summary paragraph, and the shortest reply kept as a summary.
-const SUMMARY_MAX_TOKENS = 400;
-const SUMMARY_MIN_CHARS = 20;
-export async function generateDagSummary(label, factContents, opts) {
-    const factsBlock = factContents.map((f, i) => `${i + 1}. ${redactSecretsStrict(f)}`).join('\n');
-    const prompt = DAG_SUMMARY_PROMPT
-        .replace('{label}', redactSecretsStrict(label))
-        .replace('{facts}', factsBlock);
-    const reply = await sendAnthropicMessage({
-        apiKey: opts.apiKey,
-        model: opts.model,
-        maxTokens: SUMMARY_MAX_TOKENS,
-        prompt,
-        fetcher: opts.fetcher,
-    });
-    if (!reply.ok) {
-        opts.onError?.(describeMessageFailure(reply.failure));
-        return null;
-    }
-    const defect = certainDefect(reply.text);
-    if (defect !== null) {
-        opts.onError?.(`summary quality refused: ${defect}`);
-        return null;
-    }
-    return reply.text.length >= SUMMARY_MIN_CHARS ? reply.text : null;
-}
-// Partition BEFORE clustering so one LLM summary never mixes facts from different tenants.
-// Map keeps insertion order, so a single-tenant store iterates in its original order.
+// Partition before clustering so one LLM summary never mixes tenants; Map keeps insertion order, so a single-tenant store iterates as before.
 // buildEntityProfiles partitions its L2s with this same key.
 function partitionFactsByTenant(unparented) {
     const unparentedByTenant = new Map();
@@ -93,10 +62,7 @@ function partitionFactsByTenant(unparented) {
 /** The L2 summary entry for one cluster, landing in the facts' own tenant and scope. */
 function createClusterSummaryEntry(summary, cluster, home) {
     const memberCreatedAts = cluster.members.map((m) => m.created).sort();
-    // Every member of `cluster` shares home.tenantId by construction (the
-    // tenant partition above), so the summary lands in the same tenant
-    // as the facts it summarizes instead of always 'default'
-    // (memory.ts:535 defaults tenantId when the option is omitted).
+    // Every cluster member shares home.tenantId (tenant partition above), so the summary lands in the facts' tenant, not 'default'.
     const summaryEntry = createMemory(summary, {
         layer: Layer.Semantic,
         tags: [...cluster.entityTags, ...neverAutoShareTags(cluster.members), 'dag-summary'],
@@ -204,9 +170,8 @@ function clearZeroChildSummary(hippoRoot, summary, result) {
     });
     if (changed)
         result.zeroChildSkipped++;
-    // changed=false → race lost / row vanished; silently skip. `refused`
-    // is always false here — applyRebuildResult only checks the
-    // tombstone when bumpRebuildCount is true (store/summaries.ts).
+    // changed=false means race lost or row vanished: skip silently. `refused` is always false here, as applyRebuildResult
+    // checks the tombstone only when bumpRebuildCount is true.
 }
 // Derive label from summary's existing entity tags (mirrors clusterFacts)
 function summaryLabel(summary) {
@@ -215,22 +180,12 @@ function summaryLabel(summary) {
         ? entityTags.map((t) => t.split(':')[1]).join(': ')
         : summary.content.slice(0, SUMMARY_FALLBACK_CHARS);
 }
-/**
- * Sleep-cycle phase that drains the dirty L2 summary queue.
- * Thin orchestrator; the heavy lifting lives in store.ts (load + apply)
- * and dag.ts:generateDagSummary (LLM call).
- *
- * Per-summary try/catch: one throwing rebuild does NOT abort the rest of the queue.
- *
- * Race-loser handling: applyRebuildResult's UPDATE WHERE includes
- * AND summary_dirty=1, so concurrent sleep's second writer returns
- * changed=false. Silent skip (neither rebuilt++ nor refused++ nor failed++).
- *
- * A tombstone hit counts as `refused`, not `rebuilt`; dirty clears either way.
- */
+/** Sleep-cycle phase draining the dirty L2 summary queue; one throwing rebuild does not abort the rest.
+ * A concurrent sleep's second writer gets changed=false (UPDATE requires summary_dirty=1) and is skipped silently; a tombstone hit counts as `refused`. */
 export async function rebuildDirtySummaries(hippoRoot, opts) {
     const cap = opts.cap ?? DEFAULT_REBUILD_CAP;
-    const dirty = loadAllDirtySummaries(hippoRoot);
+    // One past the cap tells whether more were waiting without reading the rest.
+    const dirty = loadAllDirtySummaries(hippoRoot, cap + 1);
     const capped = dirty.length > cap;
     const queue = dirty.slice(0, cap);
     const result = {
@@ -242,12 +197,8 @@ export async function rebuildDirtySummaries(hippoRoot, opts) {
         capped,
     };
     for (const [index, summary] of queue.entries()) {
-        // Yield the macrotask queue every 25 summaries. The cap can reach 1000,
-        // and each iteration is synchronous SQLite (the LLM await resolves as a
-        // microtask when the response is cached/mocked), so a large batch would
-        // otherwise starve timers and IPC for the whole rebuild: server
-        // keep-alive pings in production, Vitest's birpc heartbeat in tests
-        // (hardcoded 60s upstream, vitest-dev/vitest#8164).
+        // Yield the macrotask queue every 25 summaries: each iteration is synchronous SQLite, so a batch of up to 1000
+        // would starve timers and IPC (server keep-alives, Vitest's birpc heartbeat).
         if (index > 0 && index % 25 === 0) {
             await new Promise((resolve) => setImmediate(resolve));
         }
@@ -258,7 +209,7 @@ export async function rebuildDirtySummaries(hippoRoot, opts) {
             // One throw doesn't abort the queue; log enough to triage an exotic
             // failure (SQLite I/O, prepare), since audit() already catches its own.
             result.failed++;
-            log.error(`rebuildDirtySummaries: summary ${summary.id} (tenant ${summary.tenantId}) failed: ${errorMessage(err)}`);
+            log.error(`rebuildDirtySummaries: summary ${summary.id} (tenant ${summary.tenantId}) failed: ${errorMessage(err)}`, errorFields(err));
         }
     }
     return result;
@@ -309,14 +260,8 @@ async function profileCluster(hippoRoot, cluster, home, opts, result) {
     // The distinct source tags the audit row.
     clearSummaryDirtyAfterBuild(hippoRoot, profileEntry.id, home.tenantId, 'buildEntityProfiles', 'buildEntityProfiles-clean');
 }
-/**
- * Build L3 entity profiles by clustering L2 summaries with
- * shared entity tags. Threshold 2+ L2s per entity. Mirrors buildDag L1->L2
- * pattern, one level up.
- *
- * Born-dirty cancellation: each L2 link write marks the new L3 dirty, so clear it
- * or the same sleep cycle's rebuild re-rebuilds the freshly built L3.
- */
+/** Build L3 entity profiles by clustering L2 summaries sharing entity tags (2+ L2s per entity).
+ * Each L2 link write marks the new L3 dirty, so clear it or the same cycle re-rebuilds it. */
 export async function buildEntityProfiles(hippoRoot, l2Summaries, opts) {
     const result = {
         candidateClusters: 0,

package/dist/consolidate/decay.js

@@ -4,13 +4,8 @@ import { rescueSet, rankNonPinnedByTenant, validateWeights } from './memory-valu
 import { MEMORY_VALUE_WEIGHTS, SOURCE_ARTIFACT_SHA256 } from './memory-value-weights.js';
 const STRENGTH_DECIMALS = 4;
 export const DECAY_THRESHOLD = 0.05;
-// A faded, unpinned, unrescued memory leaves active memory one of three
-// ways. A raw receipt is append-only: trg_memories_raw_append_only aborts
-// a DELETE, and with it this whole cycle's batch and every later sleep,
-// so it stays where it is (stored strength refreshed) but sits out the
-// rest of this cycle the way a deleted row would. Anything else goes
-// dormant when config.dormant is on, and is deleted otherwise.
-// Only called for rows `retirable` allows (never pinned, raw, kept for good or backing a first-class object).
+// Leaving active memory: a raw receipt stays (the append-only trigger aborts DELETE for the whole batch; stored strength refreshed) but sits out this cycle;
+// others go dormant when config.dormant is on, else are deleted. Only called for rows `retirable` allows.
 function retireFaded(run, entry, strength) {
     const { result } = run;
     const why = `(strength ${strength.toFixed(STRENGTH_DECIMALS)} < ${DECAY_THRESHOLD})`;
@@ -36,11 +31,8 @@ function keepSurvivor(run, entry, strength) {
     run.result.decayed++;
     return updated;
 }
-// -------------------------------------------------------------------------
-// 1. Decay pass
-// -------------------------------------------------------------------------
-// Memory-value flag OFF runs the single-phase loop below. Flag ON classifies every entry with ZERO commits,
-// runs rescueSet per tenant, then commits; rescued entries stay full survivors for this cycle's later passes.
+// 1. Decay pass. Memory-value flag OFF runs the single-phase loop below; ON classifies every entry with zero commits, runs rescueSet per tenant, then commits.
+// Rescued entries stay full survivors for this cycle's later passes.
 export function decayPass(run) {
     if (run.config.memoryValue.enabled)
         return decayWithMemoryValue(run);
@@ -93,10 +85,7 @@ function decayWithMemoryValue(run) {
     let rescuedIds = new Set();
     let rankById = new Map();
     const { strengthById, condemnedIds } = classifyByStrength(run);
-    // --- Phase 2a: rescue decision (pure compute) ---
-    // Runs under --dry-run too (only the pendingDeletes flush and the audit write in
-    // logRun stay !dryRun-gated), so the preview matches what a
-    // real run would decide.
+    // Phase 2a: rescue decision (pure compute); runs under --dry-run too (only the pendingDeletes flush and the logRun audit write are !dryRun-gated).
     // Fail-loud must not depend on condemnation traffic: validate the frozen weights even when nothing is condemned.
     validateWeights();
     if (condemnedIds.size > 0) {
@@ -112,9 +101,8 @@ function decayWithMemoryValue(run) {
         const strength = strengthById.get(entry.id);
         if (run.retirable(entry) && strength < DECAY_THRESHOLD) {
             if (rescuedIds.has(entry.id)) {
-                // Rescued: standard survivor stored-strength refresh.
-                // Confidence is left alone here: it is an epistemic tier, not a
-                // cached computation, so resolveConfidence derives it on read.
+                // Rescued: standard survivor stored-strength refresh. Confidence is left alone: it is an epistemic tier, not a cached
+                // computation, so resolveConfidence derives it on read.
                 rescuedEntries.push(keepSurvivor(run, entry, strength));
                 reportRescue(result, entry, strength, rankById.get(entry.id));
             }

package/dist/consolidate/dedupe.d.ts

@@ -1,25 +1,6 @@
-/**
- * Store-level deduplication. Scans for memories with the same text apart
- * from spacing, keeps the stronger copy (by strength + retrieval count),
- * removes the rest.
- *
- * Extracted from cli.ts in Episode A (v1.11.3) so `api.sleep` can dedupe
- * during the consolidation pipeline without violating the cli -> api
- * dependency direction. `cmdDedup` in cli.ts continues to import and use
- * this function unchanged.
- *
- * Survivor selection is a total order as of v1.26.3
- * (docs/plans/2026-07-16-dedupe-survivor-determinism.md): strength bucket
- * desc -> retrieval_count desc -> compareEntryIdentity (content asc ->
- * layer rank -> tags -> source -> id asc; the metadata keys arrived in
- * v1.38.1, docs/plans/2026-09-04-dedupe-survivor-metadata.md). Previously
- * the strength/retrieval-count comparator could tie exactly with no terminal
- * key, so the survivor fell to load order (arrival-order-dependent); see
- * `strengthBucket` below for the bucket encoding. As of the tenant-partition
- * fix (docs/plans/2026-08-15-dedupe-tenant-partition.md) the order is scoped
- * WITHIN each tenant group; cross-tenant pairs are never compared. Raw and
- * superseded rows are not candidates at all (v1.38.1).
- */
+/** Store-level dedup: same text apart from spacing, keeping the stronger copy; split out so `api.sleep` can dedupe without cli -> api imports.
+ * Survivor order is total and tenant-scoped: strength bucket, retrieval_count, then compareEntryIdentity; raw and superseded rows are not candidates. */
+import { type MemoryEntry } from '../core/memory.js';
 export interface DedupPair {
     kept: string;
     keptContent: string;
@@ -36,40 +17,20 @@ export interface DedupResult {
     removed: number;
     pairs: DedupPair[];
 }
-/**
- * Quantize a strength value into an integer "bucket" for tie comparison.
- *
- * Encodes the historical 0.01 epsilon transitively: two strengths compare
- * equal here iff they round to the same multiple of `STRENGTH_TIE_EPSILON`,
- * which (unlike a raw `Math.abs(a - b) > epsilon` check) is a genuine
- * equivalence relation — no more "A ties B, B ties C, but A beats C"
- * (see the file-level history note above).
- *
- * Non-finite input (`NaN`, `+/-Infinity`) maps to bucket `0` rather than
- * propagating: a NaN bucket would make the sort comparator return NaN,
- * silently reintroducing the non-total-order class this fix exists to kill.
- * (`null`/`undefined` already default to strength `0` via `?? 0`, same as
- * before this change.)
- *
- * Bucket-edge nuance: two strengths straddling a bucket edge (e.g. 0.0049 vs
- * 0.0051) now compare as different, where the old raw-epsilon check called
- * them tied. The flip always favors the not-weaker entry, and the OLD
- * behavior at such pairs was itself order/engine-dependent (the defect this
- * fix exists to kill) — so there is no stable prior behavior being broken.
- */
+/** Quantize strength to an integer bucket so ties are a true equivalence relation (equal iff same multiple of `STRENGTH_TIE_EPSILON`).
+ * Non-finite input maps to 0: a NaN bucket would make the comparator return NaN and break the total order. */
 export declare function strengthBucket(strength: number | null | undefined): number;
-/**
- * Scan the store for duplicates and remove the weaker copy: same text apart
- * from spacing, since a near-duplicate can differ in a value (port, version,
- * path, name), AND the same tenant: the scan is partitioned by
- * tenantId, so byte-identical content in two tenants is never a duplicate
- * pair (the tenant boundary is an isolation boundary; cross-tenant removal
- * was the v1.32.0 known-issue data-loss bug).
- * Keeps the one with higher strength (or more retrievals if tied). `threshold` is accepted for old callers and ignored.
- */
+/** Every row of the store, read once by a caller that also needs them, with the ids of rows backing an object. */
+export interface LoadedStore {
+    readonly entries: readonly MemoryEntry[];
+    readonly backing: ReadonlySet<string>;
+}
+/** Remove the weaker copy of same-text (apart from spacing) memories within one tenant; cross-tenant pairs are never duplicates (isolation boundary).
+ * Higher strength wins, then more retrievals; `threshold` is accepted for old callers and ignored. */
 export declare function deduplicateStore(hippoRoot: string, options?: {
     threshold?: number;
     dryRun?: boolean;
     actor?: string;
+    loaded?: LoadedStore;
 }): DedupResult;
 //# sourceMappingURL=dedupe.d.ts.map