praana 0.5.0

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

@@ -0,0 +1,82 @@
+import type { Event } from "../types.js";
+import type { StateGraph } from "../state-graph.js";
+import type { PraanaConfig } from "../types.js";
+import { ArtifactStore } from "./artifact-store.js";
+import { CheckpointStore } from "./checkpoint.js";
+import { type EventLineage } from "./event-lineage.js";
+import { TelemetryRecorder, type SessionTelemetrySummary } from "./telemetry.js";
+import { TurnExtraction } from "./extraction.js";
+import { TurnLedger } from "./turn-ledger.js";
+import type { ContextEngineConfig } from "../types.js";
+import type { ActivityEntry, CheckpointDraft, IngestToolResultInput, IngestToolResultOutput, RetrieveArtifactOptions, SessionCheckpoint, StateSnapshot, TurnDigest, TurnRecord, TurnSearchMatch } from "./types.js";
+export type { ActivityEntry, ActivityEntryType, CheckpointDraft, ContentType, ContextArtifact, OpenError, ToolCallRecord, SessionCheckpoint, TurnDigest, TurnRecord, TurnSearchMatch, } from "./types.js";
+export type { ContextEngineConfig } from "../types.js";
+export { CheckpointStore, renderCheckpoint, renderContextSummary } from "./checkpoint.js";
+export { classifyContentType } from "./classify.js";
+export { estimateTokens } from "./summarize.js";
+export { ArtifactStore } from "./artifact-store.js";
+export { TurnLedger, groupEventsIntoTurns } from "./turn-ledger.js";
+export { TurnRecorder, buildTurnSearchText } from "./turn-recorder.js";
+export { extractTurnDigest, extractUserIntent } from "./turn-digest.js";
+export { snapshotStateGraph } from "./state-snapshot.js";
+export { compileEngineWithMetrics, explainUnitScore } from "./engine-compiler.js";
+export { scoreContextUnit, recencyScore } from "./scoring.js";
+export { buildEventLineage, formatEventLineage, type EventLineage } from "./event-lineage.js";
+export { TelemetryRecorder, renderSessionTelemetrySummary, type SessionTelemetrySummary, } from "./telemetry.js";
+export declare function normalizeContextEngineConfig(config?: Partial<ContextEngineConfig>): ContextEngineConfig;
+export declare function resolveContextEngineConfig(config: PraanaConfig): ContextEngineConfig;
+export declare function isContextEngineEnabled(config: PraanaConfig): boolean;
+export declare function resolveContextDbPath(config: PraanaConfig, cwd: string): string;
+export declare class ContextEngine {
+    readonly store: ArtifactStore;
+    readonly ledger: TurnLedger;
+    readonly extraction: TurnExtraction;
+    readonly checkpoint: CheckpointStore | null;
+    readonly telemetry: TelemetryRecorder;
+    private readonly config;
+    private constructor();
+    static open(dbPath: string, sessionId: string, config: Partial<ContextEngineConfig> & Pick<ContextEngineConfig, "enabled">): ContextEngine;
+    runStartupMaintenance(currentTurn: number): number;
+    runShutdownMaintenance(currentTurn: number): number;
+    migrateLedgerFromEvents(events: Event[]): number;
+    captureStateSnapshot(stateGraph: StateGraph): StateSnapshot;
+    ingestToolResult(input: IngestToolResultInput): IngestToolResultOutput;
+    flushDeferredDistillation(): Promise<number>;
+    appendTurn(record: TurnRecord): void;
+    processTurnExtraction(input: {
+        userMessage: string;
+        record: TurnRecord;
+        stateBefore: StateSnapshot;
+        stateGraph: StateGraph;
+    }): TurnDigest;
+    getRecentActivity(): ActivityEntry[];
+    getCheckpointDraft(): CheckpointDraft;
+    getLatestDigest(): TurnDigest | null;
+    renderCheckpointSection(): string | null;
+    renderContextSummary(): string;
+    getSessionCheckpoint(): SessionCheckpoint | null;
+    recordCompileTelemetry(input: {
+        turn: number;
+        pressureMode: import("./types.js").PressureMode;
+        excludedScoredUnits: number;
+    }): void;
+    finalizeTelemetry(totalTurns: number): SessionTelemetrySummary;
+    renderTelemetrySummary(totalTurns: number): string;
+    searchTurnEvents(query: string, limit?: number, currentTurn?: number): TurnSearchMatch[];
+    eventLineage(artifactId: string, currentTurn: number): {
+        ok: true;
+        lineage: EventLineage;
+        text: string;
+    } | {
+        ok: false;
+        error: string;
+    };
+    retrieveArtifact(id: string, currentTurn: number, options?: RetrieveArtifactOptions): {
+        ok: true;
+        content: string;
+    } | {
+        ok: false;
+        error: string;
+    };
+    close(): void;
+}

package/dist/context-engine/index.js

@@ -0,0 +1,238 @@
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { resolveDefaultMemoryDbPath } from "../app-identity.js";
+import { ArtifactStore } from "./artifact-store.js";
+import { CheckpointStore, renderContextSummary as formatContextSummary } from "./checkpoint.js";
+import { buildEventLineage, formatEventLineage, } from "./event-lineage.js";
+import { getTurnDigest, listSessionArtifacts } from "./db.js";
+import { renderSessionTelemetrySummary, TelemetryRecorder, } from "./telemetry.js";
+import { TurnExtraction } from "./extraction.js";
+import { TurnLedger } from "./turn-ledger.js";
+export { CheckpointStore, renderCheckpoint, renderContextSummary } from "./checkpoint.js";
+export { classifyContentType } from "./classify.js";
+export { estimateTokens } from "./summarize.js";
+export { ArtifactStore } from "./artifact-store.js";
+export { TurnLedger, groupEventsIntoTurns } from "./turn-ledger.js";
+export { TurnRecorder, buildTurnSearchText } from "./turn-recorder.js";
+export { extractTurnDigest, extractUserIntent } from "./turn-digest.js";
+export { snapshotStateGraph } from "./state-snapshot.js";
+export { compileEngineWithMetrics, explainUnitScore } from "./engine-compiler.js";
+export { scoreContextUnit, recencyScore } from "./scoring.js";
+export { buildEventLineage, formatEventLineage } from "./event-lineage.js";
+export { TelemetryRecorder, renderSessionTelemetrySummary, } from "./telemetry.js";
+const CONTEXT_ENGINE_DEFAULTS = {
+    enabled: true,
+    measurement_mode: false,
+    artifact_inline_threshold: 400,
+    artifact_ttl_turns: 50,
+    distiller: { default_intensity: "full" },
+    llm_digest: false,
+    activity_log_max_entries: 15,
+    checkpoint_enabled: true,
+    scoring: {
+        w_pin: 1.0,
+        w_recency: 0.5,
+        w_relevance: 0.3,
+    },
+    pressure: {
+        compact_at: 0.7,
+        emergency_at: 0.85,
+    },
+};
+export function normalizeContextEngineConfig(config = {}) {
+    return {
+        ...CONTEXT_ENGINE_DEFAULTS,
+        ...config,
+        distiller: {
+            ...CONTEXT_ENGINE_DEFAULTS.distiller,
+            ...(config.distiller ?? {}),
+        },
+        scoring: {
+            ...CONTEXT_ENGINE_DEFAULTS.scoring,
+            ...(config.scoring ?? {}),
+        },
+        pressure: {
+            ...CONTEXT_ENGINE_DEFAULTS.pressure,
+            ...(config.pressure ?? {}),
+        },
+    };
+}
+export function resolveContextEngineConfig(config) {
+    return normalizeContextEngineConfig(config.context_engine ?? {});
+}
+export function isContextEngineEnabled(config) {
+    return resolveContextEngineConfig(config).enabled;
+}
+export function resolveContextDbPath(config, cwd) {
+    const configuredPath = config.memory?.db_path;
+    if (configuredPath) {
+        const expanded = expandHome(configuredPath);
+        return expanded.startsWith("/") ? expanded : join(cwd, expanded);
+    }
+    return resolveDefaultMemoryDbPath();
+}
+function expandHome(p) {
+    return p.startsWith("~/") ? p.replace(/^~\//, `${homedir()}/`) : p;
+}
+export class ContextEngine {
+    store;
+    ledger;
+    extraction;
+    checkpoint;
+    telemetry;
+    config;
+    constructor(store, ledger, extraction, checkpoint, telemetry, config) {
+        this.store = store;
+        this.ledger = ledger;
+        this.extraction = extraction;
+        this.checkpoint = checkpoint;
+        this.telemetry = telemetry;
+        this.config = config;
+    }
+    static open(dbPath, sessionId, config) {
+        const resolved = normalizeContextEngineConfig(config);
+        const store = ArtifactStore.open(dbPath, sessionId, resolved);
+        const ledger = new TurnLedger(store.getDb(), sessionId);
+        const extraction = new TurnExtraction(store.getDb(), sessionId, resolved);
+        const checkpoint = resolved.checkpoint_enabled
+            ? CheckpointStore.open(store.getDb(), sessionId)
+            : null;
+        const telemetry = new TelemetryRecorder(store.getDb(), sessionId, resolved.enabled);
+        return new ContextEngine(store, ledger, extraction, checkpoint, telemetry, resolved);
+    }
+    runStartupMaintenance(currentTurn) {
+        return this.store.runEviction(currentTurn);
+    }
+    runShutdownMaintenance(currentTurn) {
+        return this.store.runEviction(currentTurn);
+    }
+    migrateLedgerFromEvents(events) {
+        return this.ledger.migrateFromEvents(events);
+    }
+    captureStateSnapshot(stateGraph) {
+        return this.extraction.captureStateSnapshot(stateGraph);
+    }
+    ingestToolResult(input) {
+        return this.store.ingestToolResult(input);
+    }
+    async flushDeferredDistillation() {
+        return this.store.flushDeferredDistillation();
+    }
+    appendTurn(record) {
+        this.ledger.append(record);
+    }
+    processTurnExtraction(input) {
+        const digest = this.extraction.processTurn(input);
+        if (this.checkpoint) {
+            this.checkpoint.reconcile(digest, this.extraction.getCheckpointDraft(), digest.turnId);
+            this.checkpoint.persist();
+        }
+        return digest;
+    }
+    getRecentActivity() {
+        return this.extraction.getRecentActivity();
+    }
+    getCheckpointDraft() {
+        return this.extraction.getCheckpointDraft();
+    }
+    getLatestDigest() {
+        return this.extraction.getLatestDigest();
+    }
+    renderCheckpointSection() {
+        if (!this.checkpoint)
+            return null;
+        const rendered = this.checkpoint.render();
+        return rendered.length > 0 ? rendered : null;
+    }
+    renderContextSummary() {
+        const artifactCount = this.store.countArtifacts();
+        if (this.checkpoint) {
+            return this.checkpoint.renderContextSummary({ artifactCount });
+        }
+        const draft = this.extraction.getCheckpointDraft();
+        return draft.lastUserIntent
+            ? formatContextSummary({
+                version: 1,
+                state: {
+                    activeRequest: draft.lastUserIntent,
+                    plans: [],
+                    constraints: draft.recentConstraints,
+                    decisions: draft.recentDecisions.map((d) => ({ ...d, compact: false })),
+                    files: [],
+                    findings: [],
+                    errors: draft.openErrors.map((e) => ({
+                        key: e.key,
+                        message: e.message,
+                        turn: e.turn,
+                        fixed: false,
+                    })),
+                    questions: [],
+                    activity: draft.recentActivity,
+                    narrative: [],
+                    lastReconciledTurn: -1,
+                },
+            }, { artifactCount })
+            : "## Context Summary\n\nNo checkpoint data yet.";
+    }
+    getSessionCheckpoint() {
+        return this.checkpoint?.getCheckpoint() ?? null;
+    }
+    recordCompileTelemetry(input) {
+        this.telemetry.recordCompileTelemetry(input);
+    }
+    finalizeTelemetry(totalTurns) {
+        return this.telemetry.finalize(totalTurns);
+    }
+    renderTelemetrySummary(totalTurns) {
+        return renderSessionTelemetrySummary(this.finalizeTelemetry(totalTurns));
+    }
+    searchTurnEvents(query, limit = 20, currentTurn) {
+        const matches = this.ledger.search(query, limit);
+        if (currentTurn !== undefined) {
+            for (const match of matches) {
+                for (const artifactId of match.artifactIds) {
+                    this.store.touchAccess(artifactId, currentTurn);
+                }
+            }
+        }
+        return matches;
+    }
+    eventLineage(artifactId, currentTurn) {
+        const artifact = this.store.getArtifact(artifactId);
+        if (!artifact) {
+            return { ok: false, error: `Artifact ${artifactId} not found` };
+        }
+        const sessionId = this.store.getSessionId();
+        const db = this.store.getDb();
+        const turnRecord = this.ledger.get(artifact.createdTurn);
+        const turnDigest = getTurnDigest(db, sessionId, artifact.createdTurn);
+        const checkpoint = this.checkpoint?.getCheckpoint() ?? null;
+        const sessionArtifacts = listSessionArtifacts(db, sessionId);
+        const turnRecords = this.ledger.list();
+        const lineage = buildEventLineage({
+            artifact,
+            turnRecord,
+            turnDigest,
+            checkpoint,
+            sessionArtifacts,
+            turnRecords,
+        });
+        this.store.touchAccess(artifactId, currentTurn);
+        this.telemetry.recordArtifactAccess(artifactId, "retrieved", currentTurn);
+        for (const related of lineage.relatedArtifacts) {
+            this.store.touchAccess(related.id, currentTurn);
+            this.telemetry.recordArtifactAccess(related.id, "retrieved", currentTurn);
+        }
+        return { ok: true, lineage, text: formatEventLineage(lineage) };
+    }
+    retrieveArtifact(id, currentTurn, options) {
+        const result = this.store.retrieve(id, currentTurn, options);
+        if (result.ok) {
+            this.telemetry.recordArtifactAccess(id, "retrieved", currentTurn);
+        }
+        return result;
+    }
+    close() {
+        this.store.close();
+    }
+}

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

@@ -0,0 +1,13 @@
+import type { ContextEngineScoringConfig } from "../types.js";
+import type { ContextUnit, ScoreBreakdown, ScoredContextUnit } from "./types.js";
+export declare function recencyScore(ageTurns: number): number;
+export declare function scoreContextUnit(unit: ContextUnit, currentTurn: number, userInput: string, weights: ContextEngineScoringConfig): {
+    score: number;
+    breakdown: ScoreBreakdown;
+};
+export declare function rankContextUnits(units: ContextUnit[], currentTurn: number, userInput: string, weights: ContextEngineScoringConfig): ScoredContextUnit[];
+export declare function selectUnitsWithinBudget(ranked: ScoredContextUnit[], tokenBudget: number): {
+    included: ScoredContextUnit[];
+    excluded: ScoredContextUnit[];
+};
+export declare function unitTokens(content: string): number;

package/dist/context-engine/scoring.js

@@ -0,0 +1,47 @@
+import { bm25Relevance } from "./bm25.js";
+import { estimateTokens } from "./summarize.js";
+const PIN_BOOST = 1000;
+export function recencyScore(ageTurns) {
+    return 1 / (1 + Math.max(0, ageTurns));
+}
+export function scoreContextUnit(unit, currentTurn, userInput, weights) {
+    const pin = unit.pinned ? PIN_BOOST * weights.w_pin : 0;
+    const age = Math.max(0, currentTurn - unit.sourceTurn);
+    const recency = recencyScore(age) * weights.w_recency;
+    const relevance = bm25Relevance(userInput, unit.content) * weights.w_relevance;
+    return {
+        score: pin + recency + relevance,
+        breakdown: { pin, recency, relevance },
+    };
+}
+export function rankContextUnits(units, currentTurn, userInput, weights) {
+    return units
+        .map((unit) => {
+        const scored = scoreContextUnit(unit, currentTurn, userInput, weights);
+        return { ...unit, ...scored };
+    })
+        .sort((a, b) => b.score - a.score || a.id.localeCompare(b.id));
+}
+export function selectUnitsWithinBudget(ranked, tokenBudget) {
+    const included = [];
+    const excluded = [];
+    let used = 0;
+    for (const unit of ranked) {
+        if (unit.pinned) {
+            included.push(unit);
+            used += unit.tokens;
+            continue;
+        }
+        if (used + unit.tokens <= tokenBudget) {
+            included.push(unit);
+            used += unit.tokens;
+        }
+        else {
+            excluded.push(unit);
+        }
+    }
+    return { included, excluded };
+}
+export function unitTokens(content) {
+    return estimateTokens(content);
+}

package/dist/context-engine/state-snapshot.d.ts

@@ -0,0 +1,8 @@
+import type { StateObject } from "../types.js";
+import type { StateGraph } from "../state-graph.js";
+import type { StateSnapshot, TurnDigestDecision } from "./types.js";
+export declare function snapshotStateGraph(stateGraph: StateGraph): StateSnapshot;
+export declare function diffStateGraph(before: StateSnapshot, afterObjects: StateObject[]): {
+    decisions: TurnDigestDecision[];
+    constraints: string[];
+};

package/dist/context-engine/state-snapshot.js

@@ -0,0 +1,50 @@
+export function snapshotStateGraph(stateGraph) {
+    const objects = new Map();
+    for (const obj of stateGraph.snapshot()) {
+        if (obj.retracted)
+            continue;
+        objects.set(obj.id, {
+            kind: obj.kind,
+            updated: obj.updated,
+            payloadJson: JSON.stringify(obj.payload),
+        });
+    }
+    return { objects };
+}
+export function diffStateGraph(before, afterObjects) {
+    const decisions = [];
+    const constraints = [];
+    for (const obj of afterObjects) {
+        if (obj.retracted)
+            continue;
+        const prev = before.objects.get(obj.id);
+        if (obj.kind === "decision") {
+            const payload = obj.payload;
+            const entry = {
+                summary: payload.summary,
+                rationale: payload.rationale || undefined,
+            };
+            // Omit rationale key entirely if not present — cleaner serialisation
+            if (!entry.rationale)
+                delete entry.rationale;
+            if (!prev) {
+                decisions.push(entry);
+                continue;
+            }
+            if (obj.updated > prev.updated || prev.payloadJson !== JSON.stringify(obj.payload)) {
+                decisions.push(entry);
+            }
+        }
+        if (obj.kind === "constraint") {
+            const text = obj.payload.text;
+            if (!prev) {
+                constraints.push(text);
+                continue;
+            }
+            if (obj.updated > prev.updated || prev.payloadJson !== JSON.stringify(obj.payload)) {
+                constraints.push(text);
+            }
+        }
+    }
+    return { decisions, constraints };
+}

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

@@ -0,0 +1,6 @@
+import type { ContentType } from "./types.js";
+/** Rough token estimate: 1 token ≈ 4 chars. */
+export declare function estimateTokens(text: string): number;
+/** Generic head/tail summary for Phase 1 (specialized distillers land in Phase 2). */
+export declare function summarizeGeneric(rawText: string, contentType: ContentType): string;
+export declare function buildArtifactCard(artifactId: string, sourceTool: string, command: string | undefined, rawTokens: number, summary: string): string;

package/dist/context-engine/summarize.js

@@ -0,0 +1,32 @@
+/** Rough token estimate: 1 token ≈ 4 chars. */
+export function estimateTokens(text) {
+    return Math.ceil(text.length / 4);
+}
+/** Generic head/tail summary for Phase 1 (specialized distillers land in Phase 2). */
+export function summarizeGeneric(rawText, contentType) {
+    if (contentType === "error") {
+        return rawText;
+    }
+    const lines = rawText.split("\n");
+    if (lines.length <= 8 && rawText.length <= 600) {
+        return rawText;
+    }
+    const headChars = 400;
+    const tailChars = 400;
+    if (rawText.length <= headChars + tailChars + 40) {
+        return rawText;
+    }
+    const head = rawText.slice(0, headChars).trimEnd();
+    const tail = rawText.slice(-tailChars).trimStart();
+    const omitted = rawText.length - head.length - tail.length;
+    return `${head}\n… [${omitted.toLocaleString()} chars omitted] …\n${tail}`;
+}
+export function buildArtifactCard(artifactId, sourceTool, command, rawTokens, summary) {
+    const label = command ? `${sourceTool}: ${command}` : sourceTool;
+    const lines = [
+        `[artifact: ${artifactId} | ${label} | ${rawTokens.toLocaleString()} tokens raw]`,
+        summary,
+        `Retrieve: retrieve_artifact("${artifactId}")`,
+    ];
+    return lines.join("\n");
+}

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

@@ -0,0 +1,25 @@
+import type Database from "better-sqlite3";
+import type { PressureMode } from "./types.js";
+import { type ArtifactAccessType, type DistillerCostRow, type SessionStatsRow } from "./db.js";
+export interface CompileTelemetryInput {
+    turn: number;
+    pressureMode: PressureMode;
+    excludedScoredUnits: number;
+}
+export interface SessionTelemetrySummary {
+    stats: SessionStatsRow;
+    artifactsProduced: number;
+    retrievalRate: number;
+    distillerRanking: DistillerCostRow[];
+}
+export declare class TelemetryRecorder {
+    private readonly db;
+    private readonly sessionId;
+    private lastPressureMode;
+    private readonly contextEngineEnabled;
+    constructor(db: Database.Database, sessionId: string, contextEngineEnabled?: boolean);
+    recordArtifactAccess(artifactId: string, accessType: ArtifactAccessType, turn: number): void;
+    recordCompileTelemetry(input: CompileTelemetryInput): void;
+    finalize(totalTurns: number): SessionTelemetrySummary;
+}
+export declare function renderSessionTelemetrySummary(summary: SessionTelemetrySummary): string;

package/dist/context-engine/telemetry.js

@@ -0,0 +1,64 @@
+import { countSessionArtifacts, finalizeSessionStats, incrementSessionStat, insertArtifactAccess, listDistillerCostRanking, } from "./db.js";
+export class TelemetryRecorder {
+    db;
+    sessionId;
+    lastPressureMode = "normal";
+    contextEngineEnabled;
+    constructor(db, sessionId, contextEngineEnabled = true) {
+        this.db = db;
+        this.sessionId = sessionId;
+        this.contextEngineEnabled = contextEngineEnabled;
+    }
+    recordArtifactAccess(artifactId, accessType, turn) {
+        insertArtifactAccess(this.db, this.sessionId, artifactId, accessType, turn);
+        if (accessType === "retrieved") {
+            incrementSessionStat(this.db, this.sessionId, "artifact_retrievals", 1, this.contextEngineEnabled);
+        }
+    }
+    recordCompileTelemetry(input) {
+        if (input.pressureMode !== "normal" && this.lastPressureMode === "normal") {
+            incrementSessionStat(this.db, this.sessionId, "pressure_events", 1, this.contextEngineEnabled);
+        }
+        if (input.pressureMode === "emergency" && this.lastPressureMode === "compact") {
+            incrementSessionStat(this.db, this.sessionId, "pressure_events", 1, this.contextEngineEnabled);
+        }
+        this.lastPressureMode = input.pressureMode;
+        if (input.excludedScoredUnits > 0) {
+            incrementSessionStat(this.db, this.sessionId, "compaction_triggers", 1, this.contextEngineEnabled);
+        }
+    }
+    finalize(totalTurns) {
+        const stats = finalizeSessionStats(this.db, this.sessionId, totalTurns, this.contextEngineEnabled);
+        const artifactsProduced = countSessionArtifacts(this.db, this.sessionId);
+        const retrievalRate = artifactsProduced > 0 ? stats.artifactRetrievals / artifactsProduced : 0;
+        const distillerRanking = listDistillerCostRanking(this.db, this.sessionId);
+        return {
+            stats,
+            artifactsProduced,
+            retrievalRate,
+            distillerRanking,
+        };
+    }
+}
+export function renderSessionTelemetrySummary(summary) {
+    const { stats, artifactsProduced, retrievalRate, distillerRanking } = summary;
+    const lines = [
+        "Context engine telemetry:",
+        `  turns: ${stats.totalTurns}`,
+        `  artifacts produced: ${artifactsProduced}`,
+        `  artifact retrievals: ${stats.artifactRetrievals} (${(retrievalRate * 100).toFixed(1)}% retrieval rate)`,
+        `  distiller token savings: ${Math.round(stats.totalDistillerSavings)}`,
+        `  pressure events: ${stats.pressureEvents}`,
+        `  compaction triggers: ${stats.compactionTriggers}`,
+    ];
+    if (distillerRanking.length > 0) {
+        lines.push("  distiller cost ranking (top 3):");
+        for (const row of distillerRanking.slice(0, 3)) {
+            lines.push(`    - ${row.distiller}/${row.tool}: ${row.runs} runs, ~${row.estimatedCost} residual tokens, ${row.avgSavingsPct}% avg savings`);
+        }
+    }
+    if (retrievalRate > 0.25) {
+        lines.push("  note: retrieval rate >25% — distillers may be too aggressive for some commands");
+    }
+    return lines.join("\n");
+}

package/dist/context-engine/turn-digest.d.ts

@@ -0,0 +1,50 @@
+import type { StateGraph } from "../state-graph.js";
+import type { StateSnapshot, TurnDigest, TurnDigestDecision } from "./types.js";
+export declare function extractUserIntent(userMessage: string): string;
+export declare function buildToolSummary(record: {
+    toolCalls: Array<{
+        tool: string;
+    }>;
+}): string;
+export declare function decisionSummary(decision: TurnDigestDecision | string): string;
+export declare function normalizeTurnDigest(raw: TurnDigest): TurnDigest;
+/**
+ * Extract implicit constraints from user messages.
+ *
+ * **Architecture note:** Regex is a minimal safety net for the most syntactically
+ * unambiguous patterns only. It is NOT the primary mechanism for capturing
+ * implicit knowledge — the system prompt nudge (see `compiler.ts` "Implicit
+ * Knowledge Capture") is the primary mechanism, because the LLM is the
+ * language-understanding component, not regex.
+ *
+ * We only capture patterns where the syntax is unambiguous enough that missing
+ * them would be worse than occasionally over-capturing. Specifically:
+ * - "not X, Y" corrections (the user directly reversing a wrong choice)
+ *
+ * Patterns like "we use", "let's use", "I prefer", "make sure", "how about"
+ * are NOT captured here because they are too variable in natural language.
+ * Those are the LLM's responsibility via the system prompt nudge.
+ */
+export declare function extractImplicitConstraints(userMessage: string): string[];
+export declare function isNarrativeWorthy(digest: TurnDigest, previousIntent?: string): boolean;
+export declare function buildNarrativeEntry(digest: TurnDigest, previousIntent?: string): string | null;
+export declare function extractPlan(assistantMessage: string): string | null;
+export declare function extractPlanItems(planText: string): string[];
+export declare function detectCompletedPlanItems(planItems: string[], digest: TurnDigest): string[];
+export declare function extractTurnDigest(input: {
+    turn: number;
+    userMessage: string;
+    record: {
+        filesRead: string[];
+        filesWritten: string[];
+        assistantMessage: string;
+        toolCalls: Array<{
+            tool: string;
+        }>;
+        artifactIds: string[];
+    };
+    stateBefore: StateSnapshot;
+    stateGraph: StateGraph;
+    errorsNew: string[];
+    errorsFixed: string[];
+}): TurnDigest;