praana 0.5.0

package/dist/context-engine/db.js

@@ -0,0 +1,505 @@
+import Database from "better-sqlite3";
+const ARTIFACT_SCHEMA = `
+CREATE TABLE IF NOT EXISTS context_artifacts (
+  id                  TEXT PRIMARY KEY,
+  sha256              TEXT NOT NULL,
+  session_id          TEXT NOT NULL,
+  source_tool         TEXT NOT NULL,
+  command             TEXT,
+  created_turn        INTEGER NOT NULL,
+  raw_tokens          INTEGER NOT NULL,
+  raw_text            TEXT NOT NULL,
+  summary             TEXT NOT NULL,
+  content_type        TEXT NOT NULL,
+  last_accessed_turn  INTEGER NOT NULL,
+  access_count        INTEGER NOT NULL DEFAULT 0,
+  created_at          INTEGER NOT NULL
+);
+
+CREATE INDEX IF NOT EXISTS idx_context_artifacts_session
+  ON context_artifacts(session_id);
+CREATE INDEX IF NOT EXISTS idx_context_artifacts_sha256
+  ON context_artifacts(sha256);
+
+CREATE TABLE IF NOT EXISTS distiller_stats (
+  id            INTEGER PRIMARY KEY AUTOINCREMENT,
+  session_id    TEXT NOT NULL,
+  tool          TEXT NOT NULL,
+  content_type  TEXT NOT NULL,
+  distiller     TEXT NOT NULL,
+  input_tokens  INTEGER NOT NULL,
+  output_tokens INTEGER NOT NULL,
+  savings_pct   REAL NOT NULL,
+  exec_time_ms  INTEGER NOT NULL,
+  turn          INTEGER NOT NULL,
+  created_at    INTEGER NOT NULL
+);
+
+CREATE INDEX IF NOT EXISTS idx_distiller_stats_session
+  ON distiller_stats(session_id);
+
+CREATE TABLE IF NOT EXISTS turn_ledger (
+  session_id          TEXT NOT NULL,
+  turn                INTEGER NOT NULL,
+  user_message        TEXT NOT NULL,
+  assistant_message   TEXT NOT NULL,
+  tool_calls_json     TEXT NOT NULL,
+  artifact_ids_json   TEXT NOT NULL,
+  files_read_json     TEXT NOT NULL,
+  files_written_json  TEXT NOT NULL,
+  errors_json         TEXT NOT NULL,
+  token_count         INTEGER NOT NULL,
+  search_text         TEXT NOT NULL,
+  timestamp           INTEGER NOT NULL,
+  PRIMARY KEY (session_id, turn)
+);
+
+CREATE INDEX IF NOT EXISTS idx_turn_ledger_session
+  ON turn_ledger(session_id);
+
+CREATE TABLE IF NOT EXISTS turn_digests (
+  session_id   TEXT NOT NULL,
+  turn         INTEGER NOT NULL,
+  digest_json  TEXT NOT NULL,
+  created_at   INTEGER NOT NULL,
+  PRIMARY KEY (session_id, turn)
+);
+
+CREATE TABLE IF NOT EXISTS activity_log (
+  id           INTEGER PRIMARY KEY AUTOINCREMENT,
+  session_id   TEXT NOT NULL,
+  turn         INTEGER NOT NULL,
+  type         TEXT NOT NULL,
+  summary      TEXT NOT NULL,
+  artifact_ref TEXT,
+  created_at   INTEGER NOT NULL
+);
+
+CREATE INDEX IF NOT EXISTS idx_activity_log_session
+  ON activity_log(session_id, id DESC);
+
+CREATE TABLE IF NOT EXISTS extraction_state (
+  session_id   TEXT PRIMARY KEY,
+  state_json   TEXT NOT NULL,
+  updated_at   INTEGER NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS session_checkpoints (
+  session_id       TEXT PRIMARY KEY,
+  checkpoint_json  TEXT NOT NULL,
+  updated_at       INTEGER NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS artifact_access (
+  id            INTEGER PRIMARY KEY AUTOINCREMENT,
+  artifact_id   TEXT NOT NULL,
+  session_id    TEXT NOT NULL,
+  access_type   TEXT NOT NULL,
+  turn          INTEGER NOT NULL,
+  created_at    INTEGER NOT NULL
+);
+
+CREATE INDEX IF NOT EXISTS idx_artifact_access_session
+  ON artifact_access(session_id, artifact_id);
+
+CREATE TABLE IF NOT EXISTS session_stats (
+  session_id              TEXT PRIMARY KEY,
+  context_engine_enabled  INTEGER NOT NULL DEFAULT 0,
+  pressure_events         INTEGER NOT NULL DEFAULT 0,
+  compaction_triggers     INTEGER NOT NULL DEFAULT 0,
+  artifact_retrievals     INTEGER NOT NULL DEFAULT 0,
+  total_distiller_savings REAL NOT NULL DEFAULT 0,
+  total_turns             INTEGER NOT NULL DEFAULT 0,
+  updated_at              INTEGER NOT NULL
+);
+`;
+export function openContextEngineDb(dbPath) {
+    const db = new Database(dbPath);
+    db.pragma("journal_mode = WAL");
+    db.exec(ARTIFACT_SCHEMA);
+    return db;
+}
+function rowToArtifact(row) {
+    return {
+        id: row.id,
+        sha256: row.sha256,
+        sessionId: row.session_id,
+        sourceTool: row.source_tool,
+        command: row.command ?? undefined,
+        createdTurn: row.created_turn,
+        rawTokens: row.raw_tokens,
+        rawText: row.raw_text,
+        summary: row.summary,
+        contentType: row.content_type,
+        lastAccessedTurn: row.last_accessed_turn,
+        accessCount: row.access_count,
+    };
+}
+export function findArtifactByHash(db, sha256) {
+    const row = db
+        .prepare("SELECT * FROM context_artifacts WHERE sha256 = ? LIMIT 1")
+        .get(sha256);
+    return row ? rowToArtifact(row) : null;
+}
+export function getArtifactById(db, id) {
+    const row = db
+        .prepare("SELECT * FROM context_artifacts WHERE id = ?")
+        .get(id);
+    return row ? rowToArtifact(row) : null;
+}
+export function insertArtifact(db, artifact) {
+    db.prepare(`INSERT INTO context_artifacts (
+      id, sha256, session_id, source_tool, command, created_turn,
+      raw_tokens, raw_text, summary, content_type,
+      last_accessed_turn, access_count, created_at
+    ) VALUES (
+      @id, @sha256, @sessionId, @sourceTool, @command, @createdTurn,
+      @rawTokens, @rawText, @summary, @contentType,
+      @lastAccessedTurn, @accessCount, @createdAt
+    )`).run({
+        id: artifact.id,
+        sha256: artifact.sha256,
+        sessionId: artifact.sessionId,
+        sourceTool: artifact.sourceTool,
+        command: artifact.command ?? null,
+        createdTurn: artifact.createdTurn,
+        rawTokens: artifact.rawTokens,
+        rawText: artifact.rawText,
+        summary: artifact.summary,
+        contentType: artifact.contentType,
+        lastAccessedTurn: artifact.lastAccessedTurn,
+        accessCount: artifact.accessCount,
+        createdAt: Date.now(),
+    });
+}
+export function touchArtifactAccess(db, id, turn) {
+    db.prepare(`UPDATE context_artifacts
+     SET last_accessed_turn = @turn, access_count = access_count + 1
+     WHERE id = @id`).run({ id, turn });
+}
+export function updateArtifactSummary(db, id, summary) {
+    db.prepare("UPDATE context_artifacts SET summary = @summary WHERE id = @id").run({
+        id,
+        summary,
+    });
+}
+export function insertDistillerStat(db, row) {
+    db.prepare(`INSERT INTO distiller_stats (
+      session_id, tool, content_type, distiller,
+      input_tokens, output_tokens, savings_pct, exec_time_ms, turn, created_at
+    ) VALUES (
+      @sessionId, @tool, @contentType, @distiller,
+      @inputTokens, @outputTokens, @savingsPct, @execTimeMs, @turn, @createdAt
+    )`).run({
+        sessionId: row.sessionId,
+        tool: row.tool,
+        contentType: row.contentType,
+        distiller: row.distiller,
+        inputTokens: row.inputTokens,
+        outputTokens: row.outputTokens,
+        savingsPct: row.savingsPct,
+        execTimeMs: row.execTimeMs,
+        turn: row.turn,
+        createdAt: Date.now(),
+    });
+}
+export function evictStaleArtifacts(db, currentTurn, ttlTurns) {
+    const cutoff = currentTurn - ttlTurns;
+    const extendedCutoff = currentTurn - ttlTurns * 2;
+    const result = db
+        .prepare(`DELETE FROM context_artifacts
+       WHERE (access_count < 4 AND last_accessed_turn < @cutoff)
+          OR (access_count >= 4 AND last_accessed_turn < @extendedCutoff)`)
+        .run({ cutoff, extendedCutoff });
+    return result.changes;
+}
+function rowToTurnRecord(row) {
+    return {
+        turn: row.turn,
+        userMessage: row.user_message,
+        assistantMessage: row.assistant_message,
+        toolCalls: JSON.parse(row.tool_calls_json),
+        artifactIds: JSON.parse(row.artifact_ids_json),
+        filesRead: JSON.parse(row.files_read_json),
+        filesWritten: JSON.parse(row.files_written_json),
+        errors: JSON.parse(row.errors_json),
+        tokenCount: row.token_count,
+        timestamp: row.timestamp,
+    };
+}
+export function getMaxLedgerTurn(db, sessionId) {
+    const row = db
+        .prepare("SELECT MAX(turn) AS max_turn FROM turn_ledger WHERE session_id = ?")
+        .get(sessionId);
+    return row?.max_turn ?? null;
+}
+export function hasLedgerTurn(db, sessionId, turn) {
+    const row = db
+        .prepare("SELECT 1 FROM turn_ledger WHERE session_id = ? AND turn = ? LIMIT 1")
+        .get(sessionId, turn);
+    return !!row;
+}
+export function insertTurnRecord(db, sessionId, record, searchText) {
+    db.prepare(`INSERT OR IGNORE INTO turn_ledger (
+      session_id, turn, user_message, assistant_message,
+      tool_calls_json, artifact_ids_json, files_read_json, files_written_json,
+      errors_json, token_count, search_text, timestamp
+    ) VALUES (
+      @sessionId, @turn, @userMessage, @assistantMessage,
+      @toolCallsJson, @artifactIdsJson, @filesReadJson, @filesWrittenJson,
+      @errorsJson, @tokenCount, @searchText, @timestamp
+    )`).run({
+        sessionId,
+        turn: record.turn,
+        userMessage: record.userMessage,
+        assistantMessage: record.assistantMessage,
+        toolCallsJson: JSON.stringify(record.toolCalls),
+        artifactIdsJson: JSON.stringify(record.artifactIds),
+        filesReadJson: JSON.stringify(record.filesRead),
+        filesWrittenJson: JSON.stringify(record.filesWritten),
+        errorsJson: JSON.stringify(record.errors),
+        tokenCount: record.tokenCount,
+        searchText,
+        timestamp: record.timestamp,
+    });
+}
+export function listTurnRecords(db, sessionId) {
+    const rows = db
+        .prepare(`SELECT * FROM turn_ledger
+       WHERE session_id = ?
+       ORDER BY turn ASC`)
+        .all(sessionId);
+    return rows.map(rowToTurnRecord);
+}
+export function getTurnRecord(db, sessionId, turn) {
+    const row = db
+        .prepare("SELECT * FROM turn_ledger WHERE session_id = ? AND turn = ?")
+        .get(sessionId, turn);
+    return row ? rowToTurnRecord(row) : null;
+}
+export function listArtifactIdsForTurn(db, sessionId, turn) {
+    const rows = db
+        .prepare(`SELECT id FROM context_artifacts
+       WHERE session_id = ? AND created_turn = ?`)
+        .all(sessionId, turn);
+    return rows.map((r) => r.id);
+}
+export function insertTurnDigest(db, sessionId, digest) {
+    db.prepare(`INSERT OR REPLACE INTO turn_digests (session_id, turn, digest_json, created_at)
+     VALUES (@sessionId, @turn, @digestJson, @createdAt)`).run({
+        sessionId,
+        turn: digest.turnId,
+        digestJson: JSON.stringify(digest),
+        createdAt: Date.now(),
+    });
+}
+export function insertActivityEntries(db, sessionId, entries) {
+    if (entries.length === 0)
+        return;
+    const stmt = db.prepare(`INSERT INTO activity_log (session_id, turn, type, summary, artifact_ref, created_at)
+     VALUES (@sessionId, @turn, @type, @summary, @artifactRef, @createdAt)`);
+    const createdAt = Date.now();
+    for (const entry of entries) {
+        stmt.run({
+            sessionId,
+            turn: entry.turn,
+            type: entry.type,
+            summary: entry.summary,
+            artifactRef: entry.artifactRef ?? null,
+            createdAt,
+        });
+    }
+}
+export function listActivityEntries(db, sessionId, limit) {
+    const rows = db
+        .prepare(`SELECT turn, type, summary, artifact_ref
+       FROM activity_log
+       WHERE session_id = ?
+       ORDER BY id DESC
+       LIMIT ?`)
+        .all(sessionId, limit);
+    return rows.reverse().map((row) => ({
+        turn: row.turn,
+        type: row.type,
+        summary: row.summary,
+        artifactRef: row.artifact_ref ?? undefined,
+    }));
+}
+export function getExtractionState(db, sessionId) {
+    const row = db
+        .prepare("SELECT state_json FROM extraction_state WHERE session_id = ?")
+        .get(sessionId);
+    if (!row)
+        return null;
+    return JSON.parse(row.state_json);
+}
+export function upsertExtractionState(db, sessionId, state) {
+    db.prepare(`INSERT INTO extraction_state (session_id, state_json, updated_at)
+     VALUES (@sessionId, @stateJson, @updatedAt)
+     ON CONFLICT(session_id) DO UPDATE SET
+       state_json = excluded.state_json,
+       updated_at = excluded.updated_at`).run({
+        sessionId,
+        stateJson: JSON.stringify(state),
+        updatedAt: Date.now(),
+    });
+}
+export function getSessionCheckpoint(db, sessionId) {
+    const row = db
+        .prepare("SELECT checkpoint_json FROM session_checkpoints WHERE session_id = ?")
+        .get(sessionId);
+    if (!row)
+        return null;
+    return JSON.parse(row.checkpoint_json);
+}
+export function upsertSessionCheckpoint(db, sessionId, checkpoint) {
+    db.prepare(`INSERT INTO session_checkpoints (session_id, checkpoint_json, updated_at)
+     VALUES (@sessionId, @checkpointJson, @updatedAt)
+     ON CONFLICT(session_id) DO UPDATE SET
+       checkpoint_json = excluded.checkpoint_json,
+       updated_at = excluded.updated_at`).run({
+        sessionId,
+        checkpointJson: JSON.stringify(checkpoint),
+        updatedAt: Date.now(),
+    });
+}
+export function getTurnDigest(db, sessionId, turn) {
+    const row = db
+        .prepare("SELECT digest_json FROM turn_digests WHERE session_id = ? AND turn = ?")
+        .get(sessionId, turn);
+    if (!row)
+        return null;
+    return normalizeStoredTurnDigest(JSON.parse(row.digest_json));
+}
+export function listTurnDigests(db, sessionId) {
+    const rows = db
+        .prepare(`SELECT digest_json FROM turn_digests
+       WHERE session_id = ?
+       ORDER BY turn ASC`)
+        .all(sessionId);
+    return rows.map((row) => normalizeStoredTurnDigest(JSON.parse(row.digest_json)));
+}
+function normalizeStoredTurnDigest(raw) {
+    const decisions = (raw.decisions ?? []).map((d) => typeof d === "string" ? { summary: d } : d);
+    return {
+        ...raw,
+        filesWritten: raw.filesWritten ?? [],
+        decisions,
+    };
+}
+export function listSessionArtifacts(db, sessionId) {
+    const rows = db
+        .prepare(`SELECT * FROM context_artifacts
+       WHERE session_id = ?
+       ORDER BY created_turn ASC, id ASC`)
+        .all(sessionId);
+    return rows.map(rowToArtifact);
+}
+export function countSessionArtifacts(db, sessionId) {
+    const row = db
+        .prepare("SELECT COUNT(*) AS count FROM context_artifacts WHERE session_id = ?")
+        .get(sessionId);
+    return row.count;
+}
+export function listAllActivityEntries(db, sessionId) {
+    const rows = db
+        .prepare(`SELECT turn, type, summary, artifact_ref
+       FROM activity_log
+       WHERE session_id = ?
+       ORDER BY id ASC`)
+        .all(sessionId);
+    return rows.map((row) => ({
+        turn: row.turn,
+        type: row.type,
+        summary: row.summary,
+        artifactRef: row.artifact_ref ?? undefined,
+    }));
+}
+export function insertArtifactAccess(db, sessionId, artifactId, accessType, turn) {
+    db.prepare(`INSERT INTO artifact_access (artifact_id, session_id, access_type, turn, created_at)
+     VALUES (@artifactId, @sessionId, @accessType, @turn, @createdAt)`).run({
+        artifactId,
+        sessionId,
+        accessType,
+        turn,
+        createdAt: Date.now(),
+    });
+}
+export function getSessionStatsRow(db, sessionId) {
+    const row = db
+        .prepare(`SELECT session_id, context_engine_enabled, pressure_events, compaction_triggers, artifact_retrievals,
+              total_distiller_savings, total_turns
+       FROM session_stats WHERE session_id = ?`)
+        .get(sessionId);
+    if (!row)
+        return null;
+    return {
+        sessionId: row.session_id,
+        contextEngineEnabled: row.context_engine_enabled === 1,
+        pressureEvents: row.pressure_events,
+        compactionTriggers: row.compaction_triggers,
+        artifactRetrievals: row.artifact_retrievals,
+        totalDistillerSavings: row.total_distiller_savings,
+        totalTurns: row.total_turns,
+    };
+}
+function ensureSessionStatsRow(db, sessionId, contextEngineEnabled = false) {
+    db.prepare(`INSERT OR IGNORE INTO session_stats (
+      session_id, context_engine_enabled, pressure_events, compaction_triggers, artifact_retrievals,
+      total_distiller_savings, total_turns, updated_at
+    ) VALUES (@sessionId, @contextEngineEnabled, 0, 0, 0, 0, 0, @updatedAt)`).run({ sessionId, contextEngineEnabled: contextEngineEnabled ? 1 : 0, updatedAt: Date.now() });
+}
+export function incrementSessionStat(db, sessionId, field, amount = 1, contextEngineEnabled = false) {
+    ensureSessionStatsRow(db, sessionId, contextEngineEnabled);
+    db.prepare(`UPDATE session_stats
+     SET ${field} = ${field} + @amount, updated_at = @updatedAt
+     WHERE session_id = @sessionId`).run({ sessionId, amount, updatedAt: Date.now() });
+}
+export function finalizeSessionStats(db, sessionId, totalTurns, contextEngineEnabled = false) {
+    ensureSessionStatsRow(db, sessionId, contextEngineEnabled);
+    const savingsRow = db
+        .prepare(`SELECT COALESCE(SUM(input_tokens - output_tokens), 0) AS savings
+       FROM distiller_stats WHERE session_id = ?`)
+        .get(sessionId);
+    db.prepare(`UPDATE session_stats
+     SET total_turns = @totalTurns,
+         total_distiller_savings = @savings,
+         context_engine_enabled = @contextEngineEnabled,
+         updated_at = @updatedAt
+     WHERE session_id = @sessionId`).run({
+        sessionId,
+        totalTurns,
+        savings: savingsRow.savings,
+        contextEngineEnabled: contextEngineEnabled ? 1 : 0,
+        updatedAt: Date.now(),
+    });
+    return getSessionStatsRow(db, sessionId);
+}
+export function listDistillerCostRanking(db, sessionId) {
+    const rows = db
+        .prepare(`SELECT distiller, tool,
+              COUNT(*) AS runs,
+              AVG(input_tokens) AS avg_input,
+              AVG(savings_pct) AS avg_savings_pct,
+              SUM(input_tokens * (1.0 - (savings_pct / 100.0))) AS estimated_cost
+       FROM distiller_stats
+       WHERE session_id = ?
+       GROUP BY distiller, tool
+       ORDER BY estimated_cost DESC`)
+        .all(sessionId);
+    return rows.map((row) => ({
+        distiller: row.distiller,
+        tool: row.tool,
+        runs: row.runs,
+        avgInputTokens: Math.round(row.avg_input),
+        avgSavingsPct: Number(row.avg_savings_pct.toFixed(1)),
+        estimatedCost: Math.round(row.estimated_cost),
+    }));
+}
+export function countArtifactAccessByType(db, sessionId, accessType) {
+    const row = db
+        .prepare(`SELECT COUNT(*) AS count FROM artifact_access
+       WHERE session_id = ? AND access_type = ?`)
+        .get(sessionId, accessType);
+    return row.count;
+}

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

@@ -0,0 +1,30 @@
+import type { ContentType } from "./types.js";
+export type DistillerIntensity = "lite" | "full";
+export type DistillerMode = "sync" | "deferred";
+export interface Distiller {
+    readonly name: string;
+    readonly contentTypes: ContentType[];
+    readonly mode: DistillerMode;
+    distill(input: string, intensity: DistillerIntensity, contentType?: ContentType): string;
+}
+export interface DistillResult {
+    summary: string;
+    distillerName: string;
+    execTimeMs: number;
+    deferred: boolean;
+}
+export interface DistillDeferredResult {
+    pendingSummary: string;
+    distillerName: string;
+    backfill: () => Promise<DistillResult>;
+}
+export declare function buildPendingSummary(): string;
+export declare function isPendingSummary(summary: string): boolean;
+export declare class DistillerRegistry {
+    private readonly distillers;
+    register(distiller: Distiller): void;
+    find(contentType: ContentType): Distiller | null;
+    selectIntensity(rawTokens: number, defaultIntensity: DistillerIntensity): DistillerIntensity;
+    distillSync(input: string, contentType: ContentType, intensity: DistillerIntensity): DistillResult;
+    distillForIngestion(input: string, contentType: ContentType, intensity: DistillerIntensity): DistillResult | DistillDeferredResult;
+}

package/dist/context-engine/distiller.js

@@ -0,0 +1,67 @@
+import { summarizeGeneric } from "./summarize.js";
+const PENDING_MARKER = "[compression pending — full content available via retrieve_artifact]";
+export function buildPendingSummary() {
+    return PENDING_MARKER;
+}
+export function isPendingSummary(summary) {
+    return summary.includes(PENDING_MARKER);
+}
+export class DistillerRegistry {
+    distillers = [];
+    register(distiller) {
+        this.distillers.push(distiller);
+    }
+    find(contentType) {
+        return this.distillers.find((d) => d.contentTypes.includes(contentType)) ?? null;
+    }
+    selectIntensity(rawTokens, defaultIntensity) {
+        if (rawTokens > 2000)
+            return "full";
+        if (rawTokens > 400)
+            return "lite";
+        return defaultIntensity;
+    }
+    distillSync(input, contentType, intensity) {
+        const distiller = this.find(contentType);
+        const start = performance.now();
+        if (!distiller || distiller.mode === "deferred") {
+            const summary = summarizeGeneric(input, contentType);
+            return {
+                summary,
+                distillerName: distiller?.name ?? "generic-fallback",
+                execTimeMs: performance.now() - start,
+                deferred: false,
+            };
+        }
+        const summary = distiller.distill(input, intensity, contentType);
+        return {
+            summary,
+            distillerName: distiller.name,
+            execTimeMs: performance.now() - start,
+            deferred: false,
+        };
+    }
+    distillForIngestion(input, contentType, intensity) {
+        const distiller = this.find(contentType);
+        if (!distiller) {
+            return this.distillSync(input, contentType, intensity);
+        }
+        if (distiller.mode === "deferred") {
+            return {
+                pendingSummary: buildPendingSummary(),
+                distillerName: distiller.name,
+                backfill: async () => {
+                    const start = performance.now();
+                    const summary = distiller.distill(input, intensity, contentType);
+                    return {
+                        summary,
+                        distillerName: distiller.name,
+                        execTimeMs: performance.now() - start,
+                        deferred: true,
+                    };
+                },
+            };
+        }
+        return this.distillSync(input, contentType, intensity);
+    }
+}

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

@@ -0,0 +1,23 @@
+import type { CompileInput, CompileMetrics } from "../compiler.js";
+import { recencyScore, scoreContextUnit } from "./scoring.js";
+import type { ActivityEntry, CompileScoreRecord, PressureMode, TurnRecord } from "./types.js";
+import type { ContextEngineConfig } from "../types.js";
+export interface EngineCompileInput extends CompileInput {
+    currentTurn: number;
+    turnRecords: TurnRecord[];
+    activityEntries?: ActivityEntry[];
+    engineConfig: ContextEngineConfig;
+    /** Model input context window; pressure is measured against this when set. */
+    contextWindowTokens?: number;
+}
+export interface EngineCompileResult {
+    prompt: string;
+    metrics: CompileMetrics;
+    scoreRecords: CompileScoreRecord[];
+    pressureRatio: number;
+    pressureMode: PressureMode;
+    excludedScoredUnits: number;
+}
+export declare function compileEngineWithMetrics(input: EngineCompileInput): EngineCompileResult;
+export declare function explainUnitScore(unitId: string, records: CompileScoreRecord[], currentTurn: number, userInput: string, weights: ContextEngineConfig["scoring"], bandTokenBudget: number, bandUsedTokens: number): string[];
+export { recencyScore, scoreContextUnit };