@substrate-ai/factory 0.19.54

package/dist/context/summary-cache.js

@@ -0,0 +1,80 @@
+/**
+ * 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 { createHash } from 'node:crypto';
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+export class SummaryCache {
+    config;
+    constructor(config) {
+        this.config = config;
+    }
+    summaryPath(hash, level) {
+        return join(this.config.storageDir, this.config.runId, 'summaries', `${hash}-${level}.json`);
+    }
+    originalPath(hash) {
+        return join(this.config.storageDir, this.config.runId, 'summaries', `${hash}.orig`);
+    }
+    async put(summary, originalContent) {
+        const dir = join(this.config.storageDir, this.config.runId, 'summaries');
+        await mkdir(dir, { recursive: true });
+        const record = { summary, cachedAt: new Date().toISOString() };
+        await writeFile(this.summaryPath(summary.originalHash, summary.level), JSON.stringify(record, null, 2));
+        if (originalContent !== undefined && this.config.storeOriginals !== false) {
+            await writeFile(this.originalPath(summary.originalHash), originalContent);
+        }
+    }
+    async get(originalHash, level) {
+        try {
+            const raw = await readFile(this.summaryPath(originalHash, level), 'utf-8');
+            const record = JSON.parse(raw);
+            return record.summary;
+        }
+        catch (err) {
+            if (err.code === 'ENOENT')
+                return null;
+            throw err;
+        }
+    }
+    async getOriginal(originalHash) {
+        try {
+            return await readFile(this.originalPath(originalHash), 'utf-8');
+        }
+        catch (err) {
+            if (err.code === 'ENOENT')
+                return null;
+            throw err;
+        }
+    }
+}
+export class CachingSummaryEngine {
+    inner;
+    cache;
+    name;
+    constructor(inner, cache) {
+        this.inner = inner;
+        this.cache = cache;
+        this.name = `caching(${inner.name})`;
+    }
+    async summarize(content, targetLevel, opts) {
+        const originalHash = createHash('sha256').update(content).digest('hex');
+        const cached = await this.cache.get(originalHash, targetLevel);
+        if (cached !== null)
+            return cached;
+        const summary = await this.inner.summarize(content, targetLevel, opts);
+        await this.cache.put(summary, content);
+        return summary;
+    }
+    async expand(summary, targetLevel, opts) {
+        const original = await this.cache.getOriginal(summary.originalHash);
+        if (original !== null)
+            return original;
+        return this.inner.expand(summary, targetLevel, opts);
+    }
+}
+//# sourceMappingURL=summary-cache.js.map

package/dist/context/summary-cache.js.map

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

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

@@ -0,0 +1,46 @@
+/**
+ * SummaryEngine interface for reversible multi-level context summarization.
+ *
+ * Zero runtime imports — pure TypeScript interface declaration only.
+ */
+import type { Summary, SummaryLevel, SummarizeOptions, ExpandOptions } from './summary-types.js';
+/**
+ * Reversible multi-level context summarization engine.
+ *
+ * Contract: expand(summarize(content, level), 'full') must preserve all
+ * code blocks, file paths, error messages, and key decisions from the original.
+ *
+ * Implementations:
+ * - LLMSummaryEngine (story 49-2): LLM-backed summarization and expansion
+ * - Passthrough mock: for tests, returns content unmodified or sliced by budget fraction
+ */
+export interface SummaryEngine {
+    /**
+     * A human-readable name for this engine instance.
+     * Used for traceability in logs and metrics.
+     */
+    readonly name: string;
+    /**
+     * Summarize content to the target level.
+     *
+     * @param content - The original content to summarize
+     * @param targetLevel - The desired summary level
+     * @param opts - Optional configuration for the summarization
+     * @returns A Summary object containing the compressed content and provenance metadata
+     */
+    summarize(content: string, targetLevel: SummaryLevel, opts?: SummarizeOptions): Promise<Summary>;
+    /**
+     * Expand a summary back toward a higher-fidelity representation.
+     *
+     * When `opts.originalContent` is provided, implementations may use it for
+     * lossless or near-lossless expansion. Without it, expansion relies on
+     * heuristics or LLM inference.
+     *
+     * @param summary - The summary to expand
+     * @param targetLevel - The target level (typically 'full' for full recovery)
+     * @param opts - Optional configuration including the original content
+     * @returns The expanded content as a string
+     */
+    expand(summary: Summary, targetLevel: SummaryLevel, opts?: ExpandOptions): Promise<string>;
+}
+//# sourceMappingURL=summary-engine.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"summary-engine.d.ts","sourceRoot":"","sources":["../../src/context/summary-engine.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,KAAK,EAAE,OAAO,EAAE,YAAY,EAAE,gBAAgB,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAA;AAEhG;;;;;;;;;GASG;AACH,MAAM,WAAW,aAAa;IAC5B;;;OAGG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IAErB;;;;;;;OAOG;IACH,SAAS,CACP,OAAO,EAAE,MAAM,EACf,WAAW,EAAE,YAAY,EACzB,IAAI,CAAC,EAAE,gBAAgB,GACtB,OAAO,CAAC,OAAO,CAAC,CAAA;IAEnB;;;;;;;;;;;OAWG;IACH,MAAM,CACJ,OAAO,EAAE,OAAO,EAChB,WAAW,EAAE,YAAY,EACzB,IAAI,CAAC,EAAE,aAAa,GACnB,OAAO,CAAC,MAAM,CAAC,CAAA;CACnB"}

package/dist/context/summary-engine.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=summary-engine.js.map

package/dist/context/summary-engine.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"summary-engine.js","sourceRoot":"","sources":["../../src/context/summary-engine.ts"],"names":[],"mappings":""}

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

@@ -0,0 +1,75 @@
+/**
+ * Summary quality metrics: compression ratio, key-fact retention, round-trip preservation.
+ *
+ * Provides pure metric computation functions, a SummaryQualityAnalyzer class, and
+ * QualityMetricsPersistence for recording metrics to a JSONL file.
+ */
+import type { Summary, SummaryLevel } from './summary-types.js';
+export interface QualityReport {
+    summaryHash: string;
+    level: SummaryLevel;
+    /** [0,1] when available; -1 sentinel when token counts absent */
+    compressionRatio: number;
+    keyFactRetentionRate: number;
+    /** null when expanded not provided */
+    roundTripScore: number | null;
+    overallScore: number;
+    /** ISO-8601 */
+    computedAt: string;
+}
+export interface PersistedQualityEntry extends QualityReport {
+    /** ISO-8601 — time written to disk */
+    recordedAt: string;
+}
+export interface QualityThresholds {
+    minKeyFactRetentionRate?: number;
+    minRoundTripScore?: number;
+    minOverallScore?: number;
+}
+export declare class QualityBelowThresholdError extends Error {
+    readonly report: QualityReport;
+    readonly failures: string[];
+    constructor(report: QualityReport, failures: string[]);
+}
+export interface QualityMetricsPersistenceConfig {
+    runId: string;
+    storageDir: string;
+}
+/**
+ * Compute the compression ratio of a summary.
+ * Returns summaryTokenCount / originalTokenCount in [0, 1].
+ * Returns -1 as a sentinel when token counts are absent or originalTokenCount is zero.
+ */
+export declare function computeCompressionRatio(summary: Summary): number;
+/**
+ * Extract key facts from content:
+ * - Fenced code blocks (triple-backtick)
+ * - File-path tokens matching known extensions
+ * - Error-type names
+ */
+export declare function extractKeyFacts(content: string): Set<string>;
+/**
+ * Compute the key-fact retention rate between original and summarized content.
+ * Returns the fraction of original key facts that appear in the summarized content.
+ * Returns 1.0 when the original has no key facts.
+ */
+export declare function computeKeyFactRetentionRate(original: string, summarized: string): number;
+/**
+ * Compute the round-trip preservation score between original and expanded content.
+ * Uses Jaccard word-set overlap: intersection / union.
+ * Returns 1.0 when both word sets are empty.
+ * Returns 0.0 when exactly one set is non-empty.
+ */
+export declare function computeRoundTripScore(original: string, expanded: string): number;
+export declare class SummaryQualityAnalyzer {
+    analyze(original: string, summary: Summary, expanded?: string): QualityReport;
+    assertQuality(report: QualityReport, thresholds: QualityThresholds): void;
+}
+export declare class QualityMetricsPersistence {
+    private readonly config;
+    constructor(config: QualityMetricsPersistenceConfig);
+    private metricsPath;
+    record(report: QualityReport): Promise<void>;
+    readAll(): Promise<PersistedQualityEntry[]>;
+}
+//# sourceMappingURL=summary-metrics.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"summary-metrics.d.ts","sourceRoot":"","sources":["../../src/context/summary-metrics.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,KAAK,EAAE,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAA;AAI/D,MAAM,WAAW,aAAa;IAC5B,WAAW,EAAE,MAAM,CAAA;IACnB,KAAK,EAAE,YAAY,CAAA;IACnB,iEAAiE;IACjE,gBAAgB,EAAE,MAAM,CAAA;IACxB,oBAAoB,EAAE,MAAM,CAAA;IAC5B,sCAAsC;IACtC,cAAc,EAAE,MAAM,GAAG,IAAI,CAAA;IAC7B,YAAY,EAAE,MAAM,CAAA;IACpB,eAAe;IACf,UAAU,EAAE,MAAM,CAAA;CACnB;AAED,MAAM,WAAW,qBAAsB,SAAQ,aAAa;IAC1D,sCAAsC;IACtC,UAAU,EAAE,MAAM,CAAA;CACnB;AAED,MAAM,WAAW,iBAAiB;IAChC,uBAAuB,CAAC,EAAE,MAAM,CAAA;IAChC,iBAAiB,CAAC,EAAE,MAAM,CAAA;IAC1B,eAAe,CAAC,EAAE,MAAM,CAAA;CACzB;AAED,qBAAa,0BAA2B,SAAQ,KAAK;aAEjC,MAAM,EAAE,aAAa;aACrB,QAAQ,EAAE,MAAM,EAAE;gBADlB,MAAM,EAAE,aAAa,EACrB,QAAQ,EAAE,MAAM,EAAE;CAKrC;AAED,MAAM,WAAW,+BAA+B;IAC9C,KAAK,EAAE,MAAM,CAAA;IACb,UAAU,EAAE,MAAM,CAAA;CACnB;AAID;;;;GAIG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,CAShE;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,GAAG,CAAC,MAAM,CAAC,CAuB5D;AAED;;;;GAIG;AACH,wBAAgB,2BAA2B,CAAC,QAAQ,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,CAUxF;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAchF;AAID,qBAAa,sBAAsB;IACjC,OAAO,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,aAAa;IAqB7E,aAAa,CAAC,MAAM,EAAE,aAAa,EAAE,UAAU,EAAE,iBAAiB,GAAG,IAAI;CAmC1E;AAID,qBAAa,yBAAyB;IACxB,OAAO,CAAC,QAAQ,CAAC,MAAM;gBAAN,MAAM,EAAE,+BAA+B;IAEpE,OAAO,CAAC,WAAW;IAIb,MAAM,CAAC,MAAM,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC;IAO5C,OAAO,IAAI,OAAO,CAAC,qBAAqB,EAAE,CAAC;CAclD"}

package/dist/context/summary-metrics.js

@@ -0,0 +1,160 @@
+/**
+ * Summary quality metrics: compression ratio, key-fact retention, round-trip preservation.
+ *
+ * Provides pure metric computation functions, a SummaryQualityAnalyzer class, and
+ * QualityMetricsPersistence for recording metrics to a JSONL file.
+ */
+import { appendFile, mkdir, readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+export class QualityBelowThresholdError extends Error {
+    report;
+    failures;
+    constructor(report, failures) {
+        super(`Summary quality below threshold: ${failures.join(', ')}`);
+        this.report = report;
+        this.failures = failures;
+        this.name = 'QualityBelowThresholdError';
+    }
+}
+// ─── Pure Metric Computation Functions ───────────────────────────────────────
+/**
+ * Compute the compression ratio of a summary.
+ * Returns summaryTokenCount / originalTokenCount in [0, 1].
+ * Returns -1 as a sentinel when token counts are absent or originalTokenCount is zero.
+ */
+export function computeCompressionRatio(summary) {
+    if (summary.originalTokenCount === undefined ||
+        summary.originalTokenCount === 0 ||
+        summary.summaryTokenCount === undefined) {
+        return -1;
+    }
+    return summary.summaryTokenCount / summary.originalTokenCount;
+}
+/**
+ * Extract key facts from content:
+ * - Fenced code blocks (triple-backtick)
+ * - File-path tokens matching known extensions
+ * - Error-type names
+ */
+export function extractKeyFacts(content) {
+    const facts = new Set();
+    // Extract fenced code blocks
+    const codeBlockRegex = /```[\s\S]*?```/g;
+    let match;
+    while ((match = codeBlockRegex.exec(content)) !== null) {
+        facts.add(match[0].trim());
+    }
+    // Extract file-path tokens
+    const filePathRegex = /[\w./]+(\.ts|\.js|\.json|\.md|\.go|\.py|\.yaml|\.yml)\b/g;
+    while ((match = filePathRegex.exec(content)) !== null) {
+        facts.add(match[0]);
+    }
+    // Extract error-type names
+    const errorTypeRegex = /\b(Error|Exception|ENOENT|ETIMEDOUT|TypeError|SyntaxError)\b/g;
+    while ((match = errorTypeRegex.exec(content)) !== null) {
+        facts.add(match[0]);
+    }
+    return facts;
+}
+/**
+ * Compute the key-fact retention rate between original and summarized content.
+ * Returns the fraction of original key facts that appear in the summarized content.
+ * Returns 1.0 when the original has no key facts.
+ */
+export function computeKeyFactRetentionRate(original, summarized) {
+    const originalFacts = extractKeyFacts(original);
+    const summarizedFacts = extractKeyFacts(summarized);
+    if (originalFacts.size === 0) {
+        return 1.0;
+    }
+    const preserved = [...originalFacts].filter(f => summarizedFacts.has(f)).length;
+    return preserved / originalFacts.size;
+}
+/**
+ * Compute the round-trip preservation score between original and expanded content.
+ * Uses Jaccard word-set overlap: intersection / union.
+ * Returns 1.0 when both word sets are empty.
+ * Returns 0.0 when exactly one set is non-empty.
+ */
+export function computeRoundTripScore(original, expanded) {
+    const words = (s) => new Set(s.toLowerCase().split(/\W+/).filter(w => w.length > 0));
+    const wordsA = words(original);
+    const wordsB = words(expanded);
+    if (wordsA.size === 0 && wordsB.size === 0) {
+        return 1.0;
+    }
+    const intersection = [...wordsA].filter(w => wordsB.has(w)).length;
+    const union = new Set([...wordsA, ...wordsB]).size;
+    return intersection / union;
+}
+// ─── SummaryQualityAnalyzer ───────────────────────────────────────────────────
+export class SummaryQualityAnalyzer {
+    analyze(original, summary, expanded) {
+        const compressionRatio = computeCompressionRatio(summary);
+        const keyFactRetentionRate = computeKeyFactRetentionRate(original, summary.content);
+        const roundTripScore = expanded !== undefined ? computeRoundTripScore(original, expanded) : null;
+        const overallScore = roundTripScore !== null
+            ? keyFactRetentionRate * 0.6 + roundTripScore * 0.4
+            : keyFactRetentionRate;
+        return {
+            summaryHash: summary.originalHash,
+            level: summary.level,
+            compressionRatio,
+            keyFactRetentionRate,
+            roundTripScore,
+            overallScore,
+            computedAt: new Date().toISOString(),
+        };
+    }
+    assertQuality(report, thresholds) {
+        const failures = [];
+        if (thresholds.minKeyFactRetentionRate !== undefined &&
+            report.keyFactRetentionRate < thresholds.minKeyFactRetentionRate) {
+            failures.push(`keyFactRetentionRate ${report.keyFactRetentionRate.toFixed(3)} < ${thresholds.minKeyFactRetentionRate}`);
+        }
+        if (thresholds.minRoundTripScore !== undefined &&
+            report.roundTripScore !== null &&
+            report.roundTripScore < thresholds.minRoundTripScore) {
+            failures.push(`roundTripScore ${report.roundTripScore.toFixed(3)} < ${thresholds.minRoundTripScore}`);
+        }
+        if (thresholds.minOverallScore !== undefined &&
+            report.overallScore < thresholds.minOverallScore) {
+            failures.push(`overallScore ${report.overallScore.toFixed(3)} < ${thresholds.minOverallScore}`);
+        }
+        if (failures.length > 0) {
+            throw new QualityBelowThresholdError(report, failures);
+        }
+    }
+}
+// ─── QualityMetricsPersistence ────────────────────────────────────────────────
+export class QualityMetricsPersistence {
+    config;
+    constructor(config) {
+        this.config = config;
+    }
+    metricsPath() {
+        return join(this.config.storageDir, 'runs', this.config.runId, 'quality-metrics.jsonl');
+    }
+    async record(report) {
+        const dir = join(this.config.storageDir, 'runs', this.config.runId);
+        await mkdir(dir, { recursive: true });
+        const entry = { ...report, recordedAt: new Date().toISOString() };
+        await appendFile(this.metricsPath(), JSON.stringify(entry) + '\n', 'utf-8');
+    }
+    async readAll() {
+        try {
+            const raw = await readFile(this.metricsPath(), 'utf-8');
+            return raw
+                .split('\n')
+                .filter(line => line.length > 0)
+                .map(line => JSON.parse(line));
+        }
+        catch (err) {
+            if (typeof err === 'object' && err !== null && err.code === 'ENOENT') {
+                return [];
+            }
+            throw err;
+        }
+    }
+}
+//# sourceMappingURL=summary-metrics.js.map

package/dist/context/summary-metrics.js.map

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

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

@@ -0,0 +1,103 @@
+/**
+ * Summary level definitions and context budget types for reversible context compression.
+ *
+ * No runtime imports — pure TypeScript type/interface/const declarations only.
+ */
+/**
+ * The level of summarization to apply to a context.
+ *
+ * - `full`: No compression — the entire context is preserved (100% of token budget).
+ * - `high`: Light compression — major details preserved (75% of token budget).
+ * - `medium`: Moderate compression — key decisions, code blocks, and errors preserved (50% of token budget).
+ * - `low`: Aggressive compression — only the most essential information preserved (25% of token budget).
+ */
+export type SummaryLevel = 'full' | 'high' | 'medium' | 'low';
+/**
+ * Token-budget fraction for each summary level.
+ * Multiply by the model's token limit to get the target token count.
+ */
+export declare const SUMMARY_BUDGET: Record<SummaryLevel, number>;
+/**
+ * The default summary level to use when none is specified.
+ * Balances compression ratio and information preservation.
+ */
+export declare const DEFAULT_SUMMARY_LEVEL: SummaryLevel;
+/**
+ * The result produced by a summarization operation.
+ * Contains the summarized content along with provenance metadata
+ * to support lossless or near-lossless expansion.
+ */
+export interface Summary {
+    /** The summary level that was applied */
+    level: SummaryLevel;
+    /** The summarized content */
+    content: string;
+    /** SHA-256 hex digest of the original content (before summarization) */
+    originalHash: string;
+    /** ISO-8601 timestamp of when the summary was created */
+    createdAt: string;
+    /** Token count of the original content, if known */
+    originalTokenCount?: number;
+    /** Token count of the summarized content, if known */
+    summaryTokenCount?: number;
+    /**
+     * The pipeline iteration index this summary was created for.
+     * Used by `factory context summarize/expand/stats` CLI commands to map
+     * iteration numbers to stored summary hashes.
+     */
+    iterationIndex?: number;
+    /** Additional arbitrary metadata from the summarization engine */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Options for a summarize() call.
+ * All boolean fields default to `true` in implementations to maximize recoverability.
+ */
+export interface SummarizeOptions {
+    /** The model's maximum token limit — used to compute the target token count */
+    modelTokenLimit?: number;
+    /** Whether to preserve code blocks verbatim (default: true) */
+    preserveCodeBlocks?: boolean;
+    /** Whether to preserve file paths (default: true) */
+    preserveFilePaths?: boolean;
+    /** Whether to preserve error messages verbatim (default: true) */
+    preserveErrorMessages?: boolean;
+}
+/**
+ * Options for an expand() call.
+ */
+export interface ExpandOptions {
+    /**
+     * The original content before summarization.
+     * When provided, implementations may use it for lossless expansion
+     * (e.g., by re-injecting preserved sections).
+     */
+    originalContent?: string;
+    /** Additional arbitrary metadata to guide expansion */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Describes the token budget for a particular summarization level
+ * relative to a model's token limit.
+ */
+export interface ContextBudget {
+    /** The model's maximum token limit */
+    modelTokenLimit: number;
+    /** The summary level this budget corresponds to */
+    level: SummaryLevel;
+    /** Target token count = Math.floor(modelTokenLimit * SUMMARY_BUDGET[level]) */
+    targetTokenCount: number;
+    /** The compression ratio = SUMMARY_BUDGET[level] */
+    compressionRatio: number;
+}
+/**
+ * Compute the context budget for a given model token limit and summary level.
+ *
+ * Pure function — no I/O, no async, no external imports.
+ *
+ * @param modelTokenLimit - The model's maximum token limit
+ * @param level - The desired summary level
+ * @returns A fully populated ContextBudget object
+ */
+export declare function computeBudget(modelTokenLimit: number, level: SummaryLevel): ContextBudget;
+//# sourceMappingURL=summary-types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"summary-types.d.ts","sourceRoot":"","sources":["../../src/context/summary-types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;;;;;GAOG;AACH,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,MAAM,GAAG,QAAQ,GAAG,KAAK,CAAA;AAE7D;;;GAGG;AACH,eAAO,MAAM,cAAc,EAAE,MAAM,CAAC,YAAY,EAAE,MAAM,CAKvD,CAAA;AAED;;;GAGG;AACH,eAAO,MAAM,qBAAqB,EAAE,YAAuB,CAAA;AAE3D;;;;GAIG;AACH,MAAM,WAAW,OAAO;IACtB,yCAAyC;IACzC,KAAK,EAAE,YAAY,CAAA;IACnB,6BAA6B;IAC7B,OAAO,EAAE,MAAM,CAAA;IACf,wEAAwE;IACxE,YAAY,EAAE,MAAM,CAAA;IACpB,yDAAyD;IACzD,SAAS,EAAE,MAAM,CAAA;IACjB,oDAAoD;IACpD,kBAAkB,CAAC,EAAE,MAAM,CAAA;IAC3B,sDAAsD;IACtD,iBAAiB,CAAC,EAAE,MAAM,CAAA;IAC1B;;;;OAIG;IACH,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,kEAAkE;IAClE,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CACnC;AAED;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC/B,+EAA+E;IAC/E,eAAe,CAAC,EAAE,MAAM,CAAA;IACxB,+DAA+D;IAC/D,kBAAkB,CAAC,EAAE,OAAO,CAAA;IAC5B,qDAAqD;IACrD,iBAAiB,CAAC,EAAE,OAAO,CAAA;IAC3B,kEAAkE;IAClE,qBAAqB,CAAC,EAAE,OAAO,CAAA;CAChC;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B;;;;OAIG;IACH,eAAe,CAAC,EAAE,MAAM,CAAA;IACxB,uDAAuD;IACvD,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CACnC;AAED;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC5B,sCAAsC;IACtC,eAAe,EAAE,MAAM,CAAA;IACvB,mDAAmD;IACnD,KAAK,EAAE,YAAY,CAAA;IACnB,+EAA+E;IAC/E,gBAAgB,EAAE,MAAM,CAAA;IACxB,oDAAoD;IACpD,gBAAgB,EAAE,MAAM,CAAA;CACzB;AAED;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,eAAe,EAAE,MAAM,EAAE,KAAK,EAAE,YAAY,GAAG,aAAa,CAQzF"}

package/dist/context/summary-types.js

@@ -0,0 +1,39 @@
+/**
+ * Summary level definitions and context budget types for reversible context compression.
+ *
+ * No runtime imports — pure TypeScript type/interface/const declarations only.
+ */
+/**
+ * Token-budget fraction for each summary level.
+ * Multiply by the model's token limit to get the target token count.
+ */
+export const SUMMARY_BUDGET = {
+    full: 1.0,
+    high: 0.75,
+    medium: 0.50,
+    low: 0.25,
+};
+/**
+ * The default summary level to use when none is specified.
+ * Balances compression ratio and information preservation.
+ */
+export const DEFAULT_SUMMARY_LEVEL = 'medium';
+/**
+ * Compute the context budget for a given model token limit and summary level.
+ *
+ * Pure function — no I/O, no async, no external imports.
+ *
+ * @param modelTokenLimit - The model's maximum token limit
+ * @param level - The desired summary level
+ * @returns A fully populated ContextBudget object
+ */
+export function computeBudget(modelTokenLimit, level) {
+    const compressionRatio = SUMMARY_BUDGET[level];
+    return {
+        modelTokenLimit,
+        level,
+        targetTokenCount: Math.floor(modelTokenLimit * compressionRatio),
+        compressionRatio,
+    };
+}
+//# sourceMappingURL=summary-types.js.map

package/dist/context/summary-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"summary-types.js","sourceRoot":"","sources":["../../src/context/summary-types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAYH;;;GAGG;AACH,MAAM,CAAC,MAAM,cAAc,GAAiC;IAC1D,IAAI,EAAE,GAAG;IACT,IAAI,EAAE,IAAI;IACV,MAAM,EAAE,IAAI;IACZ,GAAG,EAAE,IAAI;CACV,CAAA;AAED;;;GAGG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAiB,QAAQ,CAAA;AA0E3D;;;;;;;;GAQG;AACH,MAAM,UAAU,aAAa,CAAC,eAAuB,EAAE,KAAmB;IACxE,MAAM,gBAAgB,GAAG,cAAc,CAAC,KAAK,CAAC,CAAA;IAC9C,OAAO;QACL,eAAe;QACf,KAAK;QACL,gBAAgB,EAAE,IAAI,CAAC,KAAK,CAAC,eAAe,GAAG,gBAAgB,CAAC;QAChE,gBAAgB;KACjB,CAAA;AACH,CAAC"}

package/dist/convergence/__tests__/budget.test.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Unit tests for per-node budget enforcement.
+ * Story 45-3 — AC1 through AC7.
+ */
+export {};
+//# sourceMappingURL=budget.test.d.ts.map

package/dist/convergence/__tests__/budget.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"budget.test.d.ts","sourceRoot":"","sources":["../../../src/convergence/__tests__/budget.test.ts"],"names":[],"mappings":"AAAA;;;GAGG"}