@substrate-ai/factory 0.19.54

package/dist/context/cli-command.js

@@ -0,0 +1,382 @@
+/**
+ * CLI subcommand registration for pyramid summary management.
+ *
+ * Registers:
+ *   factory context summarize  --run <id> --iteration <n> --level <level>
+ *   factory context expand     --run <id> --iteration <n>
+ *   factory context stats      --run <id>
+ *
+ * Story 49-7.
+ */
+import { createHash } from 'node:crypto';
+import { readdir, readFile, stat } from 'node:fs/promises';
+import { join } from 'node:path';
+import { SummaryCache, CachingSummaryEngine } from './summary-cache.js';
+import { computeCompressionRatio, computeKeyFactRetentionRate } from './summary-metrics.js';
+/** Build a CLIJsonOutput envelope. */
+export function buildJsonOutput(command, data, version) {
+    return {
+        timestamp: new Date().toISOString(),
+        version,
+        command,
+        data,
+    };
+}
+// ---------------------------------------------------------------------------
+// StubSummaryEngine — minimal passthrough used in production CLI
+// ---------------------------------------------------------------------------
+/** Minimal stub SummaryEngine used when no engineFactory is provided. */
+class StubSummaryEngine {
+    name = 'stub';
+    async summarize(content, targetLevel) {
+        const originalHash = createHash('sha256').update(content).digest('hex');
+        return {
+            level: targetLevel,
+            content,
+            originalHash,
+            createdAt: new Date().toISOString(),
+        };
+    }
+    async expand(summary) {
+        return summary.content;
+    }
+}
+/**
+ * Scan all `*.json` summary files in summariesDir to find the most recently
+ * stored summary matching the given iteration number.
+ *
+ * Matches on `record.summary.iterationIndex === iteration`.
+ * Returns null if no match is found.
+ */
+async function findSummaryForIteration(summariesDir, iteration) {
+    let allFiles;
+    try {
+        allFiles = await readdir(summariesDir);
+    }
+    catch {
+        return null;
+    }
+    const jsonFiles = allFiles.filter((f) => f.endsWith('.json'));
+    const matches = [];
+    for (const file of jsonFiles) {
+        try {
+            const raw = await readFile(join(summariesDir, file), 'utf-8');
+            const record = JSON.parse(raw);
+            if (record.summary.iterationIndex === iteration) {
+                matches.push({
+                    hash: record.summary.originalHash,
+                    record,
+                    cachedAt: new Date(record.cachedAt).getTime(),
+                });
+            }
+        }
+        catch {
+            // Skip malformed files
+        }
+    }
+    if (matches.length === 0)
+        return null;
+    // Return the most recently stored match
+    matches.sort((a, b) => b.cachedAt - a.cachedAt);
+    const best = matches[0];
+    return { hash: best.hash, record: best.record };
+}
+/**
+ * Core logic for `factory context summarize`.
+ *
+ * Loads the original content, runs it through CachingSummaryEngine, stores the
+ * result, and prints compression statistics.
+ *
+ * @returns Exit code: 0 on success, 1 on error.
+ */
+export async function summarizeAction(opts, deps, output = {
+    stdout: process.stdout,
+    stderr: process.stderr,
+}) {
+    const { stdout, stderr } = output;
+    // Validate iteration — must be a non-negative integer (digits only)
+    if (!/^\d+$/.test(opts.iteration)) {
+        stderr.write(`Error: --iteration must be a non-negative integer, got: ${opts.iteration}\n`);
+        return 1;
+    }
+    const iteration = parseInt(opts.iteration, 10);
+    // Validate level
+    const validLevels = ['full', 'high', 'medium', 'low'];
+    if (!validLevels.includes(opts.level)) {
+        stderr.write(`Error: --level must be one of: full, high, medium, low. Got: ${opts.level}\n`);
+        return 1;
+    }
+    const level = opts.level;
+    const summariesDir = join(deps.storageDir, 'runs', opts.run, 'summaries');
+    // Check that the summaries directory exists
+    try {
+        await stat(summariesDir);
+    }
+    catch {
+        stderr.write(`Error: Run directory not found: ${summariesDir}\n`);
+        return 1;
+    }
+    // Resolve iteration → hash by scanning JSON summary files
+    const found = await findSummaryForIteration(summariesDir, iteration);
+    if (!found) {
+        stderr.write(`Error: No summary found for iteration ${iteration} in run ${opts.run}\n`);
+        return 1;
+    }
+    // SummaryCache storageDir = parent of {runId} directory
+    const cache = new SummaryCache({ runId: opts.run, storageDir: join(deps.storageDir, 'runs') });
+    // Load original content (.orig file)
+    const originalContent = await cache.getOriginal(found.hash);
+    if (originalContent === null) {
+        stderr.write(`Error: Original content (.orig) not found for hash ${found.hash.slice(0, 8)} in run ${opts.run}\n`);
+        return 1;
+    }
+    // Summarize via CachingSummaryEngine (checks cache first, delegates to inner on miss)
+    const innerEngine = deps.engineFactory
+        ? deps.engineFactory()
+        : new StubSummaryEngine();
+    const engine = new CachingSummaryEngine(innerEngine, cache);
+    const summary = await engine.summarize(originalContent, level);
+    // Explicitly store result (AC1: "stored via cache.put()")
+    await cache.put(summary, originalContent);
+    // Compute and emit metrics
+    const compressionRatio = computeCompressionRatio(summary);
+    if (opts.outputFormat === 'json') {
+        const data = {
+            hash: summary.originalHash,
+            level: summary.level,
+            compressionRatio,
+            summaryTokenCount: summary.summaryTokenCount,
+            originalTokenCount: summary.originalTokenCount,
+        };
+        stdout.write(JSON.stringify(buildJsonOutput('factory context summarize', data, deps.version)) + '\n');
+    }
+    else {
+        const ratioStr = compressionRatio >= 0 ? compressionRatio.toFixed(2) : 'n/a';
+        stdout.write(`Summarized iteration ${iteration} → level ${level} | hash: ${summary.originalHash.slice(0, 8)} | compression: ${ratioStr}\n`);
+    }
+    return 0;
+}
+/**
+ * Core logic for `factory context expand`.
+ *
+ * Finds the stored summary for the given iteration, then expands it back
+ * toward full content (lossless if .orig exists, LLM fallback otherwise).
+ *
+ * @returns Exit code: 0 on success, 1 on error.
+ */
+export async function expandAction(opts, deps, output = {
+    stdout: process.stdout,
+    stderr: process.stderr,
+}) {
+    const { stdout, stderr } = output;
+    // Validate iteration
+    if (!/^\d+$/.test(opts.iteration)) {
+        stderr.write(`Error: --iteration must be a non-negative integer, got: ${opts.iteration}\n`);
+        return 1;
+    }
+    const iteration = parseInt(opts.iteration, 10);
+    const summariesDir = join(deps.storageDir, 'runs', opts.run, 'summaries');
+    // Check that the summaries directory exists
+    try {
+        await stat(summariesDir);
+    }
+    catch {
+        stderr.write(`Error: Run directory not found: ${summariesDir}\n`);
+        return 1;
+    }
+    // Find summary for iteration
+    const found = await findSummaryForIteration(summariesDir, iteration);
+    if (!found) {
+        stderr.write(`Error: No summary found for iteration ${iteration} in run ${opts.run}\n`);
+        return 1;
+    }
+    // Expand via CachingSummaryEngine (uses lossless .orig path when available)
+    const cache = new SummaryCache({ runId: opts.run, storageDir: join(deps.storageDir, 'runs') });
+    const innerEngine = deps.engineFactory
+        ? deps.engineFactory()
+        : new StubSummaryEngine();
+    const engine = new CachingSummaryEngine(innerEngine, cache);
+    const expandedContent = await engine.expand(found.record.summary, 'full');
+    if (opts.outputFormat === 'json') {
+        const data = {
+            hash: found.record.summary.originalHash,
+            level: found.record.summary.level,
+            expandedLength: expandedContent.length,
+            content: expandedContent,
+        };
+        stdout.write(JSON.stringify(buildJsonOutput('factory context expand', data, deps.version)) + '\n');
+    }
+    else {
+        stdout.write(expandedContent + '\n');
+    }
+    return 0;
+}
+/**
+ * Core logic for `factory context stats`.
+ *
+ * Reads all stored summary records for a run, computes compression metrics,
+ * and prints a formatted table (or JSON array).
+ *
+ * @returns Exit code: 0 on success, 1 on error.
+ */
+export async function statsAction(opts, deps, output = {
+    stdout: process.stdout,
+    stderr: process.stderr,
+}) {
+    const { stdout, stderr } = output;
+    const summariesDir = join(deps.storageDir, 'runs', opts.run, 'summaries');
+    // Check that the summaries directory exists
+    try {
+        await stat(summariesDir);
+    }
+    catch {
+        stderr.write(`Error: Run directory not found: ${summariesDir}\n`);
+        return 1;
+    }
+    // Read all .json files
+    let allFiles;
+    try {
+        allFiles = await readdir(summariesDir);
+    }
+    catch {
+        stderr.write(`Error: Could not read summaries directory: ${summariesDir}\n`);
+        return 1;
+    }
+    const jsonFiles = allFiles.filter((f) => f.endsWith('.json'));
+    const rows = [];
+    for (const file of jsonFiles) {
+        try {
+            const raw = await readFile(join(summariesDir, file), 'utf-8');
+            const record = JSON.parse(raw);
+            const compressionRatio = computeCompressionRatio(record.summary);
+            // Compute keyFactRetentionRate if original content is available
+            let keyFactRetentionRate = -1;
+            try {
+                const origPath = join(summariesDir, `${record.summary.originalHash}.orig`);
+                const originalContent = await readFile(origPath, 'utf-8');
+                keyFactRetentionRate = computeKeyFactRetentionRate(originalContent, record.summary.content);
+            }
+            catch {
+                // Original not available — sentinel value -1
+            }
+            rows.push({
+                hash: record.summary.originalHash,
+                level: record.summary.level,
+                compressionRatio,
+                keyFactRetentionRate,
+                cachedAt: record.cachedAt,
+            });
+        }
+        catch {
+            // Skip malformed files
+        }
+    }
+    // Sort by cachedAt ascending
+    rows.sort((a, b) => new Date(a.cachedAt).getTime() - new Date(b.cachedAt).getTime());
+    if (opts.outputFormat === 'json') {
+        stdout.write(JSON.stringify(buildJsonOutput('factory context stats', rows, deps.version)) + '\n');
+        return 0;
+    }
+    // Text table output
+    if (rows.length === 0) {
+        stdout.write('No summaries found.\n');
+        return 0;
+    }
+    const headers = ['Hash', 'Level', 'CompRatio', 'KeyRetention', 'CachedAt'];
+    const tableRows = rows.map((row) => ({
+        Hash: row.hash.slice(0, 8),
+        Level: row.level,
+        CompRatio: row.compressionRatio >= 0 ? row.compressionRatio.toFixed(4) : 'n/a',
+        KeyRetention: row.keyFactRetentionRate >= 0 ? row.keyFactRetentionRate.toFixed(4) : 'n/a',
+        CachedAt: row.cachedAt,
+    }));
+    // Compute column widths from header + data lengths
+    const widths = headers.map((h) => {
+        const dataMax = tableRows.reduce((max, row) => {
+            const val = row[h] ?? '';
+            return Math.max(max, val.length);
+        }, 0);
+        return Math.max(h.length, dataMax);
+    });
+    const headerLine = headers.map((h, i) => h.padEnd(widths[i])).join(' | ');
+    const separator = widths.map((w) => '-'.repeat(w)).join('-+-');
+    stdout.write(headerLine + '\n');
+    stdout.write(separator + '\n');
+    for (const row of tableRows) {
+        const line = headers
+            .map((h, i) => (row[h] ?? '').padEnd(widths[i]))
+            .join(' | ');
+        stdout.write(line + '\n');
+    }
+    return 0;
+}
+// ---------------------------------------------------------------------------
+// registerContextCommand — Commander wiring
+// ---------------------------------------------------------------------------
+/**
+ * Register the `context` subcommand group on the provided factory command.
+ *
+ * Subcommands registered:
+ *   factory context summarize --run <id> --iteration <n> --level <level>
+ *   factory context expand    --run <id> --iteration <n>
+ *   factory context stats     --run <id>
+ *
+ * @param factoryCmd    - The factory Commander command to attach to
+ * @param version       - CLI version string for JSON output (e.g. "1.2.3")
+ * @param storageDir    - Base storage directory (defaults to `{cwd}/.substrate`)
+ * @param engineFactory - Optional SummaryEngine factory for testing injection
+ */
+export function registerContextCommand(factoryCmd, version, storageDir, engineFactory) {
+    const resolvedStorageDir = storageDir ?? join(process.cwd(), '.substrate');
+    const contextCmd = factoryCmd
+        .command('context')
+        .description('Inspect and manage pyramid summaries for factory runs');
+    // ---- summarize ----
+    contextCmd
+        .command('summarize')
+        .description('Compress and store a run iteration to the target summary level')
+        .requiredOption('--run <id>', 'Run ID')
+        .requiredOption('--iteration <n>', 'Iteration number')
+        .requiredOption('--level <level>', 'Summary level: high | medium | low')
+        .option('--output-format <format>', 'Output format: text | json', 'text')
+        .action(async (opts) => {
+        const code = await summarizeAction(opts, {
+            storageDir: resolvedStorageDir,
+            version,
+            ...(engineFactory !== undefined ? { engineFactory } : {}),
+        });
+        if (code !== 0)
+            process.exit(code);
+    });
+    // ---- expand ----
+    contextCmd
+        .command('expand')
+        .description('Expand a stored summary for a run iteration back to full content')
+        .requiredOption('--run <id>', 'Run ID')
+        .requiredOption('--iteration <n>', 'Iteration number')
+        .option('--output-format <format>', 'Output format: text | json', 'text')
+        .action(async (opts) => {
+        const code = await expandAction(opts, {
+            storageDir: resolvedStorageDir,
+            version,
+            ...(engineFactory !== undefined ? { engineFactory } : {}),
+        });
+        if (code !== 0)
+            process.exit(code);
+    });
+    // ---- stats ----
+    contextCmd
+        .command('stats')
+        .description('Report per-run compression statistics for all stored summaries')
+        .requiredOption('--run <id>', 'Run ID')
+        .option('--output-format <format>', 'Output format: text | json', 'text')
+        .action(async (opts) => {
+        const code = await statsAction(opts, {
+            storageDir: resolvedStorageDir,
+            version,
+        });
+        if (code !== 0)
+            process.exit(code);
+    });
+}
+//# sourceMappingURL=cli-command.js.map

package/dist/context/cli-command.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli-command.js","sourceRoot":"","sources":["../../src/context/cli-command.ts"],"names":[],"mappings":"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"}

package/dist/context/index.d.ts

@@ -0,0 +1,8 @@
+export * from './summary-types.js';
+export * from './summary-engine.js';
+export * from './summarizer.js';
+export * from './auto-summarizer.js';
+export * from './summary-cache.js';
+export * from './summary-metrics.js';
+export * from './cli-command.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/context/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/context/index.ts"],"names":[],"mappings":"AAAA,cAAc,oBAAoB,CAAA;AAClC,cAAc,qBAAqB,CAAA;AACnC,cAAc,iBAAiB,CAAA;AAC/B,cAAc,sBAAsB,CAAA;AACpC,cAAc,oBAAoB,CAAA;AAClC,cAAc,sBAAsB,CAAA;AACpC,cAAc,kBAAkB,CAAA"}

package/dist/context/index.js

@@ -0,0 +1,8 @@
+export * from './summary-types.js';
+export * from './summary-engine.js';
+export * from './summarizer.js';
+export * from './auto-summarizer.js';
+export * from './summary-cache.js';
+export * from './summary-metrics.js';
+export * from './cli-command.js';
+//# sourceMappingURL=index.js.map

package/dist/context/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/context/index.ts"],"names":[],"mappings":"AAAA,cAAc,oBAAoB,CAAA;AAClC,cAAc,qBAAqB,CAAA;AACnC,cAAc,iBAAiB,CAAA;AAC/B,cAAc,sBAAsB,CAAA;AACpC,cAAc,oBAAoB,CAAA;AAClC,cAAc,sBAAsB,CAAA;AACpC,cAAc,kBAAkB,CAAA"}

package/dist/context/summarizer.d.ts

@@ -0,0 +1,12 @@
+import type { LLMClient } from '../llm/client.js';
+import type { SummaryEngine } from './summary-engine.js';
+import type { Summary, SummaryLevel, SummarizeOptions, ExpandOptions } from './summary-types.js';
+export declare class LLMSummaryEngine implements SummaryEngine {
+    private readonly llmClient;
+    private readonly modelName;
+    readonly name = "llm";
+    constructor(llmClient: LLMClient, modelName?: string);
+    summarize(content: string, targetLevel: SummaryLevel, opts?: SummarizeOptions): Promise<Summary>;
+    expand(summary: Summary, targetLevel: SummaryLevel, opts?: ExpandOptions): Promise<string>;
+}
+//# sourceMappingURL=summarizer.d.ts.map

package/dist/context/summarizer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"summarizer.d.ts","sourceRoot":"","sources":["../../src/context/summarizer.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAA;AAEjD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAA;AACxD,OAAO,KAAK,EAAE,OAAO,EAAE,YAAY,EAAE,gBAAgB,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAA;AAwDhG,qBAAa,gBAAiB,YAAW,aAAa;IAIlD,OAAO,CAAC,QAAQ,CAAC,SAAS;IAC1B,OAAO,CAAC,QAAQ,CAAC,SAAS;IAJ5B,QAAQ,CAAC,IAAI,SAAQ;gBAGF,SAAS,EAAE,SAAS,EACpB,SAAS,GAAE,MAA0B;IAGlD,SAAS,CACb,OAAO,EAAE,MAAM,EACf,WAAW,EAAE,YAAY,EACzB,IAAI,CAAC,EAAE,gBAAgB,GACtB,OAAO,CAAC,OAAO,CAAC;IAgCb,MAAM,CACV,OAAO,EAAE,OAAO,EAChB,WAAW,EAAE,YAAY,EACzB,IAAI,CAAC,EAAE,aAAa,GACnB,OAAO,CAAC,MAAM,CAAC;CAoBnB"}

package/dist/context/summarizer.js

@@ -0,0 +1,105 @@
+/**
+ * LLMSummaryEngine — LLM-backed implementation of the SummaryEngine interface.
+ *
+ * Compresses long context strings to a target level while preserving structural
+ * elements (code blocks, file paths, error messages) for faithful recovery.
+ */
+import { createHash } from 'node:crypto';
+import { SUMMARY_BUDGET } from './summary-types.js';
+// ---------------------------------------------------------------------------
+// Prompt builders
+// ---------------------------------------------------------------------------
+function buildSummarizePrompt(content, targetTokenCount, opts) {
+    const preserveCodeBlocks = opts.preserveCodeBlocks ?? true;
+    const preserveFilePaths = opts.preserveFilePaths ?? true;
+    const preserveErrorMessages = opts.preserveErrorMessages ?? true;
+    return `Summarize the following content to approximately ${targetTokenCount} tokens.
+
+PRESERVATION RULES (MANDATORY — do NOT paraphrase or omit):
+${preserveCodeBlocks ? '- Code blocks (triple-backtick fenced sections): copy VERBATIM' : ''}
+${preserveFilePaths ? '- File paths (e.g. src/foo/bar.ts, /absolute/path): copy VERBATIM' : ''}
+${preserveErrorMessages ? '- Error messages and stack traces: copy VERBATIM' : ''}
+- Key decisions, conclusions, and action items: preserve the substance
+
+REDUCTION RULES (apply in order of preference):
+1. Remove verbose explanations and commentary
+2. Shorten transition sentences between sections
+3. Condense repetitive content to a single representative example
+4. Summarize narrative prose into concise bullet points
+
+Content:
+---
+${content}
+---`;
+}
+function buildExpandPrompt(summary) {
+    return `The following is a ${summary.level}-level summary of a longer technical document.
+Expand it back toward the full version by restoring context, explanations, and detail that would have been in the original.
+
+EXPANSION RULES:
+- Preserve all code blocks VERBATIM as they appear in the summary
+- Preserve all file paths VERBATIM as they appear in the summary
+- Preserve all error messages VERBATIM as they appear in the summary
+- Infer and restore narrative context and explanations from the summary's content
+
+Summary (${summary.level} level):
+---
+${summary.content}
+---`;
+}
+// ---------------------------------------------------------------------------
+// LLMSummaryEngine
+// ---------------------------------------------------------------------------
+export class LLMSummaryEngine {
+    llmClient;
+    modelName;
+    name = 'llm';
+    constructor(llmClient, modelName = 'claude-opus-4-5') {
+        this.llmClient = llmClient;
+        this.modelName = modelName;
+    }
+    async summarize(content, targetLevel, opts) {
+        const originalHash = createHash('sha256').update(content).digest('hex');
+        const resolvedOpts = opts ?? {};
+        const modelTokenLimit = resolvedOpts.modelTokenLimit ?? 100_000;
+        const targetTokenCount = Math.floor(modelTokenLimit * SUMMARY_BUDGET[targetLevel]);
+        const prompt = buildSummarizePrompt(content, targetTokenCount, resolvedOpts);
+        const request = {
+            model: this.modelName,
+            messages: [
+                {
+                    role: 'user',
+                    content: [{ kind: 'text', text: prompt }],
+                },
+            ],
+            maxTokens: targetTokenCount + 500,
+        };
+        const response = await this.llmClient.complete(request);
+        return {
+            level: targetLevel,
+            content: response.content,
+            originalHash,
+            createdAt: new Date().toISOString(),
+            originalTokenCount: response.usage.inputTokens,
+            summaryTokenCount: response.usage.outputTokens,
+        };
+    }
+    async expand(summary, targetLevel, opts) {
+        if (opts?.originalContent) {
+            return opts.originalContent;
+        }
+        const prompt = buildExpandPrompt(summary);
+        const request = {
+            model: this.modelName,
+            messages: [
+                {
+                    role: 'user',
+                    content: [{ kind: 'text', text: prompt }],
+                },
+            ],
+        };
+        const response = await this.llmClient.complete(request);
+        return response.content;
+    }
+}
+//# sourceMappingURL=summarizer.js.map

package/dist/context/summarizer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"summarizer.js","sourceRoot":"","sources":["../../src/context/summarizer.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AAKxC,OAAO,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAA;AAEnD,8EAA8E;AAC9E,kBAAkB;AAClB,8EAA8E;AAE9E,SAAS,oBAAoB,CAC3B,OAAe,EACf,gBAAwB,EACxB,IAAsB;IAEtB,MAAM,kBAAkB,GAAG,IAAI,CAAC,kBAAkB,IAAI,IAAI,CAAA;IAC1D,MAAM,iBAAiB,GAAG,IAAI,CAAC,iBAAiB,IAAI,IAAI,CAAA;IACxD,MAAM,qBAAqB,GAAG,IAAI,CAAC,qBAAqB,IAAI,IAAI,CAAA;IAEhE,OAAO,oDAAoD,gBAAgB;;;EAG3E,kBAAkB,CAAC,CAAC,CAAC,gEAAgE,CAAC,CAAC,CAAC,EAAE;EAC1F,iBAAiB,CAAC,CAAC,CAAC,mEAAmE,CAAC,CAAC,CAAC,EAAE;EAC5F,qBAAqB,CAAC,CAAC,CAAC,kDAAkD,CAAC,CAAC,CAAC,EAAE;;;;;;;;;;;EAW/E,OAAO;IACL,CAAA;AACJ,CAAC;AAED,SAAS,iBAAiB,CAAC,OAAgB;IACzC,OAAO,sBAAsB,OAAO,CAAC,KAAK;;;;;;;;;WASjC,OAAO,CAAC,KAAK;;EAEtB,OAAO,CAAC,OAAO;IACb,CAAA;AACJ,CAAC;AAED,8EAA8E;AAC9E,mBAAmB;AACnB,8EAA8E;AAE9E,MAAM,OAAO,gBAAgB;IAIR;IACA;IAJV,IAAI,GAAG,KAAK,CAAA;IAErB,YACmB,SAAoB,EACpB,YAAoB,iBAAiB;QADrC,cAAS,GAAT,SAAS,CAAW;QACpB,cAAS,GAAT,SAAS,CAA4B;IACrD,CAAC;IAEJ,KAAK,CAAC,SAAS,CACb,OAAe,EACf,WAAyB,EACzB,IAAuB;QAEvB,MAAM,YAAY,GAAG,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAA;QAEvE,MAAM,YAAY,GAAqB,IAAI,IAAI,EAAE,CAAA;QACjD,MAAM,eAAe,GAAG,YAAY,CAAC,eAAe,IAAI,OAAO,CAAA;QAC/D,MAAM,gBAAgB,GAAG,IAAI,CAAC,KAAK,CAAC,eAAe,GAAG,cAAc,CAAC,WAAW,CAAC,CAAC,CAAA;QAElF,MAAM,MAAM,GAAG,oBAAoB,CAAC,OAAO,EAAE,gBAAgB,EAAE,YAAY,CAAC,CAAA;QAE5E,MAAM,OAAO,GAAe;YAC1B,KAAK,EAAE,IAAI,CAAC,SAAS;YACrB,QAAQ,EAAE;gBACR;oBACE,IAAI,EAAE,MAAM;oBACZ,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC;iBAC1C;aACF;YACD,SAAS,EAAE,gBAAgB,GAAG,GAAG;SAClC,CAAA;QAED,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAA;QAEvD,OAAO;YACL,KAAK,EAAE,WAAW;YAClB,OAAO,EAAE,QAAQ,CAAC,OAAO;YACzB,YAAY;YACZ,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;YACnC,kBAAkB,EAAE,QAAQ,CAAC,KAAK,CAAC,WAAW;YAC9C,iBAAiB,EAAE,QAAQ,CAAC,KAAK,CAAC,YAAY;SAC/C,CAAA;IACH,CAAC;IAED,KAAK,CAAC,MAAM,CACV,OAAgB,EAChB,WAAyB,EACzB,IAAoB;QAEpB,IAAI,IAAI,EAAE,eAAe,EAAE,CAAC;YAC1B,OAAO,IAAI,CAAC,eAAe,CAAA;QAC7B,CAAC;QAED,MAAM,MAAM,GAAG,iBAAiB,CAAC,OAAO,CAAC,CAAA;QAEzC,MAAM,OAAO,GAAe;YAC1B,KAAK,EAAE,IAAI,CAAC,SAAS;YACrB,QAAQ,EAAE;gBACR;oBACE,IAAI,EAAE,MAAM;oBACZ,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC;iBAC1C;aACF;SACF,CAAA;QAED,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAA;QACvD,OAAO,QAAQ,CAAC,OAAO,CAAA;IACzB,CAAC;CACF"}

package/dist/context/summary-cache.d.ts

@@ -0,0 +1,41 @@
+/**
+ * SummaryCache — file-backed storage for summaries with a caching layer
+ * that prevents redundant LLM calls during long-running convergence sessions.
+ *
+ * Storage layout:
+ *   {storageDir}/{runId}/summaries/{hash}-{level}.json   ← CachedSummaryRecord
+ *   {storageDir}/{runId}/summaries/{hash}.orig            ← raw original content
+ */
+import type { Summary, SummaryLevel, SummarizeOptions, ExpandOptions } from './summary-types.js';
+import type { SummaryEngine } from './summary-engine.js';
+export interface SummaryCacheConfig {
+    /** Unique identifier for the current pipeline run. */
+    runId: string;
+    /** Absolute path to the storage root that contains run directories (e.g. `.substrate/runs/`). */
+    storageDir: string;
+    /** Whether to persist original content alongside summaries for lossless expansion. Default: true. */
+    storeOriginals?: boolean;
+}
+/** Envelope type persisted to disk — wraps Summary with cache metadata. */
+export interface CachedSummaryRecord {
+    summary: Summary;
+    cachedAt: string;
+}
+export declare class SummaryCache {
+    private readonly config;
+    constructor(config: SummaryCacheConfig);
+    private summaryPath;
+    private originalPath;
+    put(summary: Summary, originalContent?: string): Promise<void>;
+    get(originalHash: string, level: SummaryLevel): Promise<Summary | null>;
+    getOriginal(originalHash: string): Promise<string | null>;
+}
+export declare class CachingSummaryEngine implements SummaryEngine {
+    private readonly inner;
+    private readonly cache;
+    readonly name: string;
+    constructor(inner: SummaryEngine, cache: SummaryCache);
+    summarize(content: string, targetLevel: SummaryLevel, opts?: SummarizeOptions): Promise<Summary>;
+    expand(summary: Summary, targetLevel: SummaryLevel, opts?: ExpandOptions): Promise<string>;
+}
+//# sourceMappingURL=summary-cache.d.ts.map

package/dist/context/summary-cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"summary-cache.d.ts","sourceRoot":"","sources":["../../src/context/summary-cache.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAKH,OAAO,KAAK,EAAE,OAAO,EAAE,YAAY,EAAE,gBAAgB,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAA;AAChG,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAA;AAExD,MAAM,WAAW,kBAAkB;IACjC,sDAAsD;IACtD,KAAK,EAAE,MAAM,CAAA;IACb,iGAAiG;IACjG,UAAU,EAAE,MAAM,CAAA;IAClB,qGAAqG;IACrG,cAAc,CAAC,EAAE,OAAO,CAAA;CACzB;AAED,2EAA2E;AAC3E,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,OAAO,CAAA;IAChB,QAAQ,EAAE,MAAM,CAAA;CACjB;AAED,qBAAa,YAAY;IACvB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAoB;gBAE/B,MAAM,EAAE,kBAAkB;IAItC,OAAO,CAAC,WAAW;IAInB,OAAO,CAAC,YAAY;IAId,GAAG,CAAC,OAAO,EAAE,OAAO,EAAE,eAAe,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAU9D,GAAG,CAAC,YAAY,EAAE,MAAM,EAAE,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC;IAWvE,WAAW,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;CAQhE;AAED,qBAAa,oBAAqB,YAAW,aAAa;IAItD,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,KAAK;IAJxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;gBAGF,KAAK,EAAE,aAAa,EACpB,KAAK,EAAE,YAAY;IAKhC,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,YAAY,EAAE,IAAI,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAAC,OAAO,CAAC;IAShG,MAAM,CAAC,OAAO,EAAE,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,IAAI,CAAC,EAAE,aAAa,GAAG,OAAO,CAAC,MAAM,CAAC;CAKjG"}