@jacfrost/autopm 0.0.1

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

@@ -0,0 +1,898 @@
+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_SOURCE_SUMMARY_TREE_VERSION = 1;
+export const AUTOPM_MEMORY_SOURCE_SUMMARY_REGISTRY_KEY = 'summary.source.registry.v1';
+export const AUTOPM_WIKI_SOURCE_SUMMARIES_DIRNAME = 'summaries/sources';
+
+export const AUTOPM_MEMORY_SOURCE_SUMMARY_DEFAULT_SEAL_THRESHOLD = 4;
+export const AUTOPM_MEMORY_SOURCE_SUMMARY_DEFAULT_STALE_AFTER_MS = 24 * 60 * 60 * 1000;
+export const AUTOPM_MEMORY_SOURCE_SUMMARY_DEFAULT_TEXT_CHARS = 360;
+
+function nowIso() {
+  return new Date().toISOString();
+}
+
+function diagnostic({ severity = 'info', code, message, path = '$', details = {} }) {
+  return memoryDiagnostic({ severity, code, message, path, details });
+}
+
+function uniqueStrings(values) {
+  return [...new Set((Array.isArray(values) ? values : [])
+    .map((value) => String(value ?? '').trim())
+    .filter((value) => value.length > 0))];
+}
+
+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 isPlainObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function cloneJson(value, fallback) {
+  if (value === undefined || value === null) return fallback;
+  try {
+    return JSON.parse(JSON.stringify(value));
+  } catch {
+    return fallback;
+  }
+}
+
+function normalizeRegistry(value, generatedAt = nowIso()) {
+  if (isPlainObject(value) && value.schemaVersion === AUTOPM_MEMORY_SOURCE_SUMMARY_TREE_VERSION) {
+    return {
+      schemaVersion: AUTOPM_MEMORY_SOURCE_SUMMARY_TREE_VERSION,
+      updatedAt: typeof value.updatedAt === 'string' ? value.updatedAt : generatedAt,
+      sources: isPlainObject(value.sources) ? cloneJson(value.sources, {}) : {},
+      counters: {
+        chunkAppends: Number(value.counters?.chunkAppends ?? 0),
+        duplicateAppends: Number(value.counters?.duplicateAppends ?? 0),
+        seals: Number(value.counters?.seals ?? 0),
+        duplicateSeals: Number(value.counters?.duplicateSeals ?? 0),
+        staleFlushes: Number(value.counters?.staleFlushes ?? 0),
+      },
+      lastTransition: isPlainObject(value.lastTransition) ? cloneJson(value.lastTransition, null) : null,
+    };
+  }
+
+  return {
+    schemaVersion: AUTOPM_MEMORY_SOURCE_SUMMARY_TREE_VERSION,
+    updatedAt: generatedAt,
+    sources: {},
+    counters: {
+      chunkAppends: 0,
+      duplicateAppends: 0,
+      seals: 0,
+      duplicateSeals: 0,
+      staleFlushes: 0,
+    },
+    lastTransition: null,
+  };
+}
+
+function blankSourceState(sourceId) {
+  return {
+    sourceId,
+    l0Buffer: {
+      chunkIds: [],
+      firstAppendedAt: null,
+      lastAppendedAt: null,
+    },
+    sealed: [],
+    counters: {
+      chunksAppended: 0,
+      duplicateAppends: 0,
+      seals: 0,
+      duplicateSeals: 0,
+      staleFlushes: 0,
+    },
+  };
+}
+
+function normalizeSourceState(value, sourceId) {
+  const base = blankSourceState(sourceId);
+  if (!isPlainObject(value)) return base;
+  return {
+    sourceId,
+    l0Buffer: {
+      chunkIds: uniqueStrings(value.l0Buffer?.chunkIds),
+      firstAppendedAt: typeof value.l0Buffer?.firstAppendedAt === 'string' ? value.l0Buffer.firstAppendedAt : null,
+      lastAppendedAt: typeof value.l0Buffer?.lastAppendedAt === 'string' ? value.l0Buffer.lastAppendedAt : null,
+    },
+    sealed: Array.isArray(value.sealed) ? value.sealed.filter(isPlainObject) : [],
+    counters: {
+      chunksAppended: Number(value.counters?.chunksAppended ?? 0),
+      duplicateAppends: Number(value.counters?.duplicateAppends ?? 0),
+      seals: Number(value.counters?.seals ?? 0),
+      duplicateSeals: Number(value.counters?.duplicateSeals ?? 0),
+      staleFlushes: Number(value.counters?.staleFlushes ?? 0),
+    },
+  };
+}
+
+function sourceState(registry, sourceId) {
+  const state = normalizeSourceState(registry.sources[sourceId], sourceId);
+  registry.sources[sourceId] = state;
+  return state;
+}
+
+function assertStore(store) {
+  if (!store || typeof store.getEnvelope !== '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 source summary trees.'), {
+      name: 'AutoPmSourceSummaryTreeError',
+      code: 'AUTOPM_MEMORY_SOURCE_SUMMARY_STORE_REQUIRED',
+    });
+  }
+}
+
+function readRegistry(store, generatedAt = nowIso()) {
+  assertStore(store);
+  return normalizeRegistry(store.getStatusMetadata(AUTOPM_MEMORY_SOURCE_SUMMARY_REGISTRY_KEY, null), generatedAt);
+}
+
+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_SOURCE_SUMMARY_REGISTRY_KEY, nextRegistry, generatedAt);
+  return true;
+}
+
+function projectionSlugForSource(source) {
+  const basis = `${source?.uri ?? source?.sourceId ?? 'source'}-${source?.sourceId ?? 'unknown'}`;
+  const slug = basis
+    .replace(/^\.+\//, '')
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, 72);
+  return slug.length > 0 ? slug : 'source';
+}
+
+function identifierPart(value, fallback = 'item', maxLength = 32) {
+  const slug = String(value ?? fallback)
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, maxLength);
+  return slug.length > 0 ? slug : fallback;
+}
+
+function summaryIdFor({ sourceId, chunkIds }) {
+  const first = chunkIds[0] ?? 'start';
+  const last = chunkIds.at(-1) ?? first;
+  const checksum = stableHash(`${sourceId}\0${chunkIds.join('\0')}`, 8);
+  return [
+    'summary',
+    'source',
+    identifierPart(sourceId, 'source', 28),
+    identifierPart(first, 'first', 20),
+    identifierPart(last, 'last', 20),
+    String(chunkIds.length),
+    checksum,
+  ].join('-').slice(0, 128);
+}
+
+function summaryProjectionChildPath({ source, summaryId }) {
+  return `${AUTOPM_WIKI_SOURCE_SUMMARIES_DIRNAME}/${projectionSlugForSource(source)}-${summaryId}.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 lineForChunk(chunk, index, textChars) {
+  const label = chunk.metadata?.heading ?? chunk.metadata?.sourceTitle ?? `Chunk ${chunk.ordinal ?? index}`;
+  return `- ${label}: ${trimForSummary(chunk.text, textChars)}`;
+}
+
+function buildSummaryText({ source, chunks, textChars }) {
+  const sourceLabel = source?.title ?? source?.uri ?? source?.sourceId ?? 'source';
+  const lines = chunks.map((chunk, index) => lineForChunk(chunk, index, textChars));
+  return [
+    `Source summary for ${sourceLabel}.`,
+    '',
+    ...lines,
+  ].join('\n').trim();
+}
+
+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 buildSourceSummaryProjectionMarkdown({ source, summary }) {
+  const sealedChunkIds = uniqueStrings(summary.metadata?.summaryTree?.sealedChunkIds);
+  const sourceContentHashes = uniqueStrings(summary.metadata?.summaryTree?.sealedContentHashes);
+  return [
+    '---',
+    'autopm: true',
+    'record_type: summary',
+    `summary_id: ${yamlString(summary.summaryId)}`,
+    'scope: source',
+    `source_id: ${yamlString(source.sourceId)}`,
+    `source_uri: ${yamlString(source.uri)}`,
+    `source_title: ${yamlString(source.title)}`,
+    `generated_at: ${yamlString(summary.generatedAt)}`,
+    `freshness: ${yamlString(summary.metadata?.freshness?.status ?? 'fresh')}`,
+    `stale_at: ${yamlString(summary.metadata?.freshness?.staleAt ?? '')}`,
+    'sealed_chunk_ids:',
+    yamlList(sealedChunkIds, '  '),
+    'sealed_content_hashes:',
+    yamlList(sourceContentHashes, '  '),
+    '---',
+    '',
+    `# Source summary: ${source.title}`,
+    '',
+    '<!-- AutoPM generated source summary projection. Edit the original source or add manual notes under .autopm/wiki/notes/. -->',
+    '',
+    summary.text.trim(),
+    '',
+    '## Provenance',
+    '',
+    `- Source ID: \`${source.sourceId}\``,
+    `- Source URI: \`${source.uri}\``,
+    `- Source note: [[sources/${source.sourceId}]]`,
+    `- Summary ID: \`${summary.summaryId}\``,
+    '- Sealed chunks:',
+    ...sealedChunkIds.map((chunkId) => `  - \`${chunkId}\` ([[chunks/${chunkId}]])`),
+    '',
+    '## Diagnostics',
+    '',
+    `- Tree version: ${AUTOPM_MEMORY_SOURCE_SUMMARY_TREE_VERSION}`,
+    `- Node count: ${Number(summary.metadata?.summaryTree?.nodeCounts?.l0Chunks ?? sealedChunkIds.length)} L0 chunk(s), 1 L1 summary`,
+    `- Seal reason: \`${summary.metadata?.summaryTree?.sealReason ?? 'manual'}\``,
+    `- Projection path: \`${summary.metadata?.projectionPath ?? ''}\``,
+    '',
+  ].join('\n');
+}
+
+function writeIdempotentSourceSummaryProjection({ projectRoot, childRelativePath, markdown }) {
+  const resolved = resolveWikiPath(projectRoot, childRelativePath);
+  const prepared = prepareAutoPmMarkdownProjection(markdown, { path: '$.sourceSummaryProjection' });
+  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: '$.sourceSummaryProjection',
+  });
+  return Object.freeze({ ...written, written: true, skipped: false });
+}
+
+function loadSourceAndChunks({ store, sourceId, chunkIds, pathPrefix = '$' }) {
+  const diagnostics = [];
+  const source = store.getEnvelope('source', sourceId);
+  if (!source) {
+    diagnostics.push(diagnostic({
+      severity: 'error',
+      code: 'AUTOPM_MEMORY_SOURCE_SUMMARY_SOURCE_MISSING',
+      message: 'Source summary tree could not find the requested source envelope.',
+      path: `${pathPrefix}.sourceId`,
+      details: { sourceId },
+    }));
+    return { ok: false, source: null, chunks: [], diagnostics };
+  }
+
+  const chunks = [];
+  for (const [index, chunkId] of chunkIds.entries()) {
+    const chunk = store.getEnvelope('chunk', chunkId);
+    if (!chunk) {
+      diagnostics.push(diagnostic({
+        severity: 'error',
+        code: 'AUTOPM_MEMORY_SOURCE_SUMMARY_CHUNK_MISSING',
+        message: 'Source summary tree could not find a buffered chunk envelope.',
+        path: `${pathPrefix}.chunkIds[${index}]`,
+        details: { sourceId, chunkId },
+      }));
+      continue;
+    }
+    if (chunk.sourceId !== sourceId) {
+      diagnostics.push(diagnostic({
+        severity: 'error',
+        code: 'AUTOPM_MEMORY_SOURCE_SUMMARY_CHUNK_SOURCE_MISMATCH',
+        message: 'Buffered chunk belongs to a different source than the source summary tree.',
+        path: `${pathPrefix}.chunkIds[${index}]`,
+        details: { expectedSourceId: sourceId, actualSourceId: chunk.sourceId, chunkId },
+      }));
+      continue;
+    }
+    chunks.push(chunk);
+  }
+
+  return { ok: diagnostics.every((item) => item.severity !== 'error'), source, chunks, diagnostics };
+}
+
+function failureResult({ generatedAt, code, message, details = {}, path = '$', diagnostics = [] }) {
+  const error = diagnostic({ severity: 'error', code, message, path, details });
+  return Object.freeze({
+    ok: false,
+    status: 'error',
+    generatedAt,
+    summaryId: null,
+    sourceId: details.sourceId ?? null,
+    sourceStatus: 'error',
+    bufferCount: 0,
+    sealedChunkIds: Object.freeze([]),
+    projection: null,
+    artifactPathsWritten: Object.freeze([]),
+    diagnostics: Object.freeze([error, ...diagnostics]),
+    warnings: Object.freeze([]),
+    errors: Object.freeze([error, ...diagnostics.filter((item) => item.severity === 'error')]),
+    warningCodes: Object.freeze([]),
+    errorCodes: Object.freeze(uniqueStrings([code, ...diagnostics.filter((item) => item.severity === 'error').map((item) => item.code)])),
+    durableStateChanged: false,
+  });
+}
+
+function sealEntryFor({ summary, projection, reason }) {
+  return {
+    summaryId: summary.summaryId,
+    level: 'L1',
+    scope: 'source',
+    sourceId: summary.metadata.summaryTree.sourceId,
+    chunkIds: [...summary.sourceChunkIds],
+    contentHashes: [...summary.metadata.summaryTree.sealedContentHashes],
+    sealedAt: summary.metadata.summaryTree.sealedAt,
+    reason,
+    projectionPath: projection.relativePath,
+  };
+}
+
+function addOrReplaceSealEntry(state, entry) {
+  const withoutExisting = state.sealed.filter((item) => item.summaryId !== entry.summaryId);
+  state.sealed = [...withoutExisting, entry];
+}
+
+function buildSummaryEnvelope({ source, chunks, generatedAt, staleAfterMs, reason, projectionPath, textChars }) {
+  const chunkIds = chunks.map((chunk) => chunk.chunkId);
+  const sourceContentHashes = uniqueStrings(chunks.map((chunk) => chunk.contentHash));
+  const summaryId = summaryIdFor({ sourceId: source.sourceId, chunkIds });
+  const staleAt = addMs(generatedAt, staleAfterMs);
+  const topics = uniqueStrings(chunks.flatMap((chunk) => [
+    ...(Array.isArray(chunk.metadata?.topics) ? chunk.metadata.topics : []),
+    ...(Array.isArray(chunk.metadata?.topicTags) ? chunk.metadata.topicTags : []),
+  ])).sort();
+
+  const envelope = {
+    schemaVersion: AUTOPM_MEMORY_SCHEMA_VERSION,
+    recordType: 'summary',
+    summaryId,
+    scope: 'source',
+    text: buildSummaryText({ source, chunks, textChars }),
+    generatedAt,
+    sourceMemoryIds: [],
+    sourceChunkIds: chunkIds,
+    metadata: {
+      summaryTree: {
+        schemaVersion: AUTOPM_MEMORY_SOURCE_SUMMARY_TREE_VERSION,
+        treeKind: 'source',
+        level: 'L1',
+        sourceId: source.sourceId,
+        sourceTitle: source.title,
+        sourceUri: source.uri,
+        sourceStatus: source.status,
+        sealedAt: generatedAt,
+        sealReason: reason,
+        sealedChunkIds: chunkIds,
+        sealedInputRefs: chunkIds.map((chunkId) => ({ recordType: 'chunk', chunkId })),
+        sealedContentHashes: sourceContentHashes,
+        nodeCounts: {
+          l0Chunks: chunkIds.length,
+          l1Summaries: 1,
+        },
+      },
+      freshness: {
+        status: 'fresh',
+        generatedAt,
+        staleAfterMs,
+        staleAt,
+      },
+      topics,
+      projectionPath,
+      observability: {
+        sealedChunkCount: chunkIds.length,
+        sealedInputReferenceCount: chunkIds.length,
+        sourceSummaryTreeVersion: AUTOPM_MEMORY_SOURCE_SUMMARY_TREE_VERSION,
+      },
+    },
+    diagnostics: [diagnostic({
+      severity: 'info',
+      code: 'AUTOPM_MEMORY_SOURCE_SUMMARY_SEALED',
+      message: 'Source summary tree sealed buffered chunks into a source summary record.',
+      details: {
+        sourceId: source.sourceId,
+        summaryId,
+        chunkCount: chunkIds.length,
+        reason,
+        projectionPath,
+      },
+    })],
+  };
+
+  const validation = validateSummaryEnvelope(envelope);
+  if (!validation.ok) {
+    const error = Object.assign(new Error('Source summary envelope failed validation.'), {
+      name: 'AutoPmSourceSummaryTreeError',
+      code: 'AUTOPM_MEMORY_SOURCE_SUMMARY_SCHEMA_INVALID',
+      details: { errors: validation.errors },
+    });
+    throw error;
+  }
+
+  return envelope;
+}
+
+export function autoPmSourceSummaryProjectionPath({ source, summaryId } = {}) {
+  return summaryProjectionChildPath({ source, summaryId });
+}
+
+export function buildAutoPmSourceSummaryProjectionMarkdown({ source, summary } = {}) {
+  return buildSourceSummaryProjectionMarkdown({ source, summary });
+}
+
+export function readAutoPmSourceSummaryTreeRegistry(store, generatedAt = nowIso()) {
+  return Object.freeze(readRegistry(store, generatedAt));
+}
+
+export function appendAutoPmSourceSummaryBuffer({
+  store,
+  sourceId,
+  chunkIds,
+  projectRoot = process.cwd(),
+  generatedAt = nowIso(),
+  sealThreshold = AUTOPM_MEMORY_SOURCE_SUMMARY_DEFAULT_SEAL_THRESHOLD,
+  staleAfterMs = AUTOPM_MEMORY_SOURCE_SUMMARY_DEFAULT_STALE_AFTER_MS,
+  textChars = AUTOPM_MEMORY_SOURCE_SUMMARY_DEFAULT_TEXT_CHARS,
+} = {}) {
+  assertStore(store);
+  const normalizedSourceId = String(sourceId ?? '').trim();
+  const normalizedChunkIds = uniqueStrings(chunkIds);
+  if (normalizedSourceId.length === 0 || normalizedChunkIds.length === 0) {
+    return failureResult({
+      generatedAt,
+      code: 'AUTOPM_MEMORY_SOURCE_SUMMARY_APPEND_INVALID',
+      message: 'Appending to a source summary buffer requires a sourceId and at least one chunkId.',
+      details: { sourceId: normalizedSourceId, chunkIds: normalizedChunkIds },
+    });
+  }
+
+  const loaded = loadSourceAndChunks({ store, sourceId: normalizedSourceId, chunkIds: normalizedChunkIds, pathPrefix: '$.append' });
+  if (!loaded.ok) {
+    return failureResult({
+      generatedAt,
+      code: 'AUTOPM_MEMORY_SOURCE_SUMMARY_APPEND_INPUT_INVALID',
+      message: 'Source summary buffer append inputs failed validation.',
+      details: { sourceId: normalizedSourceId, chunkIds: normalizedChunkIds },
+      diagnostics: loaded.diagnostics,
+    });
+  }
+
+  const previousRegistry = readRegistry(store, generatedAt);
+  const registry = normalizeRegistry(previousRegistry, generatedAt);
+  const state = sourceState(registry, normalizedSourceId);
+  const sealedChunkIds = new Set(state.sealed.flatMap((entry) => Array.isArray(entry.chunkIds) ? entry.chunkIds : []));
+  const buffered = new Set(state.l0Buffer.chunkIds);
+  const appended = [];
+  const duplicates = [];
+
+  for (const chunkId of normalizedChunkIds) {
+    if (buffered.has(chunkId) || sealedChunkIds.has(chunkId)) {
+      duplicates.push(chunkId);
+      continue;
+    }
+    appended.push(chunkId);
+    buffered.add(chunkId);
+  }
+
+  if (appended.length > 0) {
+    state.l0Buffer.chunkIds = [...state.l0Buffer.chunkIds, ...appended];
+    state.l0Buffer.firstAppendedAt = state.l0Buffer.firstAppendedAt ?? generatedAt;
+    state.l0Buffer.lastAppendedAt = generatedAt;
+    state.counters.chunksAppended += appended.length;
+    registry.counters.chunkAppends += appended.length;
+  }
+  if (duplicates.length > 0) {
+    state.counters.duplicateAppends += duplicates.length;
+    registry.counters.duplicateAppends += duplicates.length;
+  }
+
+  registry.lastTransition = {
+    event: appended.length > 0 ? 'buffer_appended' : 'buffer_duplicate',
+    sourceId: normalizedSourceId,
+    chunkIds: normalizedChunkIds,
+    appendedChunkIds: appended,
+    duplicateChunkIds: duplicates,
+    at: generatedAt,
+  };
+  const registryChanged = writeRegistryIfChanged(store, registry, previousRegistry, generatedAt);
+
+  const threshold = clampPositiveInteger(sealThreshold, AUTOPM_MEMORY_SOURCE_SUMMARY_DEFAULT_SEAL_THRESHOLD);
+  let seal = null;
+  if (state.l0Buffer.chunkIds.length >= threshold) {
+    seal = sealAutoPmSourceSummaryBuffer({
+      store,
+      projectRoot,
+      sourceId: normalizedSourceId,
+      generatedAt,
+      reason: 'threshold',
+      staleAfterMs,
+      textChars,
+      minChunkCount: threshold,
+    });
+  }
+
+  const diagnostics = [diagnostic({
+    severity: 'info',
+    code: appended.length > 0 ? 'AUTOPM_MEMORY_SOURCE_SUMMARY_BUFFER_APPENDED' : 'AUTOPM_MEMORY_SOURCE_SUMMARY_BUFFER_DUPLICATE',
+    message: appended.length > 0
+      ? 'Source summary tree appended admitted chunks to the L0 buffer.'
+      : 'Source summary tree skipped chunks that were already buffered or sealed.',
+    details: {
+      sourceId: normalizedSourceId,
+      appendedChunkIds: appended,
+      duplicateChunkIds: duplicates,
+      bufferCount: state.l0Buffer.chunkIds.length,
+      threshold,
+      sealed: seal?.ok === true && seal.status === 'sealed',
+    },
+  })];
+
+  return Object.freeze({
+    ok: true,
+    status: seal?.ok === true && seal.status === 'sealed' ? 'sealed' : (appended.length > 0 ? 'buffered' : 'duplicate'),
+    generatedAt,
+    sourceId: normalizedSourceId,
+    appendedChunkIds: Object.freeze(appended),
+    duplicateChunkIds: Object.freeze(duplicates),
+    bufferCount: seal?.ok === true && seal.status === 'sealed' ? 0 : state.l0Buffer.chunkIds.length,
+    threshold,
+    seal,
+    artifactPathsWritten: Object.freeze(seal?.artifactPathsWritten ?? []),
+    diagnostics: Object.freeze([...diagnostics, ...(seal?.diagnostics ?? [])]),
+    warnings: Object.freeze([...(seal?.warnings ?? [])]),
+    errors: Object.freeze([]),
+    warningCodes: Object.freeze(uniqueStrings([...(seal?.warningCodes ?? [])])),
+    errorCodes: Object.freeze([]),
+    durableStateChanged: registryChanged || seal?.durableStateChanged === true,
+  });
+}
+
+export function sealAutoPmSourceSummaryBuffer({
+  store,
+  sourceId,
+  projectRoot = process.cwd(),
+  generatedAt = nowIso(),
+  reason = 'manual',
+  staleAfterMs = AUTOPM_MEMORY_SOURCE_SUMMARY_DEFAULT_STALE_AFTER_MS,
+  textChars = AUTOPM_MEMORY_SOURCE_SUMMARY_DEFAULT_TEXT_CHARS,
+  minChunkCount = 1,
+} = {}) {
+  assertStore(store);
+  const normalizedSourceId = String(sourceId ?? '').trim();
+  if (normalizedSourceId.length === 0) {
+    return failureResult({
+      generatedAt,
+      code: 'AUTOPM_MEMORY_SOURCE_SUMMARY_SEAL_INVALID',
+      message: 'Sealing a source summary buffer requires a sourceId.',
+      details: { sourceId: normalizedSourceId },
+    });
+  }
+
+  const previousRegistry = readRegistry(store, generatedAt);
+  const registry = normalizeRegistry(previousRegistry, generatedAt);
+  const state = sourceState(registry, normalizedSourceId);
+  const chunkIds = uniqueStrings(state.l0Buffer.chunkIds);
+  const minimum = clampPositiveInteger(minChunkCount, 1);
+
+  if (chunkIds.length === 0 || chunkIds.length < minimum) {
+    return Object.freeze({
+      ok: true,
+      status: 'empty',
+      generatedAt,
+      sourceId: normalizedSourceId,
+      summaryId: null,
+      sealedChunkIds: Object.freeze([]),
+      projection: null,
+      artifactPathsWritten: Object.freeze([]),
+      diagnostics: Object.freeze([diagnostic({
+        severity: 'info',
+        code: 'AUTOPM_MEMORY_SOURCE_SUMMARY_BUFFER_NOT_READY',
+        message: 'Source summary buffer was not sealed because it has too few chunks.',
+        details: { sourceId: normalizedSourceId, bufferCount: chunkIds.length, minChunkCount: minimum },
+      })]),
+      warnings: Object.freeze([]),
+      errors: Object.freeze([]),
+      warningCodes: Object.freeze([]),
+      errorCodes: Object.freeze([]),
+      durableStateChanged: false,
+    });
+  }
+
+  const loaded = loadSourceAndChunks({ store, sourceId: normalizedSourceId, chunkIds, pathPrefix: '$.seal' });
+  if (!loaded.ok) {
+    return failureResult({
+      generatedAt,
+      code: 'AUTOPM_MEMORY_SOURCE_SUMMARY_SEAL_INPUT_INVALID',
+      message: 'Source summary buffer could not be sealed because buffered inputs are missing or invalid.',
+      details: { sourceId: normalizedSourceId, chunkIds },
+      diagnostics: loaded.diagnostics,
+    });
+  }
+
+  const summaryId = summaryIdFor({ sourceId: normalizedSourceId, chunkIds });
+  const projectionPath = summaryProjectionChildPath({ source: loaded.source, summaryId });
+  const summary = buildSummaryEnvelope({
+    source: loaded.source,
+    chunks: loaded.chunks,
+    generatedAt,
+    staleAfterMs: clampPositiveInteger(staleAfterMs, AUTOPM_MEMORY_SOURCE_SUMMARY_DEFAULT_STALE_AFTER_MS),
+    reason,
+    projectionPath: `.autopm/wiki/${projectionPath}`,
+    textChars: clampPositiveInteger(textChars, AUTOPM_MEMORY_SOURCE_SUMMARY_DEFAULT_TEXT_CHARS),
+  });
+  const existing = store.getEnvelope('summary', summary.summaryId);
+  const duplicate = existing
+    && existing.scope === summary.scope
+    && JSON.stringify(existing.sourceChunkIds) === JSON.stringify(summary.sourceChunkIds)
+    && existing.metadata?.summaryTree?.sourceId === summary.metadata.summaryTree.sourceId;
+
+  let summaryWritten = false;
+  if (!duplicate) {
+    store.writeEnvelope(summary);
+    summaryWritten = true;
+  }
+
+  const projection = writeIdempotentSourceSummaryProjection({
+    projectRoot,
+    childRelativePath: projectionPath,
+    markdown: buildSourceSummaryProjectionMarkdown({ source: loaded.source, summary }),
+  });
+
+  state.l0Buffer = {
+    chunkIds: [],
+    firstAppendedAt: null,
+    lastAppendedAt: null,
+  };
+  addOrReplaceSealEntry(state, sealEntryFor({ summary, projection, reason }));
+  if (duplicate) {
+    state.counters.duplicateSeals += 1;
+    registry.counters.duplicateSeals += 1;
+  } else {
+    state.counters.seals += 1;
+    registry.counters.seals += 1;
+  }
+  if (reason === 'stale') {
+    state.counters.staleFlushes += 1;
+    registry.counters.staleFlushes += 1;
+  }
+  registry.lastTransition = {
+    event: duplicate ? 'seal_duplicate' : 'sealed',
+    sourceId: normalizedSourceId,
+    summaryId: summary.summaryId,
+    chunkIds,
+    reason,
+    projectionPath: projection.relativePath,
+    at: generatedAt,
+  };
+  const registryChanged = writeRegistryIfChanged(store, registry, previousRegistry, generatedAt);
+
+  const diagnostics = [
+    ...summary.diagnostics,
+    ...projection.redactionDiagnostics,
+    diagnostic({
+      severity: 'info',
+      code: duplicate ? 'AUTOPM_MEMORY_SOURCE_SUMMARY_SEAL_DUPLICATE' : 'AUTOPM_MEMORY_SOURCE_SUMMARY_TREE_UPDATED',
+      message: duplicate
+        ? 'Source summary seal found an existing summary for the buffered chunk set.'
+        : 'Source summary tree persisted a sealed summary node and projection.',
+      details: {
+        sourceId: normalizedSourceId,
+        summaryId: summary.summaryId,
+        chunkCount: chunkIds.length,
+        reason,
+        projectionPath: projection.relativePath,
+        summaryWritten,
+        projectionWritten: projection.written === true,
+      },
+    }),
+  ];
+  const warningCodes = uniqueStrings(diagnostics.filter((item) => item.severity === 'warning').map((item) => item.code));
+  const artifactPathsWritten = projection.durableStateChanged ? [projection.relativePath] : [];
+
+  return Object.freeze({
+    ok: true,
+    status: duplicate ? 'duplicate' : 'sealed',
+    generatedAt,
+    sourceId: normalizedSourceId,
+    summaryId: summary.summaryId,
+    summary,
+    summaryWritten,
+    duplicate: duplicate === true,
+    sealedChunkIds: Object.freeze(chunkIds),
+    projection,
+    artifactPathsWritten: Object.freeze(artifactPathsWritten),
+    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 || registryChanged,
+  });
+}
+
+export function flushStaleAutoPmSourceSummaryBuffers({
+  store,
+  projectRoot = process.cwd(),
+  generatedAt = nowIso(),
+  staleAfterMs = AUTOPM_MEMORY_SOURCE_SUMMARY_DEFAULT_STALE_AFTER_MS,
+  textChars = AUTOPM_MEMORY_SOURCE_SUMMARY_DEFAULT_TEXT_CHARS,
+} = {}) {
+  assertStore(store);
+  const registry = readRegistry(store, generatedAt);
+  const staleMs = clampPositiveInteger(staleAfterMs, AUTOPM_MEMORY_SOURCE_SUMMARY_DEFAULT_STALE_AFTER_MS);
+  const staleSources = [];
+
+  for (const [sourceId, rawState] of Object.entries(registry.sources)) {
+    const state = normalizeSourceState(rawState, sourceId);
+    if (state.l0Buffer.chunkIds.length === 0 || !state.l0Buffer.lastAppendedAt) continue;
+    const ageMs = timestampMs(generatedAt) - timestampMs(state.l0Buffer.lastAppendedAt);
+    if (ageMs >= staleMs) {
+      staleSources.push({ sourceId, ageMs, chunkCount: state.l0Buffer.chunkIds.length, lastAppendedAt: state.l0Buffer.lastAppendedAt });
+    }
+  }
+
+  const sourceResults = staleSources.map((entry) => sealAutoPmSourceSummaryBuffer({
+    store,
+    projectRoot,
+    sourceId: entry.sourceId,
+    generatedAt,
+    reason: 'stale',
+    staleAfterMs: staleMs,
+    textChars,
+    minChunkCount: 1,
+  }));
+
+  const diagnostics = [diagnostic({
+    severity: staleSources.length > 0 ? 'warning' : 'info',
+    code: staleSources.length > 0 ? 'AUTOPM_MEMORY_SOURCE_SUMMARY_STALE_FLUSH' : 'AUTOPM_MEMORY_SOURCE_SUMMARY_NO_STALE_BUFFERS',
+    message: staleSources.length > 0
+      ? 'Source summary tree flushed stale L0 buffers into sealed source summaries.'
+      : 'Source summary tree found no stale L0 buffers to flush.',
+    details: {
+      staleAfterMs: staleMs,
+      staleSourceCount: staleSources.length,
+      staleSources,
+    },
+  })];
+  diagnostics.push(...sourceResults.flatMap((result) => result.diagnostics ?? []));
+  const warningCodes = uniqueStrings(diagnostics.filter((item) => item.severity === 'warning').map((item) => item.code));
+  const errorCodes = uniqueStrings(sourceResults.flatMap((result) => result.errorCodes ?? []));
+
+  return Object.freeze({
+    ok: sourceResults.every((result) => result.ok === true),
+    status: errorCodes.length > 0 ? 'error' : (staleSources.length > 0 ? 'flushed' : 'idle'),
+    generatedAt,
+    staleAfterMs: staleMs,
+    staleSources: Object.freeze(staleSources),
+    sourceResults: Object.freeze(sourceResults),
+    sealedSummaryIds: Object.freeze(uniqueStrings(sourceResults.map((result) => result.summaryId).filter(Boolean))),
+    artifactPathsWritten: Object.freeze(uniqueStrings(sourceResults.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: sourceResults.some((result) => result.durableStateChanged === true),
+  });
+}
+
+export function getAutoPmSourceSummaryTreeDiagnostics({ store, generatedAt = nowIso(), staleAfterMs = AUTOPM_MEMORY_SOURCE_SUMMARY_DEFAULT_STALE_AFTER_MS } = {}) {
+  assertStore(store);
+  const registry = readRegistry(store, generatedAt);
+  const staleMs = clampPositiveInteger(staleAfterMs, AUTOPM_MEMORY_SOURCE_SUMMARY_DEFAULT_STALE_AFTER_MS);
+  const sources = Object.entries(registry.sources).map(([sourceId, rawState]) => {
+    const state = normalizeSourceState(rawState, sourceId);
+    const lastAppendedAt = state.l0Buffer.lastAppendedAt;
+    const ageMs = lastAppendedAt ? Math.max(0, timestampMs(generatedAt) - timestampMs(lastAppendedAt)) : 0;
+    const stale = state.l0Buffer.chunkIds.length > 0 && ageMs >= staleMs;
+    return {
+      sourceId,
+      l0ChunkCount: state.l0Buffer.chunkIds.length,
+      l1SummaryCount: state.sealed.length,
+      lastAppendedAt,
+      stale,
+      ageMs,
+      projectionPaths: uniqueStrings(state.sealed.map((entry) => entry.projectionPath)),
+      sealedChunkIds: uniqueStrings(state.sealed.flatMap((entry) => Array.isArray(entry.chunkIds) ? entry.chunkIds : [])),
+    };
+  });
+  const staleSources = sources.filter((source) => source.stale);
+  return Object.freeze({
+    ok: true,
+    status: staleSources.length > 0 ? 'warn' : 'ok',
+    generatedAt,
+    staleAfterMs: staleMs,
+    sourceCount: sources.length,
+    treeNodeCounts: Object.freeze({
+      l0Buffers: sources.filter((source) => source.l0ChunkCount > 0).length,
+      l0Chunks: sources.reduce((sum, source) => sum + source.l0ChunkCount, 0),
+      l1Summaries: sources.reduce((sum, source) => sum + source.l1SummaryCount, 0),
+    }),
+    staleSources: Object.freeze(staleSources),
+    sources: Object.freeze(sources),
+    counters: Object.freeze({ ...registry.counters }),
+    diagnostics: Object.freeze([diagnostic({
+      severity: staleSources.length > 0 ? 'warning' : 'info',
+      code: staleSources.length > 0 ? 'AUTOPM_MEMORY_SOURCE_SUMMARY_STALE_BUFFERS' : 'AUTOPM_MEMORY_SOURCE_SUMMARY_TREE_HEALTHY',
+      message: staleSources.length > 0
+        ? 'Source summary tree has stale L0 buffers waiting to be sealed.'
+        : 'Source summary tree diagnostics found no stale source buffers.',
+      details: {
+        sourceCount: sources.length,
+        staleSourceCount: staleSources.length,
+        treeNodeCounts: {
+          l0Buffers: sources.filter((source) => source.l0ChunkCount > 0).length,
+          l0Chunks: sources.reduce((sum, source) => sum + source.l0ChunkCount, 0),
+          l1Summaries: sources.reduce((sum, source) => sum + source.l1SummaryCount, 0),
+        },
+      },
+    })]),
+  });
+}