byterover-cli 1.8.0 → 2.1.0

package/dist/server/infra/context-tree/file-context-tree-snapshot-service.d.ts

@@ -12,13 +12,11 @@ export declare class FileContextTreeSnapshotService implements IContextTreeSnaps
     constructor(config?: ContextTreeSnapshotServiceConfig);
     getChanges(directory?: string): Promise<ContextTreeChanges>;
     getCurrentState(directory?: string): Promise<Map<string, FileState>>;
+    getSnapshotState(directory?: string): Promise<Map<string, FileState>>;
     hasSnapshot(directory?: string): Promise<boolean>;
     initEmptySnapshot(directory?: string): Promise<void>;
     saveSnapshot(directory?: string): Promise<void>;
-    /**
-     * Computes SHA-256 hash of file content.
-     */
-    private computeHash;
+    saveSnapshotFromState(state: Map<string, FileState>, directory?: string): Promise<void>;
     /**
      * Loads snapshot from file.
      */

package/dist/server/infra/context-tree/file-context-tree-snapshot-service.js

@@ -1,8 +1,9 @@
-import { createHash } from 'node:crypto';
-import { readdir, readFile, stat, writeFile } from 'node:fs/promises';
-import { join, relative } from 'node:path';
-import { BRV_DIR, CONTEXT_FILE_EXTENSION, CONTEXT_TREE_DIR, README_FILE, SNAPSHOT_FILE } from '../../constants.js';
+import { mkdir, readdir, readFile, stat, writeFile } from 'node:fs/promises';
+import { dirname, join, relative } from 'node:path';
+import { ARCHIVE_DIR, BRV_DIR, CONTEXT_FILE_EXTENSION, CONTEXT_TREE_DIR, README_FILE, SNAPSHOT_FILE } from '../../constants.js';
 import { ContextTreeSnapshot, } from '../../core/domain/entities/context-tree-snapshot.js';
+import { isExcludedFromSync } from './derived-artifact.js';
+import { computeContentHash } from './hash-utils.js';
 import { toUnixPath } from './path-utils.js';
 /**
  * File-based implementation of IContextTreeSnapshotService.
@@ -37,6 +38,14 @@ export class FileContextTreeSnapshotService {
         }
         return files;
     }
+    async getSnapshotState(directory) {
+        const baseDir = directory ?? this.config.baseDirectory ?? process.cwd();
+        const contextTreeDir = join(baseDir, BRV_DIR, CONTEXT_TREE_DIR);
+        const snapshot = await this.loadSnapshot(contextTreeDir);
+        if (!snapshot)
+            return new Map();
+        return new Map(snapshot.files);
+    }
     async hasSnapshot(directory) {
         const baseDir = directory ?? this.config.baseDirectory ?? process.cwd();
         const snapshotPath = join(baseDir, BRV_DIR, CONTEXT_TREE_DIR, SNAPSHOT_FILE);
@@ -63,11 +72,13 @@ export class FileContextTreeSnapshotService {
         const snapshot = ContextTreeSnapshot.create(currentState);
         await writeFile(snapshotPath, JSON.stringify(snapshot.toJson(), null, 2), 'utf8');
     }
-    /**
-     * Computes SHA-256 hash of file content.
-     */
-    computeHash(content) {
-        return createHash('sha256').update(content).digest('hex');
+    async saveSnapshotFromState(state, directory) {
+        const baseDir = directory ?? this.config.baseDirectory ?? process.cwd();
+        const contextTreeDir = join(baseDir, BRV_DIR, CONTEXT_TREE_DIR);
+        const snapshotPath = join(contextTreeDir, SNAPSHOT_FILE);
+        await mkdir(dirname(snapshotPath), { recursive: true });
+        const snapshot = ContextTreeSnapshot.create(state);
+        await writeFile(snapshotPath, JSON.stringify(snapshot.toJson(), null, 2), 'utf8');
     }
     /**
      * Loads snapshot from file.
@@ -90,7 +101,7 @@ export class FileContextTreeSnapshotService {
         const relativePath = toUnixPath(relative(rootDir, fullPath));
         const [content, fileStat] = await Promise.all([readFile(fullPath), stat(fullPath)]);
         files.set(relativePath, {
-            hash: this.computeHash(content),
+            hash: computeContentHash(content),
             size: fileStat.size,
         });
     }
@@ -107,15 +118,22 @@ export class FileContextTreeSnapshotService {
                 continue;
             }
             if (entry.isDirectory()) {
+                // Skip _archived/ directory (contains derived artifacts)
+                if (entry.name === ARCHIVE_DIR)
+                    continue;
                 tasks.push(this.scanDirectory(fullPath, rootDir, files));
             }
             else if (entry.isFile() && entry.name.endsWith(CONTEXT_FILE_EXTENSION)) {
                 // Only ignore README.md at root level, track it in subdirectories
                 const isRoot = currentDir === rootDir;
                 const isReadmeAtRoot = entry.name === README_FILE && isRoot;
-                if (!isReadmeAtRoot) {
-                    tasks.push(this.processFile(fullPath, rootDir, files));
-                }
+                if (isReadmeAtRoot)
+                    continue;
+                // Skip derived artifacts (_index.md, _manifest.json, .stub.md, .full.md)
+                const relativePath = toUnixPath(relative(rootDir, fullPath));
+                if (isExcludedFromSync(relativePath))
+                    continue;
+                tasks.push(this.processFile(fullPath, rootDir, files));
             }
         }
         await Promise.all(tasks);

package/dist/server/infra/context-tree/file-context-tree-summary-service.d.ts

@@ -0,0 +1,44 @@
+/**
+ * File-based implementation of IContextTreeSummaryService.
+ *
+ * Manages hierarchical summary nodes (_index.md) in the context tree.
+ * Uses three-tier escalation (normal → aggressive → deterministic fallback)
+ * following the same pattern as PreCompactionService.
+ *
+ * Fail-open: any error returns { actionTaken: false } — never blocks curation.
+ */
+import type { ICipherAgent } from '../../../agent/core/interfaces/i-cipher-agent.js';
+import type { StalenessCheckResult, SummaryGenerationResult } from '../../core/domain/knowledge/summary-types.js';
+import type { IContextTreeSummaryService } from '../../core/interfaces/context-tree/i-context-tree-summary-service.js';
+export declare class FileContextTreeSummaryService implements IContextTreeSummaryService {
+    checkStaleness(directoryPath: string, directory?: string): Promise<StalenessCheckResult>;
+    generateSummary(directoryPath: string, agent: ICipherAgent, directory?: string): Promise<SummaryGenerationResult>;
+    hasSummary(directoryPath: string, directory?: string): Promise<boolean>;
+    propagateStaleness(changedPaths: string[], agent: ICipherAgent, directory?: string): Promise<SummaryGenerationResult[]>;
+    /**
+     * Collect inputs for a summary (the summary input set invariant):
+     * - Leaf .md files in the directory (excluding _index.md, _archived/)
+     * - Child directory _index.md files (summaries of subdirectories)
+     */
+    private collectInputs;
+    /**
+     * Determine condensation order from directory depth relative to context tree root.
+     * Root = d3, domain = d2, topic = d1, subtopic = d0
+     */
+    private depthToCondensationOrder;
+    /**
+     * Execute a single summary generation pass via the agent.
+     */
+    private executeSummaryPass;
+    /**
+     * Three-tier escalation for summary generation.
+     * Follows the same pattern as PreCompactionService.compact().
+     */
+    private generateWithEscalation;
+    /**
+     * Check if any descendant of dirPath was stopped due to LLM/IO error.
+     * Since we process bottom-up (deepest first), a stopped child means
+     * its parent should also stop to prevent regenerating from stale state.
+     */
+    private hasStoppedDescendant;
+}

package/dist/server/infra/context-tree/file-context-tree-summary-service.js

@@ -0,0 +1,313 @@
+/* eslint-disable camelcase */
+/**
+ * File-based implementation of IContextTreeSummaryService.
+ *
+ * Manages hierarchical summary nodes (_index.md) in the context tree.
+ * Uses three-tier escalation (normal → aggressive → deterministic fallback)
+ * following the same pattern as PreCompactionService.
+ *
+ * Fail-open: any error returns { actionTaken: false } — never blocks curation.
+ */
+import { readdir, readFile, stat, unlink, writeFile } from 'node:fs/promises';
+import { dirname, join, relative } from 'node:path';
+import { BRV_DIR, CONTEXT_FILE_EXTENSION, CONTEXT_TREE_DIR, SUMMARY_INDEX_FILE } from '../../constants.js';
+import { buildDeterministicFallbackCompaction, estimateTokens, isCompactionOutputValid, shouldAcceptCompactionOutput, } from '../executor/pre-compaction/compaction-escalation.js';
+import { computeChildrenHash } from './children-hash.js';
+import { isArchiveStub, isDerivedArtifact } from './derived-artifact.js';
+import { computeContentHash } from './hash-utils.js';
+import { toUnixPath } from './path-utils.js';
+import { buildSummarySystemPrompt, buildSummaryUserMessage } from './prompts/summary-generation.js';
+import { generateSummaryContent, parseSummaryFrontmatter } from './summary-frontmatter.js';
+const ZERO_RESULT = {
+    actionTaken: false,
+    compressionRatio: 0,
+    tokenCount: 0,
+};
+export class FileContextTreeSummaryService {
+    async checkStaleness(directoryPath, directory) {
+        const baseDir = directory ?? process.cwd();
+        const contextTreeDir = join(baseDir, BRV_DIR, CONTEXT_TREE_DIR);
+        const targetDir = join(contextTreeDir, directoryPath);
+        const indexPath = join(targetDir, SUMMARY_INDEX_FILE);
+        // Collect current children
+        const children = await this.collectInputs(targetDir, contextTreeDir);
+        const currentHash = children.length > 0
+            ? computeChildrenHash(children.map((c) => ({ contentHash: c.contentHash, path: c.path })))
+            : '';
+        // Read existing _index.md
+        let storedHash = '';
+        try {
+            const content = await readFile(indexPath, 'utf8');
+            const fm = parseSummaryFrontmatter(content);
+            storedHash = fm?.children_hash ?? '';
+        }
+        catch {
+            // No _index.md exists
+        }
+        return {
+            currentChildrenHash: currentHash,
+            isStale: storedHash !== currentHash || storedHash === '',
+            path: directoryPath,
+            storedChildrenHash: storedHash,
+        };
+    }
+    async generateSummary(directoryPath, agent, directory) {
+        const baseDir = directory ?? process.cwd();
+        const contextTreeDir = join(baseDir, BRV_DIR, CONTEXT_TREE_DIR);
+        const targetDir = join(contextTreeDir, directoryPath);
+        try {
+            // Step 1: Collect inputs (summary input set invariant)
+            const children = await this.collectInputs(targetDir, contextTreeDir);
+            if (children.length === 0) {
+                return { ...ZERO_RESULT, path: directoryPath, reason: 'empty_directory' };
+            }
+            // Step 2: Compute children hash
+            const childrenHash = computeChildrenHash(children.map((c) => ({ contentHash: c.contentHash, path: c.path })));
+            // Step 3: Determine condensation order from directory depth
+            const depth = directoryPath === '.' || directoryPath === ''
+                ? 0
+                : directoryPath.split('/').length;
+            const order = this.depthToCondensationOrder(depth);
+            const level = `d${order}`;
+            // Step 4: Total input tokens
+            const totalInputTokens = children.reduce((sum, c) => sum + c.tokens, 0);
+            // Step 5: Three-tier escalation via CipherAgent
+            const taskId = `summary_${directoryPath.replaceAll('/', '_') || 'root'}`;
+            const childEntries = children.map((c) => ({ content: c.content, name: c.name }));
+            const summaryText = await this.generateWithEscalation(agent, taskId, childEntries, level, totalInputTokens);
+            // Step 6: Write _index.md
+            const summaryTokens = estimateTokens(summaryText);
+            const frontmatter = {
+                children_hash: childrenHash,
+                compression_ratio: totalInputTokens > 0 ? summaryTokens / totalInputTokens : 0,
+                condensation_order: order,
+                covers: children.map((c) => c.name).sort(),
+                covers_token_total: totalInputTokens,
+                summary_level: level,
+                token_count: summaryTokens,
+                type: 'summary',
+            };
+            const indexPath = join(targetDir, SUMMARY_INDEX_FILE);
+            await writeFile(indexPath, generateSummaryContent(frontmatter, summaryText), 'utf8');
+            return {
+                actionTaken: true,
+                compressionRatio: frontmatter.compression_ratio,
+                path: directoryPath,
+                tier: 'normal', // TODO: track actual tier from escalation
+                tokenCount: summaryTokens,
+            };
+        }
+        catch {
+            return { ...ZERO_RESULT, path: directoryPath, reason: 'llm_error' };
+        }
+    }
+    async hasSummary(directoryPath, directory) {
+        const baseDir = directory ?? process.cwd();
+        const indexPath = join(baseDir, BRV_DIR, CONTEXT_TREE_DIR, directoryPath, SUMMARY_INDEX_FILE);
+        try {
+            await stat(indexPath);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    async propagateStaleness(changedPaths, agent, directory) {
+        if (changedPaths.length === 0)
+            return [];
+        // Collect unique parent directory paths, then walk upward to root
+        const dirsToCheck = new Set();
+        for (const changedPath of changedPaths) {
+            let dir = dirname(changedPath);
+            while (dir && dir !== '.') {
+                dirsToCheck.add(dir);
+                dir = dirname(dir);
+            }
+            // Also include root
+            dirsToCheck.add('.');
+        }
+        // Sort bottom-up (deepest first)
+        const sorted = [...dirsToCheck].sort((a, b) => {
+            const depthA = a === '.' ? 0 : a.split('/').length;
+            const depthB = b === '.' ? 0 : b.split('/').length;
+            return depthB - depthA;
+        });
+        const results = [];
+        const stoppedPaths = new Set();
+        /* eslint-disable no-await-in-loop */
+        for (const dirPath of sorted) {
+            // If a descendant of this dir was stopped due to error, skip it
+            if (this.hasStoppedDescendant(dirPath, stoppedPaths))
+                continue;
+            const staleness = await this.checkStaleness(dirPath, directory);
+            if (!staleness.isStale)
+                continue;
+            const result = await this.generateSummary(dirPath, agent, directory);
+            results.push(result);
+            if (!result.actionTaken) {
+                if (result.reason === 'empty_directory') {
+                    // Delete stale _index.md and continue climbing (parent input set changed)
+                    try {
+                        const baseDir = directory ?? process.cwd();
+                        const indexPath = join(baseDir, BRV_DIR, CONTEXT_TREE_DIR, dirPath, SUMMARY_INDEX_FILE);
+                        await unlink(indexPath);
+                    }
+                    catch {
+                        // Already gone, fine
+                    }
+                }
+                else {
+                    // LLM/IO error: stop climbing from this node
+                    stoppedPaths.add(dirPath);
+                }
+            }
+        }
+        /* eslint-enable no-await-in-loop */
+        return results;
+    }
+    /**
+     * Collect inputs for a summary (the summary input set invariant):
+     * - Leaf .md files in the directory (excluding _index.md, _archived/)
+     * - Child directory _index.md files (summaries of subdirectories)
+     */
+    async collectInputs(targetDir, contextTreeDir) {
+        const children = [];
+        let entries;
+        try {
+            entries = await readdir(targetDir, { withFileTypes: true });
+        }
+        catch {
+            return children;
+        }
+        /* eslint-disable no-await-in-loop */
+        for (const entry of entries) {
+            const entryName = entry.name;
+            const fullPath = join(targetDir, entryName);
+            const relativePath = toUnixPath(relative(contextTreeDir, fullPath));
+            if (entry.isFile() && entryName.endsWith(CONTEXT_FILE_EXTENSION)) {
+                // Skip _index.md itself and derived artifacts
+                if (entryName === SUMMARY_INDEX_FILE)
+                    continue;
+                if (isDerivedArtifact(relativePath) || isArchiveStub(relativePath))
+                    continue;
+                try {
+                    const content = await readFile(fullPath, 'utf8');
+                    children.push({
+                        content,
+                        contentHash: computeContentHash(content),
+                        name: entryName,
+                        path: relativePath,
+                        tokens: estimateTokens(content),
+                    });
+                }
+                catch {
+                    // Skip unreadable files
+                }
+            }
+            else if (entry.isDirectory() && entryName !== '_archived') {
+                // Check for child directory _index.md
+                const childIndexPath = join(fullPath, SUMMARY_INDEX_FILE);
+                try {
+                    const content = await readFile(childIndexPath, 'utf8');
+                    const childRelPath = toUnixPath(relative(contextTreeDir, childIndexPath));
+                    children.push({
+                        content,
+                        contentHash: computeContentHash(content),
+                        name: `${entryName}/${SUMMARY_INDEX_FILE}`,
+                        path: childRelPath,
+                        tokens: estimateTokens(content),
+                    });
+                }
+                catch {
+                    // No _index.md in child directory, skip
+                }
+            }
+        }
+        /* eslint-enable no-await-in-loop */
+        return children;
+    }
+    /**
+     * Determine condensation order from directory depth relative to context tree root.
+     * Root = d3, domain = d2, topic = d1, subtopic = d0
+     */
+    depthToCondensationOrder(depth) {
+        if (depth === 0)
+            return 3;
+        if (depth === 1)
+            return 2;
+        if (depth === 2)
+            return 1;
+        return 0;
+    }
+    /**
+     * Execute a single summary generation pass via the agent.
+     */
+    async executeSummaryPass(agent, sessionId, taskId, childEntries, level, aggressive) {
+        try {
+            const systemPrompt = buildSummarySystemPrompt();
+            const userMessage = buildSummaryUserMessage(childEntries, level, aggressive);
+            const prompt = `${systemPrompt}\n\n${userMessage}`;
+            const response = await agent.executeOnSession(sessionId, prompt, {
+                executionContext: {
+                    clearHistory: true,
+                    commandType: 'query',
+                    maxIterations: 1,
+                    maxTokens: 4096,
+                    temperature: 0.3,
+                },
+                taskId,
+            });
+            return response || undefined;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    /**
+     * Three-tier escalation for summary generation.
+     * Follows the same pattern as PreCompactionService.compact().
+     */
+    async generateWithEscalation(agent, taskId, childEntries, level, inputTokens) {
+        const sessionId = await agent.createTaskSession(taskId, 'query');
+        try {
+            // Pass 1: Normal
+            const normalResult = await this.executeSummaryPass(agent, sessionId, taskId, childEntries, level, false);
+            if (normalResult && shouldAcceptCompactionOutput(normalResult, inputTokens) && isCompactionOutputValid(normalResult)) {
+                return normalResult.trim();
+            }
+            // Pass 2: Aggressive
+            const aggressiveResult = await this.executeSummaryPass(agent, sessionId, taskId, childEntries, level, true);
+            if (aggressiveResult && shouldAcceptCompactionOutput(aggressiveResult, inputTokens) && isCompactionOutputValid(aggressiveResult)) {
+                return aggressiveResult.trim();
+            }
+            // Pass 3: Deterministic fallback
+            const combinedInput = childEntries.map((e) => `## ${e.name}\n${e.content}`).join('\n\n');
+            return buildDeterministicFallbackCompaction({
+                inputTokens,
+                sourceText: combinedInput,
+                suffixLabel: 'summary compaction',
+            });
+        }
+        finally {
+            await agent.deleteTaskSession(sessionId);
+        }
+    }
+    /**
+     * Check if any descendant of dirPath was stopped due to LLM/IO error.
+     * Since we process bottom-up (deepest first), a stopped child means
+     * its parent should also stop to prevent regenerating from stale state.
+     */
+    hasStoppedDescendant(dirPath, stoppedPaths) {
+        if (stoppedPaths.size === 0)
+            return false;
+        const prefix = dirPath === '.' ? '' : `${dirPath}/`;
+        for (const stopped of stoppedPaths) {
+            // dirPath is ancestor of stopped if stopped starts with dirPath/
+            // Special case: dirPath '.' is ancestor of everything
+            if (prefix === '' || stopped.startsWith(prefix)) {
+                return true;
+            }
+        }
+        return false;
+    }
+}

package/dist/server/infra/context-tree/file-context-tree-writer-service.js

@@ -2,6 +2,7 @@
 import { mkdir, readFile, unlink, writeFile } from 'node:fs/promises';
 import { dirname, join } from 'node:path';
 import { BRV_DIR, CONTEXT_TREE_DIR, README_FILE } from '../../constants.js';
+import { isExcludedFromSync } from './derived-artifact.js';
 import { toUnixPath } from './path-utils.js';
 /**
  * File-based implementation of IContextTreeWriterService.
@@ -66,6 +67,10 @@ export class FileContextTreeWriterService {
             if (normalizedPath === README_FILE) {
                 continue;
             }
+            // Skip derived artifacts (_index.md, _archived/*.stub.md, _archived/*.full.md, _manifest.json)
+            if (isExcludedFromSync(normalizedPath)) {
+                continue;
+            }
             result.set(normalizedPath, file);
         }
         return result;

package/dist/server/infra/context-tree/hash-utils.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Computes SHA-256 hash of file content.
+ * Accepts both string (decoded text) and Buffer (raw bytes) so that
+ * all callers produce identical digests for the same content.
+ */
+export declare function computeContentHash(content: Buffer | string): string;

package/dist/server/infra/context-tree/hash-utils.js

@@ -0,0 +1,9 @@
+import { createHash } from 'node:crypto';
+/**
+ * Computes SHA-256 hash of file content.
+ * Accepts both string (decoded text) and Buffer (raw bytes) so that
+ * all callers produce identical digests for the same content.
+ */
+export function computeContentHash(content) {
+    return createHash('sha256').update(content).digest('hex');
+}

package/dist/server/infra/context-tree/prompts/summary-generation.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Prompts for hierarchical summary generation (_index.md).
+ *
+ * Follows the same pattern as pre-compaction prompts: clear system prompt
+ * with isCompactionOutputValid() as the actual guardrail.
+ */
+import type { SummaryLevel } from '../../../core/domain/knowledge/summary-types.js';
+/**
+ * Build the system prompt for summary generation.
+ */
+export declare function buildSummarySystemPrompt(): string;
+/**
+ * Build the user message for a summary generation pass.
+ *
+ * @param childEntries - Array of { name, content } for each child input
+ * @param level - The summary level being generated (d1, d2, d3)
+ * @param aggressive - Whether this is the aggressive (pass 2) attempt
+ */
+export declare function buildSummaryUserMessage(childEntries: Array<{
+    content: string;
+    name: string;
+}>, level: SummaryLevel, aggressive: boolean): string;

package/dist/server/infra/context-tree/prompts/summary-generation.js

@@ -0,0 +1,45 @@
+/**
+ * Prompts for hierarchical summary generation (_index.md).
+ *
+ * Follows the same pattern as pre-compaction prompts: clear system prompt
+ * with isCompactionOutputValid() as the actual guardrail.
+ */
+/**
+ * Build the system prompt for summary generation.
+ */
+export function buildSummarySystemPrompt() {
+    return `You are a knowledge summarization engine. Your ONLY task is to create a structural summary of the provided knowledge entries.
+
+## Rules
+- Condense child entries into a structural overview preserving key facts, relationships, and patterns
+- Reference child entry names so readers know where to drill down for details
+- Target compression: ~20-30% of input token count
+- PRESERVE: entity names, file paths, API signatures, architectural decisions, key relationships
+- DISCARD: verbose examples, repeated explanations, secondary detail, conversational filler
+- Output clean structured markdown (headings, bullet points, brief prose)
+- Do NOT wrap output in code blocks or XML tags
+- Do NOT search any knowledge base or use any tools
+- Output ONLY the summary text`;
+}
+/**
+ * Build the user message for a summary generation pass.
+ *
+ * @param childEntries - Array of { name, content } for each child input
+ * @param level - The summary level being generated (d1, d2, d3)
+ * @param aggressive - Whether this is the aggressive (pass 2) attempt
+ */
+export function buildSummaryUserMessage(childEntries, level, aggressive) {
+    const instruction = aggressive
+        ? `Create a MORE CONCISE structural summary at level ${level}. A previous attempt was not short enough. Aggressively compress while keeping only the most critical facts and relationships.`
+        : `Create a structural summary at level ${level} from the following knowledge entries. Preserve key facts, architectural decisions, and relationships. Reference entry names for drill-down.`;
+    const entriesText = childEntries
+        .map((entry) => `### ${entry.name}\n${entry.content}`)
+        .join('\n\n---\n\n');
+    return `${instruction}
+
+<child_entries>
+${entriesText}
+</child_entries>
+
+Output ONLY the summary text. Do NOT use any tools.`;
+}

package/dist/server/infra/context-tree/snapshot-diff.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Snapshot diff utility for detecting context tree changes.
+ *
+ * Compares pre/post snapshot states to produce a list of changed paths.
+ * Used by CurateExecutor to determine which summaries need regeneration.
+ */
+import type { FileState } from '../../core/domain/entities/context-tree-snapshot.js';
+/**
+ * Compare two snapshot states and return all changed paths.
+ *
+ * Returns paths that are:
+ * - Added: present in `after` but not in `before`
+ * - Modified: present in both but with different hashes
+ * - Deleted: present in `before` but not in `after`
+ *
+ * Derived artifacts (via isExcludedFromSync) are excluded from results
+ * since they are generated content that should not trigger summary regeneration.
+ */
+export declare function diffStates(before: Map<string, FileState>, after: Map<string, FileState>): string[];

package/dist/server/infra/context-tree/snapshot-diff.js

@@ -0,0 +1,39 @@
+/**
+ * Snapshot diff utility for detecting context tree changes.
+ *
+ * Compares pre/post snapshot states to produce a list of changed paths.
+ * Used by CurateExecutor to determine which summaries need regeneration.
+ */
+import { isExcludedFromSync } from './derived-artifact.js';
+/**
+ * Compare two snapshot states and return all changed paths.
+ *
+ * Returns paths that are:
+ * - Added: present in `after` but not in `before`
+ * - Modified: present in both but with different hashes
+ * - Deleted: present in `before` but not in `after`
+ *
+ * Derived artifacts (via isExcludedFromSync) are excluded from results
+ * since they are generated content that should not trigger summary regeneration.
+ */
+export function diffStates(before, after) {
+    const changedPaths = [];
+    // Detect additions and modifications
+    for (const [path, afterState] of after) {
+        if (isExcludedFromSync(path))
+            continue;
+        const beforeState = before.get(path);
+        if (!beforeState || beforeState.hash !== afterState.hash) {
+            changedPaths.push(path);
+        }
+    }
+    // Detect deletions
+    for (const path of before.keys()) {
+        if (isExcludedFromSync(path))
+            continue;
+        if (!after.has(path)) {
+            changedPaths.push(path);
+        }
+    }
+    return changedPaths;
+}

package/dist/server/infra/context-tree/summary-frontmatter.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Summary and archive stub frontmatter parser/writer.
+ *
+ * Follows the same pattern as MarkdownWriter.parseFrontmatter() using js-yaml.
+ */
+import type { ArchiveStubFrontmatter, SummaryFrontmatter } from '../../core/domain/knowledge/summary-types.js';
+/**
+ * Parse summary frontmatter from markdown content.
+ * Returns null if no frontmatter found or type !== 'summary'.
+ */
+export declare function parseSummaryFrontmatter(content: string): null | SummaryFrontmatter;
+/**
+ * Generate markdown content with summary frontmatter.
+ */
+export declare function generateSummaryContent(frontmatter: SummaryFrontmatter, body: string): string;
+/**
+ * Parse archive stub frontmatter from markdown content.
+ * Returns null if no frontmatter found or type !== 'archive_stub'.
+ */
+export declare function parseArchiveStubFrontmatter(content: string): ArchiveStubFrontmatter | null;
+/**
+ * Generate markdown content with archive stub frontmatter and ghost cue body.
+ */
+export declare function generateArchiveStubContent(frontmatter: ArchiveStubFrontmatter, ghostCue: string): string;