@a13xu/lucid 1.16.2 → 1.19.0

package/build/database.d.ts

@@ -45,6 +45,36 @@ export interface PlanRow {
     created_at: number;
     updated_at: number;
 }
+export interface FileBackupRow {
+    id: number;
+    filepath: string;
+    content: Buffer;
+    content_hash: string;
+    original_size: number;
+    compressed_size: number;
+    reason: string;
+    created_at: number;
+}
+export interface CliSessionRow {
+    session_id: string;
+    started_at: number;
+    last_activity_at: number;
+    prompt_count: number;
+    last_compact_hint_at: number | null;
+    last_clear_hint_at: number | null;
+    last_compact_event_at: number | null;
+    compact_count: number;
+    cwd: string | null;
+}
+export interface TruncateEventRow {
+    id: number;
+    filepath: string;
+    prev_size: number;
+    new_size: number;
+    shrink_ratio: number;
+    blocked: number;
+    created_at: number;
+}
 export interface PlanTaskRow {
     id: number;
     plan_id: number;
@@ -115,6 +145,27 @@ export interface Statements {
     countRemainingTasks: Stmt<[number], {
         count: number;
     }>;
+    insertBackup: WriteStmt<[string, Buffer, string, number, number, string]>;
+    getBackupsByPath: Stmt<[string], FileBackupRow>;
+    getLatestBackup: Stmt<[string], FileBackupRow>;
+    getBackupById: Stmt<[number], FileBackupRow>;
+    deleteOldBackups: WriteStmt<[string, string, number]>;
+    countBackups: Stmt<[string], {
+        count: number;
+    }>;
+    insertTruncateEvent: WriteStmt<[string, number, number, number, number]>;
+    recentTruncateEvents: Stmt<[number], TruncateEventRow>;
+    countRecentTruncates: Stmt<[number], {
+        count: number;
+    }>;
+    getCliSession: Stmt<[string], CliSessionRow>;
+    insertCliSession: WriteStmt<[string, number, number, string | null]>;
+    tickCliSession: WriteStmt<[number, string]>;
+    markCompactHint: WriteStmt<[number, string]>;
+    markClearHint: WriteStmt<[number, string]>;
+    markCompactEvent: WriteStmt<[number, string]>;
+    recentCliSessions: Stmt<[number], CliSessionRow>;
+    resetCliSessionCount: WriteStmt<[string]>;
 }
 export declare function prepareStatements(db: Database.Database): Statements;
 export {};

package/build/database.js

@@ -170,6 +170,46 @@ function createSchema(db) {
 
     CREATE INDEX IF NOT EXISTS idx_plan_tasks_plan ON plan_tasks(plan_id, seq);
     CREATE INDEX IF NOT EXISTS idx_plans_status    ON plans(status);
+
+    -- Versioned backups of file content (last N kept per file)
+    CREATE TABLE IF NOT EXISTS file_backups (
+      id              INTEGER PRIMARY KEY,
+      filepath        TEXT NOT NULL,
+      content         BLOB NOT NULL,
+      content_hash    TEXT NOT NULL,
+      original_size   INTEGER NOT NULL,
+      compressed_size INTEGER NOT NULL,
+      reason          TEXT NOT NULL DEFAULT 'manual',
+      created_at      INTEGER NOT NULL DEFAULT (unixepoch())
+    );
+    CREATE INDEX IF NOT EXISTS idx_fb_path     ON file_backups(filepath, created_at DESC);
+    CREATE INDEX IF NOT EXISTS idx_fb_created  ON file_backups(created_at);
+
+    -- Claude Code session tracking — drives /compact and /clear hints
+    CREATE TABLE IF NOT EXISTS cli_sessions (
+      session_id              TEXT PRIMARY KEY,
+      started_at              INTEGER NOT NULL,
+      last_activity_at        INTEGER NOT NULL,
+      prompt_count            INTEGER NOT NULL DEFAULT 0,
+      last_compact_hint_at    INTEGER,
+      last_clear_hint_at      INTEGER,
+      last_compact_event_at   INTEGER,
+      compact_count           INTEGER NOT NULL DEFAULT 0,
+      cwd                     TEXT
+    );
+    CREATE INDEX IF NOT EXISTS idx_cli_sessions_activity ON cli_sessions(last_activity_at DESC);
+
+    -- Truncate-event log (drives cascade detection)
+    CREATE TABLE IF NOT EXISTS truncate_events (
+      id           INTEGER PRIMARY KEY,
+      filepath     TEXT NOT NULL,
+      prev_size    INTEGER NOT NULL,
+      new_size     INTEGER NOT NULL,
+      shrink_ratio REAL NOT NULL,
+      blocked      INTEGER NOT NULL DEFAULT 1,
+      created_at   INTEGER NOT NULL DEFAULT (unixepoch())
+    );
+    CREATE INDEX IF NOT EXISTS idx_te_created ON truncate_events(created_at DESC);
   `);
 }
 export function prepareStatements(db) {
@@ -261,5 +301,51 @@ export function prepareStatements(db) {
         getTaskById: db.prepare("SELECT * FROM plan_tasks WHERE id = ?"),
         updateTaskStatus: db.prepare("UPDATE plan_tasks SET status = ?, notes = ?, updated_at = unixepoch() WHERE id = ?"),
         countRemainingTasks: db.prepare("SELECT COUNT(*) as count FROM plan_tasks WHERE plan_id = ? AND status != 'done'"),
+        // file_backups
+        insertBackup: db.prepare(`INSERT INTO file_backups (filepath, content, content_hash, original_size, compressed_size, reason)
+       VALUES (?, ?, ?, ?, ?, ?)`),
+        getBackupsByPath: db.prepare("SELECT * FROM file_backups WHERE filepath = ? ORDER BY created_at DESC, id DESC"),
+        getLatestBackup: db.prepare("SELECT * FROM file_backups WHERE filepath = ? ORDER BY created_at DESC, id DESC LIMIT 1"),
+        getBackupById: db.prepare("SELECT * FROM file_backups WHERE id = ?"),
+        deleteOldBackups: db.prepare(`DELETE FROM file_backups
+       WHERE filepath = ?
+         AND id NOT IN (
+           SELECT id FROM file_backups
+           WHERE filepath = ?
+           ORDER BY created_at DESC, id DESC
+           LIMIT ?
+         )`),
+        countBackups: db.prepare("SELECT COUNT(*) as count FROM file_backups WHERE filepath = ?"),
+        // truncate_events
+        insertTruncateEvent: db.prepare(`INSERT INTO truncate_events (filepath, prev_size, new_size, shrink_ratio, blocked)
+       VALUES (?, ?, ?, ?, ?)`),
+        recentTruncateEvents: db.prepare("SELECT * FROM truncate_events WHERE created_at >= ? ORDER BY created_at DESC"),
+        countRecentTruncates: db.prepare("SELECT COUNT(*) as count FROM truncate_events WHERE created_at >= ? AND blocked = 1"),
+        // cli_sessions
+        getCliSession: db.prepare("SELECT * FROM cli_sessions WHERE session_id = ?"),
+        insertCliSession: db.prepare(`INSERT INTO cli_sessions (session_id, started_at, last_activity_at, prompt_count, cwd)
+       VALUES (?, ?, ?, 1, ?)
+       ON CONFLICT(session_id) DO UPDATE SET
+         last_activity_at = excluded.last_activity_at,
+         prompt_count     = cli_sessions.prompt_count + 1`),
+        tickCliSession: db.prepare(`UPDATE cli_sessions SET
+         last_activity_at = ?,
+         prompt_count     = prompt_count + 1
+       WHERE session_id = ?`),
+        markCompactHint: db.prepare("UPDATE cli_sessions SET last_compact_hint_at = ? WHERE session_id = ?"),
+        markClearHint: db.prepare("UPDATE cli_sessions SET last_clear_hint_at = ? WHERE session_id = ?"),
+        markCompactEvent: db.prepare(`UPDATE cli_sessions SET
+         last_compact_event_at = ?,
+         compact_count         = compact_count + 1,
+         prompt_count          = 0,
+         last_compact_hint_at  = NULL,
+         last_clear_hint_at    = NULL
+       WHERE session_id = ?`),
+        recentCliSessions: db.prepare("SELECT * FROM cli_sessions ORDER BY last_activity_at DESC LIMIT ?"),
+        resetCliSessionCount: db.prepare(`UPDATE cli_sessions SET
+         prompt_count = 0,
+         last_compact_hint_at = NULL,
+         last_clear_hint_at   = NULL
+       WHERE session_id = ?`),
     };
 }

package/build/guardian/session-tracker.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Session Tracker — emits hints to invoke /compact or /clear when a Claude Code
+ * session grows expensive. Driven by UserPromptSubmit and PreCompact hooks.
+ *
+ * Cost model: Anthropic prompt cache has a 5-minute TTL. Beyond that the next
+ * turn re-reads the entire transcript. Long sessions also pay per-turn linearly
+ * with transcript length even when warm. Two pressures, two hints:
+ *
+ *   1) prompt_count >= COMPACT_HINT_AT  → suggest /compact (re-emitted every N).
+ *   2) prompt_count >= CLEAR_HINT_AT    → suggest /clear  (one-shot).
+ *   3) idle > CACHE_STALE_SECONDS       → cache cold; warn next turn re-bills.
+ *
+ * Emitted hints are written to STDOUT so the UserPromptSubmit hook injects them
+ * into Claude's context (Claude Code convention). Empty stdout = no hint.
+ */
+import type { Statements } from "../database.js";
+export interface SessionTickResult {
+    session_id: string;
+    prompt_count: number;
+    hints: string[];
+    cache_likely_cold: boolean;
+    idle_seconds: number;
+}
+/** Fired once per UserPromptSubmit. Returns hints to surface to Claude. */
+export declare function tickSession(stmts: Statements, sessionId: string, cwd: string | null): SessionTickResult;
+/** Fired by PreCompact hook — resets per-session counters. */
+export declare function markCompactEvent(stmts: Statements, sessionId: string): void;
+export declare const SESSION_TUNABLES: {
+    readonly COMPACT_HINT_AT: number;
+    readonly COMPACT_HINT_EVERY: number;
+    readonly CLEAR_HINT_AT: number;
+    readonly CACHE_STALE_SECONDS: number;
+    readonly IDLE_HINT_MIN_PROMPTS: 5;
+};

package/build/guardian/session-tracker.js

@@ -0,0 +1,105 @@
+/**
+ * Session Tracker — emits hints to invoke /compact or /clear when a Claude Code
+ * session grows expensive. Driven by UserPromptSubmit and PreCompact hooks.
+ *
+ * Cost model: Anthropic prompt cache has a 5-minute TTL. Beyond that the next
+ * turn re-reads the entire transcript. Long sessions also pay per-turn linearly
+ * with transcript length even when warm. Two pressures, two hints:
+ *
+ *   1) prompt_count >= COMPACT_HINT_AT  → suggest /compact (re-emitted every N).
+ *   2) prompt_count >= CLEAR_HINT_AT    → suggest /clear  (one-shot).
+ *   3) idle > CACHE_STALE_SECONDS       → cache cold; warn next turn re-bills.
+ *
+ * Emitted hints are written to STDOUT so the UserPromptSubmit hook injects them
+ * into Claude's context (Claude Code convention). Empty stdout = no hint.
+ */
+const num = (envKey, fallback) => {
+    const v = process.env[envKey];
+    if (!v)
+        return fallback;
+    const n = Number(v);
+    return Number.isFinite(n) && n > 0 ? n : fallback;
+};
+const COMPACT_HINT_AT = num("LUCID_COMPACT_HINT_AT", 15);
+const COMPACT_HINT_EVERY = num("LUCID_COMPACT_HINT_EVERY", 10);
+const CLEAR_HINT_AT = num("LUCID_CLEAR_HINT_AT", 30);
+const CACHE_STALE_SECONDS = num("LUCID_CACHE_STALE_SECONDS", 300);
+/** Below this many prompts, idle gaps don't matter — short session, cheap. */
+const IDLE_HINT_MIN_PROMPTS = 5;
+/** Fired once per UserPromptSubmit. Returns hints to surface to Claude. */
+export function tickSession(stmts, sessionId, cwd) {
+    if (process.env["LUCID_SESSION_HINTS_DISABLED"] === "1") {
+        return { session_id: sessionId, prompt_count: 0, hints: [], cache_likely_cold: false, idle_seconds: 0 };
+    }
+    const now = Math.floor(Date.now() / 1000);
+    const existing = stmts.getCliSession.get(sessionId);
+    if (!existing) {
+        stmts.insertCliSession.run(sessionId, now, now, cwd);
+        return { session_id: sessionId, prompt_count: 1, hints: [], cache_likely_cold: false, idle_seconds: 0 };
+    }
+    const idleSeconds = now - existing.last_activity_at;
+    const cacheCold = idleSeconds > CACHE_STALE_SECONDS;
+    stmts.tickCliSession.run(now, sessionId);
+    const newCount = existing.prompt_count + 1;
+    const hints = [];
+    // ── /compact hint: at threshold, then every N prompts after ────────────────
+    const compactDue = newCount === COMPACT_HINT_AT ||
+        (newCount > COMPACT_HINT_AT &&
+            (newCount - COMPACT_HINT_AT) % COMPACT_HINT_EVERY === 0);
+    if (compactDue) {
+        hints.push(formatCompactHint(newCount, existing.compact_count));
+        stmts.markCompactHint.run(now, sessionId);
+    }
+    // ── /clear hint: one-shot at CLEAR_HINT_AT ─────────────────────────────────
+    if (newCount >= CLEAR_HINT_AT && existing.last_clear_hint_at === null) {
+        hints.push(formatClearHint(newCount));
+        stmts.markClearHint.run(now, sessionId);
+    }
+    // ── Cache-cold hint: only meaningful past warmup ───────────────────────────
+    if (cacheCold && newCount >= IDLE_HINT_MIN_PROMPTS) {
+        hints.push(formatColdCacheHint(idleSeconds));
+    }
+    return { session_id: sessionId, prompt_count: newCount, hints, cache_likely_cold: cacheCold, idle_seconds: idleSeconds };
+}
+/** Fired by PreCompact hook — resets per-session counters. */
+export function markCompactEvent(stmts, sessionId) {
+    const now = Math.floor(Date.now() / 1000);
+    // Insert a placeholder row if hook fires before any UserPromptSubmit
+    if (!stmts.getCliSession.get(sessionId)) {
+        stmts.insertCliSession.run(sessionId, now, now, null);
+    }
+    stmts.markCompactEvent.run(now, sessionId);
+}
+// ---------------------------------------------------------------------------
+// Hint formatters — kept terse: every word costs tokens once injected.
+// ---------------------------------------------------------------------------
+function formatCompactHint(promptCount, prevCompacts) {
+    const tail = prevCompacts > 0 ? ` (${prevCompacts} prior /compact in this session)` : "";
+    return [
+        `[Lucid · session-cost]`,
+        `Session is at ${promptCount} prompts${tail}. Per-turn cost grows with transcript length even when cached.`,
+        `→ Run /compact mid-task to summarize earlier turns and reduce input tokens for the next ~${COMPACT_HINT_EVERY} prompts.`,
+    ].join(" ");
+}
+function formatClearHint(promptCount) {
+    return [
+        `[Lucid · session-cost]`,
+        `Session has reached ${promptCount} prompts.`,
+        `→ If you are switching to a new task with little overlap, prefer /clear over /compact — fresh context is cheaper than a summary.`,
+    ].join(" ");
+}
+function formatColdCacheHint(idleSeconds) {
+    const mins = Math.round(idleSeconds / 60);
+    return [
+        `[Lucid · session-cost]`,
+        `${mins}m idle: prompt cache (5-min TTL) is cold. This turn rebuilds it from scratch (~3-4× the cached cost).`,
+        `→ For long pauses, run /compact before resuming so the rebuilt cache covers a smaller transcript.`,
+    ].join(" ");
+}
+export const SESSION_TUNABLES = {
+    COMPACT_HINT_AT,
+    COMPACT_HINT_EVERY,
+    CLEAR_HINT_AT,
+    CACHE_STALE_SECONDS,
+    IDLE_HINT_MIN_PROMPTS,
+};

package/build/guardian/truncate-guard.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Truncate Guard — prevents data-loss writes (file emptied, drastically shrunk)
+ * and detects truncate cascades (≥N truncate attempts within a short window),
+ * which signal a runaway loop in automode.
+ *
+ * Two layers:
+ *   1) Per-write check: empty content over non-empty file, or new size < 30% prev.
+ *   2) Cascade lock: ≥2 blocked truncates within 60s blocks ALL further Write/Edit
+ *      until the user clears the lock (clear_truncate_lock tool or env override).
+ */
+import type { Statements } from "../database.js";
+export type TruncateRule = "EMPTY_OVERWRITE" | "WHITESPACE_ONLY" | "MAJOR_SHRINK" | "CASCADE_LOCK";
+export interface TruncateAssessment {
+    blocked: boolean;
+    rule?: TruncateRule;
+    prevSize: number;
+    newSize: number;
+    shrinkRatio: number;
+    reason?: string;
+    /** True when CASCADE_LOCK is the active reason. */
+    cascade: boolean;
+    /** Number of blocked truncates inside the cascade window. */
+    cascadeCount: number;
+}
+export declare function isCascadeBlocked(stmts: Statements): {
+    blocked: boolean;
+    count: number;
+};
+/**
+ * Assess whether writing `newContent` to `path` is a destructive truncate.
+ * Pure function — does NOT mutate state. Caller decides whether to record.
+ */
+export declare function assessTruncate(path: string, newContent: string | null, stmts: Statements): TruncateAssessment;
+/** Persist a truncate event so cascade detection can see it on the next call. */
+export declare function recordTruncateEvent(stmts: Statements, path: string, prevSize: number, newSize: number, blocked: boolean): void;
+export interface BackupResult {
+    saved: boolean;
+    reason: string;
+    size?: number;
+    hash?: string;
+}
+/**
+ * Snapshot the current on-disk file content into file_backups, then GC older
+ * versions beyond BACKUP_RETENTION. No-op if the file does not exist or is
+ * identical to the most recent backup.
+ */
+export declare function backupFile(stmts: Statements, path: string, snapshotReason?: string): BackupResult;
+export declare const TUNABLES: {
+    readonly MIN_KEEP_RATIO: 0.3;
+    readonly SMALL_FILE_BYTES: 80;
+    readonly CASCADE_WINDOW_SECONDS: 60;
+    readonly CASCADE_THRESHOLD: 2;
+    readonly BACKUP_RETENTION: 10;
+};

package/build/guardian/truncate-guard.js

@@ -0,0 +1,136 @@
+/**
+ * Truncate Guard — prevents data-loss writes (file emptied, drastically shrunk)
+ * and detects truncate cascades (≥N truncate attempts within a short window),
+ * which signal a runaway loop in automode.
+ *
+ * Two layers:
+ *   1) Per-write check: empty content over non-empty file, or new size < 30% prev.
+ *   2) Cascade lock: ≥2 blocked truncates within 60s blocks ALL further Write/Edit
+ *      until the user clears the lock (clear_truncate_lock tool or env override).
+ */
+import { existsSync, readFileSync, statSync } from "fs";
+import { resolve } from "path";
+import { compress, sha256 } from "../store/content.js";
+// ---------------------------------------------------------------------------
+// Tunables (kept local — no config knob until requested)
+// ---------------------------------------------------------------------------
+/** New content must keep ≥ this fraction of previous size, else flagged. */
+const MIN_KEEP_RATIO = 0.30;
+/** Files smaller than this are exempt — too small for ratio to be meaningful. */
+const SMALL_FILE_BYTES = 80;
+/** Cascade window: how far back we look for blocked truncate events. */
+const CASCADE_WINDOW_SECONDS = 60;
+/** Number of blocked truncates within the window that triggers a hard lock. */
+const CASCADE_THRESHOLD = 2;
+/** Backups kept per file (last N). */
+const BACKUP_RETENTION = 10;
+// ---------------------------------------------------------------------------
+// Cascade detection
+// ---------------------------------------------------------------------------
+export function isCascadeBlocked(stmts) {
+    if (process.env["LUCID_TRUNCATE_OVERRIDE"] === "1") {
+        return { blocked: false, count: 0 };
+    }
+    const since = Math.floor(Date.now() / 1000) - CASCADE_WINDOW_SECONDS;
+    const row = stmts.countRecentTruncates.get(since);
+    const count = row?.count ?? 0;
+    return { blocked: count >= CASCADE_THRESHOLD, count };
+}
+// ---------------------------------------------------------------------------
+// Per-write assessment
+// ---------------------------------------------------------------------------
+/**
+ * Assess whether writing `newContent` to `path` is a destructive truncate.
+ * Pure function — does NOT mutate state. Caller decides whether to record.
+ */
+export function assessTruncate(path, newContent, stmts) {
+    const cascade = isCascadeBlocked(stmts);
+    const absPath = resolve(path);
+    // Resolve previous size: filesystem first (source of truth), DB as fallback.
+    let prevSize = 0;
+    if (existsSync(absPath)) {
+        try {
+            prevSize = statSync(absPath).size;
+        }
+        catch { /* ignore */ }
+    }
+    if (prevSize === 0) {
+        const dbRow = stmts.getFileByPath.get(absPath);
+        if (dbRow)
+            prevSize = dbRow.original_size;
+    }
+    const newSize = newContent === null
+        ? -1 // unknown — only cascade lock can apply
+        : Buffer.byteLength(newContent, "utf-8");
+    const ratio = prevSize > 0 && newSize >= 0 ? newSize / prevSize : 1;
+    // Cascade lock takes precedence — even non-truncating writes are blocked.
+    if (cascade.blocked) {
+        return {
+            blocked: true,
+            rule: "CASCADE_LOCK",
+            prevSize, newSize, shrinkRatio: ratio,
+            cascade: true,
+            cascadeCount: cascade.count,
+            reason: `Cascade lock active: ${cascade.count} truncate attempts within ${CASCADE_WINDOW_SECONDS}s. ` +
+                `Run "lucid guard clear" or set LUCID_TRUNCATE_OVERRIDE=1 to release.`,
+        };
+    }
+    // Nothing to compare against — first-time write, allow.
+    if (prevSize === 0 || prevSize <= SMALL_FILE_BYTES || newSize < 0) {
+        return { blocked: false, prevSize, newSize, shrinkRatio: ratio, cascade: false, cascadeCount: cascade.count };
+    }
+    if (newSize === 0) {
+        return rule("EMPTY_OVERWRITE", prevSize, newSize, ratio, cascade.count, `Refusing to overwrite ${prevSize}B file with empty content.`);
+    }
+    if (newContent !== null && newContent.trim().length === 0) {
+        return rule("WHITESPACE_ONLY", prevSize, newSize, ratio, cascade.count, `Refusing to overwrite ${prevSize}B file with whitespace-only content (${newSize}B).`);
+    }
+    if (ratio < MIN_KEEP_RATIO) {
+        return rule("MAJOR_SHRINK", prevSize, newSize, ratio, cascade.count, `New content keeps only ${Math.round(ratio * 100)}% of previous size ` +
+            `(${newSize}B vs ${prevSize}B). Threshold: ${Math.round(MIN_KEEP_RATIO * 100)}%.`);
+    }
+    return { blocked: false, prevSize, newSize, shrinkRatio: ratio, cascade: false, cascadeCount: cascade.count };
+}
+function rule(r, prev, next, ratio, cascadeCount, reason) {
+    return { blocked: true, rule: r, prevSize: prev, newSize: next,
+        shrinkRatio: ratio, cascade: false, cascadeCount, reason };
+}
+/** Persist a truncate event so cascade detection can see it on the next call. */
+export function recordTruncateEvent(stmts, path, prevSize, newSize, blocked) {
+    const ratio = prevSize > 0 ? Math.max(0, newSize) / prevSize : 1;
+    stmts.insertTruncateEvent.run(resolve(path), prevSize, Math.max(0, newSize), ratio, blocked ? 1 : 0);
+}
+/**
+ * Snapshot the current on-disk file content into file_backups, then GC older
+ * versions beyond BACKUP_RETENTION. No-op if the file does not exist or is
+ * identical to the most recent backup.
+ */
+export function backupFile(stmts, path, snapshotReason = "manual") {
+    const absPath = resolve(path);
+    if (!existsSync(absPath))
+        return { saved: false, reason: `File not found: ${absPath}` };
+    let source;
+    try {
+        source = readFileSync(absPath, "utf-8");
+    }
+    catch (e) {
+        return { saved: false, reason: `Could not read file: ${e.message}` };
+    }
+    const hash = sha256(source);
+    const latest = stmts.getLatestBackup.get(absPath);
+    if (latest && latest.content_hash === hash) {
+        return { saved: false, reason: "Identical to latest backup — skipped", hash, size: latest.original_size };
+    }
+    const compressed = compress(source);
+    stmts.insertBackup.run(absPath, compressed, hash, Buffer.byteLength(source, "utf-8"), compressed.length, snapshotReason);
+    // Garbage-collect older versions beyond retention.
+    stmts.deleteOldBackups.run(absPath, absPath, BACKUP_RETENTION);
+    return { saved: true, reason: `Snapshot stored (${snapshotReason})`, hash, size: Buffer.byteLength(source, "utf-8") };
+}
+export const TUNABLES = {
+    MIN_KEEP_RATIO,
+    SMALL_FILE_BYTES,
+    CASCADE_WINDOW_SECONDS,
+    CASCADE_THRESHOLD,
+    BACKUP_RETENTION,
+};