hippo-memory 1.70.0 → 1.71.0

package/dist/connectors/slack/types.js

@@ -1,7 +1,5 @@
-/**
- * Slack Events API envelope shapes used by the ingestion connector.
- * Spec: https://api.slack.com/events-api
- */
+/** Slack Events API envelope shapes used by the ingestion connector.
+ *  Spec: https://api.slack.com/events-api */
 import { isJsonString, isJsonObject, isJsonNumber } from '../../util/json.js';
 export function isSlackEventEnvelope(x) {
     if (!isJsonObject(x))

package/dist/connectors/slack/web-client.js

@@ -1,15 +1,31 @@
 import { fetchWithRetry, isRetryableStatus } from '../../util/http-retry.js';
-import { isJsonString } from '../../util/json.js';
-/**
- * Build a SlackHistoryFetcher that pages `conversations.history` over real
- * HTTP. Wraps `fetchWithRetry` so 429 and 5xx handling is automatic. The returned
- * fetcher is the one `backfillChannel` consumes.
- *
- * Slack omits `channel` from messages in the history response, so we stamp
- * the request channel id onto each parsed message — downstream ingest needs
- * it on every event.
- */
+import { readCappedJson } from '../../util/capped-json.js';
+import { errorMessage } from '../../util/log.js';
+import { isJsonObject, isJsonString } from '../../util/json.js';
+/** Build a SlackHistoryFetcher that pages `conversations.history` over HTTP via `fetchWithRetry` (429 and 5xx handled).
+ *  Slack omits `channel` from history messages, so the request channel id is stamped onto each one for ingest. */
 const SLACK_TIMEOUT_MS = 30_000;
+// A page is at most 200 messages, each up to 40,000 characters at 4 bytes, carried once as text and once as rich-text blocks.
+const SLACK_MAX_REPLY_BYTES = 64 * 1024 * 1024;
+function isSlackMessage(m) {
+    return isJsonObject(m) && m.type === 'message' && isJsonString(m.ts);
+}
+/** The reply as a JSON object. The error names the status and the path only, since the query string carries channel ids and cursors. */
+async function readHistoryReply(r, url) {
+    const where = `slack: HTTP ${r.status} on ${url.pathname}`;
+    let body;
+    try {
+        body = await readCappedJson(r, SLACK_MAX_REPLY_BYTES);
+    }
+    catch (err) {
+        throw new Error(`${where}: ${errorMessage(err)}`, { cause: err });
+    }
+    if (!isJsonObject(body))
+        throw new Error(`${where}: the reply is not a JSON object`);
+    if (body.messages !== undefined && !Array.isArray(body.messages))
+        throw new Error(`${where}: \`messages\` is not an array`);
+    return body;
+}
 export function slackHistoryFetcher(token, fetchImpl) {
     return async ({ channelId, cursor, oldest }) => {
         const url = new URL('https://slack.com/api/conversations.history');
@@ -25,27 +41,17 @@ export function slackHistoryFetcher(token, fetchImpl) {
         });
         if (isRetryableStatus(r.status))
             throw new Error(`slack: still rate-limited or unavailable (HTTP ${r.status})`);
-        // SAFETY: body is the Slack `conversations.history` response; per the
-        // documented shape it's `{ ok, error?, messages?, response_metadata? }`.
-        const body = (await r.json());
-        if (!body.ok)
-            throw new Error(`slack: ${body.error ?? 'unknown error'}`);
-        const messages = (body.messages ?? [])
-            .filter((m) => {
-            if (m === null || Array.isArray(m) || typeof m !== 'object') {
-                return false;
-            }
-            // SAFETY: the check above just confirmed m is a non-null, non-array
-            // plain object, so it's safe to treat as a JSON-shaped record; the
-            // `m is SlackMessageEvent` predicate is what validates the fields.
-            const o = m;
-            return o.type === 'message' && isJsonString(o.ts);
-        })
+        const body = await readHistoryReply(r, url);
+        if (body.ok !== true)
+            throw new Error(`slack: ${isJsonString(body.error) ? body.error : 'unknown error'}`);
+        const messages = (Array.isArray(body.messages) ? body.messages : [])
+            .filter(isSlackMessage)
             // Slack returns messages without `channel`; stamp it from the request.
             .map((m) => ({ ...m, channel: channelId }));
+        const nextCursor = isJsonObject(body.response_metadata) ? body.response_metadata.next_cursor : undefined;
         return {
             messages,
-            next_cursor: body.response_metadata?.next_cursor ?? null,
+            next_cursor: isJsonString(nextCursor) ? nextCursor : null,
         };
     };
 }

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

@@ -1,23 +1,6 @@
 import type { HippoStore } from '../../store/index.js';
 import { type WebhookRequest } from '../../util/http-util.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 (hence PUBLIC_ROUTES); 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 declare function handleSlackEventsWebhook(request: WebhookRequest, store?: HippoStore): Promise<void>;
 //# sourceMappingURL=webhook.d.ts.map

package/dist/connectors/slack/webhook.js

@@ -9,25 +9,8 @@ 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 (hence PUBLIC_ROUTES); 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 +87,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 +150,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

@@ -3,12 +3,8 @@ import { jaccardMinShared, overlapPartners } from './overlap-index.js';
 import { isQuarantineScope } from '../trust/quarantine.js';
 import { isPersonalScope } from '../store/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

@@ -2,13 +2,11 @@ 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 { generateDagSummary } from './dag-summary.js';
 import { derivationScope, derivationPartitionKey } from '../store/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;
 export function clusterFacts(facts) {
@@ -42,41 +40,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 +57,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 +165,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,19 +175,8 @@ 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);
@@ -242,12 +191,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 +203,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 +254,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));
             }