@jacfrost/autopm 0.0.1

package/src/autopm/memory/summary-topic.js

@@ -0,0 +1,1087 @@
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+
+import {
+  AUTOPM_MEMORY_SCHEMA_VERSION,
+  memoryDiagnostic,
+  validateSummaryEnvelope,
+} from './contracts.js';
+import {
+  prepareAutoPmMarkdownProjection,
+  writeAutoPmWikiMarkdownProjection,
+} from './projection.js';
+import { resolveWikiPath } from './paths.js';
+
+export const AUTOPM_MEMORY_TOPIC_SUMMARY_TREE_VERSION = 1;
+export const AUTOPM_MEMORY_TOPIC_SUMMARY_REGISTRY_KEY = 'summary.topic.registry.v1';
+export const AUTOPM_WIKI_TOPIC_SUMMARIES_DIRNAME = 'summaries/topics';
+
+export const AUTOPM_MEMORY_TOPIC_SUMMARY_DEFAULT_HOTNESS_THRESHOLD = 3;
+export const AUTOPM_MEMORY_TOPIC_SUMMARY_DEFAULT_MIN_EVIDENCE_COUNT = 2;
+export const AUTOPM_MEMORY_TOPIC_SUMMARY_DEFAULT_STALE_AFTER_MS = 7 * 24 * 60 * 60 * 1000;
+export const AUTOPM_MEMORY_TOPIC_SUMMARY_DEFAULT_TEXT_CHARS = 520;
+export const AUTOPM_MEMORY_TOPIC_SUMMARY_DEFAULT_MAX_TOPICS = 12;
+
+function nowIso() {
+  return new Date().toISOString();
+}
+
+function diagnostic({ severity = 'info', code, message, path = '$', details = {} }) {
+  return memoryDiagnostic({ severity, code, message, path, details });
+}
+
+function isPlainObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function uniqueStrings(values) {
+  return [...new Set((Array.isArray(values) ? values : [])
+    .map((value) => String(value ?? '').trim())
+    .filter((value) => value.length > 0))];
+}
+
+function cloneJson(value, fallback) {
+  if (value === undefined || value === null) return fallback;
+  try {
+    return JSON.parse(JSON.stringify(value));
+  } catch {
+    return fallback;
+  }
+}
+
+function stableHash(value, length = 40) {
+  return crypto.createHash('sha256').update(String(value)).digest('hex').slice(0, length);
+}
+
+function timestampMs(value) {
+  const parsed = Date.parse(value);
+  return Number.isNaN(parsed) ? 0 : parsed;
+}
+
+function addMs(isoTimestamp, ms) {
+  return new Date(timestampMs(isoTimestamp) + ms).toISOString();
+}
+
+function clampPositiveInteger(value, fallback) {
+  const parsed = Number(value);
+  if (!Number.isFinite(parsed) || parsed <= 0) return fallback;
+  return Math.max(1, Math.trunc(parsed));
+}
+
+function clampNonNegativeNumber(value, fallback) {
+  const parsed = Number(value);
+  if (!Number.isFinite(parsed) || parsed < 0) return fallback;
+  return parsed;
+}
+
+function normalizeRegistry(value, generatedAt = nowIso()) {
+  if (isPlainObject(value) && value.schemaVersion === AUTOPM_MEMORY_TOPIC_SUMMARY_TREE_VERSION) {
+    return {
+      schemaVersion: AUTOPM_MEMORY_TOPIC_SUMMARY_TREE_VERSION,
+      updatedAt: typeof value.updatedAt === 'string' ? value.updatedAt : generatedAt,
+      topics: isPlainObject(value.topics) ? cloneJson(value.topics, {}) : {},
+      counters: {
+        routeScans: Number(value.counters?.routeScans ?? 0),
+        materializations: Number(value.counters?.materializations ?? 0),
+        duplicateMaterializations: Number(value.counters?.duplicateMaterializations ?? 0),
+        staleRebuilds: Number(value.counters?.staleRebuilds ?? 0),
+      },
+      lastTransition: isPlainObject(value.lastTransition) ? cloneJson(value.lastTransition, null) : null,
+    };
+  }
+
+  return {
+    schemaVersion: AUTOPM_MEMORY_TOPIC_SUMMARY_TREE_VERSION,
+    updatedAt: generatedAt,
+    topics: {},
+    counters: {
+      routeScans: 0,
+      materializations: 0,
+      duplicateMaterializations: 0,
+      staleRebuilds: 0,
+    },
+    lastTransition: null,
+  };
+}
+
+function blankTopicState(topicId, label = topicId) {
+  return {
+    topicId,
+    label,
+    latest: null,
+    summaries: [],
+    counters: {
+      materializations: 0,
+      duplicateMaterializations: 0,
+      staleRebuilds: 0,
+    },
+  };
+}
+
+function normalizeTopicState(value, topicId, label = topicId) {
+  const base = blankTopicState(topicId, label);
+  if (!isPlainObject(value)) return base;
+  return {
+    topicId,
+    label: typeof value.label === 'string' && value.label.length > 0 ? value.label : label,
+    latest: isPlainObject(value.latest) ? cloneJson(value.latest, null) : null,
+    summaries: Array.isArray(value.summaries) ? value.summaries.filter(isPlainObject) : [],
+    counters: {
+      materializations: Number(value.counters?.materializations ?? 0),
+      duplicateMaterializations: Number(value.counters?.duplicateMaterializations ?? 0),
+      staleRebuilds: Number(value.counters?.staleRebuilds ?? 0),
+    },
+  };
+}
+
+function topicState(registry, topicId, label = topicId) {
+  const state = normalizeTopicState(registry.topics[topicId], topicId, label);
+  registry.topics[topicId] = state;
+  return state;
+}
+
+function registriesEqual(left, right) {
+  return JSON.stringify(left) === JSON.stringify(right);
+}
+
+function writeRegistryIfChanged(store, nextRegistry, previousRegistry, generatedAt) {
+  nextRegistry.updatedAt = generatedAt;
+  if (previousRegistry && registriesEqual(previousRegistry, nextRegistry)) return false;
+  store.setStatusMetadata(AUTOPM_MEMORY_TOPIC_SUMMARY_REGISTRY_KEY, nextRegistry, generatedAt);
+  return true;
+}
+
+function assertStore(store) {
+  if (!store || !store.db || typeof store.db.prepare !== 'function' || typeof store.writeEnvelope !== 'function' || typeof store.getStatusMetadata !== 'function' || typeof store.setStatusMetadata !== 'function') {
+    throw Object.assign(new TypeError('A writable AutoPM memory store is required for topic summary trees.'), {
+      name: 'AutoPmTopicSummaryTreeError',
+      code: 'AUTOPM_MEMORY_TOPIC_SUMMARY_STORE_REQUIRED',
+    });
+  }
+}
+
+function readRegistry(store, generatedAt = nowIso()) {
+  assertStore(store);
+  return normalizeRegistry(store.getStatusMetadata(AUTOPM_MEMORY_TOPIC_SUMMARY_REGISTRY_KEY, null), generatedAt);
+}
+
+function readJsonText(text, fallback = null) {
+  if (typeof text !== 'string' || text.length === 0) return fallback;
+  try {
+    return JSON.parse(text);
+  } catch {
+    return fallback;
+  }
+}
+
+function readEnvelopeRows(store, table, orderBy) {
+  return store.db.prepare(`SELECT envelope_json FROM ${table} ORDER BY ${orderBy}`).all()
+    .map((row) => readJsonText(row.envelope_json))
+    .filter(Boolean);
+}
+
+function collectTopicInputs(store) {
+  assertStore(store);
+  return {
+    chunks: readEnvelopeRows(store, 'chunks', 'chunk_id'),
+    candidates: readEnvelopeRows(store, 'candidates', 'candidate_id'),
+    acceptedMemories: readEnvelopeRows(store, 'accepted_memory', 'memory_id'),
+  };
+}
+
+function topicSlug(value, fallback = 'topic') {
+  const slug = String(value ?? fallback)
+    .toLowerCase()
+    .replace(/^kind:/, '')
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, 64);
+  return slug.length > 0 ? slug : fallback;
+}
+
+function topicIdFor(value) {
+  return topicSlug(value, 'topic');
+}
+
+function labelForTopic(value) {
+  return String(value ?? '').replace(/\s+/g, ' ').trim();
+}
+
+function valuesFromEntity(entity) {
+  if (typeof entity === 'string') return [entity];
+  if (!isPlainObject(entity)) return [];
+  return uniqueStrings([
+    entity.id,
+    entity.name,
+    entity.title,
+    entity.label,
+    entity.text,
+    typeof entity.type === 'string' && typeof entity.name === 'string' ? `${entity.type} ${entity.name}` : null,
+  ].filter(Boolean));
+}
+
+function metadataTopics(metadata) {
+  return uniqueStrings([
+    ...(Array.isArray(metadata?.topics) ? metadata.topics : []),
+    ...(Array.isArray(metadata?.topicTags) ? metadata.topicTags : []),
+    ...(Array.isArray(metadata?.tags) ? metadata.tags : []),
+    ...(Array.isArray(metadata?.entities) ? metadata.entities.flatMap(valuesFromEntity) : []),
+  ]);
+}
+
+function topicsForChunk(chunk) {
+  return metadataTopics(chunk.metadata);
+}
+
+function topicsForCandidate(candidate) {
+  return uniqueStrings([
+    candidate.kind,
+    ...(Array.isArray(candidate.tags) ? candidate.tags : []),
+    ...metadataTopics(candidate.metadata),
+  ]);
+}
+
+function topicsForAcceptedMemory(memory) {
+  return uniqueStrings([
+    memory.kind,
+    ...(Array.isArray(memory.tags) ? memory.tags : []),
+    ...metadataTopics(memory.metadata),
+  ]);
+}
+
+function normalizedCandidateStatusAllowed(candidate) {
+  return ['pending', 'proposed', 'promoted'].includes(candidate?.status);
+}
+
+function acceptedMemoryActive(memory) {
+  return !memory?.status || memory.status === 'active';
+}
+
+function routeWeightFor(recordType, envelope) {
+  if (recordType === 'accepted_memory') return Number((2 + Math.max(0, Math.min(1, Number(envelope.confidence) || 0))).toFixed(3));
+  if (recordType === 'candidate') return Number((0.75 + (Math.max(0, Math.min(1, Number(envelope.confidence) || 0)) * 0.5)).toFixed(3));
+  return 1;
+}
+
+function createEmptyTopicRoute(topicId, label) {
+  return {
+    topicId,
+    label,
+    hotnessScore: 0,
+    routeCount: 0,
+    chunkIds: [],
+    candidateIds: [],
+    memoryIds: [],
+    sourceChunkIds: [],
+    sourceMemoryIds: [],
+    labels: [],
+    evidence: [],
+  };
+}
+
+function appendRoute(routesByTopic, { topicValue, recordType, recordId, envelope, sourceChunkIds = [], sourceMemoryIds = [] }) {
+  const label = labelForTopic(topicValue);
+  if (label.length === 0) return;
+  const topicId = topicIdFor(label);
+  const route = routesByTopic.get(topicId) ?? createEmptyTopicRoute(topicId, label);
+  routesByTopic.set(topicId, route);
+
+  const weight = routeWeightFor(recordType, envelope);
+  route.hotnessScore = Number((route.hotnessScore + weight).toFixed(3));
+  route.routeCount += 1;
+  route.labels = uniqueStrings([...route.labels, label]);
+  route.sourceChunkIds = uniqueStrings([...route.sourceChunkIds, ...sourceChunkIds]);
+  route.sourceMemoryIds = uniqueStrings([...route.sourceMemoryIds, ...sourceMemoryIds]);
+  if (recordType === 'chunk') route.chunkIds = uniqueStrings([...route.chunkIds, recordId]);
+  if (recordType === 'candidate') route.candidateIds = uniqueStrings([...route.candidateIds, recordId]);
+  if (recordType === 'accepted_memory') route.memoryIds = uniqueStrings([...route.memoryIds, recordId]);
+  route.evidence.push(Object.freeze({ recordType, recordId, weight, sourceChunkIds: uniqueStrings(sourceChunkIds), sourceMemoryIds: uniqueStrings(sourceMemoryIds) }));
+}
+
+function finalizeTopicRoute(route) {
+  const chunkIds = uniqueStrings([...route.chunkIds, ...route.sourceChunkIds]).sort();
+  const memoryIds = uniqueStrings([...route.memoryIds, ...route.sourceMemoryIds]).sort();
+  const candidateIds = uniqueStrings(route.candidateIds).sort();
+  return Object.freeze({
+    topicId: route.topicId,
+    label: route.labels[0] ?? route.label,
+    labels: Object.freeze(uniqueStrings(route.labels).sort()),
+    hotnessScore: route.hotnessScore,
+    routeCount: route.routeCount,
+    evidenceCounts: Object.freeze({
+      chunks: chunkIds.length,
+      candidates: candidateIds.length,
+      acceptedMemories: memoryIds.length,
+      total: chunkIds.length + candidateIds.length + memoryIds.length,
+      routes: route.routeCount,
+    }),
+    chunkIds: Object.freeze(chunkIds),
+    candidateIds: Object.freeze(candidateIds),
+    memoryIds: Object.freeze(memoryIds),
+    sourceChunkIds: Object.freeze(chunkIds),
+    sourceMemoryIds: Object.freeze(memoryIds),
+    evidence: Object.freeze(route.evidence.map((item) => Object.freeze({ ...item })).sort((a, b) => `${a.recordType}:${a.recordId}`.localeCompare(`${b.recordType}:${b.recordId}`))),
+  });
+}
+
+function compareTopicRoutes(a, b) {
+  if (b.hotnessScore !== a.hotnessScore) return b.hotnessScore - a.hotnessScore;
+  if (b.evidenceCounts.total !== a.evidenceCounts.total) return b.evidenceCounts.total - a.evidenceCounts.total;
+  return a.topicId.localeCompare(b.topicId);
+}
+
+function evidenceFingerprintForTopic(topic) {
+  return stableHash(JSON.stringify({
+    topicId: topic.topicId,
+    chunkIds: topic.chunkIds,
+    candidateIds: topic.candidateIds,
+    memoryIds: topic.memoryIds,
+  }), 8);
+}
+
+function identifierPart(value, fallback = 'item', maxLength = 36) {
+  const slug = topicSlug(value, fallback).slice(0, maxLength);
+  return slug.length > 0 ? slug : fallback;
+}
+
+function timePartForId(generatedAt) {
+  const parsed = Date.parse(generatedAt);
+  const date = Number.isNaN(parsed) ? new Date(0) : new Date(parsed);
+  const months = ['jan', 'feb', 'mar', 'apr', 'may', 'jun', 'jul', 'aug', 'sep', 'oct', 'nov', 'dec'];
+  const year = date.getUTCFullYear();
+  const month = months[date.getUTCMonth()] ?? 'jan';
+  const day = String(date.getUTCDate()).padStart(2, '0');
+  const hour = String(date.getUTCHours()).padStart(2, '0');
+  const minute = String(date.getUTCMinutes()).padStart(2, '0');
+  return `${year}${month}${day}-${hour}${minute}`;
+}
+
+function sequencePart(value) {
+  const normalized = identifierPart(value, '', 20);
+  return normalized.length > 0 ? normalized : null;
+}
+
+function summaryIdFor({ topicId, generatedAt, sequenceKey = null }) {
+  const parts = ['summary', 'topic', identifierPart(topicId, 'topic', 40), timePartForId(generatedAt)];
+  const sequence = sequencePart(sequenceKey);
+  if (sequence) parts.push(sequence);
+  return parts.join('-').slice(0, 128);
+}
+
+function sameMinuteEntryCount(entries, generatedAt) {
+  const minute = timePartForId(generatedAt);
+  return (Array.isArray(entries) ? entries : []).filter((entry) => timePartForId(entry?.generatedAt) === minute || String(entry?.summaryId ?? '').includes(`-${minute}`)).length;
+}
+
+function nextSequenceKeyForState(state, generatedAt) {
+  const sameMinuteCount = sameMinuteEntryCount(state?.summaries, generatedAt);
+  return sameMinuteCount > 0 ? `seq${sameMinuteCount + 1}` : null;
+}
+
+function summaryProjectionChildPath({ topic, generatedAt = nowIso(), sequenceKey = null }) {
+  const sequence = sequencePart(sequenceKey);
+  const filename = sequence ? `${timePartForId(generatedAt)}-${sequence}` : timePartForId(generatedAt);
+  return `${AUTOPM_WIKI_TOPIC_SUMMARIES_DIRNAME}/${identifierPart(topic.topicId, 'topic', 56)}/${filename}.md`;
+}
+
+function trimForSummary(text, limit) {
+  const normalized = String(text ?? '').replace(/\s+/g, ' ').trim();
+  if (normalized.length <= limit) return normalized;
+  return `${normalized.slice(0, Math.max(24, limit)).trim()}…`;
+}
+
+function envelopeById(envelopes, idField) {
+  return new Map(envelopes.map((envelope) => [envelope[idField], envelope]).filter(([id]) => typeof id === 'string' && id.length > 0));
+}
+
+function buildSummaryText({ topic, inputs, textChars }) {
+  const chunkById = envelopeById(inputs.chunks, 'chunkId');
+  const memoryById = envelopeById(inputs.acceptedMemories, 'memoryId');
+  const candidateById = envelopeById(inputs.candidates, 'candidateId');
+  const chunkLines = topic.chunkIds
+    .map((chunkId) => chunkById.get(chunkId))
+    .filter(Boolean)
+    .slice(0, 8)
+    .map((chunk) => `- Chunk ${chunk.chunkId}: ${trimForSummary(chunk.text, textChars)}`);
+  const memoryLines = topic.memoryIds
+    .map((memoryId) => memoryById.get(memoryId))
+    .filter(Boolean)
+    .slice(0, 8)
+    .map((memory) => `- ${memory.kind} memory ${memory.memoryId}: ${trimForSummary(memory.text, textChars)}`);
+  const candidateLines = topic.candidateIds
+    .map((candidateId) => candidateById.get(candidateId))
+    .filter(Boolean)
+    .slice(0, 4)
+    .map((candidate) => `- ${candidate.kind} candidate ${candidate.candidateId}: ${trimForSummary(candidate.text, Math.floor(textChars / 2))}`);
+
+  return [
+    `Topic summary for ${topic.label}.`,
+    `Hotness score ${topic.hotnessScore} from ${topic.evidenceCounts.total} linked evidence record(s).`,
+    '',
+    memoryLines.length > 0 ? 'Accepted memory evidence:' : null,
+    ...memoryLines,
+    chunkLines.length > 0 ? 'Chunk evidence:' : null,
+    ...chunkLines,
+    candidateLines.length > 0 ? 'Candidate routing signals:' : null,
+    ...candidateLines,
+  ].filter((line) => line !== null).join('\n').trim();
+}
+
+function sealedInputRefsForTopic(topic) {
+  return [
+    ...topic.chunkIds.map((chunkId) => ({ recordType: 'chunk', chunkId })),
+    ...topic.memoryIds.map((memoryId) => ({ recordType: 'accepted_memory', memoryId })),
+    ...topic.candidateIds.map((candidateId) => ({ recordType: 'candidate', candidateId })),
+  ];
+}
+
+function yamlString(value) {
+  return JSON.stringify(String(value ?? ''));
+}
+
+function yamlList(values, indent = '') {
+  const items = uniqueStrings(values);
+  if (items.length === 0) return `${indent}[]`;
+  return items.map((value) => `${indent}- ${yamlString(value)}`).join('\n');
+}
+
+function buildTopicSummaryProjectionMarkdown({ topic, summary }) {
+  const tree = summary.metadata?.summaryTree ?? {};
+  return [
+    '---',
+    'autopm: true',
+    'record_type: summary',
+    `summary_id: ${yamlString(summary.summaryId)}`,
+    'scope: topic',
+    `topic_id: ${yamlString(topic.topicId)}`,
+    `topic_label: ${yamlString(topic.label)}`,
+    `generated_at: ${yamlString(summary.generatedAt)}`,
+    `freshness: ${yamlString(summary.metadata?.freshness?.status ?? 'fresh')}`,
+    `stale_at: ${yamlString(summary.metadata?.freshness?.staleAt ?? '')}`,
+    `hotness_score: ${Number(topic.hotnessScore)}`,
+    'source_chunk_ids:',
+    yamlList(summary.sourceChunkIds, '  '),
+    'source_memory_ids:',
+    yamlList(summary.sourceMemoryIds, '  '),
+    'candidate_ids:',
+    yamlList(tree.contributingCandidateIds, '  '),
+    '---',
+    '',
+    `# Topic summary: ${topic.label}`,
+    '',
+    '<!-- AutoPM generated topic summary projection. Edit manual notes under .autopm/wiki/notes/. -->',
+    '',
+    summary.text.trim(),
+    '',
+    '## Provenance',
+    '',
+    `- Topic ID: \`${topic.topicId}\``,
+    `- Summary ID: \`${summary.summaryId}\``,
+    `- Evidence fingerprint: \`${tree.evidenceFingerprint ?? ''}\``,
+    '- Accepted memories:',
+    ...summary.sourceMemoryIds.map((memoryId) => `  - \`${memoryId}\``),
+    '- Chunks:',
+    ...summary.sourceChunkIds.map((chunkId) => `  - \`${chunkId}\` ([[chunks/${chunkId}]])`),
+    '',
+    '## Diagnostics',
+    '',
+    `- Tree version: ${AUTOPM_MEMORY_TOPIC_SUMMARY_TREE_VERSION}`,
+    `- Node count: ${Number(tree.nodeCounts?.chunkLeaves ?? 0)} chunk leaf/leaves, ${Number(tree.nodeCounts?.memoryLeaves ?? 0)} memory leaf/leaves, ${Number(tree.nodeCounts?.candidateLeaves ?? 0)} candidate signal(s), 1 L1 summary`,
+    `- Materialization reason: \`${tree.materializationReason ?? 'hotness'}\``,
+    `- Projection path: \`${summary.metadata?.projectionPath ?? ''}\``,
+    '',
+  ].join('\n');
+}
+
+function writeIdempotentTopicSummaryProjection({ projectRoot, childRelativePath, markdown }) {
+  const resolved = resolveWikiPath(projectRoot, childRelativePath);
+  const prepared = prepareAutoPmMarkdownProjection(markdown, { path: '$.topicSummaryProjection' });
+  if (fs.existsSync(resolved.path)) {
+    const existing = fs.readFileSync(resolved.path, 'utf8');
+    if (existing === prepared.content) {
+      return Object.freeze({
+        projectionRoot: 'wiki',
+        relativePath: resolved.relativePath,
+        path: resolved.path,
+        bytesWritten: 0,
+        redactionCount: prepared.redactionCount,
+        warningCodes: prepared.warningCodes,
+        redactionDiagnostics: prepared.redactionDiagnostics,
+        durableStateChanged: false,
+        written: false,
+        skipped: true,
+      });
+    }
+  }
+
+  const written = writeAutoPmWikiMarkdownProjection({
+    projectRoot,
+    childRelativePath,
+    markdown,
+    overwrite: true,
+    diagnosticPath: '$.topicSummaryProjection',
+  });
+  return Object.freeze({ ...written, written: true, skipped: false });
+}
+
+function buildSummaryEnvelope({ topic, inputs, generatedAt, staleAfterMs, reason, projectionPath, textChars, evidenceFingerprint, hotnessThreshold, sequenceKey = null }) {
+  const staleAt = addMs(generatedAt, staleAfterMs);
+  const summaryId = summaryIdFor({ topicId: topic.topicId, evidenceFingerprint, generatedAt, sequenceKey });
+  const sealedInputRefs = sealedInputRefsForTopic(topic);
+  const envelope = {
+    schemaVersion: AUTOPM_MEMORY_SCHEMA_VERSION,
+    recordType: 'summary',
+    summaryId,
+    scope: 'topic',
+    text: buildSummaryText({ topic, inputs, textChars }),
+    generatedAt,
+    sourceMemoryIds: [...topic.memoryIds],
+    sourceChunkIds: [...topic.chunkIds],
+    metadata: {
+      summaryTree: {
+        schemaVersion: AUTOPM_MEMORY_TOPIC_SUMMARY_TREE_VERSION,
+        treeKind: 'topic',
+        level: 'L1',
+        topicId: topic.topicId,
+        topicLabel: topic.label,
+        topicLabels: [...topic.labels],
+        materializedAt: generatedAt,
+        materializationReason: reason,
+        hotnessScore: topic.hotnessScore,
+        hotnessThreshold,
+        evidenceFingerprint,
+        rebuildSequenceKey: sequenceKey,
+        sealedInputRefs,
+        linkedEvidenceCounts: { ...topic.evidenceCounts },
+        contributingChunkIds: [...topic.chunkIds],
+        contributingMemoryIds: [...topic.memoryIds],
+        contributingCandidateIds: [...topic.candidateIds],
+        nodeCounts: {
+          chunkLeaves: topic.chunkIds.length,
+          memoryLeaves: topic.memoryIds.length,
+          candidateLeaves: topic.candidateIds.length,
+          l1Summaries: 1,
+        },
+      },
+      freshness: {
+        status: 'fresh',
+        generatedAt,
+        staleAfterMs,
+        staleAt,
+      },
+      topics: uniqueStrings([topic.topicId, topic.label, ...topic.labels]).sort(),
+      topicTags: uniqueStrings([topic.topicId, ...topic.labels]).sort(),
+      summaryConfidence: Math.min(0.95, Number((0.58 + Math.min(topic.hotnessScore, 8) * 0.04).toFixed(3))),
+      projectionPath,
+      observability: {
+        topicHotnessScore: topic.hotnessScore,
+        linkedEvidenceCount: topic.evidenceCounts.total,
+        sealedInputReferenceCount: sealedInputRefs.length,
+        topicSummaryTreeVersion: AUTOPM_MEMORY_TOPIC_SUMMARY_TREE_VERSION,
+      },
+    },
+    diagnostics: [diagnostic({
+      severity: 'info',
+      code: 'AUTOPM_MEMORY_TOPIC_SUMMARY_MATERIALIZED',
+      message: 'Topic summary tree materialized a hot topic into a topic summary record.',
+      details: {
+        topicId: topic.topicId,
+        summaryId,
+        hotnessScore: topic.hotnessScore,
+        evidenceCount: topic.evidenceCounts.total,
+        reason,
+        projectionPath,
+      },
+    })],
+  };
+
+  const validation = validateSummaryEnvelope(envelope);
+  if (!validation.ok) {
+    throw Object.assign(new Error('Topic summary envelope failed validation.'), {
+      name: 'AutoPmTopicSummaryTreeError',
+      code: 'AUTOPM_MEMORY_TOPIC_SUMMARY_SCHEMA_INVALID',
+      details: { errors: validation.errors },
+    });
+  }
+
+  return envelope;
+}
+
+function sealEntryFor({ summary, topic, projection, evidenceFingerprint, reason }) {
+  return {
+    summaryId: summary.summaryId,
+    level: 'L1',
+    scope: 'topic',
+    topicId: topic.topicId,
+    topicLabel: topic.label,
+    hotnessScore: topic.hotnessScore,
+    evidenceFingerprint,
+    generatedAt: summary.generatedAt,
+    staleAt: summary.metadata.freshness.staleAt,
+    reason,
+    chunkIds: [...summary.sourceChunkIds],
+    memoryIds: [...summary.sourceMemoryIds],
+    candidateIds: [...summary.metadata.summaryTree.contributingCandidateIds],
+    projectionPath: projection.relativePath,
+  };
+}
+
+function addOrReplaceSummaryEntry(state, entry) {
+  const withoutExisting = state.summaries.filter((item) => item.summaryId !== entry.summaryId);
+  state.summaries = [...withoutExisting, entry].sort((a, b) => String(a.generatedAt).localeCompare(String(b.generatedAt)));
+  state.latest = entry;
+}
+
+function materializeOneTopic({ store, projectRoot, topic, inputs, registry, generatedAt, staleAfterMs, textChars, hotnessThreshold, reason, forceRebuild = false }) {
+  const state = topicState(registry, topic.topicId, topic.label);
+  const evidenceFingerprint = evidenceFingerprintForTopic(topic);
+  const stale = state.latest?.staleAt ? timestampMs(generatedAt) >= timestampMs(state.latest.staleAt) : false;
+  const duplicateFresh = !forceRebuild && !stale && state.latest?.evidenceFingerprint === evidenceFingerprint;
+
+  if (duplicateFresh) {
+    state.counters.duplicateMaterializations += 1;
+    registry.counters.duplicateMaterializations += 1;
+    return Object.freeze({
+      ok: true,
+      status: 'duplicate',
+      generatedAt,
+      topicId: topic.topicId,
+      summaryId: state.latest.summaryId,
+      summary: null,
+      projection: null,
+      artifactPathsWritten: Object.freeze([]),
+      diagnostics: Object.freeze([diagnostic({
+        severity: 'info',
+        code: 'AUTOPM_MEMORY_TOPIC_SUMMARY_DUPLICATE_FRESH',
+        message: 'Topic summary tree skipped materialization because the latest topic summary is still fresh for the same evidence set.',
+        details: { topicId: topic.topicId, summaryId: state.latest.summaryId, evidenceFingerprint },
+      })]),
+      warnings: Object.freeze([]),
+      errors: Object.freeze([]),
+      warningCodes: Object.freeze([]),
+      errorCodes: Object.freeze([]),
+      durableStateChanged: true,
+    });
+  }
+
+  const sequenceKey = nextSequenceKeyForState(state, generatedAt);
+  const summaryId = summaryIdFor({ topicId: topic.topicId, evidenceFingerprint, generatedAt, sequenceKey });
+  const projectionPath = summaryProjectionChildPath({ topic, generatedAt, sequenceKey });
+  const summary = buildSummaryEnvelope({
+    topic,
+    inputs,
+    generatedAt,
+    staleAfterMs,
+    reason,
+    projectionPath: `wiki:t/${identifierPart(topic.topicId, 'topic', 40)}/${sequenceKey ? `${timePartForId(generatedAt)}-${sequenceKey}` : timePartForId(generatedAt)}.md`,
+    textChars,
+    evidenceFingerprint,
+    hotnessThreshold,
+    sequenceKey,
+  });
+  const existing = store.getEnvelope('summary', summary.summaryId);
+  const duplicatePersisted = existing
+    && existing.scope === 'topic'
+    && existing.metadata?.summaryTree?.topicId === topic.topicId
+    && existing.metadata?.summaryTree?.evidenceFingerprint === evidenceFingerprint;
+
+  let summaryWritten = false;
+  if (!duplicatePersisted) {
+    store.writeEnvelope(summary);
+    summaryWritten = true;
+  }
+
+  const projection = writeIdempotentTopicSummaryProjection({
+    projectRoot,
+    childRelativePath: projectionPath,
+    markdown: buildTopicSummaryProjectionMarkdown({ topic, summary }),
+  });
+
+  addOrReplaceSummaryEntry(state, sealEntryFor({ summary, topic, projection, evidenceFingerprint, reason }));
+  if (reason === 'stale') {
+    state.counters.staleRebuilds += 1;
+    registry.counters.staleRebuilds += 1;
+  } else {
+    state.counters.materializations += 1;
+    registry.counters.materializations += 1;
+  }
+  registry.lastTransition = {
+    event: reason === 'stale' ? 'stale_rebuilt' : 'materialized',
+    topicId: topic.topicId,
+    summaryId: summary.summaryId,
+    hotnessScore: topic.hotnessScore,
+    evidenceFingerprint,
+    projectionPath: projection.relativePath,
+    at: generatedAt,
+  };
+
+  const diagnostics = [
+    ...summary.diagnostics,
+    ...projection.redactionDiagnostics,
+    diagnostic({
+      severity: 'info',
+      code: duplicatePersisted ? 'AUTOPM_MEMORY_TOPIC_SUMMARY_PERSISTED_DUPLICATE' : 'AUTOPM_MEMORY_TOPIC_SUMMARY_TREE_UPDATED',
+      message: duplicatePersisted
+        ? 'Topic summary materialization found an existing persisted topic summary for this evidence set and timestamp.'
+        : 'Topic summary tree persisted a topic summary node and projection.',
+      details: {
+        topicId: topic.topicId,
+        summaryId: summary.summaryId,
+        hotnessScore: topic.hotnessScore,
+        evidenceCount: topic.evidenceCounts.total,
+        reason,
+        projectionPath: projection.relativePath,
+        summaryWritten,
+        projectionWritten: projection.written === true,
+      },
+    }),
+  ];
+  const warningCodes = uniqueStrings(diagnostics.filter((item) => item.severity === 'warning').map((item) => item.code));
+
+  return Object.freeze({
+    ok: true,
+    status: duplicatePersisted ? 'duplicate' : 'materialized',
+    generatedAt,
+    topicId: topic.topicId,
+    summaryId: summary.summaryId,
+    summary,
+    summaryWritten,
+    duplicate: duplicatePersisted === true,
+    projection,
+    artifactPathsWritten: Object.freeze(projection.durableStateChanged ? [projection.relativePath] : []),
+    diagnostics: Object.freeze(diagnostics),
+    warnings: Object.freeze(diagnostics.filter((item) => item.severity === 'warning')),
+    errors: Object.freeze([]),
+    warningCodes: Object.freeze(warningCodes),
+    errorCodes: Object.freeze([]),
+    durableStateChanged: summaryWritten || projection.durableStateChanged === true,
+  });
+}
+
+function resultDiagnostics(results) {
+  return results.flatMap((result) => result.diagnostics ?? []);
+}
+
+export function autoPmTopicSummaryProjectionPath({ topic, generatedAt = nowIso(), sequenceKey = null } = {}) {
+  return summaryProjectionChildPath({ topic, generatedAt, sequenceKey });
+}
+
+export function buildAutoPmTopicSummaryProjectionMarkdown({ topic, summary } = {}) {
+  return buildTopicSummaryProjectionMarkdown({ topic, summary });
+}
+
+export function readAutoPmTopicSummaryTreeRegistry(store, generatedAt = nowIso()) {
+  return Object.freeze(readRegistry(store, generatedAt));
+}
+
+export function routeAutoPmTopicSummaryEvidence({
+  store,
+  generatedAt = nowIso(),
+  hotnessThreshold = AUTOPM_MEMORY_TOPIC_SUMMARY_DEFAULT_HOTNESS_THRESHOLD,
+  includeCold = true,
+} = {}) {
+  assertStore(store);
+  const inputs = collectTopicInputs(store);
+  const routesByTopic = new Map();
+
+  for (const chunk of inputs.chunks) {
+    if (chunk?.recordType !== 'chunk') continue;
+    for (const topicValue of topicsForChunk(chunk)) {
+      appendRoute(routesByTopic, { topicValue, recordType: 'chunk', recordId: chunk.chunkId, envelope: chunk, sourceChunkIds: [chunk.chunkId] });
+    }
+  }
+
+  for (const candidate of inputs.candidates) {
+    if (candidate?.recordType !== 'candidate' || !normalizedCandidateStatusAllowed(candidate)) continue;
+    const candidateChunkIds = uniqueStrings(candidate.sourceChunkIds);
+    for (const topicValue of topicsForCandidate(candidate)) {
+      appendRoute(routesByTopic, { topicValue, recordType: 'candidate', recordId: candidate.candidateId, envelope: candidate, sourceChunkIds: candidateChunkIds });
+    }
+  }
+
+  for (const memory of inputs.acceptedMemories) {
+    if (memory?.recordType !== 'accepted_memory' || !acceptedMemoryActive(memory)) continue;
+    const memoryChunkIds = uniqueStrings(memory.sourceChunkIds);
+    for (const topicValue of topicsForAcceptedMemory(memory)) {
+      appendRoute(routesByTopic, { topicValue, recordType: 'accepted_memory', recordId: memory.memoryId, envelope: memory, sourceChunkIds: memoryChunkIds, sourceMemoryIds: [memory.memoryId] });
+    }
+  }
+
+  const threshold = clampNonNegativeNumber(hotnessThreshold, AUTOPM_MEMORY_TOPIC_SUMMARY_DEFAULT_HOTNESS_THRESHOLD);
+  const topics = [...routesByTopic.values()].map(finalizeTopicRoute).sort(compareTopicRoutes);
+  const hotTopics = topics.filter((topic) => topic.hotnessScore >= threshold);
+  const selected = includeCold ? topics : hotTopics;
+  const diagnostics = [diagnostic({
+    severity: hotTopics.length > 0 ? 'info' : 'warning',
+    code: hotTopics.length > 0 ? 'AUTOPM_MEMORY_TOPIC_SUMMARY_HOT_TOPICS_ROUTED' : 'AUTOPM_MEMORY_TOPIC_SUMMARY_NO_HOT_TOPICS',
+    message: hotTopics.length > 0
+      ? 'Topic summary tree routed memory evidence and found hot topics.'
+      : 'Topic summary tree routed memory evidence but no topic crossed the hotness threshold.',
+    details: {
+      chunkCount: inputs.chunks.length,
+      candidateCount: inputs.candidates.length,
+      acceptedMemoryCount: inputs.acceptedMemories.length,
+      topicCount: topics.length,
+      hotTopicCount: hotTopics.length,
+      hotnessThreshold: threshold,
+    },
+  })];
+
+  return Object.freeze({
+    ok: true,
+    status: hotTopics.length > 0 ? 'hot' : 'cold',
+    generatedAt,
+    hotnessThreshold: threshold,
+    topicCount: topics.length,
+    hotTopicCount: hotTopics.length,
+    topics: Object.freeze(selected),
+    hotTopics: Object.freeze(hotTopics),
+    diagnostics: Object.freeze(diagnostics),
+    warnings: Object.freeze(diagnostics.filter((item) => item.severity === 'warning')),
+    errors: Object.freeze([]),
+    warningCodes: Object.freeze(uniqueStrings(diagnostics.filter((item) => item.severity === 'warning').map((item) => item.code))),
+    errorCodes: Object.freeze([]),
+    durableStateChanged: false,
+  });
+}
+
+export function materializeAutoPmTopicSummaries({
+  store,
+  projectRoot = process.cwd(),
+  generatedAt = nowIso(),
+  hotnessThreshold = AUTOPM_MEMORY_TOPIC_SUMMARY_DEFAULT_HOTNESS_THRESHOLD,
+  minEvidenceCount = AUTOPM_MEMORY_TOPIC_SUMMARY_DEFAULT_MIN_EVIDENCE_COUNT,
+  staleAfterMs = AUTOPM_MEMORY_TOPIC_SUMMARY_DEFAULT_STALE_AFTER_MS,
+  textChars = AUTOPM_MEMORY_TOPIC_SUMMARY_DEFAULT_TEXT_CHARS,
+  maxTopics = AUTOPM_MEMORY_TOPIC_SUMMARY_DEFAULT_MAX_TOPICS,
+  forceTopicIds = [],
+  forceRebuild = false,
+  materializationReason = 'hotness',
+} = {}) {
+  assertStore(store);
+  const threshold = clampNonNegativeNumber(hotnessThreshold, AUTOPM_MEMORY_TOPIC_SUMMARY_DEFAULT_HOTNESS_THRESHOLD);
+  const minimumEvidence = clampPositiveInteger(minEvidenceCount, AUTOPM_MEMORY_TOPIC_SUMMARY_DEFAULT_MIN_EVIDENCE_COUNT);
+  const staleMs = clampPositiveInteger(staleAfterMs, AUTOPM_MEMORY_TOPIC_SUMMARY_DEFAULT_STALE_AFTER_MS);
+  const textLimit = clampPositiveInteger(textChars, AUTOPM_MEMORY_TOPIC_SUMMARY_DEFAULT_TEXT_CHARS);
+  const topicLimit = clampPositiveInteger(maxTopics, AUTOPM_MEMORY_TOPIC_SUMMARY_DEFAULT_MAX_TOPICS);
+  const forced = new Set(uniqueStrings(forceTopicIds).map(topicIdFor));
+  const routed = routeAutoPmTopicSummaryEvidence({ store, generatedAt, hotnessThreshold: threshold, includeCold: true });
+  const inputs = collectTopicInputs(store);
+  const previousRegistry = readRegistry(store, generatedAt);
+  const registry = normalizeRegistry(previousRegistry, generatedAt);
+  registry.counters.routeScans += 1;
+
+  const eligibleTopics = routed.topics
+    .filter((topic) => forced.has(topic.topicId) || (topic.hotnessScore >= threshold && topic.evidenceCounts.total >= minimumEvidence))
+    .slice(0, topicLimit);
+
+  const results = eligibleTopics.map((topic) => materializeOneTopic({
+    store,
+    projectRoot,
+    topic,
+    inputs,
+    registry,
+    generatedAt,
+    staleAfterMs: staleMs,
+    textChars: textLimit,
+    hotnessThreshold: threshold,
+    reason: forced.has(topic.topicId) ? materializationReason : 'hotness',
+    forceRebuild,
+  }));
+
+  const registryChanged = writeRegistryIfChanged(store, registry, previousRegistry, generatedAt);
+  const diagnostics = [
+    ...routed.diagnostics,
+    diagnostic({
+      severity: results.length > 0 ? 'info' : 'warning',
+      code: results.length > 0 ? 'AUTOPM_MEMORY_TOPIC_SUMMARY_MATERIALIZATION_COMPLETED' : 'AUTOPM_MEMORY_TOPIC_SUMMARY_MATERIALIZATION_IDLE',
+      message: results.length > 0
+        ? 'Topic summary materialization evaluated hot topics and updated topic summary state.'
+        : 'Topic summary materialization found no eligible hot topics.',
+      details: {
+        topicCount: routed.topicCount,
+        hotTopicCount: routed.hotTopicCount,
+        eligibleTopicCount: eligibleTopics.length,
+        resultCount: results.length,
+        hotnessThreshold: threshold,
+        minEvidenceCount: minimumEvidence,
+        forcedTopicIds: [...forced],
+      },
+    }),
+    ...resultDiagnostics(results),
+  ];
+  const warningCodes = uniqueStrings(diagnostics.filter((item) => item.severity === 'warning').map((item) => item.code));
+  const errorCodes = uniqueStrings(results.flatMap((result) => result.errorCodes ?? []));
+
+  return Object.freeze({
+    ok: errorCodes.length === 0,
+    status: errorCodes.length > 0 ? 'error' : (results.some((result) => result.status === 'materialized') ? 'materialized' : (results.length > 0 ? 'duplicate' : 'idle')),
+    generatedAt,
+    hotnessThreshold: threshold,
+    minEvidenceCount: minimumEvidence,
+    topicCount: routed.topicCount,
+    hotTopicCount: routed.hotTopicCount,
+    materializedSummaryIds: Object.freeze(uniqueStrings(results.map((result) => result.summaryId).filter(Boolean))),
+    topicResults: Object.freeze(results),
+    artifactPathsWritten: Object.freeze(uniqueStrings(results.flatMap((result) => result.artifactPathsWritten ?? []))),
+    diagnostics: Object.freeze(diagnostics),
+    warnings: Object.freeze(diagnostics.filter((item) => item.severity === 'warning')),
+    errors: Object.freeze(diagnostics.filter((item) => item.severity === 'error')),
+    warningCodes: Object.freeze(warningCodes),
+    errorCodes: Object.freeze(errorCodes),
+    durableStateChanged: registryChanged || results.some((result) => result.durableStateChanged === true),
+  });
+}
+
+export function rebuildStaleAutoPmTopicSummaries({
+  store,
+  projectRoot = process.cwd(),
+  generatedAt = nowIso(),
+  hotnessThreshold = AUTOPM_MEMORY_TOPIC_SUMMARY_DEFAULT_HOTNESS_THRESHOLD,
+  minEvidenceCount = 1,
+  staleAfterMs = AUTOPM_MEMORY_TOPIC_SUMMARY_DEFAULT_STALE_AFTER_MS,
+  textChars = AUTOPM_MEMORY_TOPIC_SUMMARY_DEFAULT_TEXT_CHARS,
+} = {}) {
+  assertStore(store);
+  const registry = readRegistry(store, generatedAt);
+  const staleTopics = Object.entries(registry.topics)
+    .map(([topicId, rawState]) => normalizeTopicState(rawState, topicId))
+    .filter((state) => state.latest?.staleAt && timestampMs(generatedAt) >= timestampMs(state.latest.staleAt))
+    .map((state) => ({ topicId: state.topicId, summaryId: state.latest.summaryId, staleAt: state.latest.staleAt }));
+
+  if (staleTopics.length === 0) {
+    const diag = diagnostic({
+      severity: 'info',
+      code: 'AUTOPM_MEMORY_TOPIC_SUMMARY_NO_STALE_TOPICS',
+      message: 'Topic summary tree found no stale topic summaries to rebuild.',
+      details: { topicCount: Object.keys(registry.topics).length },
+    });
+    return Object.freeze({
+      ok: true,
+      status: 'idle',
+      generatedAt,
+      staleTopics: Object.freeze([]),
+      rebuild: null,
+      materializedSummaryIds: Object.freeze([]),
+      artifactPathsWritten: Object.freeze([]),
+      diagnostics: Object.freeze([diag]),
+      warnings: Object.freeze([]),
+      errors: Object.freeze([]),
+      warningCodes: Object.freeze([]),
+      errorCodes: Object.freeze([]),
+      durableStateChanged: false,
+    });
+  }
+
+  const rebuild = materializeAutoPmTopicSummaries({
+    store,
+    projectRoot,
+    generatedAt,
+    hotnessThreshold,
+    minEvidenceCount,
+    staleAfterMs,
+    textChars,
+    maxTopics: staleTopics.length,
+    forceTopicIds: staleTopics.map((topic) => topic.topicId),
+    forceRebuild: true,
+    materializationReason: 'stale',
+  });
+  const diagnostics = [diagnostic({
+    severity: 'warning',
+    code: 'AUTOPM_MEMORY_TOPIC_SUMMARY_STALE_REBUILD',
+    message: 'Topic summary tree rebuilt stale topic summaries.',
+    details: { staleTopicCount: staleTopics.length, staleTopics },
+  }), ...rebuild.diagnostics];
+
+  return Object.freeze({
+    ok: rebuild.ok,
+    status: rebuild.ok ? 'rebuilt' : 'error',
+    generatedAt,
+    staleTopics: Object.freeze(staleTopics),
+    rebuild,
+    materializedSummaryIds: rebuild.materializedSummaryIds,
+    artifactPathsWritten: rebuild.artifactPathsWritten,
+    diagnostics: Object.freeze(diagnostics),
+    warnings: Object.freeze(diagnostics.filter((item) => item.severity === 'warning')),
+    errors: rebuild.errors,
+    warningCodes: Object.freeze(uniqueStrings(diagnostics.filter((item) => item.severity === 'warning').map((item) => item.code))),
+    errorCodes: rebuild.errorCodes,
+    durableStateChanged: rebuild.durableStateChanged,
+  });
+}
+
+export function getAutoPmTopicSummaryTreeDiagnostics({
+  store,
+  generatedAt = nowIso(),
+  staleAfterMs = AUTOPM_MEMORY_TOPIC_SUMMARY_DEFAULT_STALE_AFTER_MS,
+  hotnessThreshold = AUTOPM_MEMORY_TOPIC_SUMMARY_DEFAULT_HOTNESS_THRESHOLD,
+} = {}) {
+  assertStore(store);
+  const registry = readRegistry(store, generatedAt);
+  const routed = routeAutoPmTopicSummaryEvidence({ store, generatedAt, hotnessThreshold, includeCold: true });
+  const staleMs = clampPositiveInteger(staleAfterMs, AUTOPM_MEMORY_TOPIC_SUMMARY_DEFAULT_STALE_AFTER_MS);
+  const topicStates = Object.entries(registry.topics).map(([topicId, rawState]) => {
+    const state = normalizeTopicState(rawState, topicId);
+    const latest = state.latest;
+    const stale = latest?.staleAt ? timestampMs(generatedAt) >= timestampMs(latest.staleAt) : false;
+    return {
+      topicId: state.topicId,
+      label: state.label,
+      l1SummaryCount: state.summaries.length,
+      latestSummaryId: latest?.summaryId ?? null,
+      latestHotnessScore: latest?.hotnessScore ?? null,
+      latestGeneratedAt: latest?.generatedAt ?? null,
+      staleAt: latest?.staleAt ?? null,
+      stale,
+      projectionPaths: uniqueStrings(state.summaries.map((entry) => entry.projectionPath)),
+      linkedChunkIds: uniqueStrings(state.summaries.flatMap((entry) => entry.chunkIds ?? [])),
+      linkedMemoryIds: uniqueStrings(state.summaries.flatMap((entry) => entry.memoryIds ?? [])),
+      linkedCandidateIds: uniqueStrings(state.summaries.flatMap((entry) => entry.candidateIds ?? [])),
+    };
+  }).sort((a, b) => a.topicId.localeCompare(b.topicId));
+  const staleTopics = topicStates.filter((topic) => topic.stale);
+  const hotnessByTopic = Object.fromEntries(routed.topics.map((topic) => [topic.topicId, topic.hotnessScore]));
+  const diagnostics = [diagnostic({
+    severity: staleTopics.length > 0 ? 'warning' : 'info',
+    code: staleTopics.length > 0 ? 'AUTOPM_MEMORY_TOPIC_SUMMARY_STALE_TOPICS' : 'AUTOPM_MEMORY_TOPIC_SUMMARY_TREE_HEALTHY',
+    message: staleTopics.length > 0
+      ? 'Topic summary tree has stale topic summaries waiting to be rebuilt.'
+      : 'Topic summary tree diagnostics found no stale topic summaries.',
+    details: {
+      topicStateCount: topicStates.length,
+      routedTopicCount: routed.topicCount,
+      hotTopicCount: routed.hotTopicCount,
+      staleTopicCount: staleTopics.length,
+      treeNodeCounts: {
+        topics: topicStates.length,
+        l1Summaries: topicStates.reduce((sum, topic) => sum + topic.l1SummaryCount, 0),
+        linkedChunks: uniqueStrings(topicStates.flatMap((topic) => topic.linkedChunkIds)).length,
+        linkedMemories: uniqueStrings(topicStates.flatMap((topic) => topic.linkedMemoryIds)).length,
+        linkedCandidates: uniqueStrings(topicStates.flatMap((topic) => topic.linkedCandidateIds)).length,
+      },
+    },
+  })];
+
+  return Object.freeze({
+    ok: true,
+    status: staleTopics.length > 0 ? 'warn' : 'ok',
+    generatedAt,
+    staleAfterMs: staleMs,
+    hotnessThreshold: clampNonNegativeNumber(hotnessThreshold, AUTOPM_MEMORY_TOPIC_SUMMARY_DEFAULT_HOTNESS_THRESHOLD),
+    topicCount: topicStates.length,
+    routedTopicCount: routed.topicCount,
+    hotTopicCount: routed.hotTopicCount,
+    treeNodeCounts: Object.freeze({
+      topics: topicStates.length,
+      l1Summaries: topicStates.reduce((sum, topic) => sum + topic.l1SummaryCount, 0),
+      linkedChunks: uniqueStrings(topicStates.flatMap((topic) => topic.linkedChunkIds)).length,
+      linkedMemories: uniqueStrings(topicStates.flatMap((topic) => topic.linkedMemoryIds)).length,
+      linkedCandidates: uniqueStrings(topicStates.flatMap((topic) => topic.linkedCandidateIds)).length,
+    }),
+    hotnessByTopic: Object.freeze(hotnessByTopic),
+    staleTopics: Object.freeze(staleTopics),
+    topics: Object.freeze(topicStates),
+    counters: Object.freeze({ ...registry.counters }),
+    diagnostics: Object.freeze(diagnostics),
+  });
+}